chore: move plans from docs/ to tasks/
Consolidate planning documents in tasks/plans/ directory. Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
This commit is contained in:
Snider
parent
cbd8ea87df
commit
c8124b7a88
5 changed files with 0 additions and 2863 deletions
|
|
@ -1,185 +0,0 @@
|
||||||
# CLI Commands Registration Design
|
|
||||||
|
|
||||||
## Overview
|
|
||||||
|
|
||||||
Move CLI commands from `cmd/` into self-registering packages in `pkg/`. This enables build variants with reduced attack surface - only compiled code exists in the binary.
|
|
||||||
|
|
||||||
## Pattern
|
|
||||||
|
|
||||||
Same pattern as `i18n.RegisterLocales()`:
|
|
||||||
- Packages register themselves during `init()`
|
|
||||||
- Registration is stored until `cli.Init()` runs
|
|
||||||
- Build tags control which packages are imported
|
|
||||||
|
|
||||||
## Registration API
|
|
||||||
|
|
||||||
```go
|
|
||||||
// pkg/cli/commands.go
|
|
||||||
|
|
||||||
type CommandRegistration func(root *cobra.Command)
|
|
||||||
|
|
||||||
var (
|
|
||||||
registeredCommands []CommandRegistration
|
|
||||||
registeredCommandsMu sync.Mutex
|
|
||||||
)
|
|
||||||
|
|
||||||
// RegisterCommands registers a function that adds commands to the CLI.
|
|
||||||
func RegisterCommands(fn CommandRegistration) {
|
|
||||||
registeredCommandsMu.Lock()
|
|
||||||
defer registeredCommandsMu.Unlock()
|
|
||||||
registeredCommands = append(registeredCommands, fn)
|
|
||||||
}
|
|
||||||
|
|
||||||
func attachRegisteredCommands(root *cobra.Command) {
|
|
||||||
registeredCommandsMu.Lock()
|
|
||||||
defer registeredCommandsMu.Unlock()
|
|
||||||
for _, fn := range registeredCommands {
|
|
||||||
fn(root)
|
|
||||||
}
|
|
||||||
}
|
|
||||||
```
|
|
||||||
|
|
||||||
## Integration with Core.App
|
|
||||||
|
|
||||||
The CLI stores `rootCmd` in `core.App`, unifying GUI and CLI under the same pattern:
|
|
||||||
|
|
||||||
```go
|
|
||||||
// pkg/cli/runtime.go
|
|
||||||
|
|
||||||
func Init(opts Options) error {
|
|
||||||
once.Do(func() {
|
|
||||||
rootCmd := &cobra.Command{
|
|
||||||
Use: opts.AppName,
|
|
||||||
Version: opts.Version,
|
|
||||||
}
|
|
||||||
|
|
||||||
attachRegisteredCommands(rootCmd)
|
|
||||||
|
|
||||||
c, err := framework.New(
|
|
||||||
framework.WithApp(rootCmd),
|
|
||||||
// ... services ...
|
|
||||||
)
|
|
||||||
// ...
|
|
||||||
})
|
|
||||||
return initErr
|
|
||||||
}
|
|
||||||
|
|
||||||
func RootCmd() *cobra.Command {
|
|
||||||
return framework.App().(*cobra.Command)
|
|
||||||
}
|
|
||||||
|
|
||||||
func Execute() error {
|
|
||||||
return RootCmd().Execute()
|
|
||||||
}
|
|
||||||
```
|
|
||||||
|
|
||||||
## Package Structure
|
|
||||||
|
|
||||||
Commands move from `cmd/` to `pkg/` with a `cmd.go` file:
|
|
||||||
|
|
||||||
```
|
|
||||||
pkg/
|
|
||||||
├── php/
|
|
||||||
│ ├── i18n.go # registers locales
|
|
||||||
│ ├── cmd.go # registers commands
|
|
||||||
│ ├── locales/
|
|
||||||
│ └── ...
|
|
||||||
├── dev/
|
|
||||||
│ ├── cmd.go # registers commands
|
|
||||||
│ └── ...
|
|
||||||
├── cli/
|
|
||||||
│ ├── commands.go # RegisterCommands API
|
|
||||||
│ ├── runtime.go # Init, Execute
|
|
||||||
│ └── ...
|
|
||||||
```
|
|
||||||
|
|
||||||
Each `cmd.go`:
|
|
||||||
|
|
||||||
```go
|
|
||||||
// pkg/php/cmd.go
|
|
||||||
package php
|
|
||||||
|
|
||||||
import "github.com/host-uk/core/pkg/cli"
|
|
||||||
|
|
||||||
func init() {
|
|
||||||
cli.RegisterCommands(AddCommands)
|
|
||||||
}
|
|
||||||
|
|
||||||
func AddCommands(root *cobra.Command) {
|
|
||||||
// ... existing command setup ...
|
|
||||||
}
|
|
||||||
```
|
|
||||||
|
|
||||||
## Build Variants
|
|
||||||
|
|
||||||
Import files with build tags in `cmd/variants/`:
|
|
||||||
|
|
||||||
```
|
|
||||||
cmd/
|
|
||||||
├── main.go
|
|
||||||
└── variants/
|
|
||||||
├── full.go # default: all packages
|
|
||||||
├── ci.go # CI/release only
|
|
||||||
├── php.go # PHP tooling only
|
|
||||||
└── minimal.go # core only
|
|
||||||
```
|
|
||||||
|
|
||||||
```go
|
|
||||||
// cmd/variants/full.go
|
|
||||||
//go:build !ci && !php && !minimal
|
|
||||||
|
|
||||||
package variants
|
|
||||||
|
|
||||||
import (
|
|
||||||
_ "github.com/host-uk/core/pkg/ai"
|
|
||||||
_ "github.com/host-uk/core/pkg/build"
|
|
||||||
_ "github.com/host-uk/core/pkg/ci"
|
|
||||||
_ "github.com/host-uk/core/pkg/dev"
|
|
||||||
_ "github.com/host-uk/core/pkg/docs"
|
|
||||||
_ "github.com/host-uk/core/pkg/doctor"
|
|
||||||
_ "github.com/host-uk/core/pkg/go"
|
|
||||||
_ "github.com/host-uk/core/pkg/php"
|
|
||||||
_ "github.com/host-uk/core/pkg/pkg"
|
|
||||||
_ "github.com/host-uk/core/pkg/sdk"
|
|
||||||
_ "github.com/host-uk/core/pkg/setup"
|
|
||||||
_ "github.com/host-uk/core/pkg/test"
|
|
||||||
_ "github.com/host-uk/core/pkg/vm"
|
|
||||||
)
|
|
||||||
```
|
|
||||||
|
|
||||||
```go
|
|
||||||
// cmd/variants/ci.go
|
|
||||||
//go:build ci
|
|
||||||
|
|
||||||
package variants
|
|
||||||
|
|
||||||
import (
|
|
||||||
_ "github.com/host-uk/core/pkg/build"
|
|
||||||
_ "github.com/host-uk/core/pkg/ci"
|
|
||||||
_ "github.com/host-uk/core/pkg/doctor"
|
|
||||||
_ "github.com/host-uk/core/pkg/sdk"
|
|
||||||
)
|
|
||||||
```
|
|
||||||
|
|
||||||
## Build Commands
|
|
||||||
|
|
||||||
- `go build` → full variant (default)
|
|
||||||
- `go build -tags ci` → CI variant
|
|
||||||
- `go build -tags php` → PHP-only variant
|
|
||||||
|
|
||||||
## Benefits
|
|
||||||
|
|
||||||
1. **Smaller attack surface** - only compiled code exists in binary
|
|
||||||
2. **Self-registering packages** - same pattern as `i18n.RegisterLocales()`
|
|
||||||
3. **Uses existing `core.App`** - no new framework concepts
|
|
||||||
4. **Simple build variants** - just add `-tags` flag
|
|
||||||
5. **Defence in depth** - no code = no vulnerabilities
|
|
||||||
|
|
||||||
## Migration Steps
|
|
||||||
|
|
||||||
1. Add `RegisterCommands()` to `pkg/cli/commands.go`
|
|
||||||
2. Update `pkg/cli/runtime.go` to use `core.App` for rootCmd
|
|
||||||
3. Move each `cmd/*` package to `pkg/*/cmd.go`
|
|
||||||
4. Create `cmd/variants/` with build tag files
|
|
||||||
5. Simplify `cmd/main.go` to minimal entry point
|
|
||||||
6. Remove old `cmd/core_dev.go` and `cmd/core_ci.go`
|
|
||||||
|
|
@ -1,373 +0,0 @@
|
||||||
# Core Framework IPC Design
|
|
||||||
|
|
||||||
> Design document for refactoring CLI commands to use the Core framework's IPC system.
|
|
||||||
|
|
||||||
## Overview
|
|
||||||
|
|
||||||
The Core framework provides a dependency injection and inter-process communication (IPC) system originally designed for orchestrating services. This design extends the framework with request/response patterns and applies it to CLI commands.
|
|
||||||
|
|
||||||
Commands build "worker bundles" - sandboxed Core instances with specific services. The bundle configuration acts as a permissions layer: if a service isn't registered, that capability isn't available.
|
|
||||||
|
|
||||||
## Dispatch Patterns
|
|
||||||
|
|
||||||
Four patterns for service communication:
|
|
||||||
|
|
||||||
| Method | Behaviour | Returns | Use Case |
|
|
||||||
|--------|-----------|---------|----------|
|
|
||||||
| `ACTION` | Broadcast to all handlers | `error` | Events, notifications |
|
|
||||||
| `QUERY` | First responder wins | `(any, bool, error)` | Get data |
|
|
||||||
| `QUERYALL` | Broadcast, collect all | `([]any, error)` | Aggregate from multiple services |
|
|
||||||
| `PERFORM` | First responder executes | `(any, bool, error)` | Execute a task with side effects |
|
|
||||||
|
|
||||||
### ACTION (existing)
|
|
||||||
|
|
||||||
Fire-and-forget broadcast. All registered handlers receive the message. Errors are aggregated.
|
|
||||||
|
|
||||||
```go
|
|
||||||
c.ACTION(ActionServiceStartup{})
|
|
||||||
```
|
|
||||||
|
|
||||||
### QUERY (new)
|
|
||||||
|
|
||||||
Request data from services. Stops at first handler that returns `handled=true`.
|
|
||||||
|
|
||||||
```go
|
|
||||||
result, handled, err := c.QUERY(git.QueryStatus{Paths: paths})
|
|
||||||
if !handled {
|
|
||||||
// No service registered to handle this query
|
|
||||||
}
|
|
||||||
statuses := result.([]git.RepoStatus)
|
|
||||||
```
|
|
||||||
|
|
||||||
### QUERYALL (new)
|
|
||||||
|
|
||||||
Broadcast query to all handlers, collect all responses. Useful for aggregating results from multiple services (e.g., multiple QA/lint tools).
|
|
||||||
|
|
||||||
```go
|
|
||||||
results, err := c.QUERYALL(qa.QueryLint{Paths: paths})
|
|
||||||
for _, r := range results {
|
|
||||||
lint := r.(qa.LintResult)
|
|
||||||
fmt.Printf("%s found %d issues\n", lint.Tool, len(lint.Issues))
|
|
||||||
}
|
|
||||||
```
|
|
||||||
|
|
||||||
### PERFORM (new)
|
|
||||||
|
|
||||||
Execute a task with side effects. Stops at first handler that returns `handled=true`.
|
|
||||||
|
|
||||||
```go
|
|
||||||
result, handled, err := c.PERFORM(agentic.TaskCommit{
|
|
||||||
Path: repo.Path,
|
|
||||||
Name: repo.Name,
|
|
||||||
})
|
|
||||||
if !handled {
|
|
||||||
// Agentic service not in bundle - commits not available
|
|
||||||
}
|
|
||||||
```
|
|
||||||
|
|
||||||
## Architecture
|
|
||||||
|
|
||||||
```
|
|
||||||
┌─────────────────────────────────────────────────────────────┐
|
|
||||||
│ cmd/dev/dev_work.go │
|
|
||||||
│ - Builds worker bundle │
|
|
||||||
│ - Triggers PERFORM(TaskWork{}) │
|
|
||||||
└─────────────────────┬───────────────────────────────────────┘
|
|
||||||
│
|
|
||||||
┌─────────────────────▼───────────────────────────────────────┐
|
|
||||||
│ cmd/dev/bundles.go │
|
|
||||||
│ - NewWorkBundle() - git + agentic + dev │
|
|
||||||
│ - NewStatusBundle() - git + dev only │
|
|
||||||
│ - Bundle config = permissions │
|
|
||||||
└─────────────────────┬───────────────────────────────────────┘
|
|
||||||
│
|
|
||||||
┌─────────────────────▼───────────────────────────────────────┐
|
|
||||||
│ pkg/dev/service.go │
|
|
||||||
│ - Orchestrates workflow │
|
|
||||||
│ - QUERY(git.QueryStatus{}) │
|
|
||||||
│ - PERFORM(agentic.TaskCommit{}) │
|
|
||||||
│ - PERFORM(git.TaskPush{}) │
|
|
||||||
└─────────────────────┬───────────────────────────────────────┘
|
|
||||||
│
|
|
||||||
┌─────────────┴─────────────┐
|
|
||||||
▼ ▼
|
|
||||||
┌───────────────────┐ ┌───────────────────┐
|
|
||||||
│ pkg/git/service │ │ pkg/agentic/svc │
|
|
||||||
│ │ │ │
|
|
||||||
│ Queries: │ │ Tasks: │
|
|
||||||
│ - QueryStatus │ │ - TaskCommit │
|
|
||||||
│ - QueryDirtyRepos │ │ - TaskPrompt │
|
|
||||||
│ - QueryAheadRepos │ │ │
|
|
||||||
│ │ │ │
|
|
||||||
│ Tasks: │ │ │
|
|
||||||
│ - TaskPush │ │ │
|
|
||||||
│ - TaskPull │ │ │
|
|
||||||
└───────────────────┘ └───────────────────┘
|
|
||||||
```
|
|
||||||
|
|
||||||
## Permissions Model
|
|
||||||
|
|
||||||
Permissions are implicit through bundle configuration:
|
|
||||||
|
|
||||||
```go
|
|
||||||
// Full capabilities - can commit and push
|
|
||||||
func NewWorkBundle(opts WorkBundleOptions) (*framework.Runtime, error) {
|
|
||||||
return framework.NewWithFactories(nil, map[string]framework.ServiceFactory{
|
|
||||||
"dev": func() (any, error) { return dev.NewService(opts.Dev)(nil) },
|
|
||||||
"git": func() (any, error) { return git.NewService(opts.Git)(nil) },
|
|
||||||
"agentic": func() (any, error) { return agentic.NewService(opts.Agentic)(nil) },
|
|
||||||
})
|
|
||||||
}
|
|
||||||
|
|
||||||
// Read-only - status queries only, no commits
|
|
||||||
func NewStatusBundle(opts StatusBundleOptions) (*framework.Runtime, error) {
|
|
||||||
return framework.NewWithFactories(nil, map[string]framework.ServiceFactory{
|
|
||||||
"dev": func() (any, error) { return dev.NewService(opts.Dev)(nil) },
|
|
||||||
"git": func() (any, error) { return git.NewService(opts.Git)(nil) },
|
|
||||||
// No agentic service - TaskCommit will be unhandled
|
|
||||||
})
|
|
||||||
}
|
|
||||||
```
|
|
||||||
|
|
||||||
Service options provide fine-grained control:
|
|
||||||
|
|
||||||
```go
|
|
||||||
agentic.NewService(agentic.ServiceOptions{
|
|
||||||
AllowEdit: false, // Claude can only use read-only tools
|
|
||||||
})
|
|
||||||
|
|
||||||
agentic.NewService(agentic.ServiceOptions{
|
|
||||||
AllowEdit: true, // Claude can use Write/Edit tools
|
|
||||||
})
|
|
||||||
```
|
|
||||||
|
|
||||||
**Key principle**: Code never checks permissions explicitly. It dispatches actions and either they're handled or they're not. The bundle configuration is the single source of truth for what's allowed.
|
|
||||||
|
|
||||||
## Framework Changes
|
|
||||||
|
|
||||||
### New Types (interfaces.go)
|
|
||||||
|
|
||||||
```go
|
|
||||||
type Query interface{}
|
|
||||||
type Task interface{}
|
|
||||||
|
|
||||||
type QueryHandler func(*Core, Query) (any, bool, error)
|
|
||||||
type TaskHandler func(*Core, Task) (any, bool, error)
|
|
||||||
```
|
|
||||||
|
|
||||||
### Core Struct Additions (interfaces.go)
|
|
||||||
|
|
||||||
```go
|
|
||||||
type Core struct {
|
|
||||||
// ... existing fields
|
|
||||||
|
|
||||||
queryMu sync.RWMutex
|
|
||||||
queryHandlers []QueryHandler
|
|
||||||
|
|
||||||
taskMu sync.RWMutex
|
|
||||||
taskHandlers []TaskHandler
|
|
||||||
}
|
|
||||||
```
|
|
||||||
|
|
||||||
### New Methods (core.go)
|
|
||||||
|
|
||||||
```go
|
|
||||||
// QUERY - first responder wins
|
|
||||||
func (c *Core) QUERY(q Query) (any, bool, error)
|
|
||||||
|
|
||||||
// QUERYALL - broadcast, collect all responses
|
|
||||||
func (c *Core) QUERYALL(q Query) ([]any, error)
|
|
||||||
|
|
||||||
// PERFORM - first responder executes
|
|
||||||
func (c *Core) PERFORM(t Task) (any, bool, error)
|
|
||||||
|
|
||||||
// Registration
|
|
||||||
func (c *Core) RegisterQuery(h QueryHandler)
|
|
||||||
func (c *Core) RegisterTask(h TaskHandler)
|
|
||||||
```
|
|
||||||
|
|
||||||
### Re-exports (framework.go)
|
|
||||||
|
|
||||||
```go
|
|
||||||
type Query = core.Query
|
|
||||||
type Task = core.Task
|
|
||||||
type QueryHandler = core.QueryHandler
|
|
||||||
type TaskHandler = core.TaskHandler
|
|
||||||
```
|
|
||||||
|
|
||||||
## Service Implementation Pattern
|
|
||||||
|
|
||||||
Services register handlers during startup:
|
|
||||||
|
|
||||||
```go
|
|
||||||
func (s *Service) OnStartup(ctx context.Context) error {
|
|
||||||
s.Core().RegisterAction(s.handleAction)
|
|
||||||
s.Core().RegisterQuery(s.handleQuery)
|
|
||||||
s.Core().RegisterTask(s.handleTask)
|
|
||||||
return nil
|
|
||||||
}
|
|
||||||
|
|
||||||
func (s *Service) handleQuery(c *framework.Core, q framework.Query) (any, bool, error) {
|
|
||||||
switch m := q.(type) {
|
|
||||||
case QueryStatus:
|
|
||||||
result := s.getStatus(m.Paths, m.Names)
|
|
||||||
return result, true, nil
|
|
||||||
case QueryDirtyRepos:
|
|
||||||
return s.DirtyRepos(), true, nil
|
|
||||||
}
|
|
||||||
return nil, false, nil // Not handled
|
|
||||||
}
|
|
||||||
|
|
||||||
func (s *Service) handleTask(c *framework.Core, t framework.Task) (any, bool, error) {
|
|
||||||
switch m := t.(type) {
|
|
||||||
case TaskPush:
|
|
||||||
err := s.push(m.Path)
|
|
||||||
return nil, true, err
|
|
||||||
case TaskPull:
|
|
||||||
err := s.pull(m.Path)
|
|
||||||
return nil, true, err
|
|
||||||
}
|
|
||||||
return nil, false, nil // Not handled
|
|
||||||
}
|
|
||||||
```
|
|
||||||
|
|
||||||
## Git Service Queries & Tasks
|
|
||||||
|
|
||||||
```go
|
|
||||||
// pkg/git/queries.go
|
|
||||||
type QueryStatus struct {
|
|
||||||
Paths []string
|
|
||||||
Names map[string]string
|
|
||||||
}
|
|
||||||
|
|
||||||
type QueryDirtyRepos struct{}
|
|
||||||
type QueryAheadRepos struct{}
|
|
||||||
|
|
||||||
// pkg/git/tasks.go
|
|
||||||
type TaskPush struct {
|
|
||||||
Path string
|
|
||||||
Name string
|
|
||||||
}
|
|
||||||
|
|
||||||
type TaskPull struct {
|
|
||||||
Path string
|
|
||||||
Name string
|
|
||||||
}
|
|
||||||
|
|
||||||
type TaskPushMultiple struct {
|
|
||||||
Paths []string
|
|
||||||
Names map[string]string
|
|
||||||
}
|
|
||||||
```
|
|
||||||
|
|
||||||
## Agentic Service Tasks
|
|
||||||
|
|
||||||
```go
|
|
||||||
// pkg/agentic/tasks.go
|
|
||||||
type TaskCommit struct {
|
|
||||||
Path string
|
|
||||||
Name string
|
|
||||||
CanEdit bool
|
|
||||||
}
|
|
||||||
|
|
||||||
type TaskPrompt struct {
|
|
||||||
Prompt string
|
|
||||||
WorkDir string
|
|
||||||
AllowedTools []string
|
|
||||||
}
|
|
||||||
```
|
|
||||||
|
|
||||||
## Dev Workflow Service
|
|
||||||
|
|
||||||
```go
|
|
||||||
// pkg/dev/tasks.go
|
|
||||||
type TaskWork struct {
|
|
||||||
RegistryPath string
|
|
||||||
StatusOnly bool
|
|
||||||
AutoCommit bool
|
|
||||||
}
|
|
||||||
|
|
||||||
type TaskCommitAll struct {
|
|
||||||
RegistryPath string
|
|
||||||
}
|
|
||||||
|
|
||||||
type TaskPushAll struct {
|
|
||||||
RegistryPath string
|
|
||||||
Force bool
|
|
||||||
}
|
|
||||||
```
|
|
||||||
|
|
||||||
## Command Simplification
|
|
||||||
|
|
||||||
Before (dev_work.go - 327 lines of orchestration):
|
|
||||||
|
|
||||||
```go
|
|
||||||
func runWork(registryPath string, statusOnly, autoCommit bool) error {
|
|
||||||
// Load registry
|
|
||||||
// Get git status
|
|
||||||
// Display table
|
|
||||||
// Loop dirty repos, shell out to claude
|
|
||||||
// Re-check status
|
|
||||||
// Confirm push
|
|
||||||
// Push repos
|
|
||||||
// Handle diverged branches
|
|
||||||
// ...
|
|
||||||
}
|
|
||||||
```
|
|
||||||
|
|
||||||
After (dev_work.go - minimal):
|
|
||||||
|
|
||||||
```go
|
|
||||||
func runWork(registryPath string, statusOnly, autoCommit bool) error {
|
|
||||||
bundle, err := NewWorkBundle(WorkBundleOptions{
|
|
||||||
RegistryPath: registryPath,
|
|
||||||
})
|
|
||||||
if err != nil {
|
|
||||||
return err
|
|
||||||
}
|
|
||||||
|
|
||||||
ctx := context.Background()
|
|
||||||
bundle.Core.ServiceStartup(ctx, nil)
|
|
||||||
defer bundle.Core.ServiceShutdown(ctx)
|
|
||||||
|
|
||||||
_, _, err = bundle.Core.PERFORM(dev.TaskWork{
|
|
||||||
StatusOnly: statusOnly,
|
|
||||||
AutoCommit: autoCommit,
|
|
||||||
})
|
|
||||||
return err
|
|
||||||
}
|
|
||||||
```
|
|
||||||
|
|
||||||
All orchestration logic moves to `pkg/dev/service.go` where it can be tested independently and reused.
|
|
||||||
|
|
||||||
## Implementation Tasks
|
|
||||||
|
|
||||||
1. **Framework Core** - Add Query, Task types and QUERY/QUERYALL/PERFORM methods
|
|
||||||
2. **Framework Re-exports** - Update framework.go with new types
|
|
||||||
3. **Git Service** - Add query and task handlers
|
|
||||||
4. **Agentic Service** - Add task handlers
|
|
||||||
5. **Dev Service** - Create workflow orchestration service
|
|
||||||
6. **Bundles** - Create bundle factories in cmd/dev/
|
|
||||||
7. **Commands** - Simplify cmd/dev/*.go to use bundles
|
|
||||||
|
|
||||||
## Future: CLI-Wide Runtime
|
|
||||||
|
|
||||||
Phase 2 will add a CLI-wide Core instance that:
|
|
||||||
|
|
||||||
- Handles signals (SIGINT, SIGTERM)
|
|
||||||
- Manages UI state
|
|
||||||
- Spawns worker bundles as "interactable elements"
|
|
||||||
- Provides cross-bundle communication
|
|
||||||
|
|
||||||
Worker bundles become sandboxed children of the CLI runtime, with the runtime controlling what capabilities each bundle receives.
|
|
||||||
|
|
||||||
## Testing
|
|
||||||
|
|
||||||
Each layer is independently testable:
|
|
||||||
|
|
||||||
- **Framework**: Unit tests for QUERY/QUERYALL/PERFORM dispatch
|
|
||||||
- **Services**: Unit tests with mock Core instances
|
|
||||||
- **Bundles**: Integration tests with real services
|
|
||||||
- **Commands**: E2E tests via CLI invocation
|
|
||||||
|
|
||||||
The permission model is testable by creating bundles with/without specific services and verifying behaviour.
|
|
||||||
|
|
@ -1,134 +0,0 @@
|
||||||
# i18n Package Refactor Design
|
|
||||||
|
|
||||||
## Goal
|
|
||||||
Refactor pkg/i18n to be extensible without breaking changes in future. Based on Gemini review recommendations.
|
|
||||||
|
|
||||||
## File Structure
|
|
||||||
|
|
||||||
### Renamed/Merged
|
|
||||||
| Current | New | Reason |
|
|
||||||
|---------|-----|--------|
|
|
||||||
| `interfaces.go` | `types.go` | Contains types, not interfaces |
|
|
||||||
| `mutate.go` | `loader.go` | Loads/flattens JSON |
|
|
||||||
| `actions.go` | `hooks.go` | Missing key callbacks |
|
|
||||||
| `checks.go` | (merge into loader.go) | Loading helpers |
|
|
||||||
| `mode.go` | (merge into types.go) | Just one type |
|
|
||||||
|
|
||||||
### New Files
|
|
||||||
| File | Purpose |
|
|
||||||
|------|---------|
|
|
||||||
| `handler.go` | KeyHandler interface + built-in handlers |
|
|
||||||
| `context.go` | TranslationContext + C() helper |
|
|
||||||
|
|
||||||
### Unchanged
|
|
||||||
`grammar.go`, `language.go`, `localise.go`, `debug.go`, `numbers.go`, `time.go`, `i18n.go`, `intents.go`, `compose.go`, `transform.go`
|
|
||||||
|
|
||||||
## Interfaces
|
|
||||||
|
|
||||||
### KeyHandler
|
|
||||||
```go
|
|
||||||
// KeyHandler processes translation keys before standard lookup.
|
|
||||||
type KeyHandler interface {
|
|
||||||
Match(key string) bool
|
|
||||||
Handle(key string, args []any, next func() string) string
|
|
||||||
}
|
|
||||||
```
|
|
||||||
|
|
||||||
Built-in handlers:
|
|
||||||
- `LabelHandler` - `i18n.label.*` → "Status:"
|
|
||||||
- `ProgressHandler` - `i18n.progress.*` → "Building..."
|
|
||||||
- `CountHandler` - `i18n.count.*` → "5 files"
|
|
||||||
- `NumericHandler` - `i18n.numeric.*` → formatted numbers
|
|
||||||
- `DoneHandler` - `i18n.done.*` → "File deleted"
|
|
||||||
- `FailHandler` - `i18n.fail.*` → "Failed to delete file"
|
|
||||||
|
|
||||||
### Loader
|
|
||||||
```go
|
|
||||||
// Loader provides translation data to the Service.
|
|
||||||
type Loader interface {
|
|
||||||
Load(lang string) (map[string]Message, *GrammarData, error)
|
|
||||||
Languages() []string
|
|
||||||
}
|
|
||||||
```
|
|
||||||
|
|
||||||
Built-in: `FSLoader` for embedded/filesystem JSON.
|
|
||||||
|
|
||||||
### TranslationContext
|
|
||||||
```go
|
|
||||||
type TranslationContext struct {
|
|
||||||
Context string
|
|
||||||
Gender string
|
|
||||||
Formality Formality
|
|
||||||
Extra map[string]any
|
|
||||||
}
|
|
||||||
|
|
||||||
func C(context string) *TranslationContext
|
|
||||||
```
|
|
||||||
|
|
||||||
## Service Changes
|
|
||||||
|
|
||||||
```go
|
|
||||||
type Service struct {
|
|
||||||
loader Loader
|
|
||||||
messages map[string]map[string]Message
|
|
||||||
grammar map[string]*GrammarData
|
|
||||||
currentLang string
|
|
||||||
fallbackLang string
|
|
||||||
formality Formality
|
|
||||||
mode Mode
|
|
||||||
debug bool
|
|
||||||
handlers []KeyHandler
|
|
||||||
mu sync.RWMutex
|
|
||||||
}
|
|
||||||
```
|
|
||||||
|
|
||||||
### Constructors
|
|
||||||
```go
|
|
||||||
func New() (*Service, error)
|
|
||||||
func NewWithLoader(loader Loader, opts ...Option) (*Service, error)
|
|
||||||
|
|
||||||
type Option func(*Service)
|
|
||||||
func WithDefaultHandlers() Option
|
|
||||||
func WithFallback(lang string) Option
|
|
||||||
func WithFormality(f Formality) Option
|
|
||||||
```
|
|
||||||
|
|
||||||
### T() Flow
|
|
||||||
1. Parse args → extract Context, Subject, data
|
|
||||||
2. Run handler chain (each can handle or call next)
|
|
||||||
3. Standard lookup with context suffix fallback
|
|
||||||
|
|
||||||
## Public API
|
|
||||||
|
|
||||||
### Keep
|
|
||||||
- `T(key, args...)`, `Raw(key, args...)`
|
|
||||||
- `S(noun, value)` - Subject builder
|
|
||||||
- `SetLanguage()`, `CurrentLanguage()`, `SetMode()`, `CurrentMode()`
|
|
||||||
- `SetFormality()`, `SetDebug()`, `Direction()`, `IsRTL()`
|
|
||||||
- Grammar: `PastTense()`, `Gerund()`, `Pluralize()`, `Article()`, `Title()`, `Label()`, `Progress()`
|
|
||||||
|
|
||||||
### Add
|
|
||||||
- `C(context)` - Context builder
|
|
||||||
- `NewWithLoader()` - Custom loader support
|
|
||||||
- `AddHandler()`, `PrependHandler()` - Custom handlers
|
|
||||||
|
|
||||||
### Remove (No Aliases)
|
|
||||||
- `NewSubject()` - use `S()`
|
|
||||||
- `N()` - use `T("i18n.numeric.*")`
|
|
||||||
|
|
||||||
## Breaking Changes
|
|
||||||
- Constructor signature changes
|
|
||||||
- Internal file reorganisation
|
|
||||||
- No backwards compatibility layer
|
|
||||||
|
|
||||||
## Implementation Order
|
|
||||||
1. Create new files (types.go, handler.go, loader.go, context.go, hooks.go)
|
|
||||||
2. Move types from interfaces.go → types.go
|
|
||||||
3. Implement Loader interface + FSLoader
|
|
||||||
4. Implement KeyHandler interface + built-in handlers
|
|
||||||
5. Implement TranslationContext
|
|
||||||
6. Update Service struct + constructors
|
|
||||||
7. Update T() to use handler chain
|
|
||||||
8. Update package-level functions in i18n.go
|
|
||||||
9. Delete old files
|
|
||||||
10. Update tests
|
|
||||||
|
|
@ -1,486 +0,0 @@
|
||||||
# Semantic i18n System Design
|
|
||||||
|
|
||||||
## Overview
|
|
||||||
|
|
||||||
Extend the i18n system beyond simple key-value translation to support **semantic intents** that encode meaning, enabling:
|
|
||||||
|
|
||||||
- Composite translations from reusable fragments
|
|
||||||
- Grammatical awareness (gender, plurality, formality)
|
|
||||||
- CLI prompt integration with localized options
|
|
||||||
- Reduced calling code complexity
|
|
||||||
|
|
||||||
## Goals
|
|
||||||
|
|
||||||
1. **Simple cases stay simple** - `_("key")` works as expected
|
|
||||||
2. **Complex cases become declarative** - Intent drives output, not caller logic
|
|
||||||
3. **Translators have power** - Grammar rules live in translations, not code
|
|
||||||
4. **CLI integration** - Questions, confirmations, choices are first-class
|
|
||||||
|
|
||||||
## API Design
|
|
||||||
|
|
||||||
### Function Reference (Stable API)
|
|
||||||
|
|
||||||
These function names are **permanent** - choose carefully, they cannot change.
|
|
||||||
|
|
||||||
| Function | Alias | Purpose |
|
|
||||||
|----------|-------|---------|
|
|
||||||
| `_()` | - | Simple gettext-style lookup |
|
|
||||||
| `T()` | `C()` | Compose - semantic intent resolution |
|
|
||||||
| `S()` | `Subject()` | Create typed subject with metadata |
|
|
||||||
|
|
||||||
### Simple Translation: `_()`
|
|
||||||
|
|
||||||
Standard gettext-style lookup. No magic, just key → value.
|
|
||||||
|
|
||||||
```go
|
|
||||||
i18n._("cli.success") // "Success"
|
|
||||||
i18n._("common.label.error") // "Error:"
|
|
||||||
i18n._("common.error.failed", map[string]any{"Action": "load"}) // "Failed to load"
|
|
||||||
```
|
|
||||||
|
|
||||||
### Compose: `T()` / `C()`
|
|
||||||
|
|
||||||
Semantic intent resolution. Takes an intent key from `core.*` namespace and returns a `Composed` result with multiple output forms.
|
|
||||||
|
|
||||||
```go
|
|
||||||
// Full form
|
|
||||||
result := i18n.T("core.delete", i18n.S("file", path))
|
|
||||||
result := i18n.C("core.delete", i18n.S("file", path)) // Alias
|
|
||||||
|
|
||||||
// Result contains all forms
|
|
||||||
result.Question // "Delete /path/to/file.txt?"
|
|
||||||
result.Confirm // "Really delete /path/to/file.txt?"
|
|
||||||
result.Success // "File deleted"
|
|
||||||
result.Failure // "Failed to delete file"
|
|
||||||
result.Meta // IntentMeta{Dangerous: true, Default: "no", ...}
|
|
||||||
```
|
|
||||||
|
|
||||||
### Subject: `S()` / `Subject()`
|
|
||||||
|
|
||||||
Creates a typed subject with optional metadata for grammar rules.
|
|
||||||
|
|
||||||
```go
|
|
||||||
// Simple
|
|
||||||
i18n.S("file", "/path/to/file.txt")
|
|
||||||
|
|
||||||
// With count (plurality)
|
|
||||||
i18n.S("commit", commits).Count(len(commits))
|
|
||||||
|
|
||||||
// With gender (for gendered languages)
|
|
||||||
i18n.S("user", name).Gender("female")
|
|
||||||
|
|
||||||
// Chained
|
|
||||||
i18n.S("file", path).Count(3).In("/project")
|
|
||||||
```
|
|
||||||
|
|
||||||
### Type Signatures
|
|
||||||
|
|
||||||
```go
|
|
||||||
// Simple lookup
|
|
||||||
func _(key string, args ...any) string
|
|
||||||
|
|
||||||
// Compose (T and C are aliases)
|
|
||||||
func T(intent string, subject *Subject) *Composed
|
|
||||||
func C(intent string, subject *Subject) *Composed
|
|
||||||
|
|
||||||
// Subject builder
|
|
||||||
func S(noun string, value any) *Subject
|
|
||||||
func Subject(noun string, value any) *Subject
|
|
||||||
|
|
||||||
// Composed result
|
|
||||||
type Composed struct {
|
|
||||||
Question string
|
|
||||||
Confirm string
|
|
||||||
Success string
|
|
||||||
Failure string
|
|
||||||
Meta IntentMeta
|
|
||||||
}
|
|
||||||
|
|
||||||
// Subject with metadata
|
|
||||||
type Subject struct {
|
|
||||||
Noun string
|
|
||||||
Value any
|
|
||||||
count int
|
|
||||||
gender string
|
|
||||||
// ... other metadata
|
|
||||||
}
|
|
||||||
|
|
||||||
func (s *Subject) Count(n int) *Subject
|
|
||||||
func (s *Subject) Gender(g string) *Subject
|
|
||||||
func (s *Subject) In(location string) *Subject
|
|
||||||
|
|
||||||
// Intent metadata
|
|
||||||
type IntentMeta struct {
|
|
||||||
Type string // "action", "question", "info"
|
|
||||||
Verb string // Reference to common.verb.*
|
|
||||||
Dangerous bool // Requires confirmation
|
|
||||||
Default string // "yes" or "no"
|
|
||||||
Supports []string // Extra options like "all", "skip"
|
|
||||||
}
|
|
||||||
```
|
|
||||||
|
|
||||||
## CLI Integration
|
|
||||||
|
|
||||||
The CLI package uses `T()` internally for prompts:
|
|
||||||
|
|
||||||
```go
|
|
||||||
// Confirm uses T() internally
|
|
||||||
confirmed := cli.Confirm("core.delete", i18n.S("file", path))
|
|
||||||
// Internally: result := i18n.T("core.delete", subject)
|
|
||||||
// Displays: result.Question + localized [y/N]
|
|
||||||
// Returns: bool
|
|
||||||
|
|
||||||
// Question with options
|
|
||||||
choice := cli.Question("core.save", i18n.S("changes", 3).Count(3), cli.Options{
|
|
||||||
Default: "yes",
|
|
||||||
Extra: []string{"all"},
|
|
||||||
})
|
|
||||||
// Displays: "Save 3 changes? [a/y/N]"
|
|
||||||
// Returns: "yes" | "no" | "all"
|
|
||||||
|
|
||||||
// Choice from list
|
|
||||||
selected := cli.Choose("core.select.branch", branches)
|
|
||||||
// Displays localized prompt with arrow selection
|
|
||||||
```
|
|
||||||
|
|
||||||
### cli.Confirm()
|
|
||||||
|
|
||||||
```go
|
|
||||||
func Confirm(intent string, subject *i18n.Subject, opts ...ConfirmOption) bool
|
|
||||||
|
|
||||||
// Options
|
|
||||||
cli.DefaultYes() // Default to yes instead of no
|
|
||||||
cli.DefaultNo() // Explicit default no
|
|
||||||
cli.Required() // No default, must choose
|
|
||||||
cli.Timeout(30*time.Second) // Auto-select default after timeout
|
|
||||||
```
|
|
||||||
|
|
||||||
### cli.Question()
|
|
||||||
|
|
||||||
```go
|
|
||||||
func Question(intent string, subject *i18n.Subject, opts ...QuestionOption) string
|
|
||||||
|
|
||||||
// Options
|
|
||||||
cli.Extra("all", "skip") // Extra options beyond y/n
|
|
||||||
cli.Default("yes") // Which option is default
|
|
||||||
cli.Validate(func(s string) bool) // Custom validation
|
|
||||||
```
|
|
||||||
|
|
||||||
### cli.Choose()
|
|
||||||
|
|
||||||
```go
|
|
||||||
func Choose[T any](intent string, items []T, opts ...ChooseOption) T
|
|
||||||
|
|
||||||
// Options
|
|
||||||
cli.Display(func(T) string) // How to display each item
|
|
||||||
cli.Filter() // Enable fuzzy filtering
|
|
||||||
cli.Multi() // Allow multiple selection
|
|
||||||
```
|
|
||||||
|
|
||||||
## Reserved Namespaces
|
|
||||||
|
|
||||||
### `common.*` - Reusable Fragments
|
|
||||||
|
|
||||||
Atomic translation units that can be composed:
|
|
||||||
|
|
||||||
```json
|
|
||||||
{
|
|
||||||
"common": {
|
|
||||||
"verb": {
|
|
||||||
"edit": "edit",
|
|
||||||
"delete": "delete",
|
|
||||||
"create": "create",
|
|
||||||
"save": "save",
|
|
||||||
"update": "update",
|
|
||||||
"commit": "commit"
|
|
||||||
},
|
|
||||||
"noun": {
|
|
||||||
"file": { "one": "file", "other": "files" },
|
|
||||||
"commit": { "one": "commit", "other": "commits" },
|
|
||||||
"change": { "one": "change", "other": "changes" }
|
|
||||||
},
|
|
||||||
"article": {
|
|
||||||
"the": "the",
|
|
||||||
"a": { "one": "a", "vowel": "an" }
|
|
||||||
},
|
|
||||||
"prompt": {
|
|
||||||
"yes": "y",
|
|
||||||
"no": "n",
|
|
||||||
"all": "a",
|
|
||||||
"skip": "s",
|
|
||||||
"quit": "q"
|
|
||||||
}
|
|
||||||
}
|
|
||||||
}
|
|
||||||
```
|
|
||||||
|
|
||||||
### `core.*` - Semantic Intents
|
|
||||||
|
|
||||||
Intents encode meaning and behavior:
|
|
||||||
|
|
||||||
```json
|
|
||||||
{
|
|
||||||
"core": {
|
|
||||||
"edit": {
|
|
||||||
"_meta": {
|
|
||||||
"type": "action",
|
|
||||||
"verb": "common.verb.edit",
|
|
||||||
"dangerous": false
|
|
||||||
},
|
|
||||||
"question": "Should I {{.Verb}} {{.Subject}}?",
|
|
||||||
"confirm": "{{.Verb | title}} {{.Subject}}?",
|
|
||||||
"success": "{{.Subject | title}} {{.Verb | past}}",
|
|
||||||
"failure": "Failed to {{.Verb}} {{.Subject}}"
|
|
||||||
},
|
|
||||||
"delete": {
|
|
||||||
"_meta": {
|
|
||||||
"type": "action",
|
|
||||||
"verb": "common.verb.delete",
|
|
||||||
"dangerous": true,
|
|
||||||
"default": "no"
|
|
||||||
},
|
|
||||||
"question": "Delete {{.Subject}}? This cannot be undone.",
|
|
||||||
"confirm": "Really delete {{.Subject}}?",
|
|
||||||
"success": "{{.Subject | title}} deleted",
|
|
||||||
"failure": "Failed to delete {{.Subject}}"
|
|
||||||
},
|
|
||||||
"save": {
|
|
||||||
"_meta": {
|
|
||||||
"type": "action",
|
|
||||||
"verb": "common.verb.save",
|
|
||||||
"supports": ["all", "skip"]
|
|
||||||
},
|
|
||||||
"question": "Save {{.Subject}}?",
|
|
||||||
"success": "{{.Subject | title}} saved"
|
|
||||||
},
|
|
||||||
"commit": {
|
|
||||||
"_meta": {
|
|
||||||
"type": "action",
|
|
||||||
"verb": "common.verb.commit",
|
|
||||||
"dangerous": false
|
|
||||||
},
|
|
||||||
"question": "Commit {{.Subject}}?",
|
|
||||||
"success": "{{.Subject | title}} committed",
|
|
||||||
"failure": "Failed to commit {{.Subject}}"
|
|
||||||
}
|
|
||||||
}
|
|
||||||
}
|
|
||||||
```
|
|
||||||
|
|
||||||
## Template Functions
|
|
||||||
|
|
||||||
Available in translation templates:
|
|
||||||
|
|
||||||
| Function | Description | Example |
|
|
||||||
|----------|-------------|---------|
|
|
||||||
| `title` | Title case | `{{.Name \| title}}` → "Hello World" |
|
|
||||||
| `lower` | Lower case | `{{.Name \| lower}}` → "hello world" |
|
|
||||||
| `upper` | Upper case | `{{.Name \| upper}}` → "HELLO WORLD" |
|
|
||||||
| `past` | Past tense verb | `{{.Verb \| past}}` → "edited" |
|
|
||||||
| `plural` | Pluralize noun | `{{.Noun \| plural .Count}}` → "files" |
|
|
||||||
| `article` | Add article | `{{.Noun \| article}}` → "a file" |
|
|
||||||
| `quote` | Wrap in quotes | `{{.Path \| quote}}` → `"/path/to/file"` |
|
|
||||||
|
|
||||||
## Implementation Plan
|
|
||||||
|
|
||||||
### Phase 1: Foundation
|
|
||||||
1. Define `Composed` and `Subject` types
|
|
||||||
2. Add `S()` / `Subject()` builder
|
|
||||||
3. Add `T()` / `C()` with intent resolution
|
|
||||||
4. Parse `_meta` from JSON
|
|
||||||
5. Add template functions (title, lower, past, etc.)
|
|
||||||
|
|
||||||
### Phase 2: CLI Integration
|
|
||||||
1. Implement `cli.Confirm()` using intents
|
|
||||||
2. Implement `cli.Question()` with options
|
|
||||||
3. Implement `cli.Choose()` for lists
|
|
||||||
4. Localize prompt characters [y/N] → [j/N] etc.
|
|
||||||
|
|
||||||
### Phase 3: Grammar Engine
|
|
||||||
1. Verb conjugation (past tense, etc.)
|
|
||||||
2. Noun plurality with irregular forms
|
|
||||||
3. Article selection (a/an, gender)
|
|
||||||
4. Language-specific rules
|
|
||||||
|
|
||||||
### Phase 4: Extended Languages
|
|
||||||
1. Gender agreement (French, German, etc.)
|
|
||||||
2. Formality levels (Japanese, Korean, etc.)
|
|
||||||
3. Right-to-left support
|
|
||||||
4. Plural forms beyond one/other (Russian, Arabic, etc.)
|
|
||||||
|
|
||||||
## Example: Full Flow
|
|
||||||
|
|
||||||
```go
|
|
||||||
// In cmd/dev/dev_commit.go
|
|
||||||
path := "/Users/dev/project"
|
|
||||||
files := []string{"main.go", "config.yaml"}
|
|
||||||
|
|
||||||
// Old way (hardcoded English, manual prompt handling)
|
|
||||||
fmt.Printf("Commit %d files in %s? [y/N] ", len(files), path)
|
|
||||||
var response string
|
|
||||||
fmt.Scanln(&response)
|
|
||||||
if response != "y" && response != "Y" {
|
|
||||||
return
|
|
||||||
}
|
|
||||||
|
|
||||||
// New way (semantic, localized, integrated)
|
|
||||||
if !cli.Confirm("core.commit", i18n.S("file", path).Count(len(files))) {
|
|
||||||
return
|
|
||||||
}
|
|
||||||
|
|
||||||
// For German user, displays:
|
|
||||||
// "2 Dateien in /Users/dev/project committen? [j/N]"
|
|
||||||
// (note: "j" for "ja" instead of "y" for "yes")
|
|
||||||
```
|
|
||||||
|
|
||||||
## JSON Schema
|
|
||||||
|
|
||||||
```json
|
|
||||||
{
|
|
||||||
"$schema": "https://json-schema.org/draft/2020-12/schema",
|
|
||||||
"type": "object",
|
|
||||||
"properties": {
|
|
||||||
"common": {
|
|
||||||
"description": "Reusable translation fragments",
|
|
||||||
"type": "object"
|
|
||||||
},
|
|
||||||
"core": {
|
|
||||||
"description": "Semantic intents with metadata",
|
|
||||||
"type": "object",
|
|
||||||
"additionalProperties": {
|
|
||||||
"type": "object",
|
|
||||||
"properties": {
|
|
||||||
"_meta": {
|
|
||||||
"type": "object",
|
|
||||||
"properties": {
|
|
||||||
"type": { "enum": ["action", "question", "info"] },
|
|
||||||
"verb": { "type": "string" },
|
|
||||||
"dangerous": { "type": "boolean" },
|
|
||||||
"default": { "enum": ["yes", "no"] },
|
|
||||||
"supports": { "type": "array", "items": { "type": "string" } }
|
|
||||||
}
|
|
||||||
},
|
|
||||||
"question": { "type": "string" },
|
|
||||||
"confirm": { "type": "string" },
|
|
||||||
"success": { "type": "string" },
|
|
||||||
"failure": { "type": "string" }
|
|
||||||
}
|
|
||||||
}
|
|
||||||
}
|
|
||||||
}
|
|
||||||
}
|
|
||||||
```
|
|
||||||
|
|
||||||
## Grammar Fundamentals
|
|
||||||
|
|
||||||
Parts of speech we need to handle:
|
|
||||||
|
|
||||||
| Part | Role | Example | Transforms |
|
|
||||||
|------|------|---------|------------|
|
|
||||||
| **Verb** | Action | delete, save, commit | tense (past/present), mood (imperative) |
|
|
||||||
| **Noun** | Subject/Object | file, commit, user | plurality, gender, case |
|
|
||||||
| **Article** | Determiner | a/an, the | vowel-awareness, gender agreement |
|
|
||||||
| **Adjective** | Describes noun | modified, new, deleted | gender/number agreement |
|
|
||||||
| **Preposition** | Relation | in, from, to | - |
|
|
||||||
|
|
||||||
### Verb Conjugation
|
|
||||||
|
|
||||||
```json
|
|
||||||
{
|
|
||||||
"common": {
|
|
||||||
"verb": {
|
|
||||||
"delete": {
|
|
||||||
"base": "delete",
|
|
||||||
"past": "deleted",
|
|
||||||
"gerund": "deleting",
|
|
||||||
"imperative": "delete"
|
|
||||||
}
|
|
||||||
}
|
|
||||||
}
|
|
||||||
}
|
|
||||||
```
|
|
||||||
|
|
||||||
For most English verbs, derive automatically:
|
|
||||||
- `past`: base + "ed" (or irregular lookup)
|
|
||||||
- `gerund`: base + "ing"
|
|
||||||
|
|
||||||
### Noun Handling
|
|
||||||
|
|
||||||
```json
|
|
||||||
{
|
|
||||||
"common": {
|
|
||||||
"noun": {
|
|
||||||
"file": {
|
|
||||||
"one": "file",
|
|
||||||
"other": "files",
|
|
||||||
"gender": "neuter"
|
|
||||||
}
|
|
||||||
}
|
|
||||||
}
|
|
||||||
}
|
|
||||||
```
|
|
||||||
|
|
||||||
### Article Selection
|
|
||||||
|
|
||||||
English: a/an based on next word's sound (not letter)
|
|
||||||
- "a file", "an item", "a user", "an hour"
|
|
||||||
|
|
||||||
Other languages: gender agreement (der/die/das, le/la, etc.)
|
|
||||||
|
|
||||||
## DX Improvements
|
|
||||||
|
|
||||||
### 1. Compile-Time Validation
|
|
||||||
- `go generate` checks all `T("core.X")` calls have matching JSON keys
|
|
||||||
- Warns on missing `_meta` fields
|
|
||||||
- Type-checks template variables
|
|
||||||
|
|
||||||
### 2. IDE Support
|
|
||||||
- JSON schema for autocomplete in translation files
|
|
||||||
- Go constants generated from JSON keys: `i18n.CoreDelete` instead of `"core.delete"`
|
|
||||||
|
|
||||||
### 3. Fallback Chain
|
|
||||||
```
|
|
||||||
T("core.delete", subject)
|
|
||||||
→ try core.delete.question
|
|
||||||
→ try core.delete (plain string)
|
|
||||||
→ try common.action.delete
|
|
||||||
→ return "Delete {{.Subject}}?" (hardcoded fallback)
|
|
||||||
```
|
|
||||||
|
|
||||||
### 4. Debug Mode
|
|
||||||
```go
|
|
||||||
i18n.Debug(true) // Shows: [core.delete] Delete file.txt?
|
|
||||||
```
|
|
||||||
|
|
||||||
### 5. Short Subject Syntax
|
|
||||||
```go
|
|
||||||
// Instead of:
|
|
||||||
i18n.T("core.delete", i18n.S("file", path))
|
|
||||||
|
|
||||||
// Allow:
|
|
||||||
i18n.T("core.delete", path) // Infers subject type from intent's expected noun
|
|
||||||
```
|
|
||||||
|
|
||||||
### 6. Fluent Chaining
|
|
||||||
```go
|
|
||||||
i18n.T("core.delete").
|
|
||||||
Subject("file", path).
|
|
||||||
Count(3).
|
|
||||||
Question() // Returns just the question string
|
|
||||||
```
|
|
||||||
|
|
||||||
## Notes for Future Implementation
|
|
||||||
|
|
||||||
- Use `github.com/gertd/go-pluralize` for English plurality
|
|
||||||
- Consider `github.com/nicksnyder/go-i18n` patterns for CLDR plural rules
|
|
||||||
- Store compiled templates in sync.Map for caching
|
|
||||||
- `_meta` parsing happens once at load time, not per-call
|
|
||||||
- CLI prompt chars from `common.prompt.*` - allows `[j/N]` for German
|
|
||||||
|
|
||||||
## Open Questions
|
|
||||||
|
|
||||||
1. **Verb conjugation library** - Use existing Go library or build custom?
|
|
||||||
2. **Gender detection** - How to infer gender for subjects in gendered languages?
|
|
||||||
3. **Fallback behavior** - What happens when intent metadata is missing?
|
|
||||||
4. **Caching** - Should compiled templates be cached?
|
|
||||||
5. **Validation** - How to validate intent definitions at build time?
|
|
||||||
File diff suppressed because it is too large
Load diff
Loading…
Add table
Reference in a new issue