vouchington-tooling 0.29.0 → 0.30.0

package/dist/agent-harness-config/policy.mjs

@@ -1,51 +0,0 @@
-export const DEFAULT_EXTRA_WRITABLE_ROOTS = [
-    '~/.cargo',
-    '~/Library/pnpm',
-    '~/.local/share/pnpm',
-    '~/.pnpm-store',
-    '~/Library/Caches/no-mistakes',
-    '~/Library/Caches/pnpm',
-    '~/.pnpm-state',
-    '~/.cache/no-mistakes',
-    '~/.cache/pnpm',
-    '~/.local/state/pnpm',
-    '/var/folders',
-    '/private/var/folders',
-];
-export const CLAUDE_DEFAULT_MODE = 'auto';
-export const CODEX_APPROVAL_POLICY = 'on-request';
-export const CODEX_APPROVALS_REVIEWER = 'auto_review';
-export const CODEX_SANDBOX_MODE = 'workspace-write';
-export const GROK_PERMISSION_MODE = 'auto';
-export const GROK_SANDBOX_PROFILE = 'workspace-write';
-export const GROK_AUTO_MODE_ENABLED = true;
-export const GROK_DEFAULT_AUTO_MODE = true;
-export const CURSOR_APPROVAL_MODE = 'auto-review';
-export const CURSOR_SANDBOX_MODE = 'enabled';
-export function dumpHarnessPolicy(extraWritableRoots = DEFAULT_EXTRA_WRITABLE_ROOTS) {
-    return {
-        claude: {
-            defaultMode: CLAUDE_DEFAULT_MODE,
-            sandboxEnabled: true,
-            sandboxFailIfUnavailable: true,
-            useAutoModeDuringPlan: true,
-        },
-        codex: {
-            approval_policy: CODEX_APPROVAL_POLICY,
-            approvals_reviewer: CODEX_APPROVALS_REVIEWER,
-            sandbox_mode: CODEX_SANDBOX_MODE,
-        },
-        cursor: { approvalMode: CURSOR_APPROVAL_MODE, sandboxMode: CURSOR_SANDBOX_MODE },
-        extraWritableRoots: [...extraWritableRoots],
-        grok: {
-            auto_mode_enabled: GROK_AUTO_MODE_ENABLED,
-            default_auto_mode: GROK_DEFAULT_AUTO_MODE,
-            permission_mode: GROK_PERMISSION_MODE,
-            sandbox_profile_defined: GROK_SANDBOX_PROFILE,
-            sandbox_profile_requires_cli_selection: true,
-        },
-    };
-}
-export function sameValue(left, right) {
-    return JSON.stringify(left) === JSON.stringify(right);
-}

package/dist/agent-harness-config/prerequisites.d.mts

@@ -1,2 +0,0 @@
-import type { HarnessConfigOptions, HarnessPrerequisite } from './types.mts';
-export declare function checkHarnessPrerequisites(root: string | undefined, options?: HarnessConfigOptions): Promise<HarnessPrerequisite[]>;

package/dist/agent-harness-config/prerequisites.mjs

@@ -1,67 +0,0 @@
-import { readFile } from 'node:fs/promises';
-import { homedir } from 'node:os';
-import { join, resolve } from 'node:path';
-import { readTomlKey } from './merge-toml.mjs';
-import { CURSOR_APPROVAL_MODE } from './policy.mjs';
-import { HARNESS_IDS } from './types.mjs';
-async function readOptional(path) {
-    try {
-        return await readFile(path, 'utf8');
-    }
-    catch (error) {
-        if (error.code === 'ENOENT')
-            return '';
-        throw error;
-    }
-}
-function selected(options, harness) {
-    return (options?.harnesses ?? HARNESS_IDS).includes(harness);
-}
-function homeDir(options) {
-    return resolve(options?.home ?? homedir());
-}
-async function codexTrust(root, options) {
-    const source = await readOptional(join(homeDir(options), '.codex', 'config.toml'));
-    const table = `projects.${JSON.stringify(resolve(root))}`;
-    return {
-        harness: 'codex',
-        key: 'trusted-project',
-        message: 'trust this project in Codex before relying on its .codex/config.toml',
-        satisfied: readTomlKey(source, table, 'trust_level') === 'trusted',
-    };
-}
-async function cursorApproval(options) {
-    const source = await readOptional(join(homeDir(options), '.cursor', 'cli-config.json'));
-    let satisfied = false;
-    try {
-        const parsed = JSON.parse(source);
-        satisfied = parsed.approvalMode === CURSOR_APPROVAL_MODE;
-    }
-    catch {
-        // A missing or invalid user config leaves the prerequisite unsatisfied.
-    }
-    return {
-        harness: 'cursor',
-        key: 'global-auto-review',
-        message: 'set approvalMode=auto-review in ~/.cursor/cli-config.json',
-        satisfied,
-    };
-}
-function grokSandbox() {
-    return {
-        harness: 'grok',
-        key: 'sandbox-profile-selection',
-        message: 'start Grok with --sandbox workspace-write to activate the defined profile',
-        satisfied: false,
-    };
-}
-export async function checkHarnessPrerequisites(root, options) {
-    const prerequisites = [];
-    if (selected(options, 'grok'))
-        prerequisites.push(grokSandbox());
-    if (root !== undefined && selected(options, 'codex'))
-        prerequisites.push(await codexTrust(root, options));
-    if (root !== undefined && selected(options, 'cursor'))
-        prerequisites.push(await cursorApproval(options));
-    return prerequisites;
-}

package/dist/agent-harness-config/toml-value.d.mts

@@ -1,6 +0,0 @@
-import type { TomlValue } from './types.mts';
-export declare function formatTomlValue(value: TomlValue): string;
-export declare function parseTomlValue(text: string, start: number): {
-    end: number;
-    value: boolean | string | string[];
-};

package/dist/agent-harness-config/toml-value.mjs

@@ -1,69 +0,0 @@
-export function formatTomlValue(value) {
-    if (typeof value === 'boolean')
-        return value ? 'true' : 'false';
-    if (typeof value === 'string')
-        return JSON.stringify(value);
-    const items = value.map((entry) => `  ${JSON.stringify(entry)},`).join('\n');
-    return `[\n${items}\n]`;
-}
-function skipSpaceAndComments(text, start) {
-    let index = start;
-    while (index < text.length) {
-        const char = text[index];
-        if (char === ' ' || char === '\t' || char === '\n' || char === '\r' || char === ',') {
-            index += 1;
-            continue;
-        }
-        if (char === '#') {
-            while (index < text.length && text[index] !== '\n')
-                index += 1;
-            continue;
-        }
-        break;
-    }
-    return index;
-}
-function parseTomlString(text, start) {
-    const quote = text[start];
-    let index = start + 1;
-    let value = '';
-    while (index < text.length) {
-        const char = text[index];
-        if (char === quote)
-            return { end: index + 1, value };
-        if (quote === '"' && char === '\\') {
-            const next = text[index + 1];
-            if (next === undefined)
-                break;
-            value += next === 'n' ? '\n' : next === 't' ? '\t' : next;
-            index += 2;
-            continue;
-        }
-        value += char;
-        index += 1;
-    }
-    throw new Error('unterminated TOML string');
-}
-export function parseTomlValue(text, start) {
-    const index = skipSpaceAndComments(text, start);
-    if (text.startsWith('true', index))
-        return { end: index + 4, value: true };
-    if (text.startsWith('false', index))
-        return { end: index + 5, value: false };
-    if (text[index] === '"' || text[index] === "'")
-        return parseTomlString(text, index);
-    if (text[index] !== '[')
-        throw new Error('unsupported TOML value');
-    const items = [];
-    let cursor = index + 1;
-    for (;;) {
-        cursor = skipSpaceAndComments(text, cursor);
-        if (text[cursor] === ']')
-            return { end: cursor + 1, value: items };
-        if (text[cursor] !== '"' && text[cursor] !== "'")
-            throw new Error('unsupported TOML array value');
-        const parsed = parseTomlString(text, cursor);
-        items.push(parsed.value);
-        cursor = parsed.end;
-    }
-}

package/dist/agent-harness-config/types.d.mts

@@ -1,90 +0,0 @@
-import { HARNESS_IDS } from '../agent-harness-identity/index.mts';
-import type { HarnessId } from '../agent-harness-identity/index.mts';
-export { HARNESS_IDS };
-export type { HarnessId };
-export type ApplyTarget = {
-    readonly kind: 'global';
-} | {
-    readonly kind: 'repo';
-    readonly root: string;
-};
-export interface JsonPatch {
-    readonly merge?: 'union';
-    readonly path: readonly string[];
-    readonly value: unknown;
-}
-export type TomlValue = boolean | string | readonly string[];
-export interface TomlPatch {
-    readonly key: string;
-    readonly table: string;
-    readonly value: TomlValue;
-}
-export type FilePlan = {
-    readonly format: 'json';
-    readonly patches: readonly JsonPatch[];
-    readonly path: string;
-} | {
-    readonly format: 'toml';
-    readonly patches: readonly TomlPatch[];
-    readonly path: string;
-};
-export interface KeyDrift {
-    readonly current: unknown;
-    readonly desired: unknown;
-    readonly key: string;
-    readonly path: string;
-}
-export interface FileResult {
-    readonly action: 'create' | 'update' | 'ok' | 'missing';
-    readonly drifts: readonly KeyDrift[];
-    readonly path: string;
-}
-export interface HarnessPlan {
-    readonly files: readonly FilePlan[];
-    readonly target: ApplyTarget;
-}
-export interface HarnessCheckResult {
-    readonly compliant: boolean;
-    readonly files: readonly FileResult[];
-    readonly prerequisites: readonly HarnessPrerequisite[];
-    readonly target: ApplyTarget;
-}
-export interface HarnessPrerequisite {
-    readonly harness: HarnessId;
-    readonly key: string;
-    readonly message: string;
-    readonly satisfied: boolean;
-}
-export interface HarnessApplyResult extends HarnessCheckResult {
-    readonly written: readonly string[];
-}
-export interface HarnessConfigOptions {
-    readonly extraWritableRoots?: readonly string[];
-    readonly harnesses?: readonly HarnessId[];
-    readonly home?: string;
-}
-export interface HarnessPolicyDump {
-    readonly claude: {
-        readonly defaultMode: 'auto';
-        readonly sandboxEnabled: true;
-        readonly sandboxFailIfUnavailable: true;
-        readonly useAutoModeDuringPlan: true;
-    };
-    readonly codex: {
-        readonly approval_policy: 'on-request';
-        readonly approvals_reviewer: 'auto_review';
-        readonly sandbox_mode: 'workspace-write';
-    };
-    readonly cursor: {
-        readonly approvalMode: 'auto-review';
-        readonly sandboxMode: 'enabled';
-    };
-    readonly extraWritableRoots: readonly string[];
-    readonly grok: {
-        readonly auto_mode_enabled: true;
-        readonly default_auto_mode: true;
-        readonly permission_mode: 'auto';
-        readonly sandbox_profile_defined: 'workspace-write';
-        readonly sandbox_profile_requires_cli_selection: true;
-    };
-}

package/dist/agent-harness-config/types.mjs

@@ -1,2 +0,0 @@
-import { HARNESS_IDS } from '../agent-harness-identity/index.mjs';
-export { HARNESS_IDS };

package/docs/agent-harness-config.md

@@ -1,134 +0,0 @@
-# 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.