From 213a04a3b01bb6c63a2ea99f865109c871cdef07 Mon Sep 17 00:00:00 2001 From: Yuto Nishida Date: Sun, 4 Oct 2026 20:09:34 -0700 Subject: [PATCH] silverwood: configure CLI_SPEC manually --- experimental/silverwood/CLI_SPEC.jsonnet | 217 ++++++++++++----------- 1 file changed, 110 insertions(+), 107 deletions(-) diff --git a/experimental/silverwood/CLI_SPEC.jsonnet b/experimental/silverwood/CLI_SPEC.jsonnet index ed96cac..7f673e6 100644 --- a/experimental/silverwood/CLI_SPEC.jsonnet +++ b/experimental/silverwood/CLI_SPEC.jsonnet @@ -10,34 +10,31 @@ { name: "silverwood", - intentHint: "Expose the same persistent workstream and session state to humans and shell-driven frontends.", - generatedDescriptionHint: "Frontend-agnostic backend for code and agent workstreams.", + intentHint: "Frontend-agnostic backend for code and agent workstreams.", options: [ { longName: "forest", - generatedDescriptionHint: "Path to the forest; overrides the environment and home default.", + intentHint: "Path to the forest; precedence is this flag > SILVERWOOD_FOREST_PATH env var > $HOME/.silverwood", domain: { semanticName: "DIR", validation: "rustType:std::path::Path" }, }, - { longName: "json", generatedDescriptionHint: "Emit machine-readable JSON instead of human-readable text." }, + { longName: "json", intentHint: "Emit the output as machine-readable JSON." }, ], subcommands: { choices: [ - { name: "info", generatedDescriptionHint: "Open the forest and print its identity." }, + { name: "info", intentHint: "Print basic info about the forest." }, { name: "new", - intentHint: "Make the user choose a workstream kind and supply a human name.", - generatedDescriptionHint: "Create a workstream.", + intentHint: "Create a new workstream.", options: [ { longName: "name", generatedDescriptionHint: "Human-friendly workstream name.", domain: { semanticName: "NAME" } }, ], subcommands: { - intentHint: "Choose the kind of workstream to create.", + intentHint: "Specify the workstream kind.", generatedDescriptionHint: "Available workstream kinds.", choices: [ { name: "basic", - intentHint: "Make checkout timing and mode explicit before creating a managed code checkout.", - generatedDescriptionHint: "Create a basic workstream using a checkout mode.", + intentHint: "Create a basic workstream using a checkout mode.", options: [ { longName: "checkout-extent", @@ -47,43 +44,44 @@ }, ], subcommands: { + intentHint: "Specify the checkout mode.", choices: [ { name: "jj-colocated", - generatedDescriptionHint: "Clone an HTTPS Git endpoint with a colocated jj repository.", + intentHint: "Clone a git repo with a colocated jj repo.", positionals: [ { - generatedDescriptionHint: "HTTPS Git endpoint to clone.", + intentHint: "HTTPS git endpoint to clone.", domain: { semanticName: "SOURCE_HTTPS_URL", validation: "silverwoodFn:httpsGitUrl" }, }, ], }, { name: "jj-colocated-direnv-unsafe", - generatedDescriptionHint: "Clone with jj, then preapprove the checkout environment with direnv.", + intentHint: "Same as jj-colocated, then automatically approve the checkout's direnv.", positionals: [ { - generatedDescriptionHint: "HTTPS Git endpoint to clone.", + intentHint: "HTTPS git endpoint to clone.", domain: { semanticName: "SOURCE_HTTPS_URL", validation: "silverwoodFn:httpsGitUrl" }, }, ], }, { name: "apfs-cow", - generatedDescriptionHint: "Copy a local directory using APFS copy-on-write.", + intentHint: "Copy a local directory using APFS copy-on-write.", positionals: [ { - generatedDescriptionHint: "Absolute source directory to copy.", + intentHint: "Absolute path to copy.", domain: { semanticName: "ABSOLUTE_PATH", validation: "silverwoodFn:absolutePath" }, }, ], }, { name: "apfs-cow-direnv-unsafe", - generatedDescriptionHint: "Copy a local directory using APFS, then preapprove its environment.", + intentHint: "Same as apfs-cow, then automatically approve the copied-over direnv.", positionals: [ { - generatedDescriptionHint: "Absolute source directory to copy.", + intentHint: "Absolute path to copy.", domain: { semanticName: "ABSOLUTE_PATH", validation: "silverwoodFn:absolutePath" }, }, ], @@ -93,54 +91,53 @@ }, { name: "local-unmanaged-existing-path", - generatedDescriptionHint: "Adopt an existing directory without managing it.", + intentHint: "Adopt an existing path as a workstream. Its workstream lifecycle is unmanaged; do not delete the path.", positionals: [ { - generatedDescriptionHint: "Absolute path of the existing directory.", + intentHint: "Absolute path of the existing directory.", domain: { semanticName: "ABSOLUTE_PATH", validation: "silverwoodFn:absolutePath" }, }, ], }, - { name: "local-tmp", generatedDescriptionHint: "Create a fresh ephemeral directory under /tmp." }, - { name: "local-blank", generatedDescriptionHint: "Create a fresh empty directory inside the forest." }, + { name: "local-tmp", intentHint: "Create an ephemeral directory under /tmp." }, + { name: "local-blank", intentHint: "Create an empty directory inside the forest." }, ], }, }, { name: "ls", - generatedDescriptionHint: "List workstreams.", + intentHint: "List workstreams.", options: [ - { longName: "all", generatedDescriptionHint: "Include archived and deleted workstreams." }, + { longName: "all", intentHint: "Include all workstreams (eg. archived, deleted)." }, ], }, { name: "workstream", - intentHint: "Group actions that affect a specific workstream under its stable id.", - generatedDescriptionHint: "Operate on one workstream by id.", + intentHint: "Group actions that are associated with workstreams.", positionals: [ - { generatedDescriptionHint: "The workstream id.", domain: { semanticName: "ID", validation: "silverwoodFn:workstreamId" } }, + { intentHint: "The workstream id to operate on.", domain: { semanticName: "ID", validation: "silverwoodFn:workstreamId" } }, ], subcommands: { choices: [ - { name: "show", generatedDescriptionHint: "Show the workstream." }, - { name: "archive", generatedDescriptionHint: "Archive the workstream." }, + { name: "show", intentHint: "Print basic info about the workstream." }, + { name: "archive", intentHint: "Archive the workstream." }, { name: "remove", - generatedDescriptionHint: "Delete a managed workstream and its directory when safe.", + intentHint: "Delete the workstream.", options: [ - { longName: "force", generatedDescriptionHint: "Override the managed directory safety check." }, + { longName: "force", intentHint: "Override safety checks that gate a workstream's deletion." }, ], }, { name: "rename", - generatedDescriptionHint: "Rename the workstream.", + intentHint: "Rename the workstream.", positionals: [ { generatedDescriptionHint: "The new display name.", domain: { semanticName: "NAME" } }, ], }, { name: "basic", - generatedDescriptionHint: "Operations specific to a basic workstream.", + intentHint: "Operations specific to a basic workstream.", subcommands: { choices: [ { name: "checkout", generatedDescriptionHint: "Provision a deferred basic checkout." }, @@ -152,44 +149,43 @@ }, { name: "kv", - intentHint: "Allow frontends to persist their own per-workstream state without changing core schema.", - generatedDescriptionHint: "Read and write frontend-owned namespaced key-value state.", + intentHint: "Allow frontends to persist their own per-workstream state without changing the core schema.", subcommands: { choices: [ { name: "set", - generatedDescriptionHint: "Set a JSON string value.", + intentHint: "Set a value.", positionals: [ - { generatedDescriptionHint: "The workstream id.", domain: { semanticName: "ID", validation: "silverwoodFn:workstreamId" } }, - { generatedDescriptionHint: "Namespace to write.", domain: { semanticName: "NAMESPACE" } }, - { generatedDescriptionHint: "Key within the namespace.", domain: { semanticName: "KEY" } }, + { intentHint: "The workstream id.", domain: { semanticName: "ID", validation: "silverwoodFn:workstreamId" } }, + { intentHint: "Namespace to write.", domain: { semanticName: "NAMESPACE" } }, + { intentHint: "Key within the namespace.", domain: { semanticName: "KEY" } }, { generatedDescriptionHint: "Opaque JSON string value.", domain: { semanticName: "VALUE" } }, ], }, { name: "get", - generatedDescriptionHint: "Get one value.", + generatedDescriptionHint: "Get a value.", positionals: [ - { generatedDescriptionHint: "The workstream id.", domain: { semanticName: "ID", validation: "silverwoodFn:workstreamId" } }, - { generatedDescriptionHint: "Namespace containing the key.", domain: { semanticName: "NAMESPACE" } }, - { generatedDescriptionHint: "Key within the namespace.", domain: { semanticName: "KEY" } }, + { intentHint: "The workstream id.", domain: { semanticName: "ID", validation: "silverwoodFn:workstreamId" } }, + { intentHint: "Namespace to read.", domain: { semanticName: "NAMESPACE" } }, + { intentHint: "Key to read within the namespace.", domain: { semanticName: "KEY" } }, ], }, { name: "ls", - generatedDescriptionHint: "List every entry in a namespace.", + intentHint: "List entries in a namespace.", positionals: [ - { generatedDescriptionHint: "The workstream id.", domain: { semanticName: "ID", validation: "silverwoodFn:workstreamId" } }, - { generatedDescriptionHint: "Namespace to list.", domain: { semanticName: "NAMESPACE" } }, + { intentHint: "The workstream id.", domain: { semanticName: "ID", validation: "silverwoodFn:workstreamId" } }, + { intentHint: "Namespace to list.", domain: { semanticName: "NAMESPACE" } }, ], }, { name: "unset", - generatedDescriptionHint: "Remove one value.", + intentHint: "Remove a value.", positionals: [ - { generatedDescriptionHint: "The workstream id.", domain: { semanticName: "ID", validation: "silverwoodFn:workstreamId" } }, - { generatedDescriptionHint: "Namespace containing the key.", domain: { semanticName: "NAMESPACE" } }, - { generatedDescriptionHint: "Key to remove.", domain: { semanticName: "KEY" } }, + { intentHint: "The workstream id.", domain: { semanticName: "ID", validation: "silverwoodFn:workstreamId" } }, + { intentHint: "Namespace containing the key.", domain: { semanticName: "NAMESPACE" } }, + { intentHint: "Key to remove.", domain: { semanticName: "KEY" } }, ], }, ], @@ -197,73 +193,77 @@ }, { name: "session", - intentHint: "Treat agent and shell sessions as durable records associated with a workstream.", - generatedDescriptionHint: "Manage sessions attached to workstreams.", + intentHint: "Manage agent and shell sessions. Sessions are records attached to workstreams.", subcommands: { choices: [ { name: "create", - generatedDescriptionHint: "Create a session of a chosen kind.", + intentHint: "Create a session of a chosen kind.", subcommands: { + intentHint: "Specify the session kind.", choices: [ { name: "claude-code", + intentHint: "A claude-code session. Managed externally by claude-code.", generatedDescriptionHint: "Record a Claude Code session.", options: [ - { longName: "name", generatedDescriptionHint: "Display name; defaults to the session id.", domain: { semanticName: "NAME" } }, + { longName: "name", intentHint: "Display name; defaults to the session id.", domain: { semanticName: "NAME" } }, ], positionals: [ - { generatedDescriptionHint: "The workstream id.", domain: { semanticName: "ID", validation: "silverwoodFn:workstreamId" } }, - { generatedDescriptionHint: "The session id.", domain: { semanticName: "SESSION_ID" } }, + { intentHint: "The workstream id.", domain: { semanticName: "ID", validation: "silverwoodFn:workstreamId" } }, + { intentHint: "The session id.", domain: { semanticName: "SESSION_ID" } }, ], }, { name: "codex", + intentHint: "A codex session. Managed externally by codex.", generatedDescriptionHint: "Start Codex and register its generated session id.", options: [ - { longName: "name", generatedDescriptionHint: "Display name; defaults to the generated id.", domain: { semanticName: "NAME" } }, + { longName: "name", intentHint: "Display name; defaults to the generated id.", domain: { semanticName: "NAME" } }, ], positionals: [ - { generatedDescriptionHint: "The workstream id.", domain: { semanticName: "ID", validation: "silverwoodFn:workstreamId" } }, + { intentHint: "The workstream id.", domain: { semanticName: "ID", validation: "silverwoodFn:workstreamId" } }, ], }, { name: "plain-shell", - generatedDescriptionHint: "Record a plain login shell session.", + intentHint: "A plain shell session. Does not hold any state; shell output and history is ephemeral.", options: [ - { longName: "name", generatedDescriptionHint: "Display name; defaults to the session id.", domain: { semanticName: "NAME" } }, + { longName: "name", intentHint: "Display name; defaults to the session id.", domain: { semanticName: "NAME" } }, ], positionals: [ - { generatedDescriptionHint: "The workstream id.", domain: { semanticName: "ID", validation: "silverwoodFn:workstreamId" } }, - { generatedDescriptionHint: "The session id.", domain: { semanticName: "SESSION_ID" } }, + { intentHint: "The workstream id.", domain: { semanticName: "ID", validation: "silverwoodFn:workstreamId" } }, + { intentHint: "The session id.", domain: { semanticName: "SESSION_ID" } }, ], }, { name: "claude-code-noninteractiveshell", + intentHint: "Similar to 'claude-code', but the session is ran directly, not inside an interactive shell.", generatedDescriptionHint: "Record a Claude Code session run without an interactive shell.", options: [ - { longName: "name", generatedDescriptionHint: "Display name; defaults to the session id.", domain: { semanticName: "NAME" } }, + { longName: "name", intentHint: "Display name; defaults to the session id.", domain: { semanticName: "NAME" } }, { longName: "run-direnv-exec", - generatedDescriptionHint: "Whether to run claude under direnv exec; supply true or false.", + intentHint: "Whether to run direnv exec.", domain: { semanticName: "RUN_DIRENV_EXEC", extensionalDef: ["true", "false"] }, required: true, }, ], positionals: [ - { generatedDescriptionHint: "The workstream id.", domain: { semanticName: "ID", validation: "silverwoodFn:workstreamId" } }, - { generatedDescriptionHint: "The session id.", domain: { semanticName: "SESSION_ID" } }, + { intentHint: "The workstream id.", domain: { semanticName: "ID", validation: "silverwoodFn:workstreamId" } }, + { intentHint: "The session id.", domain: { semanticName: "SESSION_ID" } }, ], }, { name: "disk-space", + intentHint: "Show disk space usage.", generatedDescriptionHint: "Record a disk-space monitor session.", options: [ - { longName: "name", generatedDescriptionHint: "Display name; defaults to the session id.", domain: { semanticName: "NAME" } }, + { longName: "name", intentHint: "Display name; defaults to the session id.", domain: { semanticName: "NAME" } }, ], positionals: [ - { generatedDescriptionHint: "The workstream id.", domain: { semanticName: "ID", validation: "silverwoodFn:workstreamId" } }, - { generatedDescriptionHint: "The session id.", domain: { semanticName: "SESSION_ID" } }, + { intentHint: "The workstream id.", domain: { semanticName: "ID", validation: "silverwoodFn:workstreamId" } }, + { intentHint: "The session id.", domain: { semanticName: "SESSION_ID" } }, ], }, ], @@ -271,63 +271,64 @@ }, { name: "ls", - generatedDescriptionHint: "List sessions on a workstream.", + intentHint: "List sessions on a workstream.", positionals: [ - { generatedDescriptionHint: "The workstream id.", domain: { semanticName: "ID", validation: "silverwoodFn:workstreamId" } }, + { intentHint: "The workstream id.", domain: { semanticName: "ID", validation: "silverwoodFn:workstreamId" } }, ], }, { name: "rename", - generatedDescriptionHint: "Rename one session.", + intentHint: "Rename a session.", positionals: [ - { generatedDescriptionHint: "The workstream id.", domain: { semanticName: "ID", validation: "silverwoodFn:workstreamId" } }, - { generatedDescriptionHint: "The session id.", domain: { semanticName: "SESSION_ID" } }, - { generatedDescriptionHint: "The new display name.", domain: { semanticName: "NAME" } }, + { intentHint: "The workstream id.", domain: { semanticName: "ID", validation: "silverwoodFn:workstreamId" } }, + { intentHint: "The session id.", domain: { semanticName: "SESSION_ID" } }, + { intentHint: "The new display name.", domain: { semanticName: "NAME" } }, ], }, { name: "rm", - generatedDescriptionHint: "Remove one session.", + intentHint: "Remove a session.", positionals: [ - { generatedDescriptionHint: "The workstream id.", domain: { semanticName: "ID", validation: "silverwoodFn:workstreamId" } }, - { generatedDescriptionHint: "The session id.", domain: { semanticName: "SESSION_ID" } }, + { intentHint: "The workstream id.", domain: { semanticName: "ID", validation: "silverwoodFn:workstreamId" } }, + { intentHint: "The session id.", domain: { semanticName: "SESSION_ID" } }, ], }, { name: "lock", - generatedDescriptionHint: "Acquire a session advisory lock.", + intentHint: "Acquire a session lock.", options: [ { longName: "holder", - generatedDescriptionHint: "Opaque token identifying the lock holder.", + intentHint: "Opaque token identifying the lock holder.", domain: { semanticName: "HOLDER" }, required: true, }, - { longName: "force", generatedDescriptionHint: "Steal an existing lock." }, + { longName: "force", intentHint: "Steal an existing lock." }, ], positionals: [ - { generatedDescriptionHint: "The workstream id.", domain: { semanticName: "ID", validation: "silverwoodFn:workstreamId" } }, - { generatedDescriptionHint: "The session id.", domain: { semanticName: "SESSION_ID" } }, + { intentHint: "The workstream id.", domain: { semanticName: "ID", validation: "silverwoodFn:workstreamId" } }, + { intentHint: "The session id.", domain: { semanticName: "SESSION_ID" } }, ], }, { name: "unlock", - generatedDescriptionHint: "Release a session advisory lock.", + intentHint: "Release a session lock.", options: [ - { longName: "holder", generatedDescriptionHint: "Only release a lock held by this token.", domain: { semanticName: "HOLDER" } }, - { longName: "force", generatedDescriptionHint: "Release regardless of current holder." }, + // TODO: should `holder` be required? + { longName: "holder", intentHint: "Only release a lock held by this token.", domain: { semanticName: "HOLDER" } }, + { longName: "force", intentHint: "Release regardless of current holder." }, ], positionals: [ - { generatedDescriptionHint: "The workstream id.", domain: { semanticName: "ID", validation: "silverwoodFn:workstreamId" } }, - { generatedDescriptionHint: "The session id.", domain: { semanticName: "SESSION_ID" } }, + { intentHint: "The workstream id.", domain: { semanticName: "ID", validation: "silverwoodFn:workstreamId" } }, + { intentHint: "The session id.", domain: { semanticName: "SESSION_ID" } }, ], }, { name: "doctor", generatedDescriptionHint: "Report the health of a recorded session.", positionals: [ - { generatedDescriptionHint: "The workstream id.", domain: { semanticName: "ID", validation: "silverwoodFn:workstreamId" } }, - { generatedDescriptionHint: "The session id.", domain: { semanticName: "SESSION_ID" } }, + { intentHint: "The workstream id.", domain: { semanticName: "ID", validation: "silverwoodFn:workstreamId" } }, + { intentHint: "The session id.", domain: { semanticName: "SESSION_ID" } }, ], }, ], @@ -335,20 +336,22 @@ }, { name: "upgrade-forest", - generatedDescriptionHint: "Upgrade every document to the latest schema version.", + intentHint: "Upgrade every document to the latest schema version.", options: [ - { longName: "dry-run", generatedDescriptionHint: "Report what would change without writing." }, + // TODO: dry-run should be the default + { longName: "dry-run", intentHint: "Report what would change without writing." }, ], }, - { name: "new-schema", generatedDescriptionHint: "Describe the new subcommand tree for frontends." }, - { name: "session-schema", generatedDescriptionHint: "Describe session creation kinds for frontends." }, + { name: "new-schema", intentHint: "Describe the new subcommand tree for frontends." }, + { name: "session-schema", intentHint: "Describe session creation kinds for frontends." }, { name: "spawn", - intentHint: "Launch a recorded or direct session in the intended working directory; --json reveals the plan.", - generatedDescriptionHint: "Run a session, or inspect its shell plan with --json.", + intentHint: "Low-level helper for launching a session's environment.", + generatedDescriptionHint: "Run a session in the intended working directory, or inspect its shell plan with --json.", subcommands: { choices: [ { + // TODO: move this to be under the `session` subcommand name: "from-id", generatedDescriptionHint: "Run a recorded session in its workstream checkout.", options: [ @@ -365,29 +368,29 @@ }, { name: "plain-shell", - generatedDescriptionHint: "Run a plain interactive login shell.", + intentHint: "Launch a plain interactive shell.", options: [ { longName: "override-working-directory", - generatedDescriptionHint: "Working directory to run in (default: this process's own cwd).", + intentHint: "Working directory to run in. Default: this process's own cwd.", domain: { semanticName: "PATH", validation: "rustType:std::path::Path" }, }, ], }, { name: "disk-space", - generatedDescriptionHint: "Run a disk-space monitor.", + intentHint: "Launch a disk-space monitor.", options: [ { longName: "override-working-directory", - generatedDescriptionHint: "Working directory to run in (default: this process's own cwd).", + intentHint: "Working directory to run in. Default: this process's own cwd.", domain: { semanticName: "PATH", validation: "rustType:std::path::Path" }, }, ], }, { name: "claude-code", - generatedDescriptionHint: "Run a Claude Code session.", + intentHint: "Launch claude-code as if a human ran it from the command line.", subcommands: { choices: [ { @@ -396,7 +399,7 @@ options: [ { longName: "override-working-directory", - generatedDescriptionHint: "Working directory to run in (default: this process's own cwd).", + intentHint: "Working directory to run in. Default: this process's own cwd.", domain: { semanticName: "PATH", validation: "rustType:std::path::Path" }, }, ], @@ -410,7 +413,7 @@ options: [ { longName: "override-working-directory", - generatedDescriptionHint: "Working directory to run in (default: this process's own cwd).", + intentHint: "Working directory to run in. Default: this process's own cwd.", domain: { semanticName: "PATH", validation: "rustType:std::path::Path" }, }, ], @@ -423,11 +426,11 @@ }, { name: "claude-code-noninteractiveshell", - generatedDescriptionHint: "Run Claude Code without an interactive shell.", + intentHint: "Launch the claude-code CLI directly.", options: [ { longName: "run-direnv-exec", - generatedDescriptionHint: "Whether to run claude under direnv exec; supply true or false.", + intentHint: "Whether to run direnv exec.", domain: { semanticName: "RUN_DIRENV_EXEC", extensionalDef: ["true", "false"] }, required: true, }, @@ -440,7 +443,7 @@ options: [ { longName: "override-working-directory", - generatedDescriptionHint: "Working directory to run in (default: this process's own cwd).", + intentHint: "Working directory to run in. Default: this process's own cwd.", domain: { semanticName: "PATH", validation: "rustType:std::path::Path" }, }, ], @@ -454,7 +457,7 @@ options: [ { longName: "override-working-directory", - generatedDescriptionHint: "Working directory to run in (default: this process's own cwd).", + intentHint: "Working directory to run in. Default: this process's own cwd.", domain: { semanticName: "PATH", validation: "rustType:std::path::Path" }, }, ], -- 2.51.2