@praxis/auditor-cli

Shared guard runtime for Praxis shell policy: argv parsing (shell-quote), evaluateShellProposal / evaluateArgv / gateShellCommand, JSONL audit append, and the shell approval bridge under .cursor/guard/bridge.

Single entry: auditor

Use one built binary for MCP stdio, Cursor hook, and diagnostics:

| Surface | Command | |--------|---------| | MCP (mcp.json) | auditor + args ["mcp"], or node …/auditor-cli/dist/cli.js mcp | | Hook (.cursor/hooks.json) | node …/auditor-cli/dist/cli.js hook before-shell (or auditor hook before-shell if auditor is on PATH) |

@praxis/guard-mcp remains as a thin shim (dist/server.js → @praxis/auditor-cli/mcp) for older configs that still point at guard-mcp.

Policy source of truth

Classification rules live in @praxis/auditor-policy (loadPoliciesV1, classifyArgv, policies.v1.json via the path resolved from the built policy package). This package re-exports loadPoliciesV1 for convenience; hooks may still import classifyArgv from @praxis/auditor-policy when they need hook-specific tier handling.

Bridge directory contract

One-shot approvals for terminal execution use:

• Directory: path.resolve(cwd, ".cursor/guard/bridge")
• Files: ${sha256(JSON.stringify(argv))}_${uuid}.json with TTL 10 minutes (DEFAULT_SHELL_BRIDGE_TTL_MS).

Do not change this layout without updating Cursor + MCP flows that rely on it.

Python packages/auditor

The legacy Python guard under packages/auditor/ remains for existing installs; new work should target @praxis/auditor-cli and Node-based tooling. Long-term migration: shell aliases or install scripts pointing at the auditor binary (npx / workspace) instead of python3 guard.py (see AUDITOR_CLI_SOLUTION_PLAN.md).

CLI (auditor binary)

After pnpm -C packages/auditor-cli build, the auditor command is available from this package (package.json bin).

| Command | Purpose | |--------|---------| | auditor mcp | MCP stdio server (registers tool guard). Use in Cursor mcp.json as the server command. | | auditor hook before-shell | Cursor hook: stdin JSON { "command", "cwd?" } → stdout JSON { "permission", ... } (fail-closed on crash). | | auditor doctor | Prints resolved policy path, bridge dir, audit log path, Node version, and PRAXIS_GUARD_AUDIT_LOG status. | | auditor whoami | Prints uid, profile email/display name, and token source via the guardWhoAmI callable (requires auth like policies sync). | | auditor version | Package version plus git rev-parse --short HEAD when run inside a git checkout. | | auditor help | Usage summary. |

From the repo root: pnpm exec auditor doctor / pnpm exec auditor mcp (after pnpm -C packages/auditor-cli build), or node packages/auditor-cli/dist/cli.js ….