@pugi/cli 0.1.0-alpha.10

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

@@ -0,0 +1,227 @@
+/**
+ * REPL slash command registry — Sprint α5.7, expanded α6.14 wave 2.
+ *
+ * The REPL input box surfaces a palette of slash commands the operator
+ * can run from inside a persistent session. The wave-2 expansion (CEO
+ * 2026-05-25) grows the surface from 6 to 20 commands so the `/help`
+ * overlay matches the breadth Claude Code / Codex CLI operators expect.
+ *
+ * The registry is pure: each `parseSlashCommand` call returns a
+ * `SlashCommandResult` describing what the REPL session should do next.
+ * The session module owns the side effects (network calls, dispatcher
+ * invocation, exit, transcript clear). Keeping the surface pure lets
+ * the unit test exercise every shape without standing up an Ink runtime
+ * or an Anvil endpoint.
+ *
+ * Tiering (per CEO wave-2 spec):
+ *
+ *   Tier 1 — wired against real state (3 + existing 6 = 9 wired):
+ *     brief, agents, stop, help, quit, web, clear, version, jobs.
+ *
+ *   Tier 2 — best-effort wiring against existing surfaces (3):
+ *     diff, cost, status.
+ *
+ *   Tier 3 — deterministic stubs ("coming in αX.Y") (8):
+ *     compact, resume, memory, config, privacy, budget, mcp, undo.
+ *
+ * Brand voice (brandbook §08): power words `brief / dispatch / stop /
+ * agents / quit / shipped`. Tagline `Brief it. It ships.` reserved for
+ * `/quit` confirmation and `/help` footer — never inline.
+ */
+import { listRoles } from '../agents/registry.js';
+/**
+ * Deterministic stub copy returned by the Tier 3 commands. Spec'd
+ * inline so the unit test can pin the exact text without poking at
+ * the help overlay. The version tag at the end maps to the sprint we
+ * intend to land the real wiring in.
+ */
+export const SLASH_STUB_MESSAGES = Object.freeze({
+    brief: '',
+    agents: '',
+    stop: '',
+    help: '',
+    quit: '',
+    web: '',
+    clear: '',
+    version: '',
+    jobs: '',
+    diff: '',
+    cost: '',
+    status: '',
+    compact: 'Manual context compaction lands in α6.5.',
+    resume: 'Resume last session lands in α6.4 once SQLite session.db lands.',
+    memory: 'Session memory editor lands in α6.5.',
+    config: 'Run `pugi config list` from a fresh shell for the full surface; in-REPL editor lands in α6.5.',
+    privacy: 'Run `pugi privacy show` from a fresh shell; in-REPL toggle lands in α6.5.',
+    budget: 'Run `pugi budget` from a fresh shell; in-REPL summary lands in α6.5.',
+    mcp: 'Run `pugi config mcp list` from a fresh shell; in-REPL palette lands in α6.5.',
+    undo: 'Run `pugi undo` from a fresh shell; in-REPL undo lands in α6.5.',
+});
+export const SLASH_COMMAND_HELP = Object.freeze([
+    // Workforce dispatch
+    { name: 'brief', args: '<text>', gloss: 'Dispatch a brief to the workforce', group: 'Workforce dispatch' },
+    { name: 'agents', args: '', gloss: 'List the on-watch agent roster', group: 'Workforce dispatch' },
+    { name: 'stop', args: '<persona>', gloss: 'Stop one agent by persona slug', group: 'Workforce dispatch' },
+    { name: 'jobs', args: '', gloss: 'List background jobs', group: 'Workforce dispatch' },
+    // Session
+    { name: 'clear', args: '', gloss: 'Clear conversation pane', group: 'Session' },
+    { name: 'resume', args: '', gloss: 'Resume last session  (α6.4)', group: 'Session', stub: true },
+    { name: 'compact', args: '', gloss: 'Manual context compaction  (α6.5)', group: 'Session', stub: true },
+    { name: 'memory', args: '', gloss: 'Session memory editor  (α6.5)', group: 'Session', stub: true },
+    // Pugi tools
+    { name: 'web', args: '<url>', gloss: 'Fetch a URL into context', group: 'Pugi tools' },
+    { name: 'diff', args: '', gloss: 'Show pending diff', group: 'Pugi tools' },
+    { name: 'cost', args: '', gloss: 'Token usage + budget', group: 'Pugi tools' },
+    { name: 'status', args: '', gloss: 'Backend + tenant status', group: 'Pugi tools' },
+    // Settings
+    { name: 'config', args: '', gloss: 'Show config', group: 'Settings', stub: true },
+    { name: 'privacy', args: '', gloss: 'Show privacy mode', group: 'Settings', stub: true },
+    { name: 'budget', args: '', gloss: 'Show usage budget', group: 'Settings', stub: true },
+    { name: 'mcp', args: '', gloss: 'List MCP servers', group: 'Settings', stub: true },
+    { name: 'undo', args: '', gloss: 'Undo last write', group: 'Settings', stub: true },
+    // Meta
+    { name: 'help', args: '', gloss: 'Show this help overlay', group: 'Meta' },
+    { name: 'version', args: '', gloss: 'Show CLI version', group: 'Meta' },
+    { name: 'quit', args: '', gloss: 'Exit the REPL', group: 'Meta' },
+]);
+/**
+ * Ordered list of groups. Drives the `/help` overlay sectioning so the
+ * operator reads commands by intent (dispatch first, meta last).
+ */
+export const SLASH_COMMAND_GROUPS = Object.freeze([
+    'Workforce dispatch',
+    'Session',
+    'Pugi tools',
+    'Settings',
+    'Meta',
+]);
+/**
+ * Parse one line of input from the REPL. The contract:
+ *
+ *   - Empty / whitespace-only input returns `noop` with the original
+ *     text so the REPL can ignore it without printing anything.
+ *   - Input that does not start with `/` is treated as an implicit
+ *     `/brief <text>` — the most-common operator action.
+ *   - `/<name> [args]` resolves the name against the registry; unknown
+ *     names return `error` so the REPL can render a one-line tip
+ *     instead of silently dropping the input.
+ *   - Tier 3 stubs return `{ kind: 'stub', name, message }` so the REPL
+ *     can render the deterministic "coming in αX.Y" copy uniformly.
+ *
+ * The function never throws. Bad input maps to a structured result the
+ * REPL can render — the alternative (throwing from a keystroke handler)
+ * would unmount Ink mid-frame.
+ */
+export function parseSlashCommand(input) {
+    const trimmed = input.trim();
+    if (trimmed.length === 0) {
+        return { kind: 'noop', text: '' };
+    }
+    if (!trimmed.startsWith('/')) {
+        return { kind: 'dispatch', brief: trimmed };
+    }
+    // `/` with no name → render help overlay so the operator discovers
+    // the command palette without typing `/help`.
+    if (trimmed === '/') {
+        return { kind: 'help' };
+    }
+    const space = trimmed.indexOf(' ');
+    const head = space === -1 ? trimmed.slice(1) : trimmed.slice(1, space);
+    const tail = space === -1 ? '' : trimmed.slice(space + 1).trim();
+    const name = head.toLowerCase();
+    switch (name) {
+        case 'brief': {
+            if (tail.length === 0) {
+                return { kind: 'error', message: 'Usage: /brief <text>' };
+            }
+            return { kind: 'dispatch', brief: tail };
+        }
+        case 'agents':
+        case 'agent':
+        case 'roster': {
+            return { kind: 'roster' };
+        }
+        case 'stop':
+        case 'kill': {
+            if (tail.length === 0) {
+                return {
+                    kind: 'error',
+                    message: `Usage: /stop <persona> (try one of: ${listRoles().join(', ')})`,
+                };
+            }
+            return { kind: 'stop', persona: tail.toLowerCase() };
+        }
+        case 'help':
+        case '?': {
+            return { kind: 'help' };
+        }
+        case 'quit':
+        case 'exit':
+        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 };
+        }
+        case 'clear':
+        case 'cls': {
+            return { kind: 'clear' };
+        }
+        case 'version':
+        case 'v': {
+            return { kind: 'version' };
+        }
+        case 'jobs': {
+            return { kind: 'jobs' };
+        }
+        case 'diff': {
+            return { kind: 'diff' };
+        }
+        case 'cost': {
+            return { kind: 'cost' };
+        }
+        case 'status': {
+            return { kind: 'status' };
+        }
+        case 'compact':
+        case 'resume':
+        case 'memory':
+        case 'config':
+        case 'privacy':
+        case 'budget':
+        case 'mcp':
+        case 'undo': {
+            return {
+                kind: 'stub',
+                name: name,
+                message: SLASH_STUB_MESSAGES[name],
+            };
+        }
+        default: {
+            return {
+                kind: 'error',
+                message: `Unknown command /${head}. Try /help for the palette.`,
+            };
+        }
+    }
+}
+/**
+ * Filter SLASH_COMMAND_HELP rows whose name starts with the typed
+ * prefix. The REPL input box uses this to render an inline palette
+ * after the operator types `/`.
+ *
+ * Matching is case-insensitive; the prefix is normalized to lowercase
+ * before comparison so the operator can type `/HELP` and still see
+ * suggestions.
+ */
+export function matchSlashPrefix(prefix) {
+    const normalized = prefix.toLowerCase().replace(/^\//, '');
+    if (normalized.length === 0)
+        return SLASH_COMMAND_HELP;
+    return SLASH_COMMAND_HELP.filter((row) => row.name.startsWith(normalized));
+}
+//# sourceMappingURL=slash-commands.js.map

package/dist/core/repl/workspace-context.js

@@ -0,0 +1,113 @@
+/**
+ * Workspace context resolver — Sprint α6.14 wave 4.
+ *
+ * Reads the operator's cwd and synthesises the workspace bundle the CLI
+ * forwards to admin-api on POST /api/pugi/sessions. Mira's prompt v1.1
+ * consumes the bundle so "what repo is this?" / "а изучи репо…" answers
+ * from the live cwd instead of bouncing back "репо не привязано" (CEO
+ * dogfood 2026-05-25).
+ *
+ * Three fields:
+ *
+ *   - `workspaceCwd`     — absolute path the CLI was launched from.
+ *   - `workspaceSlug`    — a stable short identifier (slugForCwd).
+ *   - `workspaceSummary` — first ~200 chars of `.pugi/PUGI.md` if the
+ *                          repo has one, else the directory basename.
+ *
+ * The helper is pure-ish (reads the filesystem but does not mutate it)
+ * so the production caller in `runtime/cli.ts` can call it eagerly at
+ * REPL launch without touching the network. Tests pass an explicit cwd
+ * + `fs` stub so the resolver stays deterministic.
+ *
+ * Failure mode: any FS error (permission denied, missing PUGI.md,
+ * symlink loop) returns the basename fallback. The CLI never bubbles
+ * the error to the operator — workspace context is a best-effort hint,
+ * not a precondition for opening the session.
+ */
+import { existsSync, readFileSync, statSync } from 'node:fs';
+import { basename, resolve as resolvePath } from 'node:path';
+import { slugForCwd } from './history.js';
+/** Cap on the PUGI.md head we forward. Mirrors the admin-api clamp. */
+const PUGI_MD_HEAD_LIMIT = 200;
+/**
+ * Resolve a `ReplWorkspaceContext` from the operator's working directory.
+ * Returns a bundle with at least `workspaceCwd` + `workspaceSlug` +
+ * `workspaceSummary` populated. The summary is the PUGI.md head when
+ * available, else the directory basename.
+ */
+export function resolveWorkspaceContext(cwd) {
+    const normalised = resolvePath(cwd);
+    const slug = slugForCwd(normalised);
+    const summary = readPugiSummary(normalised) ?? basename(normalised) ?? 'workspace';
+    return {
+        workspaceCwd: normalised,
+        workspaceSlug: slug,
+        workspaceSummary: summary,
+    };
+}
+/**
+ * Read the first ~200 chars of `.pugi/PUGI.md` if the file exists. The
+ * project's own description is the highest-signal one-line summary we
+ * can hand to Mira — `pugi init` writes it on workspace creation, and
+ * the operator may have edited it since.
+ *
+ * Returns null on any FS error so the caller falls back to the
+ * basename. We never throw — workspace context is best-effort.
+ */
+function readPugiSummary(cwd) {
+    const candidate = resolvePath(cwd, '.pugi', 'PUGI.md');
+    try {
+        if (!existsSync(candidate))
+            return null;
+        const st = statSync(candidate);
+        if (!st.isFile())
+            return null;
+        // Cap the read at 2 KB — even a malformed PUGI.md will not be
+        // bigger than that's worth on a one-line summary, and capping
+        // bounds the slice cost on a giant file.
+        const raw = readFileSync(candidate, 'utf8').slice(0, 2048);
+        return summariseMarkdown(raw);
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Reduce a PUGI.md head to one short summary line: strip the front-
+ * matter and the leading H1 marker, take the first non-empty line,
+ * cap at PUGI_MD_HEAD_LIMIT. Whitespace collapses to single spaces so
+ * the summary survives the admin-api clamp without weird wrap.
+ */
+export function summariseMarkdown(raw) {
+    if (!raw || raw.trim().length === 0)
+        return null;
+    const body = stripFrontmatter(raw);
+    const lines = body.split(/\r?\n/);
+    for (const line of lines) {
+        // Strip leading `#` markers + trim whitespace. A heading like
+        // "# My Project" becomes "My Project".
+        const stripped = line.replace(/^#+\s*/, '').trim();
+        if (stripped.length === 0)
+            continue;
+        const oneLine = stripped.replace(/\s+/g, ' ');
+        return oneLine.length > PUGI_MD_HEAD_LIMIT
+            ? oneLine.slice(0, PUGI_MD_HEAD_LIMIT)
+            : oneLine;
+    }
+    return null;
+}
+/**
+ * Drop a YAML front-matter block (`---\n…\n---`) from the head of a
+ * Markdown file. Mira does not need to see the metadata; the prose body
+ * carries the project description.
+ */
+function stripFrontmatter(raw) {
+    if (!raw.startsWith('---'))
+        return raw;
+    const end = raw.indexOf('\n---', 3);
+    if (end === -1)
+        return raw;
+    const afterFrontmatter = raw.slice(end + 4);
+    return afterFrontmatter.replace(/^\r?\n/, '');
+}
+//# sourceMappingURL=workspace-context.js.map

package/dist/core/session.js

@@ -0,0 +1,258 @@
+import { randomUUID } from 'node:crypto';
+import { appendFileSync, existsSync, mkdirSync } from 'node:fs';
+import { resolve } from 'node:path';
+export function openSession(root) {
+    const pugiDir = resolve(root, '.pugi');
+    const enabled = existsSync(pugiDir);
+    const id = `local-${Date.now()}-${randomUUID()}`;
+    const eventsPath = resolve(pugiDir, 'events.jsonl');
+    if (enabled) {
+        mkdirSync(pugiDir, { recursive: true });
+        appendEvent({ id: randomUUID(), sessionId: id, timestamp: now(), type: 'session', name: 'created' }, eventsPath);
+    }
+    return {
+        id,
+        root,
+        pugiDir,
+        eventsPath,
+        enabled,
+    };
+}
+export function recordCommandStarted(session, command) {
+    if (!session.enabled)
+        return;
+    appendEvent({
+        id: randomUUID(),
+        sessionId: session.id,
+        timestamp: now(),
+        type: 'session',
+        name: 'command_started',
+        command,
+    }, session.eventsPath);
+}
+export function recordCommandCompleted(session, command, status) {
+    if (!session.enabled)
+        return;
+    appendEvent({
+        id: randomUUID(),
+        sessionId: session.id,
+        timestamp: now(),
+        type: 'session',
+        name: 'command_completed',
+        command,
+        status,
+    }, session.eventsPath);
+}
+export function recordToolCall(session, tool, inputSummary) {
+    const id = randomUUID();
+    if (!session.enabled)
+        return id;
+    appendEvent({
+        id,
+        sessionId: session.id,
+        timestamp: now(),
+        type: 'tool_call',
+        tool,
+        inputSummary,
+    }, session.eventsPath);
+    return id;
+}
+export function recordToolResult(session, toolCallId, status, outputSummary) {
+    if (!session.enabled)
+        return;
+    appendEvent({
+        id: randomUUID(),
+        sessionId: session.id,
+        timestamp: now(),
+        type: 'tool_result',
+        toolCallId,
+        status,
+        outputSummary,
+    }, session.eventsPath);
+}
+export function recordFileMutation(session, input) {
+    if (!session.enabled)
+        return;
+    appendEvent({
+        id: randomUUID(),
+        sessionId: session.id,
+        timestamp: now(),
+        type: 'file_mutation',
+        ...input,
+    }, session.eventsPath);
+}
+export function recordHookInvoked(session, input) {
+    if (!session.enabled)
+        return;
+    appendEvent({
+        id: randomUUID(),
+        sessionId: session.id,
+        timestamp: now(),
+        type: 'hook.invoked',
+        event: input.event,
+        matchSummary: input.matchSummary,
+        runSummary: input.runSummary,
+    }, session.eventsPath);
+}
+export function recordHookResult(session, input) {
+    if (!session.enabled)
+        return;
+    appendEvent({
+        id: randomUUID(),
+        sessionId: session.id,
+        timestamp: now(),
+        type: 'hook.result',
+        event: input.event,
+        ok: input.ok,
+        exitCode: input.exitCode,
+        elapsedMs: input.elapsedMs,
+        stdoutLen: input.stdoutLen,
+        stderrLen: input.stderrLen,
+    }, session.eventsPath);
+}
+export function recordHookSkipped(session, input) {
+    if (!session.enabled)
+        return;
+    appendEvent({
+        id: randomUUID(),
+        sessionId: session.id,
+        timestamp: now(),
+        type: 'hook.skipped',
+        event: input.event,
+        reason: input.reason,
+    }, session.eventsPath);
+}
+/**
+ * Record a `subagent.spawned` event in the session audit log. Inputs
+ * arrive untyped (the dispatcher emits JSON to stay decoupled from this
+ * module); the recorder validates the role and isolation at the typed
+ * audit-event union boundary, so a malformed role would fail at the
+ * `AuditEvent` cast site rather than silently writing garbage. The cast
+ * itself is the load-bearing check: `assertSubagentRole` and
+ * `assertSubagentIsolation` narrow at runtime.
+ */
+export function recordSubagentSpawned(session, input) {
+    if (!session.enabled)
+        return;
+    appendEvent({
+        id: randomUUID(),
+        sessionId: session.id,
+        timestamp: now(),
+        type: 'subagent.spawned',
+        taskId: input.taskId,
+        role: assertSubagentRole(input.role),
+        personaSlug: input.personaSlug,
+        parentSessionId: input.parentSessionId,
+        isolation: assertSubagentIsolation(input.isolation),
+    }, session.eventsPath);
+}
+export function recordSubagentToolCall(session, input) {
+    if (!session.enabled)
+        return;
+    appendEvent({
+        id: randomUUID(),
+        sessionId: session.id,
+        timestamp: now(),
+        type: 'subagent.tool_call',
+        taskId: input.taskId,
+        role: assertSubagentRole(input.role),
+        personaSlug: input.personaSlug,
+        toolName: input.toolName,
+        toolCallId: input.toolCallId,
+    }, session.eventsPath);
+}
+export function recordSubagentCompleted(session, input) {
+    if (!session.enabled)
+        return;
+    appendEvent({
+        id: randomUUID(),
+        sessionId: session.id,
+        timestamp: now(),
+        type: 'subagent.completed',
+        taskId: input.taskId,
+        role: assertSubagentRole(input.role),
+        personaSlug: input.personaSlug,
+        toolCallCount: input.toolCallCount,
+        tokensIn: input.tokensIn,
+        tokensOut: input.tokensOut,
+        durationMs: input.durationMs,
+    }, session.eventsPath);
+}
+export function recordSubagentBlocked(session, input) {
+    if (!session.enabled)
+        return;
+    appendEvent({
+        id: randomUUID(),
+        sessionId: session.id,
+        timestamp: now(),
+        type: 'subagent.blocked',
+        taskId: input.taskId,
+        role: assertSubagentRole(input.role),
+        personaSlug: input.personaSlug,
+        reason: assertSubagentBlockedReason(input.reason),
+        detail: input.detail,
+    }, session.eventsPath);
+}
+export function recordSubagentFailed(session, input) {
+    if (!session.enabled)
+        return;
+    appendEvent({
+        id: randomUUID(),
+        sessionId: session.id,
+        timestamp: now(),
+        type: 'subagent.failed',
+        taskId: input.taskId,
+        role: assertSubagentRole(input.role),
+        personaSlug: input.personaSlug,
+        error: input.error,
+    }, session.eventsPath);
+}
+const SUBAGENT_ROLES = new Set([
+    'orchestrator',
+    'architect',
+    'coder',
+    'verifier',
+    'reviewer',
+    'researcher',
+    'release',
+    'devops',
+    'design_qa',
+]);
+const SUBAGENT_ISOLATIONS = new Set([
+    'prompt_only',
+    'shared_fs_readonly',
+    'shared_fs_serialized',
+    'worktree',
+    'remote_vm',
+]);
+const SUBAGENT_BLOCKED_REASONS = new Set([
+    'budget_exhausted',
+    'plan_mode_refused',
+    'permission_denied',
+    'tool_unavailable',
+]);
+function assertSubagentRole(value) {
+    if (!SUBAGENT_ROLES.has(value)) {
+        throw new Error(`recordSubagent*: unknown role '${value}'`);
+    }
+    return value;
+}
+function assertSubagentIsolation(value) {
+    if (!SUBAGENT_ISOLATIONS.has(value)) {
+        throw new Error(`recordSubagent*: unknown isolation '${value}'`);
+    }
+    return value;
+}
+function assertSubagentBlockedReason(value) {
+    if (!SUBAGENT_BLOCKED_REASONS.has(value)) {
+        throw new Error(`recordSubagent*: unknown blocked reason '${value}'`);
+    }
+    return value;
+}
+function appendEvent(event, eventsPath) {
+    appendFileSync(eventsPath, `${JSON.stringify(event)}\n`, { encoding: 'utf8', mode: 0o600 });
+}
+function now() {
+    return new Date().toISOString();
+}
+//# sourceMappingURL=session.js.map

package/dist/core/settings.js

@@ -0,0 +1,59 @@
+import { existsSync, readFileSync } from 'node:fs';
+import { resolve } from 'node:path';
+import { z } from 'zod';
+const pugiSettingsSchema = z.object({
+    schema: z.number().int().positive().default(1),
+    workflow: z
+        .object({
+        brand: z.string().default('pugi'),
+        legacyName: z.string().optional(),
+        approvals: z.enum(['auto', 'manual']).default('auto'),
+        notAutomatic: z.array(z.string()).default([]),
+        defaultBaseBranch: z.string().default('dev'),
+        branchPrefixes: z.array(z.string()).default(['feature', 'fix', 'refactor', 'chore']),
+        aiCoAuthorTrailers: z.boolean().default(false),
+    })
+        .default({}),
+    permissions: z
+        .object({
+        mode: z.enum(['plan', 'ask', 'acceptEdits', 'auto', 'dontAsk', 'bypassPermissions']).default('auto'),
+        allow: z.array(z.string()).default([]),
+        deny: z.array(z.string()).default([]),
+        notAutomatic: z.array(z.string()).default([]),
+    })
+        .default({}),
+    privacy: z
+        .object({
+        mode: z.enum(['balanced', 'embeddings-only', 'airgapped']).default('balanced'),
+        telemetry: z.enum(['off', 'anonymous', 'community']).default('off'),
+    })
+        .default({}),
+    artifacts: z
+        .object({
+        defaultPath: z.string().default('.pugi/artifacts'),
+        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');
+    if (!existsSync(settingsPath)) {
+        return pugiSettingsSchema.parse({});
+    }
+    const parsed = JSON.parse(readFileSync(settingsPath, 'utf8'));
+    return pugiSettingsSchema.parse(parsed);
+}
+//# sourceMappingURL=settings.js.map