@pugi/cli 0.1.0-alpha.3

package/dist/tools/file-tools.js

@@ -0,0 +1,346 @@
+import { spawnSync } from 'node:child_process';
+import { existsSync, readFileSync, realpathSync, renameSync, writeFileSync } from 'node:fs';
+import { dirname, isAbsolute, relative } from 'node:path';
+import { globSync } from 'node:fs';
+import { decidePermission } from '../core/permission.js';
+import { createReadRecord, hashContent } from '../core/file-cache.js';
+import { resolveWorkspacePath } from '../core/path-security.js';
+import { recordFileMutation, recordToolCall, recordToolResult } from '../core/session.js';
+/**
+ * Re-check the permission decision against the *resolved* real path so
+ * a workspace-local symlink (`alias -> .env`) cannot bypass the protected
+ * basename check. The first `decidePermission` call sees only the user
+ * input (`alias`); this second call sees the realpath relative to root
+ * (`.env`), which `protectedTargetReason` recognises.
+ *
+ * Returns the resolved absolute path. Throws when the resolved path is
+ * gated by anything other than `allow`.
+ */
+function permissionGatedResolve(ctx, inputPath, action, toolName) {
+    const resolved = resolveWorkspacePath(ctx.root, inputPath);
+    let realPath;
+    try {
+        realPath = realpathSync.native(resolved);
+    }
+    catch (error) {
+        // For writes to a file that does not yet exist there is no symlink
+        // to follow; fall back to the resolved path so the workspace check
+        // already done in `resolveWorkspacePath` is the only gate.
+        const code = error.code;
+        if (code === 'ENOENT' || code === 'ENOTDIR')
+            return resolved;
+        throw error;
+    }
+    if (realPath === resolved)
+        return resolved;
+    const realRelative = relative(ctx.root, realPath);
+    const realDecision = decidePermission({ tool: toolName, kind: action, target: realRelative }, ctx.settings, ctx.root);
+    if (realDecision.decision !== 'allow') {
+        throw new Error(`Permission ${realDecision.decision} for ${action} ${realRelative} (via symlink ${inputPath}): ${realDecision.reason}`);
+    }
+    return realPath;
+}
+export function readTool(ctx, path) {
+    const toolCallId = recordToolCall(ctx.session, 'read', path);
+    const decision = decidePermission({ tool: 'read', kind: 'read', target: path }, ctx.settings, ctx.root);
+    if (decision.decision !== 'allow') {
+        const reason = `Permission ${decision.decision} for read ${path}: ${decision.reason}`;
+        recordToolResult(ctx.session, toolCallId, 'error', reason);
+        throw new Error(reason);
+    }
+    let resolved;
+    try {
+        resolved = permissionGatedResolve(ctx, path, 'read', 'read');
+    }
+    catch (error) {
+        const reason = error.message;
+        recordToolResult(ctx.session, toolCallId, 'error', reason);
+        throw error;
+    }
+    const content = readFileSync(resolved, 'utf8');
+    ctx.readCache.set(createReadRecord(ctx.root, path, content, 'read_tool'));
+    recordToolResult(ctx.session, toolCallId, 'success', `Read ${path}`);
+    return content;
+}
+export function writeTool(ctx, path, content) {
+    const toolCallId = recordToolCall(ctx.session, 'write', path);
+    const decision = decidePermission({ tool: 'write', kind: 'edit', target: path }, ctx.settings, ctx.root);
+    if (decision.decision !== 'allow') {
+        const reason = `Permission ${decision.decision} for write ${path}: ${decision.reason}`;
+        recordToolResult(ctx.session, toolCallId, 'error', reason);
+        throw new Error(reason);
+    }
+    let resolved;
+    try {
+        resolved = permissionGatedResolve(ctx, path, 'edit', 'write');
+    }
+    catch (error) {
+        const reason = error.message;
+        recordToolResult(ctx.session, toolCallId, 'error', reason);
+        throw error;
+    }
+    const existed = existsSync(resolved);
+    const before = existed ? readFileSync(resolved, 'utf8') : undefined;
+    const tmp = `${resolved}.pugi-tmp-${Date.now()}`;
+    writeFileSync(tmp, content, { encoding: 'utf8', mode: 0o600 });
+    renameSync(tmp, resolved);
+    recordFileMutation(ctx.session, {
+        toolCallId,
+        path,
+        operation: existed ? 'update' : 'create',
+        beforeHash: before ? hashContent(before) : undefined,
+        afterHash: hashContent(content),
+    });
+    recordToolResult(ctx.session, toolCallId, 'success', `${existed ? 'Updated' : 'Created'} ${path}`);
+}
+export function editTool(ctx, path, oldString, newString) {
+    const toolCallId = recordToolCall(ctx.session, 'edit', path);
+    const decision = decidePermission({ tool: 'edit', kind: 'edit', target: path }, ctx.settings, ctx.root);
+    if (decision.decision !== 'allow') {
+        const reason = `Permission ${decision.decision} for edit ${path}: ${decision.reason}`;
+        recordToolResult(ctx.session, toolCallId, 'error', reason);
+        throw new Error(reason);
+    }
+    const readRecord = ctx.readCache.get(ctx.root, path);
+    if (!readRecord) {
+        throw new Error(`Cannot edit ${path}: file must be read first`);
+    }
+    let resolved;
+    try {
+        resolved = permissionGatedResolve(ctx, path, 'edit', 'edit');
+    }
+    catch (error) {
+        const reason = error.message;
+        recordToolResult(ctx.session, toolCallId, 'error', reason);
+        throw error;
+    }
+    const before = readFileSync(resolved, 'utf8');
+    const currentHash = hashContent(before);
+    if (currentHash !== readRecord.sha256) {
+        throw new Error(`Cannot edit ${path}: file changed since last read`);
+    }
+    const matches = before.split(oldString).length - 1;
+    if (matches === 0)
+        throw new Error(`Cannot edit ${path}: oldString not found`);
+    if (matches > 1)
+        throw new Error(`Cannot edit ${path}: oldString is not unique`);
+    const after = before.replace(oldString, newString);
+    const tmp = `${resolved}.pugi-tmp-${Date.now()}`;
+    writeFileSync(tmp, after, { encoding: 'utf8', mode: 0o600 });
+    renameSync(tmp, resolved);
+    ctx.readCache.set(createReadRecord(ctx.root, path, after, 'read_tool'));
+    recordFileMutation(ctx.session, {
+        toolCallId,
+        path,
+        operation: 'update',
+        beforeHash: currentHash,
+        afterHash: hashContent(after),
+    });
+    recordToolResult(ctx.session, toolCallId, 'success', `Edited ${path}`);
+}
+export function globTool(ctx, pattern) {
+    const toolCallId = recordToolCall(ctx.session, 'glob', pattern);
+    // Pugi globs are workspace-scoped. Reject any pattern that could enumerate
+    // outside the workspace:
+    //   1. absolute paths (`/etc/**/*`) — globSync resolves these against `/`
+    //      regardless of `cwd`, so they fan out outside the repo.
+    //   2. `..` as a path SEGMENT (`../*`, `src/../etc`) — parent traversal.
+    //      A substring check would over-reject legitimate names like
+    //      `src/v1..v2/*` so we split on `/` instead.
+    if (isAbsolute(pattern)) {
+        const reason = `Absolute glob patterns are not allowed: ${pattern}`;
+        recordToolResult(ctx.session, toolCallId, 'error', reason);
+        throw new Error(reason);
+    }
+    if (pattern.split('/').some((segment) => segment === '..')) {
+        const reason = `Glob pattern escapes workspace via '..' segment: ${pattern}`;
+        recordToolResult(ctx.session, toolCallId, 'error', reason);
+        throw new Error(reason);
+    }
+    const results = globSync(pattern, {
+        cwd: ctx.root,
+        withFileTypes: false,
+        exclude: ['node_modules/**', 'dist/**', '.git/**', '.pugi/**'],
+    })
+        .map((entry) => String(entry))
+        .slice(0, 500);
+    recordToolResult(ctx.session, toolCallId, 'success', `Glob matched ${results.length} paths`);
+    return results;
+}
+export function grepTool(ctx, query) {
+    const toolCallId = recordToolCall(ctx.session, 'grep', query);
+    const files = globTool(ctx, '**/*').filter((path) => !path.endsWith('/'));
+    const matches = [];
+    for (const path of files) {
+        if (matches.length >= 200)
+            break;
+        // Permission gate every file read individually — grep used to bypass
+        // `decidePermission` and could surface lines from protected files
+        // (.env, *.sql, *.pem, ~/.ssh/**) when invoked from a directory walk.
+        const decision = decidePermission({ tool: 'grep', kind: 'read', target: path }, ctx.settings, ctx.root);
+        if (decision.decision !== 'allow')
+            continue;
+        let fullPath;
+        try {
+            // `permissionGatedResolve` follows symlinks and re-checks the
+            // realpath against the permission rules. Without this an attacker
+            // could plant `alias -> .env` inside the workspace and recover
+            // secrets through `pugi explain .` because the initial decision
+            // only saw the unprotected basename `alias`.
+            fullPath = permissionGatedResolve(ctx, path, 'read', 'grep');
+        }
+        catch {
+            continue;
+        }
+        if (dirname(fullPath).includes('node_modules'))
+            continue;
+        try {
+            const lines = readFileSync(fullPath, 'utf8').split('\n');
+            lines.forEach((text, index) => {
+                if (matches.length < 200 && text.includes(query)) {
+                    matches.push({ path: relative(ctx.root, fullPath), line: index + 1, text });
+                }
+            });
+        }
+        catch {
+            // Binary or unreadable files are ignored by the scaffolded grep tool.
+        }
+    }
+    recordToolResult(ctx.session, toolCallId, 'success', `Grep matched ${matches.length} lines`);
+    return matches;
+}
+/**
+ * Workspace-scoped bash tool. Sized for the M1 engine adapter:
+ *   - Runs through `/bin/sh -c <command>` so the model can use pipes,
+ *     redirection, and shell builtins (`ls | wc -l`, `git status`).
+ *   - `cwd` is pinned to the workspace root so a stray `cd /` cannot
+ *     leak commands outside the repo (the child process inherits root
+ *     filesystem visibility — destructive patterns are blocked by
+ *     `decidePermission`, not by chroot).
+ *   - Output capped at 64KB combined stdout/stderr to keep the
+ *     transcript bounded; the model gets the head + a `(...truncated)`
+ *     marker if the cap fires.
+ *   - 30s wall-clock timeout. The engine loop's per-tool error path
+ *     surfaces the timeout to the model so it can retry with a narrower
+ *     command or give up.
+ *
+ * Permission gating: `kind: 'bash'`. The CLI's permission module already
+ * hard-denies the destructive-patterns list (rm -rf /, DROP DATABASE,
+ * etc) regardless of mode. Plan-mode callers MUST gate the bash tool
+ * out before it reaches the registry — `engine-tools.ts` does this.
+ */
+export const BASH_OUTPUT_CAP = 64 * 1024;
+export const BASH_DEFAULT_TIMEOUT_MS = 30_000;
+// Child-process stdio buffer — large enough that the model-facing
+// truncation cap (`BASH_OUTPUT_CAP`) is always the gate, never the
+// child's internal buffer. Code Reviewer P2 retro 2026-05-23 flagged
+// `BASH_OUTPUT_CAP * 2` as too tight: real builds (`pnpm build`,
+// `tsc --noEmit`) routinely exceed 128 KB combined and the model
+// then saw a fatal `ERR_CHILD_PROCESS_STDIO_MAXBUFFER` instead of a
+// graceful `(...truncated at N bytes)` tail.
+export const BASH_CHILD_MAXBUFFER = 10 * 1024 * 1024;
+export function bashTool(ctx, command, options = {}) {
+    const toolCallId = recordToolCall(ctx.session, 'bash', command);
+    const decision = decidePermission({ tool: 'bash', kind: 'bash', target: command }, ctx.settings, ctx.root);
+    if (decision.decision !== 'allow') {
+        const reason = `Permission ${decision.decision} for bash: ${decision.reason}`;
+        recordToolResult(ctx.session, toolCallId, 'error', reason);
+        throw new Error(reason);
+    }
+    // `/bin/sh -c` is portable enough for the M1 alpha; downstream
+    // operators on hosts without /bin/sh can override via $SHELL, but
+    // that is an explicit opt-in for now.
+    //
+    // Env sanitisation strategy: build the child env from an explicit
+    // allow-list rather than inheriting `process.env` and trying to
+    // strip secrets after the fact. Code Reviewer P1 2026-05-23 flagged
+    // that the deny-list approach missed ANTHROPIC_API_KEY / GH_TOKEN
+    // / AWS_SECRET_ACCESS_KEY / DATABASE_URL / arbitrary *_TOKEN /
+    // *_SECRET / *_KEY variables — every CI agent rotation would risk
+    // leaking a new secret name. Allow-listed PATH / HOME / USER /
+    // SHELL / LANG / LC_* / TERM / TZ + Pugi-internal PUGI_ROOT for
+    // tools that need it. Any other env variable is invisible to the
+    // child process.
+    const childEnv = {};
+    const SAFE_ENV_ALLOW = new Set([
+        'PATH',
+        'HOME',
+        'USER',
+        'LOGNAME',
+        'SHELL',
+        'LANG',
+        'TZ',
+        'TERM',
+        'PWD',
+    ]);
+    for (const [key, value] of Object.entries(process.env)) {
+        if (value === undefined)
+            continue;
+        if (SAFE_ENV_ALLOW.has(key) || key.startsWith('LC_')) {
+            childEnv[key] = value;
+        }
+    }
+    const timeoutMs = options.timeoutMs ?? BASH_DEFAULT_TIMEOUT_MS;
+    // `spawnSync` (vs `execFileSync`) captures stdout AND stderr on
+    // BOTH success and failure paths. Code Reviewer P1 2026-05-23:
+    // `execFileSync` returns only stdout on exit 0, silently dropping
+    // stderr output from `tsc`, `eslint`, `pytest`, etc. — the model
+    // would see `(no output)` for successful runs that emitted real
+    // warnings.
+    //
+    // maxBuffer is generous (10 MB) so the child process is never the
+    // truncation gate — the post-hoc `.slice(0, BASH_OUTPUT_CAP)` below
+    // is the single source of truth for what the model sees. Code
+    // Reviewer P2 retro 2026-05-23: the previous `BASH_OUTPUT_CAP * 2`
+    // (128 KB) would hard-throw `ERR_CHILD_PROCESS_STDIO_MAXBUFFER`
+    // on noisy commands (`pnpm build`, `tsc --noEmit` on the whole
+    // monorepo) instead of returning the truncated head.
+    const result = spawnSync('/bin/sh', ['-c', command], {
+        cwd: ctx.root,
+        env: childEnv,
+        encoding: 'utf8',
+        stdio: ['ignore', 'pipe', 'pipe'],
+        timeout: timeoutMs,
+        maxBuffer: BASH_CHILD_MAXBUFFER,
+    });
+    if (result.error) {
+        const err = result.error;
+        if (err.code === 'ETIMEDOUT' || result.signal === 'SIGTERM') {
+            const reason = `bash command timed out after ${timeoutMs}ms`;
+            recordToolResult(ctx.session, toolCallId, 'error', reason);
+            throw new Error(reason);
+        }
+        if (err.code === 'ERR_CHILD_PROCESS_STDIO_MAXBUFFER') {
+            // maxBuffer overflow — surface as truncated rather than an
+            // opaque Node internal code so the model sees the same
+            // truncation marker it gets on stdout/stderr cap hits. With the
+            // post-Code-Reviewer-P2-retro-2026-05-23 maxBuffer at 10 MB
+            // this branch only fires on truly pathological output (>10 MB
+            // single command).
+            const reason = `bash output exceeded ${BASH_CHILD_MAXBUFFER} byte child-process buffer`;
+            recordToolResult(ctx.session, toolCallId, 'error', reason);
+            throw new Error(reason);
+        }
+        const reason = `bash invocation failed: ${err.message ?? String(err)}`;
+        recordToolResult(ctx.session, toolCallId, 'error', reason);
+        throw new Error(reason);
+    }
+    const stdout = (result.stdout ?? '').toString();
+    const stderr = (result.stderr ?? '').toString();
+    const truncatedOut = stdout.length > BASH_OUTPUT_CAP;
+    const truncatedErr = stderr.length > BASH_OUTPUT_CAP;
+    const truncated = truncatedOut || truncatedErr;
+    const out = truncatedOut
+        ? `${stdout.slice(0, BASH_OUTPUT_CAP)}\n(...truncated at ${BASH_OUTPUT_CAP} bytes)`
+        : stdout;
+    const err = truncatedErr
+        ? `${stderr.slice(0, BASH_OUTPUT_CAP)}\n(...truncated at ${BASH_OUTPUT_CAP} bytes)`
+        : stderr;
+    const exitCode = result.status ?? 1;
+    // Non-zero exit is a normal outcome (e.g. `grep` finding no match,
+    // `test -f` returning 1). Surface it as a success at the audit
+    // layer; the engine loop feeds the exit code back to the model.
+    recordToolResult(ctx.session, toolCallId, 'success', `bash exit=${exitCode} stdout=${stdout.length} stderr=${stderr.length}`);
+    return { stdout: out, stderr: err, exitCode, truncated };
+}
+//# sourceMappingURL=file-tools.js.map

package/dist/tools/registry.js

@@ -0,0 +1,24 @@
+const registry = [
+    { name: 'bash', permission: 'bash', risk: 'high', concurrencySafe: false, m1: true },
+    { name: 'edit', permission: 'edit', risk: 'medium', concurrencySafe: false, m1: true },
+    { name: 'glob', permission: 'read', risk: 'low', concurrencySafe: true, m1: true },
+    { name: 'grep', permission: 'read', risk: 'low', concurrencySafe: true, m1: true },
+    { name: 'question', permission: 'none', risk: 'low', concurrencySafe: false, m1: true },
+    { name: 'read', permission: 'read', risk: 'low', concurrencySafe: true, m1: true },
+    { name: 'skill', permission: 'read', risk: 'low', concurrencySafe: true, m1: true },
+    { name: 'task_create', permission: 'none', risk: 'low', concurrencySafe: false, m1: true },
+    { name: 'task_get', permission: 'none', risk: 'low', concurrencySafe: true, m1: true },
+    { name: 'task_list', permission: 'none', risk: 'low', concurrencySafe: true, m1: true },
+    { name: 'task_update', permission: 'none', risk: 'low', concurrencySafe: false, m1: true },
+    { name: 'write', permission: 'edit', risk: 'medium', concurrencySafe: false, m1: true },
+];
+export const toolRegistry = registry.sort((a, b) => a.name.localeCompare(b.name));
+export function toolSchemaBundleHashInput() {
+    return JSON.stringify(toolRegistry.map((tool) => ({
+        name: tool.name,
+        permission: tool.permission,
+        risk: tool.risk,
+        concurrencySafe: tool.concurrencySafe,
+    })));
+}
+//# sourceMappingURL=registry.js.map

package/package.json

@@ -0,0 +1,58 @@
+{
+  "name": "@pugi/cli",
+  "version": "0.1.0-alpha.3",
+  "description": "Pugi CLI — terminal-native software execution system",
+  "homepage": "https://pugi.io",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/pugi-io/pugi.git",
+    "directory": "apps/pugi-cli"
+  },
+  "bugs": {
+    "url": "https://github.com/pugi-io/pugi/issues"
+  },
+  "keywords": [
+    "pugi",
+    "cli",
+    "ai",
+    "agents",
+    "engineering",
+    "orchestrator"
+  ],
+  "author": "Pugi <hello@pugi.io>",
+  "license": "MIT",
+  "type": "module",
+  "bin": {
+    "pugi": "./bin/run.js"
+  },
+  "files": [
+    "bin/run.js",
+    "dist/**/*.js",
+    "README.md",
+    "LICENSE"
+  ],
+  "engines": {
+    "node": ">=20"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "dependencies": {
+    "zod": "^3.23.0",
+    "@pugi/sdk": "0.1.0-alpha.3"
+  },
+  "devDependencies": {
+    "@types/node": "^22.0.0",
+    "tsx": "^4.19.0",
+    "typescript": "~5.6.0"
+  },
+  "scripts": {
+    "build": "pnpm --filter @pugi/sdk build && tsc -p tsconfig.json && node scripts/make-bin-executable.mjs",
+    "dev": "tsx src/index.ts",
+    "typecheck": "pnpm --filter @pugi/sdk build && tsc -p tsconfig.json --noEmit",
+    "test": "pnpm run build && node --test --import tsx test/*.spec.ts",
+    "version:cli": "tsx src/index.ts version",
+    "doctor": "tsx src/index.ts doctor --json",
+    "pack:smoke": "node scripts/pack-smoke.mjs"
+  }
+}