vouchington-tooling 0.11.0 → 0.11.2

package/docs/agent-harness-config.md

@@ -0,0 +1,134 @@
+# Agent harness config
+
+`vouchington agent-harness-config` merges a portable **classifier-auto + sandbox**
+policy into Claude, Codex, Grok, and Cursor config files. It does not copy
+allowlists, hooks, plugins, MCP servers, or models.
+
+Use it to keep local interactive sessions on a permission classifier (routine
+work proceeds, risky calls still prompt) with an OS sandbox enabled.
+
+## Classifier vs always-approve
+
+Always-approve / YOLO is not the same as classifier auto. Cursor
+`unrestricted` also forces the sandbox off.
+
+| Harness | Classifier (this tool writes)                                             | Do not use                                        | Sandbox                                                            |
+| ------- | ------------------------------------------------------------------------- | ------------------------------------------------- | ------------------------------------------------------------------ |
+| Claude  | `permissions.defaultMode = "auto"`                                        | `bypassPermissions`                               | `sandbox.enabled = true`, fail closed if unavailable               |
+| Codex   | `approval_policy = "on-request"` and `approvals_reviewer = "auto_review"` | `approval_policy = "never"`                       | `sandbox_mode = "workspace-write"` plus extra writable roots       |
+| Grok    | `ui.permission_mode = "auto"`                                             | `always-approve` / `bypassPermissions` / `--yolo` | defines `workspace-write`; invoke with `--sandbox workspace-write` |
+| Cursor  | `approvalMode = "auto-review"`                                            | `unrestricted` (`--force` / `--yolo`)             | `sandbox.mode = "enabled"`                                         |
+
+Grok Auto is a separate mode from plan. Shift+Tab is `Normal → Plan → Auto
+(when enabled) → Always-approve`. The tool also writes `auto_mode.enabled =
+true` and `default_auto_mode = true` so Auto is available by default and
+stays the permission classifier under plan mode. Plan-file edits remain
+auto-approved; other file edits stay blocked. That is not YOLO.
+
+Repo Claude settings set `sandbox.enabled` and `sandbox.failIfUnavailable`.
+They do not change a
+project `permissions.defaultMode` of `"plan"`.
+
+Grok config can define a sandbox profile but cannot activate it for a future
+session. Start Grok with `--sandbox workspace-write`; `check` reports this as
+an unmet manual prerequisite so it never claims the profile is active.
+
+## CLI
+
+```bash
+vouchington agent-harness-config dump
+vouchington agent-harness-config check --global
+vouchington agent-harness-config check --repo /path/to/checkout
+vouchington agent-harness-config apply --global --repo /path --repo /other
+vouchington agent-harness-config apply --global --harness grok --harness cursor
+```
+
+- `dump` prints the canonical key map as JSON. It does not need `--global` or `--repo`.
+- `check` and `apply` require at least one of `--global` or `--repo` (repeatable).
+- `--harness` filters to `claude`, `codex`, `grok`, or `cursor`. Default is all four.
+- `--home` overrides the user home directory (tests and nonstandard layouts).
+- `check` exits `0` when every targeted file and prerequisite matches, `1` on drift or an unmet prerequisite, and `2` on usage errors.
+- `apply` writes only drifted keys, then exits `1` when a prerequisite remains unmet and `2` on I/O or usage errors.
+
+## Library
+
+```ts
+import {
+  applyHarnessConfig,
+  checkHarnessConfig,
+  dumpHarnessPolicy,
+  planHarnessConfig,
+} from 'vouchington-tooling/agent-harness-config'
+
+const dump = dumpHarnessPolicy()
+await checkHarnessConfig({ kind: 'global' }, { home: '/tmp/isolated-home' })
+await applyHarnessConfig({ kind: 'repo', root: '/path/to/checkout' }, { harnesses: ['grok'] })
+```
+
+Pass `home` in options so tests never touch the real `~/.claude` or `~/.cursor`.
+`extraWritableRoots` replaces the shipped toolchain cache list.
+
+## Files
+
+Global (`--global`, under `$HOME` or `--home`):
+
+| File                      | Keys                                                                                               |
+| ------------------------- | -------------------------------------------------------------------------------------------------- |
+| `.claude/settings.json`   | `permissions.defaultMode`, `sandbox.enabled`, `sandbox.failIfUnavailable`, `useAutoModeDuringPlan` |
+| `.codex/config.toml`      | `approval_policy`, `approvals_reviewer`, `sandbox_mode`, `[sandbox_workspace_write]`               |
+| `.grok/sandbox.toml`      | `[profiles.workspace-write]` extra roots (written first)                                           |
+| `.grok/config.toml`       | `ui.permission_mode`, `auto_mode.enabled`, `default_auto_mode`                                     |
+| `.cursor/cli-config.json` | `approvalMode`, `sandbox.mode`                                                                     |
+
+The Grok profile is selected per invocation with `--sandbox workspace-write`.
+
+Repo (`--repo`):
+
+| File                    | Keys                                                                            |
+| ----------------------- | ------------------------------------------------------------------------------- |
+| `.claude/settings.json` | `sandbox.enabled`, `sandbox.failIfUnavailable`, `sandbox.filesystem.allowWrite` |
+| `.codex/config.toml`    | same Codex keys as global                                                       |
+| `.grok/sandbox.toml`    | extra roots only (project config cannot set the default profile)                |
+| `.cursor/sandbox.json`  | `workspace_readwrite` extra roots and `networkPolicy.default = allow`           |
+
+Repo-local classifier settings have user-level prerequisites:
+
+- Codex loads `.codex/config.toml` only after the absolute checkout path has
+  `trust_level = "trusted"` in `~/.codex/config.toml`. This command checks that
+  entry but never creates or changes it.
+- Cursor approval mode belongs in `~/.cursor/cli-config.json`; the repo command
+  checks for global `auto-review` and intentionally leaves `.cursor/cli.json`
+  untouched.
+- Grok sandbox activation is per invocation as described above.
+
+These scope boundaries follow the current vendor references for
+[Claude sandboxing](https://code.claude.com/docs/en/sandboxing),
+[Codex project config](https://developers.openai.com/codex/config-reference),
+[Grok settings](https://docs.x.ai/build/settings),
+[Grok permissions](https://docs.x.ai/build/features/permissions),
+[Cursor CLI config](https://prod.cursor.com/docs/cli/reference/configuration), and
+[Cursor repo sandbox config](https://prod.cursor.com/docs/reference/sandbox).
+
+Missing files are created with only these keys. Sibling keys are preserved.
+JSON is pretty-printed with a trailing newline. TOML upserts named keys
+without rewriting unrelated tables such as `[[marketplace.sources]]` or
+`[projects."…"]`.
+
+## Extra writable roots
+
+The default list is toolchain caches, not product paths:
+
+- `~/.cargo`
+- `~/Library/pnpm`, `~/.local/share/pnpm`, `~/.pnpm-store`
+- `~/Library/Caches/pnpm`, `~/.cache/pnpm`
+- `~/.pnpm-state`, `~/.local/state/pnpm`
+- `~/Library/Caches/no-mistakes`, `~/.cache/no-mistakes`
+- `/var/folders`, `/private/var/folders`
+
+Replace the list through `extraWritableRoots` when a checkout needs different roots.
+
+## Out of scope
+
+The tool does not copy permission allow/deny lists, `sandbox.excludedCommands`,
+hooks, plugins, MCP servers, or model settings. Those stay in each checkout
+or user config.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "vouchington-tooling",
-  "version": "0.11.0",
+  "version": "0.11.2",
   "description": "Vouchington CLI and extractable tooling libraries.",
   "homepage": "https://github.com/vouchington/vouchington-tooling/tree/main/packages/vouchington-tooling#readme",
   "bugs": {
@@ -19,6 +19,7 @@
   "files": [
     "ast-grep",
     "dist",
+    "docs",
     "skills",
     "scripts",
     "README.md"
@@ -102,6 +103,11 @@
       "import": "./dist/ast-grep-pack/index.mjs",
       "default": "./dist/ast-grep-pack/index.mjs"
     },
+    "./agent-harness-config": {
+      "types": "./dist/agent-harness-config/index.d.mts",
+      "import": "./dist/agent-harness-config/index.mjs",
+      "default": "./dist/agent-harness-config/index.mjs"
+    },
     "./vitest-blob-manifest": {
       "types": "./dist/vitest-blob-manifest/index.d.mts",
       "import": "./dist/vitest-blob-manifest/index.mjs",
@@ -287,6 +293,7 @@
     "csv-stringify": "6.8.3",
     "dockerfile-ast": "0.7.1",
     "picomatch": "4.0.7",
+    "smol-toml": "1.8.0",
     "yaml": "2.9.0"
   },
   "devDependencies": {

package/dist/cli/commands/post-review.d.mts

@@ -1 +0,0 @@
-export declare function runPostReviewCommand(): Promise<number>;

package/dist/cli/commands/post-review.mjs

@@ -1,4 +0,0 @@
-import { runPostReviewCli } from '../../gha-post-review/cli.mjs';
-export function runPostReviewCommand() {
-    return runPostReviewCli();
-}

package/dist/cli/commands/stage-review-payload.d.mts

@@ -1 +0,0 @@
-export declare function runStageReviewPayloadCommand(args: readonly string[]): number;

package/dist/cli/commands/stage-review-payload.mjs

@@ -1,4 +0,0 @@
-import { runStageReviewPayloadCli } from '../../gha-review-payload/cli.mjs';
-export function runStageReviewPayloadCommand(args) {
-    return runStageReviewPayloadCli(args);
-}

package/dist/cli/commands/swift-semantic-equal.d.mts

@@ -1 +0,0 @@
-export declare function runSwiftSemanticEqualCommand(args: readonly string[]): number;

package/dist/cli/commands/swift-semantic-equal.mjs

@@ -1,4 +0,0 @@
-import { runSwiftSemanticEqualCli } from '../../swift-semantic-equal/cli.mjs';
-export function runSwiftSemanticEqualCommand(args) {
-    return runSwiftSemanticEqualCli(args);
-}