@pugi/cli 0.1.0-beta.36 → 0.1.0-beta.37

package/dist/core/mcp/orchestrator-tools.js

@@ -29,10 +29,11 @@
  *   - PUGI_MCP_PUBLISH_ENABLED=1  — enables `pugi.publish`
  *   - PUGI_MCP_DEPLOY_ENABLED=1   — enables `pugi.deploy`
  *
- * `pugi.read` / `pugi.write` / `pugi.dispatch` do not require an env
- * gate (read+write enforce workspace + protected-path containment;
- * dispatch only sends prompts to the operator's already-authenticated
- * Anvil session). All three still pass through the MCP-server
+ * `pugi.read` / `pugi.write` do not require an env gate (read+write
+ * enforce workspace + protected-path containment). `pugi.dispatch`
+ * uses PUGI_MCP_EXEC_ENABLED (shared with `pugi.run`) because it
+ * shells the local `pugi` binary to drive the full engine loop
+ * client-side. All three still pass through the MCP-server
  * permissionGate, so an operator running `pugi mcp serve` without
  * `--allow-write` still sees `pugi.write` refused at dispatch.
  */
@@ -130,9 +131,15 @@ export function resolveWorkspacePathOrThrow(ctx, requested) {
  * specific `pugi.run` call via the per-tool prompt without restarting
  * the server.
  */
+/**
+ * Allowed dispatch subcommands. Mirror of the `command` enum in the
+ * admin-api `EngineRequestDto` (apps/admin-api/src/pugi-engine/
+ * pugi-engine.controller.ts). Kept as a local literal so this surface
+ * stays decoupled from the admin-api package — the CLI must work
+ * standalone after `npm i -g @pugi/cli`.
+ */
+const ALLOWED_DISPATCH_COMMANDS = ['code', 'explain', 'fix', 'plan', 'build'];
 export function buildOrchestratorTools(ctx) {
-    const fetchImpl = ctx.fetchImpl ??
-        ((...args) => fetch(...args));
     const execImpl = ctx.execFileImpl ?? execFileAsync;
     const tools = [
         {
@@ -290,62 +297,106 @@ export function buildOrchestratorTools(ctx) {
         },
         {
             name: 'pugi.dispatch',
-            description: 'Send a prompt to the live Pugi engine (Anvil-routed). Returns the synthesised ' +
-                'response, tool calls, cost, duration, and file changes. Uses the operator’s ' +
-                'currently active credential — set PUGI_API_KEY or run `pugi login` first.',
-            permission: 'network',
+            description: 'Run the Pugi engine loop end-to-end by shelling to `pugi <command> <prompt>` ' +
+                '(default command "code"). Drives the full client-side tool-use loop, so the ' +
+                'caller sees real file writes, real shell exec, real cost — not just one Anvil ' +
+                'turn. Workspace cwd must be `pugi init`-ed already; auth resolves through the ' +
+                'CLI (PUGI_API_KEY env or on-disk `pugi login` state). ' +
+                'Requires PUGI_MCP_EXEC_ENABLED=1 at server boot.',
+            permission: 'bash',
             inputSchema: {
                 type: 'object',
                 additionalProperties: false,
                 required: ['prompt'],
                 properties: {
                     prompt: { type: 'string' },
-                    persona: {
+                    command: {
                         type: 'string',
-                        description: 'Persona id, default "mira".',
+                        enum: ['code', 'explain', 'fix', 'plan', 'build'],
+                        description: 'Pugi CLI subcommand. Default "code".',
                     },
-                    workspace: {
+                    cwd: {
                         type: 'string',
-                        description: 'Workspace label (logical, not a filesystem path).',
+                        description: 'Optional workspace-relative cwd; defaults to the MCP workspace root. ' +
+                            'Must already be `pugi init`-ed.',
+                    },
+                    timeoutMs: {
+                        type: 'number',
+                        minimum: 100,
+                        maximum: 600000,
+                        description: 'Hard timeout in ms (default 180000).',
                     },
                 },
             },
             async execute(args) {
+                if (!ctx.capabilities.exec) {
+                    throw new Error('pugi.dispatch: PUGI_MCP_EXEC_ENABLED is not set. ' +
+                        'Restart `pugi mcp serve` with PUGI_MCP_EXEC_ENABLED=1 to enable shell-driven dispatch.');
+                }
                 const prompt = requireString(args, 'prompt');
-                const persona = optionalString(args, 'persona') ?? 'mira';
-                const workspace = optionalString(args, 'workspace');
-                if (!ctx.apiKey) {
-                    throw new Error('pugi.dispatch: no active credential. Set PUGI_API_KEY or run `pugi login`.');
+                // Argv-injection guard. The `pugi` CLI parser (runtime/cli.ts) uses
+                // an allowlist of known global flags (`--remote`, `--allow-fetch`,
+                // `--allow-search`, `--triple`, etc.) and does not honour a `--`
+                // end-of-options sentinel. Passing a prompt that begins with `--`
+                // risks the parser swallowing it as a CLI flag (e.g. an attacker-
+                // controlled MCP client sending `prompt: "--allow-fetch"` to
+                // silently unlock a capability the operator did not intend to
+                // grant for this turn). Reject at the MCP boundary so we fail
+                // loud rather than silently shift CLI behaviour. Operators with
+                // legitimate prompts starting with `--` can prepend a space.
+                if (prompt.startsWith('--')) {
+                    throw new Error('pugi.dispatch: prompt cannot start with "--" — the child CLI parser would ' +
+                        'interpret it as a flag. Prepend a space (" --foo") or rephrase.');
                 }
-                const endpoint = `${ctx.apiUrl.replace(/\/+$/, '')}/api/pugi/engine`;
+                const command = optionalString(args, 'command') ?? 'code';
+                if (!ALLOWED_DISPATCH_COMMANDS.includes(command)) {
+                    throw new Error(`pugi.dispatch: invalid command "${command}" (allowed: ${ALLOWED_DISPATCH_COMMANDS.join(', ')})`);
+                }
+                const cwdInput = optionalString(args, 'cwd');
+                const cwd = cwdInput
+                    ? resolveWorkspacePathOrThrow(ctx, cwdInput).absolute
+                    : ctx.workspaceRoot;
+                const timeoutMs = optionalNumber(args, 'timeoutMs', 180000);
                 const started = Date.now();
-                const response = await fetchImpl(endpoint, {
-                    method: 'POST',
-                    headers: {
-                        Authorization: `Bearer ${ctx.apiKey}`,
-                        'Content-Type': 'application/json',
-                        Accept: 'application/json',
-                        'User-Agent': 'pugi-mcp-orchestrator/1',
-                    },
-                    body: JSON.stringify({
-                        prompt,
-                        persona,
-                        ...(workspace ? { workspace } : {}),
-                    }),
-                });
-                const durationMs = Date.now() - started;
-                if (!response.ok) {
-                    const bodyText = await safeText(response);
-                    throw new Error(`pugi.dispatch: ${response.status} ${response.statusText} — ${clamp(bodyText, 2000)}`);
+                try {
+                    const { stdout, stderr } = await execImpl(ctx.pugiBin, [command, prompt, '--no-tty'], {
+                        cwd,
+                        timeout: timeoutMs,
+                        maxBuffer: 8 * 1024 * 1024,
+                        // Auth-bearing envs are passed through here even though
+                        // `sanitisedEnv()` strips them for `pugi.run`. Rationale:
+                        // dispatch is explicitly an authenticated engine call, so
+                        // the child must reach Anvil. The CLI prefers on-disk
+                        // `pugi login` state when both are present.
+                        env: dispatchEnv(),
+                    });
+                    return JSON.stringify({
+                        command,
+                        cwd,
+                        exitCode: 0,
+                        durationMs: Date.now() - started,
+                        stdout: clamp(stdout, 16 * 1024),
+                        stderr: clamp(stderr, 4 * 1024),
+                    });
+                }
+                catch (err) {
+                    const e = err;
+                    // `||` chain (not `??`) so an empty / whitespace-only `e.stderr`
+                    // does not swallow a spawn-side `e.message` like `"spawn pugi
+                    // ENOENT"`. Operators need to distinguish "pugi binary missing"
+                    // from "pugi ran and exited 1 silently."
+                    const stderrText = e.stderr || e.message || '';
+                    return JSON.stringify({
+                        command,
+                        cwd,
+                        exitCode: typeof e.code === 'number' ? e.code : 1,
+                        durationMs: Date.now() - started,
+                        stdout: clamp(e.stdout ?? '', 16 * 1024),
+                        stderr: clamp(stderrText, 4 * 1024),
+                        ...(e.signal ? { signal: e.signal } : {}),
+                        ...(e.killed ? { killed: true } : {}),
+                    });
                 }
-                const parsed = (await response.json().catch(() => ({})));
-                return JSON.stringify({
-                    response: typeof parsed.response === 'string' ? parsed.response : '',
-                    toolCalls: Array.isArray(parsed.toolCalls) ? parsed.toolCalls : [],
-                    cost: typeof parsed.cost === 'number' ? parsed.cost : 0,
-                    durationMs,
-                    fileChanges: Array.isArray(parsed.fileChanges) ? parsed.fileChanges : [],
-                });
             },
         },
         {
@@ -557,13 +608,29 @@ function sanitisedEnv() {
     }
     return out;
 }
-async function safeText(response) {
-    try {
-        return await response.text();
-    }
-    catch {
-        return '';
+function dispatchEnv() {
+    // Like sanitisedEnv() but threads PUGI_API_KEY / PUGI_API_URL through
+    // so the child `pugi <command>` invocation can resolve auth from env
+    // when on-disk `pugi login` state is unavailable (CI, fresh container).
+    const allow = [
+        'PATH',
+        'HOME',
+        'USER',
+        'SHELL',
+        'LANG',
+        'LC_ALL',
+        'TERM',
+        'NODE_OPTIONS',
+        'PUGI_API_KEY',
+        'PUGI_API_URL',
+    ];
+    const out = {};
+    for (const key of allow) {
+        const value = process.env[key];
+        if (value !== undefined)
+            out[key] = value;
     }
+    return out;
 }
 function extractGitHead(stdout) {
     // Match "HEAD is now at <sha> …" or "<sha> commit message" — the

package/dist/core/permissions/auto-classifier.js

@@ -0,0 +1,124 @@
+/**
+ * Auto-mode classifier — Wave 7 Phase 1 (regex allowlist + denylist).
+ *
+ * `permissionMode === 'auto'` is the Claude Code parity mode where the
+ * classifier decides safe-vs-unsafe per call. Phase 1 ships without
+ * ML — just two curated regex lists covering the 80% of "obviously
+ * safe" and "obviously catastrophic" patterns. Anything that doesn't
+ * match either list returns `ask`, so the operator stays in the loop
+ * для the ambiguous middle.
+ *
+ * Phase 2 (deferred, NOT in this PR): semantic classifier consulting
+ * the model with a tight system prompt. The interface (`AutoVerdict`)
+ * is stable so we can swap implementations without touching the gate.
+ *
+ * Design notes:
+ *
+ *   - Patterns are conservative: a read-only command is only
+ *     allow-listed когда its argv shape is unambiguous (no `-exec`,
+ *     no `--delete`, no `|` к shell). When в doubt, fall back to ask.
+ *   - The denylist matches catastrophic patterns even в auto-mode so
+ *     a misclick can't shred the workspace. The circuit-breaker
+ *     (`circuit-breaker.ts`) covers the same surface для bypass-mode;
+ *     this denylist is the auto-mode equivalent.
+ *   - All matches operate on the FULL command string, not parsed
+ *     argv. This is deliberately permissive on whitespace but strict
+ *     on operator characters (`|`, `&`, `;`, `>`, backticks) — a
+ *     pipe-into-shell или command-chain forces fallback к ask.
+ */
+/**
+ * Catastrophic patterns — the auto-mode regex denylist. Each entry
+ * carries a human-readable reason surfaced в the deny payload so the
+ * operator + audit log see why the gate refused. Order matters: most-
+ * specific первой так "rm -rf /" reports as that, не the generic
+ * "rm -rf".
+ */
+const AUTO_DENY_PATTERNS = [
+    { pattern: /\brm\s+(-[a-z]*r[a-z]*f|-[a-z]*f[a-z]*r)\b/i, reason: 'rm -rf (recursive force-delete)' },
+    { pattern: /\bgit\s+push\s+(-{1,2}force\b|\-f\b)/i, reason: 'git push --force (history rewrite)' },
+    { pattern: /\bgit\s+reset\s+--hard\b/i, reason: 'git reset --hard (uncommitted-work loss)' },
+    { pattern: /\bdd\s+if=\/(dev|)/i, reason: 'dd if=/dev/* (raw device read/write)' },
+    { pattern: /\bmkfs(\.|\s|$)/i, reason: 'mkfs (filesystem format)' },
+    { pattern: /\bchmod\s+-R\s+777\b/i, reason: 'chmod -R 777 (world-writable recursive)' },
+    { pattern: /\bchown\s+-R\b/i, reason: 'chown -R (recursive ownership change)' },
+    { pattern: /:\(\)\s*\{\s*:\s*\|\s*:\s*&\s*\}\s*;?\s*:/, reason: 'fork bomb signature' },
+    { pattern: /\bsudo\b/i, reason: 'sudo (privilege escalation)' },
+    { pattern: /\b(npm|pnpm|yarn)\s+publish\b/i, reason: 'package publish (irreversible npm release)' },
+    { pattern: /\b(curl|wget)\b[^|;&]*\|\s*(sh|bash|zsh)\b/i, reason: 'pipe-to-shell installer (curl … | sh)' },
+];
+/**
+ * Safe-by-default patterns — auto-mode regex allowlist. Each regex
+ * must match the FULL command (with `^…$` anchors) so a leading
+ * `sudo ls` или a trailing `; rm -rf /` does NOT slip through. The
+ * caller passes the trimmed command string; whitespace around argv
+ * tokens is tolerated.
+ */
+const AUTO_ALLOW_PATTERNS = [
+    { pattern: /^ls(\s+-[a-zA-Z]+)*(\s+[^|;&`>$()\\]+)?$/, reason: 'ls (directory listing)' },
+    { pattern: /^pwd\s*$/, reason: 'pwd (working directory)' },
+    { pattern: /^cat\s+[^|;&`>$()\\]+$/, reason: 'cat (file read)' },
+    { pattern: /^head(\s+-n?\s*\d+)?\s+[^|;&`>$()\\]+$/, reason: 'head (file preview)' },
+    { pattern: /^tail(\s+-n?\s*\d+)?\s+[^|;&`>$()\\]+$/, reason: 'tail (file preview)' },
+    { pattern: /^wc(\s+-[a-z]+)?\s+[^|;&`>$()\\]+$/, reason: 'wc (line/word count)' },
+    { pattern: /^du\s+-sh?\s+[^|;&`>$()\\]+$/, reason: 'du -sh (disk usage summary)' },
+    { pattern: /^df\s+-h\s*$/, reason: 'df -h (filesystem free space)' },
+    { pattern: /^git\s+status(\s+--short|\s+-s)?\s*$/, reason: 'git status' },
+    { pattern: /^git\s+diff(\s+[a-zA-Z0-9_./~^-]+)*\s*$/, reason: 'git diff (read-only)' },
+    { pattern: /^git\s+log(\s+[a-zA-Z0-9_./~^-]+)*\s*$/, reason: 'git log (read-only)' },
+    { pattern: /^git\s+branch(\s+-[a-z]+)?\s*$/, reason: 'git branch (read-only)' },
+    { pattern: /^git\s+remote\s+-v\s*$/, reason: 'git remote -v (read-only)' },
+    { pattern: /^pnpm\s+(typecheck|lint|test\s+--run|test\s+--watch=false)\s*$/, reason: 'pnpm read-only build check' },
+    { pattern: /^npm\s+(--version|-v|run\s+typecheck|run\s+lint)\s*$/, reason: 'npm read-only check' },
+    { pattern: /^node\s+--version\s*$/, reason: 'node --version' },
+    { pattern: /^pnpm\s+--version\s*$/, reason: 'pnpm --version' },
+    { pattern: /^which\s+[a-zA-Z0-9_-]+\s*$/, reason: 'which (command lookup)' },
+    { pattern: /^find\s+\.\s+-type\s+f(\s+-name\s+[^|;&`>$()\\]+)?\s*$/, reason: 'find -type f (read-only)' },
+    { pattern: /^(rg|ripgrep|grep)\s+(-[a-z]+\s+)*[^|;&`>$()\\]+(\s+[^|;&`>$()\\]+)?\s*$/, reason: 'grep/ripgrep (read-only search)' },
+];
+/**
+ * Classify an auto-mode command. Order:
+ *   1. Catastrophic deny patterns — surface the explicit deny reason.
+ *   2. Safe allow patterns — surface the matched reason.
+ *   3. Fallback к ask.
+ *
+ * The order matters: a destructive pattern that ALSO looks like a
+ * read-only token (e.g. `git diff ; rm -rf .`) hits deny first because
+ * the allow patterns require `^…$` anchors that the chained command
+ * fails to satisfy. Belt + suspenders.
+ */
+export function classifyAutoMode(command) {
+    const trimmed = command.trim();
+    if (trimmed.length === 0)
+        return { verdict: 'ask' };
+    for (const entry of AUTO_DENY_PATTERNS) {
+        if (entry.pattern.test(trimmed)) {
+            return {
+                verdict: 'deny',
+                reason: entry.reason,
+                pattern: entry.pattern.source,
+            };
+        }
+    }
+    for (const entry of AUTO_ALLOW_PATTERNS) {
+        if (entry.pattern.test(trimmed)) {
+            return {
+                verdict: 'allow',
+                reason: entry.reason,
+                pattern: entry.pattern.source,
+            };
+        }
+    }
+    return { verdict: 'ask' };
+}
+/**
+ * Diagnostic accessors — exposed для doctor surfaces + spec coverage.
+ * The arrays are frozen at module load so callers can iterate without
+ * mutating the source-of-truth.
+ */
+export function listAutoAllowPatterns() {
+    return AUTO_ALLOW_PATTERNS.map((e) => ({ pattern: e.pattern.source, reason: e.reason }));
+}
+export function listAutoDenyPatterns() {
+    return AUTO_DENY_PATTERNS.map((e) => ({ pattern: e.pattern.source, reason: e.reason }));
+}
+//# sourceMappingURL=auto-classifier.js.map

package/dist/core/permissions/circuit-breaker.js

@@ -0,0 +1,83 @@
+/**
+ * bypassPermissions circuit-breaker — Wave 7.
+ *
+ * `bypassPermissions` is "skip ALL checks" for trusted scripted runs.
+ * Even so, certain commands are catastrophic enough that the gate
+ * MUST refuse regardless of mode. This module owns that short list.
+ *
+ * The breaker is conservative on purpose:
+ *   - rm -rf against `/`, `~`, or workspace root (`.`)
+ *   - fork bomb signature (`:(){:|:&};:`)
+ *   - dd if=/ (raw block-device read or write)
+ *
+ * False positives are acceptable here — an operator who really wants
+ * to nuke their root filesystem can switch to `dontAsk` and re-issue;
+ * the breaker is the "are you sure you typed this correctly?" guard,
+ * not a hard policy boundary.
+ *
+ * `evaluateCircuitBreaker` is pure regex matching — no IO, no state.
+ * It's called by the gate before any other routing so a bypass-mode
+ * session that types `rm -rf /` sees the deny path first.
+ */
+/**
+ * Pattern list — kept narrow on purpose. Each entry must match the
+ * canonical destructive shape; argv variants without the exact form
+ * fall through к the regular `dontAsk` / `bypassPermissions` allow
+ * path, which is what the operator opted into.
+ */
+const CIRCUIT_BREAKER_PATTERNS = [
+    // rm -rf against absolute root, $HOME, ~, $WORKSPACE_ROOT, or `.`
+    // with no further token. The negative lookahead на `[/~.]\S` makes
+    // sure `rm -rf /tmp/foo` (specific subtree) doesn't trip — only the
+    // catastrophic `rm -rf /` or `rm -rf ~` or `rm -rf .` shapes do.
+    {
+        pattern: /\brm\s+(-[a-z]*r[a-z]*f|-[a-z]*f[a-z]*r)\s+(\/|~|\$HOME|\$\{HOME\}|\.)\s*$/i,
+        reason: 'rm -rf against /, $HOME, ~, or workspace root',
+    },
+    // Fork bomb signature. Whitespace-tolerant но shape-strict.
+    {
+        pattern: /:\s*\(\s*\)\s*\{\s*:\s*\|\s*:\s*&\s*\}\s*;?\s*:/,
+        reason: 'fork bomb (`:(){ :|:& };:`)',
+    },
+    // dd to/from raw devices. Either direction is catastrophic enough
+    // to warrant the breaker (read of /dev/random into a workspace file
+    // can fill the disk, write to /dev/sda destroys the disk).
+    {
+        pattern: /\bdd\b[^|;&]*\b(if|of)=\/dev\//i,
+        reason: 'dd reading/writing /dev/* (catastrophic IO)',
+    },
+    // mkfs against any disk — single regex covers ext*, xfs, btrfs, vfat.
+    {
+        pattern: /\bmkfs(\.[a-z0-9]+)?\s+\/dev\//i,
+        reason: 'mkfs against /dev/* (filesystem format)',
+    },
+];
+/**
+ * Test the command against every circuit-breaker pattern. Returns the
+ * first match (most-catastrophic-first ordering is encoded в the array
+ * order); when no pattern matches, the breaker is `tripped: false` so
+ * the caller proceeds to the regular gate decision.
+ *
+ * Pure function — no IO, no module-scoped state. Safe to call from any
+ * surface (gate, doctor command, audit replay).
+ */
+export function evaluateCircuitBreaker(command) {
+    const trimmed = command.trim();
+    if (trimmed.length === 0)
+        return { tripped: false, reason: '' };
+    for (const entry of CIRCUIT_BREAKER_PATTERNS) {
+        if (entry.pattern.test(trimmed)) {
+            return { tripped: true, reason: entry.reason };
+        }
+    }
+    return { tripped: false, reason: '' };
+}
+/**
+ * Diagnostic accessor — exposed для doctor surfaces + spec coverage so
+ * the test layer can iterate the full list and assert each entry trips
+ * on representative input.
+ */
+export function listCircuitBreakerPatterns() {
+    return CIRCUIT_BREAKER_PATTERNS.map((e) => ({ pattern: e.pattern.source, reason: e.reason }));
+}
+//# sourceMappingURL=circuit-breaker.js.map