@pugi/cli 0.1.0-alpha.5 → 0.1.0-alpha.7

package/dist/core/repl/history.js

@@ -0,0 +1,172 @@
+/**
+ * Persistent REPL history (per-workspace) - Sprint α6.14.
+ *
+ * Stores submitted briefs in `~/.pugi/history/<workspace-slug>.jsonl`,
+ * one JSON object per line. The format is line-delimited JSON so the
+ * file can be appended to atomically (single `write(2)` per entry on
+ * Linux/macOS for entries < PIPE_BUF) and tailed by humans without a
+ * parser. Per-workspace separation lets the operator switch repos and
+ * keep brief history contextual: `brief: fix the cabinet sidebar 401`
+ * does not bleed into the agents repo.
+ *
+ * Contract:
+ *
+ *   - `append({ home, workspaceSlug, brief })` writes one line. Dedups
+ *     a brief that is identical to the immediately preceding entry
+ *     (most common operator pattern: Up + Enter to re-run).
+ *   - `read({ home, workspaceSlug })` returns entries oldest-first so
+ *     the caller can navigate with `index = entries.length - 1` for
+ *     "most recent" semantics.
+ *   - The file is capped at MAX_ENTRIES; on overflow we keep the most
+ *     recent slice and rewrite. Cheap because briefs are short text
+ *     and the cap is 1000.
+ *   - `slugForCwd(cwd)` normalises a working directory into a safe
+ *     filename component (alphanumerics + `-`, lowercase, slashes
+ *     collapsed). Empty cwd resolves to `default`.
+ *   - Failures (missing $HOME, disk full, EACCES) NEVER throw. History
+ *     is operator comfort, not a contract surface; degrading to "no
+ *     history this session" is correct.
+ *
+ * Brand voice: file is operator-facing if they `cat` it, so the JSON
+ * keys stay readable English (`brief`, `ts`). No forbidden words.
+ */
+import { existsSync, mkdirSync, readFileSync, writeFileSync, appendFileSync, renameSync, unlinkSync, } from 'node:fs';
+import { homedir } from 'node:os';
+import { dirname, join } from 'node:path';
+/** Cap on stored entries per workspace. Drops oldest on overflow. */
+export const MAX_HISTORY_ENTRIES = 1000;
+/**
+ * Compute the on-disk path for a given workspace slug. Tests rely on
+ * this to assert per-workspace isolation without re-implementing the
+ * directory math.
+ */
+export function historyPath(io) {
+    const home = io.home ?? homedir();
+    const safe = sanitiseSlug(io.workspaceSlug);
+    return join(home, '.pugi', 'history', `${safe}.jsonl`);
+}
+/**
+ * Append a brief to history. Dedups consecutive identical entries.
+ * Returns the entry that was written, or `null` when the entry was
+ * deduped or the brief was empty.
+ */
+export function append(input) {
+    const brief = input.brief.trim();
+    if (brief.length === 0)
+        return null;
+    const path = historyPath(input);
+    try {
+        ensureDir(dirname(path));
+    }
+    catch {
+        return null;
+    }
+    const existing = read({ home: input.home, workspaceSlug: input.workspaceSlug });
+    const last = existing[existing.length - 1];
+    if (last && last.brief === brief) {
+        return null;
+    }
+    const ts = (input.now ?? (() => new Date()))().toISOString();
+    const entry = { ts, brief };
+    // Overflow path: combined length > cap means we trim before rewrite.
+    // Write to a sibling tmp file and renameSync over the target so
+    // concurrent CLI instances in the same workspace cannot observe a
+    // half-written file or race a parallel appendFileSync into oblivion.
+    // POSIX renameSync is atomic within a directory; on Windows fs.rename
+    // is atomic too as long as both paths are on the same volume (the tmp
+    // sibling guarantees that). P2 fix from PR #335 triple-review.
+    if (existing.length + 1 > MAX_HISTORY_ENTRIES) {
+        const trimmed = [...existing.slice(existing.length + 1 - MAX_HISTORY_ENTRIES), entry];
+        const tmpPath = `${path}.tmp`;
+        try {
+            writeFileSync(tmpPath, trimmed.map(serialize).join('\n') + '\n', { mode: 0o600 });
+            renameSync(tmpPath, path);
+        }
+        catch {
+            // Best-effort cleanup of the orphan tmp file; never throw out.
+            try {
+                unlinkSync(tmpPath);
+            }
+            catch {
+                /* ignore — tmp file may not exist yet */
+            }
+            return null;
+        }
+        return entry;
+    }
+    try {
+        appendFileSync(path, serialize(entry) + '\n', { mode: 0o600 });
+    }
+    catch {
+        return null;
+    }
+    return entry;
+}
+/**
+ * Read history for a workspace, oldest-first. Returns `[]` when the
+ * file is missing, unreadable, or empty. Malformed lines are dropped
+ * silently - one bad line should not nuke the whole history.
+ */
+export function read(io) {
+    const path = historyPath(io);
+    if (!existsSync(path))
+        return [];
+    let raw;
+    try {
+        raw = readFileSync(path, 'utf8');
+    }
+    catch {
+        return [];
+    }
+    const out = [];
+    for (const line of raw.split('\n')) {
+        const trimmed = line.trim();
+        if (trimmed.length === 0)
+            continue;
+        try {
+            const parsed = JSON.parse(trimmed);
+            if (typeof parsed === 'object' &&
+                parsed !== null &&
+                typeof parsed.brief === 'string' &&
+                typeof parsed.ts === 'string') {
+                out.push({
+                    ts: parsed.ts,
+                    brief: parsed.brief,
+                });
+            }
+        }
+        catch {
+            // Drop malformed line.
+        }
+    }
+    return out;
+}
+/**
+ * Normalise a cwd or workspace name into a safe filename component.
+ * Lowercase, alphanumerics + `-` only. Slashes become `-`. Empty input
+ * resolves to `default` so we never produce an empty filename.
+ */
+export function slugForCwd(cwd) {
+    if (!cwd || cwd.trim().length === 0)
+        return 'default';
+    // Strip leading slash so `/Users/foo` becomes `users-foo`.
+    const normalised = cwd
+        .replace(/^[/\\]+/, '')
+        .replace(/[/\\]+/g, '-')
+        .toLowerCase();
+    return sanitiseSlug(normalised);
+}
+function sanitiseSlug(raw) {
+    const cleaned = raw.replace(/[^a-z0-9-]/gi, '-').toLowerCase().replace(/-+/g, '-');
+    const trimmed = cleaned.replace(/^-+|-+$/g, '');
+    return trimmed.length === 0 ? 'default' : trimmed;
+}
+function serialize(entry) {
+    return JSON.stringify(entry);
+}
+function ensureDir(dir) {
+    if (existsSync(dir))
+        return;
+    mkdirSync(dir, { recursive: true, mode: 0o700 });
+}
+//# sourceMappingURL=history.js.map

package/dist/core/repl/kill-ring.js

@@ -0,0 +1,138 @@
+/**
+ * Kill ring for the REPL input - Sprint α6.14.
+ *
+ * Tiny LIFO buffer that backs the readline-style kill commands:
+ *
+ *   Ctrl+U  - kill from cursor to line start
+ *   Ctrl+K  - kill from cursor to line end
+ *   Ctrl+W  - kill word backwards (whitespace + punctuation delimiter)
+ *   Ctrl+Y  - yank the most recent kill at the cursor
+ *
+ * The ring is bounded (MAX_RING_ENTRIES = 10) so the operator's
+ * recent kills are reachable without leaking memory across long
+ * sessions. We do NOT implement Meta+Y (cycle yanks) at this layer -
+ * sticking to the most-recent-yank keeps the input box logic small
+ * and matches the bash default for new operators.
+ *
+ * The module is pure functional: every operation returns a NEW ring,
+ * so the input box can stash one in `useState` without mutation
+ * worries. Empty slices are no-ops (we do not push empty strings) so
+ * Ctrl+U at column 0 does not pollute the ring with `""`.
+ */
+export const MAX_RING_ENTRIES = 10;
+export const EMPTY_KILL_RING = { entries: [] };
+/**
+ * Push a slice into the ring. Returns a new ring with the slice at
+ * the front; older entries shift right and the tail is dropped if
+ * the cap is exceeded. Empty / whitespace-only slices are a no-op so
+ * the ring stays meaningful.
+ */
+export function push(ring, slice) {
+    if (slice.length === 0)
+        return ring;
+    const next = [slice, ...ring.entries];
+    return { entries: next.slice(0, MAX_RING_ENTRIES) };
+}
+/**
+ * Read the most-recent entry without mutating the ring. Returns
+ * `null` when the ring is empty so the caller can decide whether to
+ * beep, no-op, or fall through to plain insert.
+ */
+export function yank(ring) {
+    return ring.entries.length > 0 ? ring.entries[0] : null;
+}
+/**
+ * Word delimiter used by Ctrl+W. Whitespace + ASCII punctuation,
+ * matching the readline default. We treat `_` and `-` as part of the
+ * word so kebab-case and snake_case identifiers behave as one token
+ * (the brief frequently mentions filenames + symbols).
+ */
+const WORD_DELIMITERS = new Set([
+    ' ', '\t', '\n',
+    '.', ',', ';', ':',
+    '/', '\\',
+    '!', '?', '@', '#', '$', '%', '^', '&', '*',
+    '(', ')', '[', ']', '{', '}', '<', '>',
+    '"', "'", '`',
+    '=', '+', '|', '~',
+]);
+/**
+ * Compute the start of the previous word given a cursor position.
+ * Walks LEFT from `cursor - 1`, skipping any delimiters that
+ * immediately precede the cursor (so Ctrl+W at the end of `foo `
+ * still kills `foo`), then continues left until it hits the next
+ * delimiter or the start of the line.
+ *
+ * Returns the offset BEFORE which the kill should start (i.e. the
+ * slice to remove is `line.slice(start, cursor)`).
+ */
+export function previousWordStart(line, cursor) {
+    let i = Math.min(cursor, line.length) - 1;
+    // Skip trailing delimiters.
+    while (i >= 0 && WORD_DELIMITERS.has(line[i]))
+        i -= 1;
+    // Walk through the word.
+    while (i >= 0 && !WORD_DELIMITERS.has(line[i]))
+        i -= 1;
+    return i + 1;
+}
+/**
+ * Apply a Ctrl+U kill: from cursor to line start. Returns the new
+ * line + cursor + ring. No-op when cursor is already at column 0.
+ */
+export function killToLineStart(line, cursor, ring) {
+    if (cursor === 0)
+        return { line, cursor, ring };
+    const slice = line.slice(0, cursor);
+    return {
+        line: line.slice(cursor),
+        cursor: 0,
+        ring: push(ring, slice),
+    };
+}
+/**
+ * Apply a Ctrl+K kill: from cursor to line end. Returns the new
+ * line + cursor + ring. No-op when cursor is already past the last
+ * character.
+ */
+export function killToLineEnd(line, cursor, ring) {
+    if (cursor >= line.length)
+        return { line, cursor, ring };
+    const slice = line.slice(cursor);
+    return {
+        line: line.slice(0, cursor),
+        cursor,
+        ring: push(ring, slice),
+    };
+}
+/**
+ * Apply a Ctrl+W kill: from cursor back to the start of the previous
+ * word. Returns the new line + cursor + ring. No-op when cursor is
+ * at column 0.
+ */
+export function killWordBackward(line, cursor, ring) {
+    if (cursor === 0)
+        return { line, cursor, ring };
+    const start = previousWordStart(line, cursor);
+    const slice = line.slice(start, cursor);
+    return {
+        line: line.slice(0, start) + line.slice(cursor),
+        cursor: start,
+        ring: push(ring, slice),
+    };
+}
+/**
+ * Apply a Ctrl+Y yank: insert the most-recent entry at the cursor.
+ * Returns the new line + cursor unchanged when the ring is empty
+ * (the caller decides whether to surface a visual cue).
+ */
+export function yankAtCursor(line, cursor, ring) {
+    const entry = yank(ring);
+    if (entry === null)
+        return { line, cursor };
+    return {
+        line: line.slice(0, cursor) + entry + line.slice(cursor),
+        cursor: cursor + entry.length,
+    };
+}
+//# sourceMappingURL=kill-ring.js.map

package/dist/core/repl/session.js

@@ -30,6 +30,8 @@ import { randomUUID } from 'node:crypto';
 import { listRoles, getPersonaForRole } from '../agents/registry.js';
 import { evaluateCap, describeVerdict } from './cap-warning.js';
 import { parseSlashCommand } from './slash-commands.js';
+import { webFetchTool } from '../../tools/web-fetch.js';
+import { loadSettings } from '../settings.js';
 const MAX_TRANSCRIPT_ROWS = 500;
 const MAX_RECONNECT_ATTEMPTS = 10;
 const RECONNECT_BASE_MS = 250;
@@ -133,7 +135,49 @@ export class ReplSession {
                 await this.dispatchBrief(verdict.brief);
                 return verdict;
             }
+            case 'web': {
+                await this.dispatchWebFetch(verdict.url);
+                return verdict;
+            }
+        }
+    }
+    /**
+     * Fetch one URL via the web_fetch tool and inject the resulting
+     * Markdown into the transcript as an operator-attributed brief. The
+     * `<untrusted-content>` sentinel travels with the body so the Mira
+     * system prompt can refuse to follow instructions inside it.
+     *
+     * Gating: the dispatcher reads PugiSettings from disk on every
+     * call so the operator can flip `web.fetch.enabled` mid-session
+     * without restarting the REPL. The CLI's bare `--allow-fetch` flag
+     * is honored by the runtime entry point and propagates through
+     * env to keep the session module transport-free.
+     */
+    async dispatchWebFetch(url) {
+        // Malformed `.pugi/settings.json` must not crash the REPL —
+        // surface the error to the operator and treat fetch as disabled
+        // (fail-safe). The session keeps running.
+        let settings;
+        try {
+            settings = loadSettings(process.cwd());
+        }
+        catch (error) {
+            const msg = error instanceof Error ? error.message : String(error);
+            this.appendSystemLine(`web_fetch refused: failed to load .pugi/settings.json (${msg}).`);
+            return;
+        }
+        const allowFetch = (this.options.env ?? process.env).PUGI_ALLOW_FETCH === '1';
+        const result = await webFetchTool({ url }, { settings, allowFetch });
+        if (!result.ok) {
+            this.appendSystemLine(`web_fetch refused: ${result.error}`);
+            return;
         }
+        this.appendOperatorLine(`/web ${result.url}`);
+        this.appendSystemLine(`Fetched ${result.title} (${result.fetched_at}).`);
+        // Surface the Markdown body so the operator sees what landed in
+        // the brief; downstream the body is the actual dispatch payload.
+        this.appendSystemLine(result.content_md);
+        await this.dispatchBrief(`Brief from fetched page:\n\n${result.content_md}`);
     }
     /* ------------- dispatch -------------- */
     async dispatchBrief(brief) {

package/dist/core/repl/slash-commands.js

@@ -26,6 +26,7 @@ export const SLASH_COMMAND_HELP = Object.freeze([
     { name: 'stop', args: '<persona>', gloss: 'Stop one agent by persona slug' },
     { name: 'help', args: '', gloss: 'Show this help overlay' },
     { name: 'quit', args: '', gloss: 'Exit the REPL (session resumes via pugi resume)' },
+    { name: 'web', args: '<url>', gloss: 'Fetch a URL and brief Pugi on the page' },
 ]);
 /**
  * Parse one line of input from the REPL. The contract:
@@ -90,6 +91,13 @@ export function parseSlashCommand(input) {
         case 'q': {
             return { kind: 'quit' };
         }
+        case 'web':
+        case 'fetch': {
+            if (tail.length === 0) {
+                return { kind: 'error', message: 'Usage: /web <url>' };
+            }
+            return { kind: 'web', url: tail };
+        }
         default: {
             return {
                 kind: 'error',

package/dist/core/settings.js

@@ -34,6 +34,19 @@ const pugiSettingsSchema = z.object({
         promoteExplicitly: z.boolean().default(true),
     })
         .default({}),
+    // `web.fetch.enabled` gates the `pugi web` / `/web` SSRF-guarded
+    // fetcher. Default-off matches the spec posture; the schema must
+    // declare it explicitly because Zod's strict-pass strips unknown
+    // keys and would silently swallow the operator's intent.
+    web: z
+        .object({
+        fetch: z
+            .object({
+            enabled: z.boolean().optional(),
+        })
+            .optional(),
+    })
+        .optional(),
 });
 export function loadSettings(root) {
     const settingsPath = resolve(root, '.pugi/settings.json');