@pugi/cli 0.1.0-beta.21 → 0.1.0-beta.22

package/dist/core/share/uploader.js

@@ -0,0 +1,267 @@
+/**
+ * Upload paths for `pugi share` (Leak L20, 2026-05-27).
+ *
+ * Two targets:
+ *
+ *   - `gist`  shells out to `gh gist create` (requires the `gh` CLI in
+ *             PATH AND `gh auth status` ok, OR `GITHUB_TOKEN` env). The
+ *             gist is created with a fixed filename so the URL paths
+ *             stay stable across re-shares.
+ *   - `pugi`  POSTs to admin-api `/api/pugi/share`. The endpoint is NOT
+ *             present in admin-api today (2026-05-27 audit) — the
+ *             handler degrades gracefully: it surfaces a clear "endpoint
+ *             not yet wired" message and tells the operator to use
+ *             `--gist` for now. The structured payload is otherwise
+ *             ready for the server-side handler to consume; landing the
+ *             endpoint is a separate sprint.
+ *
+ * The two paths share one decision shape (`UploadResult`) so the
+ * command handler renders identical telemetry regardless of which target
+ * was chosen.
+ *
+ * Why we shell out for gist instead of using octokit: octokit would add
+ * a transitive HTTP client + ~200 KB to the npm package surface for a
+ * single feature. `gh gist create` is the operator-friendly form
+ * (already auth'd, public URL on stdout, attribution in the gist
+ * metadata) and degrades cleanly when `gh` is absent.
+ */
+import { spawn } from 'node:child_process';
+/**
+ * Default execa shim. Spawns the binary with `args`, pipes `input` into
+ * stdin if provided, captures stdout + stderr in memory. The CLI ships
+ * with `execa` already pulled for other paths; we use the lighter
+ * `child_process.spawn` here so the share module stays import-clean.
+ */
+export const defaultExecaLike = (file, args, options) => {
+    return new Promise((resolveProm, rejectProm) => {
+        const child = spawn(file, [...args], { stdio: ['pipe', 'pipe', 'pipe'] });
+        let stdout = '';
+        let stderr = '';
+        child.stdout.on('data', (chunk) => {
+            stdout += chunk.toString('utf8');
+        });
+        child.stderr.on('data', (chunk) => {
+            stderr += chunk.toString('utf8');
+        });
+        child.on('error', (err) => {
+            // ENOENT (binary missing) lands here; the caller maps it.
+            rejectProm(err);
+        });
+        child.on('close', (code) => {
+            resolveProm({ exitCode: code ?? 0, stdout, stderr });
+        });
+        if (options?.input) {
+            child.stdin.write(options.input);
+        }
+        child.stdin.end();
+    });
+};
+/**
+ * Top-level upload dispatch. The handler picks the right path and
+ * surfaces a uniform result envelope.
+ */
+export async function uploadShare(req) {
+    if (req.target === 'gist') {
+        return uploadGist(req);
+    }
+    return uploadPugi(req);
+}
+/**
+ * Gist upload. Two-step: probe `gh --version` (fast, costs nothing) to
+ * detect a missing binary cleanly, then run `gh gist create`. We pipe
+ * the markdown into stdin to avoid temp files + the OS-level argv
+ * length cap.
+ */
+async function uploadGist(req) {
+    const exec = req.execaLike ?? defaultExecaLike;
+    const description = req.description ?? `Pugi session ${req.sessionId}`;
+    try {
+        // Probe step. `gh --version` returns 0 quickly and surfaces a
+        // distinctive "command not found" via ENOENT on the reject path.
+        const probe = await exec('gh', ['--version']);
+        if (probe.exitCode !== 0) {
+            return {
+                ok: false,
+                target: 'gist',
+                reason: 'gh_not_installed',
+                message: 'gh CLI not available. Install from https://cli.github.com or use --pugi instead.',
+            };
+        }
+    }
+    catch {
+        return {
+            ok: false,
+            target: 'gist',
+            reason: 'gh_not_installed',
+            message: 'gh CLI not available. Install from https://cli.github.com or use --pugi instead.',
+        };
+    }
+    // Create the gist. `gh` reads stdin when `-` is the filename arg, which
+    // works with our `--filename` override. The `--public` flag is
+    // intentionally omitted — gists default to secret (unlisted URL), which
+    // is the right default for a session transcript. Operators who want a
+    // public gist can run `gh gist edit --add-public <id>` after the fact.
+    const createArgs = [
+        'gist',
+        'create',
+        '--filename',
+        'pugi-session.md',
+        '--desc',
+        description,
+        '-',
+    ];
+    try {
+        const result = await exec('gh', createArgs, { input: req.markdown });
+        if (result.exitCode !== 0) {
+            // Auth failure is the common case. `gh` prints "gh auth login" to
+            // stderr; we tag it specifically so the gate banner can hint.
+            const looksLikeAuth = /auth/i.test(result.stderr) || /authenticated/i.test(result.stderr);
+            return {
+                ok: false,
+                target: 'gist',
+                reason: looksLikeAuth ? 'gh_unauthenticated' : 'gh_failed',
+                message: looksLikeAuth
+                    ? 'gh is installed but not authenticated. Run `gh auth login` first.'
+                    : `gh gist create exited ${result.exitCode}: ${result.stderr.trim().slice(0, 200)}`,
+            };
+        }
+        // gh prints the URL on stdout. Trim newline + any leading whitespace.
+        const url = result.stdout.trim().split('\n').pop() ?? '';
+        if (!/^https?:\/\//.test(url)) {
+            return {
+                ok: false,
+                target: 'gist',
+                reason: 'gh_failed',
+                message: `gh did not return a URL (stdout: "${result.stdout.trim().slice(0, 200)}")`,
+            };
+        }
+        const remoteId = url.split('/').pop() ?? undefined;
+        return remoteId !== undefined
+            ? { ok: true, target: 'gist', url, remoteId }
+            : { ok: true, target: 'gist', url };
+    }
+    catch (err) {
+        const message = err instanceof Error ? err.message : String(err);
+        return {
+            ok: false,
+            target: 'gist',
+            reason: 'gh_failed',
+            message: `gh gist create threw: ${message}`,
+        };
+    }
+}
+/**
+ * Pugi.io upload. POSTs the transcript to admin-api `/api/pugi/share`.
+ * The endpoint is NOT yet wired (audit 2026-05-27); when it returns 404
+ * we surface a friendly hint instead of a stack trace. When the operator
+ * is signed-out we surface `pugi_auth_missing` so the gate banner can
+ * point at `pugi login`.
+ *
+ * The wire payload is intentionally minimal so a future server-side
+ * implementation has a stable contract to build against:
+ *
+ *   { sessionId, markdown, description?, cliVersion? }
+ *
+ * Response (when wired):
+ *
+ *   200 { ok: true, url, id }     URL is the pugi.io/share/<id> public link.
+ *   404 / 501                     endpoint not yet implemented — graceful skip.
+ *   401                           auth missing/expired — operator runs `pugi login`.
+ */
+async function uploadPugi(req) {
+    const fetchFn = req.fetchLike ?? globalThis.fetch;
+    if (typeof fetchFn !== 'function') {
+        return {
+            ok: false,
+            target: 'pugi',
+            reason: 'pugi_network_error',
+            message: 'No fetch implementation available (Node >=18 expected).',
+        };
+    }
+    if (!req.apiUrl) {
+        return {
+            ok: false,
+            target: 'pugi',
+            reason: 'pugi_auth_missing',
+            message: 'pugi.io share requires a signed-in session. Run `pugi login` and retry.',
+        };
+    }
+    const url = `${req.apiUrl.replace(/\/+$/u, '')}/api/pugi/share`;
+    const headers = {
+        'content-type': 'application/json',
+        accept: 'application/json',
+    };
+    if (req.apiToken) {
+        headers.authorization = `Bearer ${req.apiToken}`;
+    }
+    const body = JSON.stringify({
+        sessionId: req.sessionId,
+        markdown: req.markdown,
+        description: req.description ?? `Pugi session ${req.sessionId}`,
+    });
+    let res;
+    try {
+        res = await fetchFn(url, { method: 'POST', headers, body });
+    }
+    catch (err) {
+        const message = err instanceof Error ? err.message : String(err);
+        return {
+            ok: false,
+            target: 'pugi',
+            reason: 'pugi_network_error',
+            message: `pugi.io upload failed: ${message}`,
+        };
+    }
+    // 404 / 501 → endpoint not yet wired. Surface a friendly hint instead
+    // of dumping the response body.
+    if (res.status === 404 || res.status === 501) {
+        return {
+            ok: false,
+            target: 'pugi',
+            reason: 'pugi_endpoint_unimplemented',
+            message: 'pugi.io /api/pugi/share is not yet wired in admin-api. ' +
+                'Use `--gist` for now; the pugi.io upload lands in a follow-up sprint.',
+        };
+    }
+    if (res.status === 401 || res.status === 403) {
+        return {
+            ok: false,
+            target: 'pugi',
+            reason: 'pugi_auth_missing',
+            message: 'pugi.io rejected the credentials. Run `pugi login` and retry.',
+        };
+    }
+    if (!res.ok) {
+        return {
+            ok: false,
+            target: 'pugi',
+            reason: 'pugi_network_error',
+            message: `pugi.io upload returned ${res.status} ${res.statusText}.`,
+        };
+    }
+    let payload;
+    try {
+        payload = (await res.json());
+    }
+    catch (err) {
+        const message = err instanceof Error ? err.message : String(err);
+        return {
+            ok: false,
+            target: 'pugi',
+            reason: 'pugi_network_error',
+            message: `pugi.io upload returned non-JSON: ${message}`,
+        };
+    }
+    if (!payload.ok || !payload.url) {
+        return {
+            ok: false,
+            target: 'pugi',
+            reason: 'pugi_network_error',
+            message: 'pugi.io upload succeeded but the response was missing { ok, url }.',
+        };
+    }
+    return payload.id !== undefined
+        ? { ok: true, target: 'pugi', url: payload.url, remoteId: payload.id }
+        : { ok: true, target: 'pugi', url: payload.url };
+}
+//# sourceMappingURL=uploader.js.map

package/dist/core/todos/invariant.js

@@ -0,0 +1,10 @@
+/**
+ * Single-in-progress invariant constants and types — Leak L16.
+ *
+ * Kept in a separate module so the tool-bridge dispatcher and the
+ * spec layer can import the sentinel string + types without pulling
+ * in `node:fs` via `state.ts`. The sentinel prefix is stable so the
+ * engine adapter / model prompt can pattern-match on it verbatim.
+ */
+export const TODO_INVARIANT_VIOLATED = 'TODO_INVARIANT_VIOLATED';
+//# sourceMappingURL=invariant.js.map

package/dist/core/todos/state.js

@@ -0,0 +1,177 @@
+/**
+ * Workspace-scoped todo board persistence — Leak L16 (TodoWrite invariant).
+ *
+ * `todo_write` is the BATCH-replace counterpart to the granular `task_*`
+ * journal in `tools/tasks.ts`. Where `task_*` appends one journal line
+ * per mutation (session-scoped, JSONL, append-only), `todo_write` snaps
+ * the entire board to disk in one atomic write (workspace-scoped, JSON,
+ * snapshot-only). They are complementary surfaces for the same problem
+ * — `task_*` is fine-grained, `todo_write` mirrors Claude Code's
+ * TodoWrite verbatim so a model trained on that grammar speaks Pugi's
+ * variant 1:1.
+ *
+ * Single-in-progress invariant
+ * ----------------------------
+ * Claude Code TodoWrite enforces at most ONE todo `status: 'in_progress'`
+ * at a time. The invariant prevents the model from fragmenting attention
+ * across multiple parallel claims of "I am working on X right now" — a
+ * pattern that empirically produces stalled work and operator confusion
+ * about which thread is alive. We enforce the same invariant at the tool
+ * boundary: a dispatch with >1 `in_progress` rejects with
+ * `TODO_INVARIANT_VIOLATED: ...` and the board on disk is left unchanged.
+ *
+ * Persistence shape
+ * -----------------
+ * Path: `<workspaceRoot>/.pugi/todos.json` (one board per workspace).
+ * Atomic: write to `<path>.pugi-tmp-<ts>` then `renameSync` — the rename
+ * is the commit point. A crash mid-write leaves the previous snapshot
+ * intact (or, on first write, leaves the dangling tmp file which the
+ * loader ignores). Mode 0o600 — the board can contain operator task
+ * descriptions and should not be world-readable through an inherited
+ * umask.
+ *
+ * Why workspace-scoped, not session-scoped
+ * ----------------------------------------
+ * The Claude Code TodoWrite contract is "the board persists across the
+ * session". Pugi sessions are short-lived (one REPL run); the operator's
+ * mental model of the board is "this is the workspace's plan", not "this
+ * is THIS session's plan". Workspace scope matches that mental model and
+ * lets `/todos` (when wired) read the latest board even after a CLI
+ * restart. The `task_*` ledger remains session-scoped for the agent's
+ * dispatch trace.
+ */
+import { chmodSync, existsSync, mkdirSync, readFileSync, renameSync, writeFileSync, } from 'node:fs';
+import { dirname, join } from 'node:path';
+import { TODO_INVARIANT_VIOLATED } from './invariant.js';
+/** Path the board lives at. Workspace-scoped, NOT session-scoped. */
+export function todoBoardPath(ctx) {
+    return join(ctx.workspaceRoot, '.pugi', 'todos.json');
+}
+function ensureDir(path) {
+    const dir = dirname(path);
+    if (!existsSync(dir)) {
+        mkdirSync(dir, { recursive: true });
+        try {
+            chmodSync(dir, 0o700);
+        }
+        catch {
+            // Best-effort; Windows NTFS no-op. The 0o600 mode on the JSON
+            // file itself remains the primary guard.
+        }
+    }
+}
+function nowIso(ctx) {
+    return (ctx.now ? ctx.now() : new Date()).toISOString();
+}
+/**
+ * Load the current board. Returns an empty board when the file is
+ * absent or malformed — the rationale is that a corrupted state file
+ * should NOT brick the tool surface; the model can re-emit the full
+ * board on the next call. Malformed loads are silent (no throw) so a
+ * fresh workspace and a corrupted workspace look identical to the
+ * caller.
+ *
+ * The schema check is deliberately defensive: any missing field, wrong
+ * type, or unexpected status string drops the load to an empty board.
+ * The model will see `todos: []` and is free to redeclare the plan.
+ */
+export function loadTodoBoard(ctx) {
+    const path = todoBoardPath(ctx);
+    if (!existsSync(path)) {
+        return { version: 1, updatedAt: nowIso(ctx), todos: [] };
+    }
+    try {
+        const raw = readFileSync(path, 'utf8');
+        const parsed = JSON.parse(raw);
+        if (!isPlainObject(parsed))
+            return emptyBoard(ctx);
+        if (parsed.version !== 1)
+            return emptyBoard(ctx);
+        if (typeof parsed.updatedAt !== 'string')
+            return emptyBoard(ctx);
+        if (!Array.isArray(parsed.todos))
+            return emptyBoard(ctx);
+        const todos = [];
+        for (const entry of parsed.todos) {
+            if (!isPlainObject(entry))
+                return emptyBoard(ctx);
+            if (typeof entry.id !== 'string' || entry.id.length === 0)
+                return emptyBoard(ctx);
+            if (typeof entry.content !== 'string' || entry.content.length === 0) {
+                return emptyBoard(ctx);
+            }
+            if (entry.status !== 'pending' &&
+                entry.status !== 'in_progress' &&
+                entry.status !== 'completed') {
+                return emptyBoard(ctx);
+            }
+            const item = {
+                id: entry.id,
+                content: entry.content,
+                status: entry.status,
+                ...(typeof entry.activeForm === 'string' && entry.activeForm.length > 0
+                    ? { activeForm: entry.activeForm }
+                    : {}),
+            };
+            todos.push(item);
+        }
+        return { version: 1, updatedAt: parsed.updatedAt, todos };
+    }
+    catch {
+        return emptyBoard(ctx);
+    }
+}
+function emptyBoard(ctx) {
+    return { version: 1, updatedAt: nowIso(ctx), todos: [] };
+}
+function isPlainObject(value) {
+    return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+/**
+ * Persist a new board atomically. Enforces the single-in-progress
+ * invariant BEFORE touching disk so a violating dispatch never reaches
+ * the filesystem. On invariant violation, throws an Error whose message
+ * starts with `TODO_INVARIANT_VIOLATED:` (the sentinel prefix the tool
+ * dispatcher pattern-matches on).
+ *
+ * The atomic write uses tmp+rename — `writeFileSync` to a sibling tmp
+ * path, then `renameSync` onto the real file. POSIX guarantees rename is
+ * atomic within the same directory; on a crash, the operator sees the
+ * previous board (or no board at all on first write), never a torn
+ * write. Mode 0o600 is set on the tmp file so the rename inherits the
+ * restrictive mode.
+ */
+export function saveTodoBoard(ctx, todos) {
+    // Invariant check FIRST — never write a violating board.
+    const inProgress = todos.filter((t) => t.status === 'in_progress').length;
+    if (inProgress > 1) {
+        throw new Error(`${TODO_INVARIANT_VIOLATED}: ${inProgress} items in_progress simultaneously. ` +
+            `Mark all-but-one as 'pending' or 'completed'.`);
+    }
+    // Duplicate-id check — every id must be unique within the board so
+    // a `todo_get(id)` would have a single answer. The model emits ids;
+    // we refuse to persist a board that would silently shadow one.
+    const seen = new Set();
+    for (const todo of todos) {
+        if (seen.has(todo.id)) {
+            throw new Error(`TODO_DUPLICATE_ID: id "${todo.id}" appears more than once in the batch. ` +
+                `Use a stable, unique id per todo item.`);
+        }
+        seen.add(todo.id);
+    }
+    const board = {
+        version: 1,
+        updatedAt: nowIso(ctx),
+        todos: todos.map((t) => ({ ...t })),
+    };
+    const path = todoBoardPath(ctx);
+    ensureDir(path);
+    const tmp = `${path}.pugi-tmp-${Date.now()}`;
+    writeFileSync(tmp, `${JSON.stringify(board, null, 2)}\n`, {
+        encoding: 'utf8',
+        mode: 0o600,
+    });
+    renameSync(tmp, path);
+    return board;
+}
+//# sourceMappingURL=state.js.map