@neurodock/cli 0.2.0 → 0.6.0

package/CHANGELOG.md

@@ -1,6 +1,203 @@
 # @neurodock/cli changelog
 
-## 0.2.0 (unreleased)
+## 0.6.0
+
+### Added — `neurodock install-hooks` (proactive guardrails Phases 1 + 3)
+
+One command wires NeuroDock's proactive-guardrail layer into a fresh
+install. Bundled self-contained Python scripts ship with the npm
+package — no extra `pip install` step.
+
+```sh
+neurodock install-hooks --self-test
+neurodock install-hooks --install-daemon --self-test
+neurodock install-hooks --uninstall
+neurodock install-hooks --dry-run
+```
+
+The command:
+
+1. Copies `proactive_guardrail.py` to `~/.neurodock/hooks/` (Phase 1
+   Claude Code hook; auto-fires chronometric / rumination /
+   sycophancy checks on every Nth tool use, banners on stderr).
+2. Copies `neurodock_daemon.py` to the same dir (Phase 3 host-agnostic
+   poller; same heuristics, native OS notifications).
+3. Idempotently merges 4 entries into `~/.claude/settings.json`
+   (`SessionStart`, `PreToolUse`, `PostToolUse`, `Stop`), preserving
+   any existing hooks from other tools.
+4. With `--install-daemon`, registers the daemon at user-login
+   autostart: HKCU Run on Windows, LaunchAgent on macOS, systemd
+   `--user` unit on Linux.
+5. With `--self-test`, runs both scripts' built-in smoke test to
+   verify Python is on PATH and the heuristics fire.
+
+**Opt-out:**
+
+```sh
+neurodock install-hooks --uninstall        # removes hook + daemon entries
+export NEURODOCK_GUARDRAILS=off            # disables without removing
+```
+
+### Fixed — Windows path-escape lockout (regression-pinned)
+
+Pre-0.6.0 the hook command written into `settings.json` used
+backslashes on Windows. Bash-style shells (Git Bash / MinGW — what
+Claude Code uses for hooks on Windows) interpret `\U`, `\h`, `\p`
+etc. as escape sequences and strip them, mangling the path to
+`pythonscript.py` and causing every PreToolUse hook to fail, which
+**blocks every tool call** until the user manually edits
+`settings.json`. The 0.0.22 install command hit this. Twice.
+
+0.6.0 always normalises the script path to forward slashes (Python
+accepts them on Windows) and always wraps it in double quotes. The
+new install summary also echoes the exact hook command string so the
+bug class can't recur silently.
+
+Regression test: `packages/cli/tests/install-hooks.test.ts` pins the
+contract — the test fails if any hook entry contains a backslash in
+its script-path portion.
+
+### Internals
+
+- New build step `scripts/copy-assets.mjs` copies `src/assets/` into
+  `dist/assets/` after `tsc`, so the published npm tarball contains
+  the bundled Python scripts.
+- `package.json` `files` array already includes `dist/`, so no
+  manifest change needed.
+
+## 0.5.0
+
+### Changed (breaking)
+
+- `neurodock update` now upgrades NeuroDock to the latest version
+  (re-installs the six MCP servers via `pip install --upgrade` or
+  `uv tool install` and re-wires clients). Previously, `update` only
+  re-shaped client config JSON without touching package versions —
+  which confused users who expected `update` to behave like every
+  other CLI's `update` verb.
+- The previous behavior moved to a new verb: `neurodock sync`. Same
+  flags (`--client`, `--dry-run`), same code path, same semantics.
+- The new `update` command accepts the same flags as `install-all`
+  (`--client`, `--profile`, `--installer`, `--skip-install`, `--yes`,
+  `--dry-run`, `--no-native-host`).
+
+### Added
+
+- README now has a dedicated `## Update` section documenting the
+  one-liner: `npx --yes @neurodock/cli update`.
+
+### Migration
+
+If you scripted against `neurodock update --client X --dry-run` to
+reconcile client configs, rename the call to `neurodock sync` — the
+old flags still work there. If you wanted package upgrades, the new
+`neurodock update` is what you were looking for.
+
+## 0.4.3
+
+### Changed
+
+- `homepage` in `package.json` now points at https://neurodock.org/
+  (was the GitHub README anchor). Repository link unchanged. Adds
+  `bugs`, `keywords`, and richer `description` for the npm listing.
+- README rewritten to lead with the new slogan ("A cognitive substrate
+  that remembers, paces, and refuses"), reference NeuroDock by brand
+  rather than as an internal monorepo, and add a Links section with
+  the canonical home / docs / repo / issues / changelog URLs.
+
+No behaviour change. Same surface as 0.4.2.
+
+## 0.4.2
+
+### Fixed
+
+- `neurodock init` now wires all FIVE MCP servers into the MCP-aware
+  client config, not just three. Previously chronometric +
+  cognitive-graph + task-fractionator got registered but translation
+  - guardrail were skipped — so users saw 3/5 servers in Claude even
+    after a clean `install-all` + restart. The pip install registered
+    the entrypoints; the CLI just wasn't pointing the client at them.
+    `mcp-entries.ts` `NEURODOCK_SERVERS` list extended with the missing
+    two. `examples` and `install-all` already iterated all five, so no
+    changes there.
+
+## 0.4.1
+
+### Changed
+
+- `neurodock install-all` now also registers the optional native-messaging
+  host at the end of the run (previously a separate `neurodock host install`
+  step). Brings first-time install to truly one command: pip-install the
+  six MCP servers, wire the MCP-aware clients, and register the host the
+  browser extension uses to read `~/.neurodock/profile.yaml`.
+- New `--no-native-host` flag on `install-all` for users who don't want the
+  browser-extension bridge wired (e.g. headless / server installs).
+- Host-install failure is non-fatal: the whole command stays exit 0, prints
+  a `[warn]` line, and tells the user they can re-run `neurodock host install`
+  later. Rationale: the host is only useful if the user also installs the
+  browser extension, so failing the entire first-time install over it is
+  worse UX than warning.
+- Added a "What this just did" three-bullet recap at the end of `install-all`
+  so the user can see what was wired without re-reading the full log.
+- New tests in `tests/install-all.test.ts`: happy-path host install,
+  `--no-native-host` skip, host-failure warn-but-don't-fail.
+
+## 0.4.0
+
+### Added
+
+- `neurodock plugin` command group for managing plugins under
+  `~/.neurodock/plugins/` per ADR 0007. Six subcommands:
+  - `plugin add <source>` — install a plugin from a local directory.
+    Validates `plugin.yaml` against `plugin.schema.json` before copying
+    into `~/.neurodock/plugins/<name>/`. Flags: `--yes`, `--dry-run`,
+    `--force`. Exit codes: 0 ok, 1 source invalid, 2 already-installed
+    without `--force`, 3 schema validation failure.
+  - `plugin remove <name>` (alias: `uninstall`) — remove an installed
+    plugin. Flags: `--yes`, `--dry-run`.
+  - `plugin list` — list installed plugins with their enabled state.
+    `--json` for machine-readable output.
+  - `plugin enable <name>` — activate an installed plugin by writing a
+    `.enabled` marker file into the plugin directory. The substrate's
+    filesystem walk (per ADR 0007) treats marker presence as the
+    single source of truth for activation; no central registry file
+    is maintained.
+  - `plugin disable <name>` — remove the `.enabled` marker without
+    deleting the plugin files.
+  - `plugin validate <source>` — schema-validate a plugin manifest
+    without installing. `--json` flag for scripting. Exit codes: 0
+    valid, 1 invalid, 2 `plugin.yaml` missing.
+- New tests: `tests/plugin-add.test.ts`, `tests/plugin-remove.test.ts`,
+  `tests/plugin-list.test.ts`, `tests/plugin-enable.test.ts`,
+  `tests/plugin-disable.test.ts`, `tests/plugin-validate.test.ts`.
+- `pluginsDir(env)` helper in `lib/paths.ts` resolves to
+  `<profileDir>/plugins/` so tests that set `NEURODOCK_PROFILE_PATH`
+  get an isolated plugin tree for free.
+
+## 0.3.0
+
+### Added
+
+- `neurodock install-all` — single-command first-time install. Detects
+  whether `uv` is on PATH (preferred) and falls back to `python -m pip`,
+  then installs the six Python MCP servers (`neurodock-mcp-chronometric`,
+  `neurodock-mcp-cognitive-graph`, `neurodock-mcp-task-fractionator`,
+  `neurodock-mcp-translation`, `neurodock-mcp-guardrail`,
+  `neurodock-evals`), verifies each entrypoint is on PATH with
+  `<command> --help`, and runs `neurodock init` to wire MCP clients —
+  collapsing six `pip install` lines plus an `init` into one command.
+  Flags: `--client`, `--profile`, `--installer <uv|pip|auto>`,
+  `--skip-install`, `--yes`, `--dry-run`. Exit codes: 0 on success,
+  1 if any entrypoint is missing from PATH, 2 if init fails.
+- `neurodock examples` — copy-pasteable prompt cheat-sheet that exercises
+  every wired NeuroDock MCP tool. Detects which servers are wired across
+  all detected client configs and prints 2–3 example prompts per server,
+  each annotated with the underlying tool name. Flags: `--server <name>`
+  to filter, `--json` for scripting. Honors `NO_COLOR` / `FORCE_COLOR`
+  via the existing `colorEnabled()` helper.
+- New tests: `tests/install-all.test.ts`, `tests/examples.test.ts`.
+
+## 0.2.0
 
 ### Added
 

package/README.md

@@ -1,14 +1,17 @@
 # @neurodock/cli
 
-The `neurodock` installer and diagnostic CLI.
+The `neurodock` installer and diagnostic CLI for [NeuroDock](https://neurodock.org/) — a local-first cognitive substrate for neurodivergent professionals.
 
-Status: Phase 1 (v0.1 developer preview).
+Status: **v0.6.0**.
 
 ## Quickstart
 
 ```bash
-# From a published package once it lands on npm:
-npx neurodock init
+# From a published package:
+npx --yes @neurodock/cli@latest install-all
+
+# Or step-by-step, also from npm:
+npx --yes @neurodock/cli@latest init
 
 # From a fresh clone of the monorepo:
 pnpm install
@@ -16,24 +19,56 @@ pnpm --filter @neurodock/cli build
 node packages/cli/dist/index.js init
 ```
 
-`neurodock init` wires three Python MCP servers (chronometric, cognitive-graph,
-task-fractionator) into every MCP-aware client it can detect.
+`neurodock init` wires five Python MCP servers (chronometric,
+cognitive-graph, task-fractionator, translation, guardrail) into every
+MCP-aware client it can detect. A sixth, the optional native messaging
+host, is wired separately via `neurodock host install`.
 
-**Prerequisite:** the CLI does not install Python deps for you. From a clone
-run `uv sync` (or `pip install -e packages/mcp-chronometric` etc.) so the
-`neurodock-mcp-*` console entry points are on `$PATH` for `uv run`. From a
-published install this matures into `uv tool install neurodock-mcp-*`.
+**Prerequisite:** the CLI does not install Python deps for you unless you
+use `install-all`. From a clone run `uv sync` (or
+`pip install -e packages/mcp-chronometric` etc.) so the
+`neurodock-mcp-*` console entry points are on `$PATH`. From a published
+install, `install-all` runs the `pip install` step automatically.
 
 ## Commands
 
-| Command | What it does |
-|---|---|
-| `neurodock init` | Install MCP servers into Claude Desktop / Claude Code / Cursor. |
-| `neurodock doctor` | Diagnose your install — profile validity, client wiring, tool availability. |
-| `neurodock profile validate` | Validate `~/.neurodock/profile.yaml` against the v0.1 schema. |
-| `neurodock profile show` | Print the resolved profile with loader defaults applied. |
-| `neurodock host install` | Register the optional native messaging host so the browser extension can read `~/.neurodock/profile.yaml` directly. |
-| `neurodock host uninstall` | Remove all NeuroDock native-host manifests and registry pointers. |
+| Command                      | What it does                                                                                                               |
+| ---------------------------- | -------------------------------------------------------------------------------------------------------------------------- |
+| `neurodock install-all`      | One-command first-time install: pip-install the six servers, wire every detected client, copy the starter profile.         |
+| `neurodock init`             | Install MCP servers into Claude Desktop / Claude Code / Cursor (the wiring half of `install-all`).                         |
+| `neurodock doctor`           | Diagnose your install — profile validity, client wiring, tool availability.                                                |
+| `neurodock validate`         | Schema-validate a profile file (`~/.neurodock/profile.yaml` by default).                                                   |
+| `neurodock update`           | Upgrade NeuroDock to the latest version — re-installs the six MCP servers via pip/uv and re-wires client configs.          |
+| `neurodock sync`             | Re-shape stale NeuroDock MCP entries in existing client configs. No package upgrade. Non-NeuroDock entries are preserved.  |
+| `neurodock uninstall`        | Reverse `init` — remove NeuroDock MCP entries from each client config. Optionally purge `~/.neurodock/`.                   |
+| `neurodock examples`         | Print a copy-pasteable prompt cheat-sheet that exercises every wired NeuroDock MCP tool.                                   |
+| `neurodock host install`     | Register the optional Chrome Native Messaging host so the browser extension can read `~/.neurodock/profile.yaml` directly. |
+| `neurodock host uninstall`   | Remove all NeuroDock native-host manifests and registry pointers.                                                          |
+| `neurodock profile show`     | Print the resolved profile with loader defaults applied.                                                                   |
+| `neurodock profile validate` | Validate `~/.neurodock/profile.yaml` against the v0.1 schema.                                                              |
+| `neurodock plugin add`       | Install a plugin from a local directory into `~/.neurodock/plugins/`.                                                      |
+| `neurodock plugin remove`    | Uninstall a plugin (alias: `plugin uninstall`).                                                                            |
+| `neurodock plugin list`      | List installed plugins and their enabled state. `--json` for scripting.                                                    |
+| `neurodock plugin enable`    | Activate an installed plugin (writes a `.enabled` marker file).                                                            |
+| `neurodock plugin disable`   | Deactivate an installed plugin without deleting its files.                                                                 |
+| `neurodock plugin validate`  | Schema-validate a plugin manifest without installing.                                                                      |
+
+### `neurodock install-all`
+
+```
+neurodock install-all [--client=claude-desktop|claude-code|cursor|all] \
+                      [--profile=minimal|example] \
+                      [--installer=uv|pip|auto] \
+                      [--skip-install] [--yes] [--dry-run]
+```
+
+Single-command first-time install. Prefers `uv` if it is on PATH; falls
+back to `python -m pip`. After install, verifies each server entrypoint
+is on PATH with `<command> --help`, then delegates to `init` to wire
+clients.
+
+Exit codes: `0` ok, `1` an entrypoint is missing from PATH after
+install, `2` init failed.
 
 ### `neurodock init`
 
@@ -52,21 +87,74 @@ What `init` does, in order:
 
 1. Detects supported clients per platform (see "Detection locations" below).
 2. Copies `profile.example.yaml` or `profile.minimal.yaml` to `~/.neurodock/profile.yaml` if it does not already exist. Sets `identity.display_name` from `$USER` / `%USERNAME%`.
-3. Adds three `mcpServers` entries (`neurodock-chronometric`, `neurodock-cognitive-graph`, `neurodock-task-fractionator`) to each detected client's config.
+3. Adds `mcpServers` entries for each NeuroDock server to each detected client's config.
 4. Preserves all unrelated keys, comments, and unknown server entries already in those configs.
 
 Idempotent. Re-running with no changes is a no-op. Collisions on a previous
 key are skipped unless `--yes` is supplied.
 
+### `neurodock update`
+
+```
+neurodock update [--client=claude-desktop|claude-code|cursor|all] \
+                 [--profile=minimal|example] \
+                 [--installer=uv|pip|auto] \
+                 [--skip-install] [--yes] [--dry-run] [--no-native-host]
+```
+
+One-command upgrade. Same code path as `install-all` — re-runs
+`pip install --upgrade` (or `uv tool install`) for every NeuroDock MCP
+server, re-wires the detected MCP clients, and re-registers the
+optional native-messaging host. Exit codes match `install-all`:
+`0` ok, `1` an entrypoint is missing from PATH, `2` init failed.
+
+### `neurodock sync`
+
+```
+neurodock sync [--client <id>] [--dry-run]
+```
+
+Re-shape stale NeuroDock MCP entries in existing client configs
+(version drift, command/args/cwd changes) without upgrading any
+packages. Non-NeuroDock entries round-trip untouched. Useful when the
+desired wiring shape changed but you don't need a package upgrade.
+
+Before 0.5.0 this lived under `neurodock update`. The verb moved
+because users typed `neurodock update` expecting a version upgrade.
+
+### `neurodock validate` / `uninstall`
+
+```
+neurodock validate [--file <path>] [--strict]
+neurodock uninstall [--client <id>] [--yes] [--purge] [--dry-run]
+```
+
+`validate` runs Ajv against `profile.schema.json` and reports field-path
+violations. `uninstall` removes NeuroDock entries from every detected
+client config; asks (interactively) whether to delete
+`~/.neurodock/profile.yaml` and `~/.neurodock/cognitive-graph.sqlite`
+(default: no). `--purge` deletes those without prompting.
+
+### `neurodock examples`
+
+```
+neurodock examples [--server <name>] [--json]
+```
+
+Detects which NeuroDock servers are wired across all detected client
+configs and prints 2–3 example prompts per server, each annotated with
+the underlying tool name. `--server` filters to one server; `--json`
+emits machine-readable output. Honors `NO_COLOR` / `FORCE_COLOR`.
+
 ### Detection locations
 
-| Client | Platform | Path |
-|---|---|---|
-| Claude Desktop | macOS | `~/Library/Application Support/Claude/claude_desktop_config.json` |
-| Claude Desktop | Windows | `%APPDATA%\Claude\claude_desktop_config.json` |
-| Claude Desktop | Linux | `~/.config/Claude/claude_desktop_config.json` |
-| Claude Code | All | `./.claude/settings.json` (project, preferred) then `~/.claude/settings.json` (user) |
-| Cursor | All | `./.cursor/mcp.json` (project, preferred) then `~/.cursor/mcp.json` (user) |
+| Client         | Platform | Path                                                                                 |
+| -------------- | -------- | ------------------------------------------------------------------------------------ |
+| Claude Desktop | macOS    | `~/Library/Application Support/Claude/claude_desktop_config.json`                    |
+| Claude Desktop | Windows  | `%APPDATA%\Claude\claude_desktop_config.json`                                        |
+| Claude Desktop | Linux    | `~/.config/Claude/claude_desktop_config.json`                                        |
+| Claude Code    | All      | `./.claude/settings.json` (project, preferred) then `~/.claude/settings.json` (user) |
+| Cursor         | All      | `./.cursor/mcp.json` (project, preferred) then `~/.cursor/mcp.json` (user)           |
 
 ### `neurodock host install` / `uninstall`
 
@@ -88,6 +176,36 @@ is a placeholder.
 The host is OPTIONAL. The extension keeps working without it — the
 popup just shows `Profile sync: extension-local`.
 
+### `neurodock profile show` / `validate`
+
+```
+neurodock profile show
+neurodock profile validate [--file <path>]
+```
+
+`show` prints the resolved profile with loader defaults applied (per
+ADR 0004 §15). `validate` runs Ajv against the profile schema.
+
+### `neurodock plugin` group
+
+```
+neurodock plugin add <source> [--yes] [--dry-run] [--force]
+neurodock plugin remove <name> [--yes] [--dry-run]
+neurodock plugin list [--json]
+neurodock plugin enable <name>
+neurodock plugin disable <name>
+neurodock plugin validate <source> [--json]
+```
+
+`add` validates `plugin.yaml` against `plugin.schema.json` before copying
+into `~/.neurodock/plugins/<name>/`. Enablement is tracked via a
+`.enabled` marker file inside each plugin directory — the substrate's
+filesystem walk treats marker presence as the single source of truth
+(per ADR 0007).
+
+Exit codes for `add`: `0` ok, `1` source invalid, `2` already installed
+without `--force`, `3` schema validation failure.
+
 ### Profile precedence
 
 Loader precedence (highest first):
@@ -116,7 +234,17 @@ node dist/index.js --help
 - All loader defaults live in `src/profile/defaults.ts` and mirror
   `profile.schema.json` — JSON Schema validation does not apply defaults
   itself, so the loader does.
-- No telemetry, no remote calls, no auto-install of Python packages.
+- No telemetry, no remote calls. `install-all` is the only command that
+  shells out to a package manager, and it does so only when invoked.
+
+## Links
+
+- **Home:** [neurodock.org](https://neurodock.org/)
+- **Documentation:** [docs.neurodock.org](https://docs.neurodock.org/)
+- **Repository:** [github.com/tlennon-ie/neurodock](https://github.com/tlennon-ie/neurodock) (monorepo; this package lives at `packages/cli/`)
+- **Issues:** [github.com/tlennon-ie/neurodock/issues](https://github.com/tlennon-ie/neurodock/issues)
+- **Changelog:** [`packages/cli/CHANGELOG.md`](https://github.com/tlennon-ie/neurodock/blob/main/packages/cli/CHANGELOG.md)
+- **Manifesto + ethics:** [`MANIFESTO.md`](https://github.com/tlennon-ie/neurodock/blob/main/MANIFESTO.md), [`ETHICS.md`](https://github.com/tlennon-ie/neurodock/blob/main/ETHICS.md)
 
 ## License