release(cli): ship 0.2.0 command surface

Author: PatrickJS

AGENTS.md

@@ -11,7 +11,11 @@ that runs directory-backed project and user-global commands.
 - Preserve command directories as the move unit.
 - Keep `script` valid as a command segment; only `script.{ts,mts,js,mjs}` files
   make a command directory runnable.
-- Do not add shell entrypoints, completions, trust prompts, or MCP mode in v1.
+- v0.2 ships completions, the overlay trust model, `--edit`/`--rm`, templates,
+  the `cli-cwd` pragma, `--doctor`, MCP server mode, and command packs; keep
+  their contracts aligned with `SPEC.md`.
+- Do not add non-JavaScript entrypoints (`.sh`, `.py`) or a hosted pack
+  registry.
 - Do not move or delete `../cli (1)/SPEC.md`; it is source material outside this
   package.
 

API_SURFACE.md

@@ -16,13 +16,25 @@
 
 ```js
 import {
+  addPack,
+  complete,
+  completionScript,
   copyCommand,
   createCommand,
   discoverRoots,
   listCommands,
+  localOverlayTrust,
   moveCommand,
+  overlayTrustState,
+  recordOverlayTrust,
+  removeCommand,
+  removeOverlayTrust,
   resolveCommand,
-  runCommand
+  runCommand,
+  runDoctor,
+  runMcpServer,
+  trustLocalOverlays,
+  untrustLocalOverlays
 } from "@async/cli";
 ```
 
@@ -43,12 +55,20 @@ and shadowed scripts.
 
 ### `runCommand(options, args)`
 
-Executes the resolved script with inherited stdio by default, caller cwd,
-forwarded arguments, and `CLI_*` environment values.
+Executes the resolved script with inherited stdio by default, forwarded
+arguments, and `CLI_*` environment values. The working directory follows the
+script's `// cli-cwd:` pragma (caller by default). Local-overlay scripts are
+refused with exit 3 unless the overlay is trusted.
 
 ### `createCommand(options, commandPath)`
 
-Creates a command directory with a default `script.ts`.
+Creates a command directory with a default `script.ts`, or copies
+`_templates/<name>/` when `options.template` is set.
+
+### `removeCommand(options, commandPath)`
+
+Removes a whole command directory from the nearest local overlay (or the root
+tree) and prunes empty parents. Nested commands require `options.force`.
 
 ### `copyCommand(options, commandPath)`
 
@@ -59,3 +79,32 @@ when a script imports through `../`.
 
 Moves a whole command directory between local and user-global roots and warns
 when a script imports through `../`.
+
+### `addPack(options, source)`
+
+Shallow-clones a Git source and installs its `.cli/` command directories into
+the root or local tree, optionally under `options.prefix`, refusing conflicts
+unless `options.force`.
+
+### Trust
+
+`trustLocalOverlays`, `untrustLocalOverlays`, `localOverlayTrust`,
+`overlayTrustState`, `recordOverlayTrust`, `removeOverlayTrust`,
+`ensureOverlayTrusted`, `hashOverlayTree`, `isTrustEnforced`, and
+`trustStorePath` manage the content-hash trust store kept in `.trust.json`
+under the user-global root. `ASYNC_CLI_TRUST=off` disables enforcement.
+
+### `runDoctor(options)` / `renderDoctorReport(report)`
+
+Audits all command roots and returns `{ version, problems, summary }` with
+error, warning, and info findings.
+
+### `complete(options, words)` / `completionScript(shell)`
+
+Next-segment command completion and the bash, zsh, and fish completion
+scripts that call it.
+
+### `runMcpServer(options, io)`
+
+Serves the command tree as MCP tools over newline-delimited JSON-RPC stdio.
+Untrusted local overlays are excluded from listing and refused at call time.

CHANGELOG.md

@@ -1,5 +1,33 @@
 # Changelog
 
+## 0.2.0 - 2026-07-06
+
+- Adds a direnv-style trust model for repo-local overlays: `cli --trust`,
+  `cli --untrust`, `cli --trust --status`, content-hash validation, exit 3 on
+  untrusted or changed overlays, and `ASYNC_CLI_TRUST=off` for controlled
+  environments. CLI mutations (`--new`, `--cp/--mv --to local`,
+  `--add --to local`) record or refresh trust for the target overlay.
+- Adds shell completions: `cli --completions bash|zsh|fish` and the hidden
+  `cli --complete` helper that completes command segments and built-in flags.
+- Adds `cli --edit <cmd...>` to open the resolved script in `$VISUAL`/`$EDITOR`
+  and `cli --rm <cmd...> [--root] [--force]` with nested-command protection
+  and empty-parent pruning.
+- Adds `--new --template <name>`, copying command templates from
+  `_templates/` in any command root, nearest-local first.
+- Adds the `// cli-cwd: caller|project-root|script-dir` pragma plus a
+  `CLI_CALLER_CWD` environment value for scripts.
+- Adds `cli --doctor [--json]`: audits ambiguous script directories, escaping
+  imports, empty command directories, trust state, descriptions, shadowing,
+  and managed context-block drift.
+- Adds `cli --mcp`, a zero-dependency MCP stdio server that exposes the
+  command tree as tools (`gh pull` becomes `gh__pull`), excluding untrusted
+  local overlays.
+- Adds command packs: `cli --add <git-url> [--to root|local]
+  [--prefix <name>] [--force]` installs `.cli/` trees from any Git source.
+- Exports `removeCommand`, `addPack`, `runDoctor`, `complete`,
+  `completionScript`, `runMcpServer`, and the trust helpers from the root
+  export.
+
 ## 0.1.2 - 2026-07-02
 
 - Adds `cli --cp <command...> [--to root|local]` and `copyCommand()` for

README.md

@@ -14,10 +14,12 @@ maps to a command directory like:
 .cli/gh/pull/script.ts
 ```
 
-The v1 contract is defined in `SPEC.md`. The package implements local and
-user-global command discovery, command resolution, script execution,
-machine-readable listing, `--which`, `--new`, `--mv`, context-file pointers,
-help, command copy, and version output.
+The contract is defined in `SPEC.md`. The package implements local and
+user-global command discovery, command resolution, script execution with a
+trust model for local overlays, machine-readable listing, `--which`, command
+scaffolding with templates, command copy/move/remove, `--edit`, command packs
+via `--add`, shell completions, a tree doctor, an MCP server mode,
+context-file pointers, help, and version output.
 
 ## Install
 
@@ -52,24 +54,80 @@ cli --list --json
 cli --which gh pull
 cli --new gh pr
 cli --new gh pr --root
+cli --new gh pr --template worker
+cli --edit gh pull
+cli --rm gh pull
 cli --cp gh pull
 cli --cp gh pull --to local
 cli --mv gh pull
 cli --mv gh pull --to local
+cli --add https://example.com/org/pack.git
+cli --trust
+cli --trust --status
+cli --untrust
+cli --doctor
+cli --completions bash
+cli --mcp
 cli --agents
 cli --agents --write
 cli --agents --check
 cli --agents --claude --write
 cli --version
 ```
 
-Command scripts run from the caller's original working directory. `.js` and
-`.mjs` scripts run directly with Node; `.ts` and `.mts` scripts use Node 24
-native type stripping.
+Command scripts run from the caller's original working directory by default;
+a `// cli-cwd: project-root` or `// cli-cwd: script-dir` head comment changes
+that per script. `.js` and `.mjs` scripts run directly with Node; `.ts` and
+`.mts` scripts use Node 24 native type stripping.
 
 Use `--cp` to clone a command directory between local and user-global command
 trees without removing the source. Use `--mv` when the source should be
-transferred instead.
+transferred instead, and `--rm` to delete a command directory.
+
+## Trust
+
+Repo-local `.cli/` overlays are refused at execution time until you trust
+them, because cloned repositories can shadow your user-global commands:
+
+```sh
+cli --trust           # trust the local overlays discovered from here
+cli --trust --status  # trusted | changed | untrusted per overlay
+cli --untrust         # revoke
+```
+
+Trust records a content hash of the overlay; any change requires re-trusting.
+Listing and `--which` never require trust. Set `ASYNC_CLI_TRUST=off` to
+disable enforcement in controlled environments.
+
+## Completions
+
+```sh
+eval "$(cli --completions bash)"   # or zsh
+cli --completions fish | source    # fish
+```
+
+## Doctor
+
+`cli --doctor [--json]` audits every command root: ambiguous script
+directories, `../` imports that break `--cp`/`--mv`, empty command
+directories, untrusted overlays, missing descriptions, shadowed commands, and
+stale `--agents` pointer blocks.
+
+## MCP
+
+`cli --mcp` serves the command tree as MCP tools over stdio (JSON-RPC 2.0,
+zero dependencies), so agent runtimes can discover and call the same commands
+humans use. Untrusted local overlays are excluded.
+
+## Packs
+
+Install commands from any Git repository that carries a `.cli/` tree:
+
+```sh
+cli --add https://example.com/org/pack.git             # into ~/.cli
+cli --add https://example.com/org/pack.git --prefix vendor
+cli --add https://example.com/org/pack.git --to local  # into this repo
+```
 
 ## Development