@pugi/cli 0.1.0-alpha.3

package/dist/core/engine/tool-bridge.js

@@ -0,0 +1,215 @@
+import { bashTool, editTool, globTool, grepTool, readTool, writeTool, } from '../../tools/file-tools.js';
+/**
+ * Tool-bridge: turns the abstract tool registry into:
+ *   1. An OpenAI-shaped tools schema for `EngineLoopClient.send`.
+ *   2. A single executor callback that dispatches each tool_call to the
+ *      concrete `file-tools.ts` handler under workspace permissions.
+ *
+ * The bridge enforces two CLI-side invariants that the runtime cannot:
+ *   - Plan-mode refusal. When `kind === 'plan'`, the executor refuses
+ *     write/edit/bash by throwing `PLAN_MODE_REFUSED:<tool>` (sentinel
+ *     recognised by `runEngineLoop` to terminate with status
+ *     `tool_refused`). The schema also omits the mutating tools so the
+ *     model is unlikely to attempt them in the first place.
+ *   - Argument validation. Each call's `arguments` string is JSON-parsed
+ *     and shape-checked here; bad JSON or missing fields are surfaced
+ *     to the model as a tool error string so it can correct itself.
+ *
+ * The bridge does NOT touch session.ts directly — `file-tools.ts`
+ * already records every call. The engine adapter wires a hook layer on
+ * top that surfaces tool events into the engine's status stream.
+ */
+/**
+ * Read-only subset surfaced to plan-mode. Mutating tools (write, edit,
+ * bash) are intentionally absent so the model rarely tries them.
+ */
+const READ_ONLY_TOOLS = new Set(['read', 'grep', 'glob']);
+/**
+ * Tools we actually wire today. The registry has more entries
+ * (task_*, skill, question) — those route through the runtime layer, not
+ * the local filesystem, so they ship in a follow-up PR. M1 cornerstone is
+ * the six core tools.
+ */
+const WIRED_TOOLS = new Set(['read', 'write', 'edit', 'grep', 'glob', 'bash']);
+export function buildToolsSchema(kind) {
+    const planMode = kind === 'plan';
+    const toolDefs = [
+        {
+            name: 'read',
+            description: 'Read the contents of a workspace file. Required before edit on a file. Returns the full UTF-8 text. Workspace-scoped: paths must be relative to the workspace root.',
+            parameters: {
+                type: 'object',
+                additionalProperties: false,
+                required: ['path'],
+                properties: {
+                    path: { type: 'string', description: 'Workspace-relative file path.' },
+                },
+            },
+        },
+        {
+            name: 'grep',
+            description: 'Substring-match every workspace file. Returns up to 200 matches with {path, line, text}. Use this to locate code by symbol/keyword.',
+            parameters: {
+                type: 'object',
+                additionalProperties: false,
+                required: ['query'],
+                properties: {
+                    query: { type: 'string', description: 'Substring to search for.' },
+                },
+            },
+        },
+        {
+            name: 'glob',
+            description: 'List files matching a glob pattern (workspace-scoped, node_modules / dist / .git / .pugi excluded). Up to 500 paths.',
+            parameters: {
+                type: 'object',
+                additionalProperties: false,
+                required: ['pattern'],
+                properties: {
+                    pattern: { type: 'string', description: 'Glob pattern, e.g. "src/**/*.ts".' },
+                },
+            },
+        },
+    ];
+    if (!planMode) {
+        toolDefs.push({
+            name: 'write',
+            description: 'Create or overwrite a workspace file. Use for new files only — prefer edit for existing files. Workspace-scoped.',
+            parameters: {
+                type: 'object',
+                additionalProperties: false,
+                required: ['path', 'content'],
+                properties: {
+                    path: { type: 'string', description: 'Workspace-relative file path.' },
+                    content: { type: 'string', description: 'Full new file contents (UTF-8).' },
+                },
+            },
+        }, {
+            name: 'edit',
+            description: 'Replace exactly one occurrence of oldString with newString inside an already-read file. Fails if the file changed since you read it or if oldString is missing/duplicate.',
+            parameters: {
+                type: 'object',
+                additionalProperties: false,
+                required: ['path', 'oldString', 'newString'],
+                properties: {
+                    path: { type: 'string' },
+                    oldString: { type: 'string' },
+                    newString: { type: 'string' },
+                },
+            },
+        }, {
+            name: 'bash',
+            description: 'Run a shell command inside the workspace root via /bin/sh -c. Inherits a sanitized env (PUGI_API_KEY/PUGI_LOGIN_TOKEN stripped). 30s timeout. Output capped at 64KB. Returns {exitCode, stdout, stderr, truncated}.',
+            parameters: {
+                type: 'object',
+                additionalProperties: false,
+                required: ['command'],
+                properties: {
+                    command: { type: 'string', description: 'Single shell command to execute.' },
+                },
+            },
+        });
+    }
+    return toolDefs;
+}
+function parseArgs(raw) {
+    if (!raw || raw.trim() === '')
+        return {};
+    try {
+        const parsed = JSON.parse(raw);
+        if (parsed === null || typeof parsed !== 'object' || Array.isArray(parsed)) {
+            throw new Error('tool arguments must be a JSON object');
+        }
+        return parsed;
+    }
+    catch (error) {
+        throw new Error(`invalid JSON in tool arguments: ${error.message}`);
+    }
+}
+function requireString(obj, key) {
+    const v = obj[key];
+    if (typeof v !== 'string') {
+        throw new Error(`tool argument "${key}" must be a string`);
+    }
+    return v;
+}
+export function buildExecutor(input) {
+    const { kind, ctx } = input;
+    const planMode = kind === 'plan';
+    return async ({ name, arguments: argsRaw }) => {
+        if (!WIRED_TOOLS.has(name)) {
+            throw new Error(`unknown tool: ${name}`);
+        }
+        if (planMode && !READ_ONLY_TOOLS.has(name)) {
+            // Sentinel recognised by `runEngineLoop` — terminates the loop
+            // with status `tool_refused`. The CLI surfaces this as a blocked
+            // outcome, not a failure, because plan mode is doing its job.
+            throw new Error(`PLAN_MODE_REFUSED: ${name} is not allowed in plan mode`);
+        }
+        const args = parseArgs(argsRaw);
+        switch (name) {
+            case 'read': {
+                const { path } = { path: requireString(args, 'path') };
+                const content = readTool(ctx, path);
+                // Cap the content surfaced back to the model so a 10MB file
+                // does not blow the context window. The model sees the head
+                // and a truncation marker; if it needs more it can grep.
+                const CAP = 32 * 1024;
+                if (content.length > CAP) {
+                    return `${content.slice(0, CAP)}\n(...truncated at ${CAP} bytes; use grep or glob to narrow the read)`;
+                }
+                return content;
+            }
+            case 'write': {
+                const wargs = {
+                    path: requireString(args, 'path'),
+                    content: requireString(args, 'content'),
+                };
+                writeTool(ctx, wargs.path, wargs.content);
+                return `wrote ${wargs.path} (${wargs.content.length} bytes)`;
+            }
+            case 'edit': {
+                const eargs = {
+                    path: requireString(args, 'path'),
+                    oldString: requireString(args, 'oldString'),
+                    newString: requireString(args, 'newString'),
+                };
+                editTool(ctx, eargs.path, eargs.oldString, eargs.newString);
+                return `edited ${eargs.path}`;
+            }
+            case 'grep': {
+                const gargs = { query: requireString(args, 'query') };
+                const matches = grepTool(ctx, gargs.query);
+                if (matches.length === 0)
+                    return `no matches for ${gargs.query}`;
+                const head = matches.slice(0, 50);
+                const rendered = head.map((m) => `${m.path}:${m.line}: ${m.text}`).join('\n');
+                const more = matches.length > head.length ? `\n(... ${matches.length - head.length} more)` : '';
+                return `${matches.length} match(es):\n${rendered}${more}`;
+            }
+            case 'glob': {
+                const gargs = { pattern: requireString(args, 'pattern') };
+                const results = globTool(ctx, gargs.pattern);
+                if (results.length === 0)
+                    return `no paths match ${gargs.pattern}`;
+                return `${results.length} path(s):\n${results.slice(0, 100).join('\n')}${results.length > 100 ? `\n(... ${results.length - 100} more)` : ''}`;
+            }
+            case 'bash': {
+                const bargs = { command: requireString(args, 'command') };
+                const result = bashTool(ctx, bargs.command);
+                const body = [
+                    `exit=${result.exitCode}`,
+                    result.stdout ? `stdout:\n${result.stdout}` : '',
+                    result.stderr ? `stderr:\n${result.stderr}` : '',
+                ]
+                    .filter(Boolean)
+                    .join('\n');
+                return body || '(no output)';
+            }
+            default:
+                // Exhaustive; unreachable because of the WIRED_TOOLS guard above.
+                throw new Error(`unhandled tool: ${name}`);
+        }
+    };
+}
+//# sourceMappingURL=tool-bridge.js.map

package/dist/core/file-cache.js

@@ -0,0 +1,29 @@
+import { createHash } from 'node:crypto';
+import { statSync } from 'node:fs';
+import { resolve } from 'node:path';
+export class FileReadCache {
+    records = new Map();
+    set(record) {
+        this.records.set(record.resolvedPath, record);
+    }
+    get(root, path) {
+        return this.records.get(resolve(root, path));
+    }
+}
+export function hashContent(content) {
+    return createHash('sha256').update(content).digest('hex');
+}
+export function createReadRecord(root, path, content, source) {
+    const resolvedPath = resolve(root, path);
+    const stat = statSync(resolvedPath);
+    return {
+        path,
+        resolvedPath,
+        sha256: hashContent(content),
+        sizeBytes: stat.size,
+        mtimeMs: stat.mtimeMs,
+        readAt: new Date().toISOString(),
+        source,
+    };
+}
+//# sourceMappingURL=file-cache.js.map

package/dist/core/index-store.js

@@ -0,0 +1,260 @@
+import { existsSync, readFileSync, readdirSync, statSync, writeFileSync } from 'node:fs';
+import { resolve, relative } from 'node:path';
+import { z } from 'zod';
+import { auditEventSchema } from '@pugi/sdk';
+/**
+ * `.pugi/index.json` — materialized session + artifact index.
+ *
+ * The append-only event log at `.pugi/events.jsonl` is the source of truth.
+ * `index.json` is a cached projection rebuilt on demand. Reads prefer the
+ * cached view; writes (idea/plan/build/review/handoff/resume) update both.
+ *
+ * Local-first invariant: this file is regenerable from events.jsonl plus
+ * filesystem scan of artifacts/handoffs. Deleting it never loses data.
+ */
+export const pugiIndexArtifactSchema = z.object({
+    id: z.string().min(1),
+    kind: z.enum([
+        'idea',
+        'plan',
+        'build',
+        'review',
+        'triple-review',
+        'resume',
+        'handoff',
+        'other',
+    ]),
+    path: z.string().min(1),
+    sessionId: z.string().min(1).nullable(),
+    createdAt: z.string().datetime(),
+    files: z.array(z.string()).default([]),
+});
+export const pugiIndexSessionSchema = z.object({
+    id: z.string().min(1),
+    startedAt: z.string().datetime(),
+    endedAt: z.string().datetime().nullable(),
+    commandCount: z.number().int().nonnegative(),
+    commands: z.array(z.object({
+        command: z.string().min(1),
+        status: z.enum(['started', 'success', 'error']),
+        timestamp: z.string().datetime(),
+    })),
+    artifactIds: z.array(z.string()).default([]),
+});
+export const pugiIndexSchema = z.object({
+    schema: z.literal(1),
+    updatedAt: z.string().datetime(),
+    artifacts: z.array(pugiIndexArtifactSchema),
+    sessions: z.array(pugiIndexSessionSchema),
+});
+export function indexPath(root) {
+    return resolve(root, '.pugi', 'index.json');
+}
+export function readIndex(root) {
+    const path = indexPath(root);
+    if (!existsSync(path))
+        return null;
+    try {
+        const raw = JSON.parse(readFileSync(path, 'utf8'));
+        const parsed = pugiIndexSchema.safeParse(raw);
+        return parsed.success ? parsed.data : null;
+    }
+    catch {
+        return null;
+    }
+}
+export function writeIndex(root, index) {
+    const path = indexPath(root);
+    writeFileSync(path, `${JSON.stringify(index, null, 2)}\n`, { encoding: 'utf8', mode: 0o600 });
+}
+export function emptyIndex() {
+    return {
+        schema: 1,
+        updatedAt: new Date().toISOString(),
+        artifacts: [],
+        sessions: [],
+    };
+}
+/**
+ * Rebuild the index from the event log + filesystem.
+ *
+ * This is the canonical recovery path: even if `.pugi/index.json` is
+ * deleted or corrupt, we can always reconstruct it.
+ */
+export function rebuildIndex(root) {
+    const events = readEvents(root);
+    const sessions = groupSessionsFromEvents(events);
+    const artifacts = scanArtifacts(root, events);
+    return {
+        schema: 1,
+        updatedAt: new Date().toISOString(),
+        artifacts,
+        sessions,
+    };
+}
+/**
+ * Append an artifact to the index, dedup by id. Touches `updatedAt`.
+ */
+export function upsertArtifact(index, artifact) {
+    const next = { ...index };
+    const existing = next.artifacts.findIndex((a) => a.id === artifact.id);
+    if (existing >= 0) {
+        next.artifacts = next.artifacts.map((a, i) => (i === existing ? artifact : a));
+    }
+    else {
+        next.artifacts = [...next.artifacts, artifact];
+    }
+    next.updatedAt = new Date().toISOString();
+    // Attach to session bucket if we know the sessionId.
+    if (artifact.sessionId) {
+        next.sessions = next.sessions.map((session) => session.id === artifact.sessionId
+            ? {
+                ...session,
+                artifactIds: session.artifactIds.includes(artifact.id)
+                    ? session.artifactIds
+                    : [...session.artifactIds, artifact.id],
+            }
+            : session);
+    }
+    return next;
+}
+export function readEvents(root) {
+    const eventsPath = resolve(root, '.pugi', 'events.jsonl');
+    if (!existsSync(eventsPath))
+        return [];
+    const raw = readFileSync(eventsPath, 'utf8');
+    const out = [];
+    for (const line of raw.split('\n')) {
+        const trimmed = line.trim();
+        if (!trimmed)
+            continue;
+        try {
+            const parsed = auditEventSchema.safeParse(JSON.parse(trimmed));
+            if (parsed.success)
+                out.push(parsed.data);
+        }
+        catch {
+            // Tolerate corrupt single lines so the rest of the log keeps loading.
+        }
+    }
+    return out;
+}
+function groupSessionsFromEvents(events) {
+    const map = new Map();
+    for (const event of events) {
+        if (event.type !== 'session')
+            continue;
+        let session = map.get(event.sessionId);
+        if (!session) {
+            session = {
+                id: event.sessionId,
+                startedAt: event.timestamp,
+                endedAt: null,
+                commandCount: 0,
+                commands: [],
+                artifactIds: [],
+            };
+            map.set(event.sessionId, session);
+        }
+        if (event.name === 'command_started' && event.command) {
+            session.commandCount += 1;
+            session.commands.push({
+                command: event.command,
+                status: 'started',
+                timestamp: event.timestamp,
+            });
+        }
+        else if (event.name === 'command_completed' && event.command) {
+            session.commands.push({
+                command: event.command,
+                status: event.status === 'error' ? 'error' : 'success',
+                timestamp: event.timestamp,
+            });
+            session.endedAt = event.timestamp;
+        }
+        else if (event.name === 'created') {
+            session.startedAt = event.timestamp;
+        }
+    }
+    return [...map.values()].sort((a, b) => b.startedAt.localeCompare(a.startedAt));
+}
+function scanArtifacts(root, events) {
+    const artifactsDir = resolve(root, '.pugi', 'artifacts');
+    const handoffsDir = resolve(root, '.pugi', 'handoffs');
+    const out = [];
+    // Map artifact dir names to sessionIds via tool_call events (best-effort).
+    // Artifact ids are timestamped slugs (e.g. `2026-05-22T03-51-37-260Z-triple-review`);
+    // tool_call records the `inputSummary` which often contains the prompt.
+    // We attach sessionId by mtime proximity to the closest tool_call event.
+    const toolCallTimes = events
+        .filter((e) => e.type === 'tool_call')
+        .map((e) => ({ sessionId: e.sessionId, timestamp: Date.parse(e.timestamp) }))
+        .filter((entry) => Number.isFinite(entry.timestamp));
+    if (existsSync(artifactsDir)) {
+        for (const entry of readdirSync(artifactsDir, { withFileTypes: true })) {
+            if (!entry.isDirectory())
+                continue;
+            const dir = resolve(artifactsDir, entry.name);
+            const files = readdirSync(dir, { withFileTypes: true })
+                .filter((file) => file.isFile())
+                .map((file) => file.name)
+                .sort();
+            const stat = statSync(dir);
+            out.push({
+                id: entry.name,
+                kind: inferKindFromFiles(files),
+                path: relative(root, dir),
+                sessionId: nearestSessionId(stat.mtimeMs, toolCallTimes),
+                createdAt: stat.mtime.toISOString(),
+                files,
+            });
+        }
+    }
+    if (existsSync(handoffsDir)) {
+        for (const entry of readdirSync(handoffsDir, { withFileTypes: true })) {
+            if (!entry.isFile() || !entry.name.endsWith('.json'))
+                continue;
+            const path = resolve(handoffsDir, entry.name);
+            const stat = statSync(path);
+            out.push({
+                id: entry.name.replace(/\.json$/, ''),
+                kind: 'handoff',
+                path: relative(root, path),
+                sessionId: nearestSessionId(stat.mtimeMs, toolCallTimes),
+                createdAt: stat.mtime.toISOString(),
+                files: [entry.name],
+            });
+        }
+    }
+    return out.sort((a, b) => b.createdAt.localeCompare(a.createdAt));
+}
+function inferKindFromFiles(files) {
+    if (files.some((f) => f === 'triple-review-request.json' || f === 'triple-review.md')) {
+        return 'triple-review';
+    }
+    if (files.includes('brief.md') && files.includes('execution-graph.json'))
+        return 'idea';
+    if (files.includes('plan.md'))
+        return 'plan';
+    if (files.includes('build.md'))
+        return 'build';
+    if (files.includes('review.md'))
+        return 'review';
+    if (files.includes('resume.md'))
+        return 'resume';
+    return 'other';
+}
+function nearestSessionId(mtimeMs, toolCallTimes) {
+    if (toolCallTimes.length === 0)
+        return null;
+    let best = null;
+    for (const entry of toolCallTimes) {
+        const delta = Math.abs(entry.timestamp - mtimeMs);
+        if (!best || delta < best.delta)
+            best = { sessionId: entry.sessionId, delta };
+    }
+    // Cap attribution to a 5-minute window so unrelated sessions do not collect
+    // each other's artifacts on long-lived repos.
+    return best && best.delta <= 5 * 60 * 1000 ? best.sessionId : null;
+}
+//# sourceMappingURL=index-store.js.map

package/dist/core/path-security.js

@@ -0,0 +1,63 @@
+import { realpathSync } from 'node:fs';
+import { basename, relative, resolve } from 'node:path';
+/**
+ * Resolve and validate that an inputPath stays within the workspace.
+ *
+ * Defends against:
+ *   1. relative-path traversal (`../etc/passwd`)
+ *   2. URL-encoded traversal (`..%2Fetc%2Fpasswd`)
+ *   3. symlink escapes at the target itself (`alias-link -> /etc/passwd`)
+ *
+ * The previous implementation also resolved the parent's realpath and
+ * compared to the workspace root. That broke `pugi explain .` on macOS
+ * where the workspace is under a symlinked prefix (`/tmp` → `/private/tmp`)
+ * because the parent's realpath legitimately sits one level above the
+ * workspace. The fix: compute the target's realpath (or the literal
+ * resolved path when the target does not yet exist) and require that to
+ * stay inside the workspace's realpath. Parent-chain symlinks that
+ * actually escape will fail this check; benign system symlinks above
+ * the workspace will not.
+ *
+ * Throws when the resolved path is outside the workspace. Returns the
+ * literal absolute path on disk (suitable for `readFileSync` /
+ * `writeFileSync`).
+ */
+export function resolveWorkspacePath(root, inputPath) {
+    const decoded = decodeURIComponent(inputPath);
+    const target = resolve(root, decoded);
+    const realRoot = realpathSync.native(root);
+    let realTarget;
+    try {
+        realTarget = realpathSync.native(target);
+    }
+    catch (error) {
+        const code = error.code;
+        if (code !== 'ENOENT' && code !== 'ENOTDIR')
+            throw error;
+        // Target does not exist yet (write/create). Anchor against the
+        // parent's realpath so the new file we are about to create stays
+        // inside the workspace.
+        let realParent;
+        try {
+            realParent = realpathSync.native(resolve(target, '..'));
+        }
+        catch (parentError) {
+            const parentCode = parentError.code;
+            if (parentCode !== 'ENOENT' && parentCode !== 'ENOTDIR')
+                throw parentError;
+            throw new Error(`Path escapes workspace (missing parent): ${inputPath}`);
+        }
+        realTarget = resolve(realParent, basename(target));
+    }
+    if (!isInsideWorkspace(realTarget, realRoot)) {
+        throw new Error(`Path escapes workspace: ${inputPath}`);
+    }
+    return target;
+}
+function isInsideWorkspace(child, workspaceRoot) {
+    if (child === workspaceRoot)
+        return true;
+    const rel = relative(workspaceRoot, child);
+    return Boolean(rel) && !rel.startsWith('..') && rel !== '..';
+}
+//# sourceMappingURL=path-security.js.map