@pugi/cli 0.1.0-alpha.10

package/dist/core/permission.js

@@ -0,0 +1,309 @@
+import { basename, resolve } from 'node:path';
+import { classifyBash, listDestructivePatterns, } from './bash-classifier.js';
+/**
+ * Map `PermissionAction.kind` to the `HookMatch.permission` taxonomy.
+ * The hook taxonomy uses `mcp`/`subagent` slots that the permission
+ * engine does not currently emit; `workflow` has no hook-side
+ * equivalent so it falls through as undefined (any matching hook with
+ * an explicit `permission` filter will not match).
+ */
+function toHookPermission(kind) {
+    switch (kind) {
+        case 'read':
+        case 'edit':
+        case 'bash':
+        case 'network':
+        case 'mcp':
+            return kind;
+        case 'workflow':
+            return undefined;
+    }
+}
+/**
+ * Fire the `PermissionRequest` hook for the given action and decision.
+ * Caller is the permission engine's user-facing surface — when the
+ * decision is `ask`, hooks can observe (and, with `onFailure: 'block'`,
+ * pre-empt) the prompt. The hook system does NOT replace the prompt —
+ * a `block` hook simply turns the decision into a refusal that the
+ * caller surfaces as a denial.
+ *
+ * Returns true when no blocking hook objected; false when at least one
+ * `onFailure: 'block'` hook returned a non-zero exit. Callers should
+ * treat false as "deny this action".
+ */
+export async function firePermissionRequestHook(action, decision, hooks, sessionId) {
+    hooks.resetBatch();
+    const ctx = {
+        sessionId,
+        event: 'PermissionRequest',
+        tool: action.tool,
+        permission: toHookPermission(action.kind),
+        path: action.kind === 'read' || action.kind === 'edit' ? action.target : undefined,
+        payload: { action, decision },
+    };
+    const matching = hooks.listMatching(ctx);
+    const results = await hooks.fire(ctx);
+    for (let i = 0; i < matching.length; i += 1) {
+        const hook = matching[i];
+        const result = results[i];
+        if (hook && result && hook.onFailure === 'block' && !result.ok) {
+            return false;
+        }
+    }
+    return true;
+}
+const protectedBasenames = new Set([
+    '.env',
+    '.npmrc',
+    '.yarnrc',
+    '.pypirc',
+    '.gitconfig',
+    'id_rsa',
+    'id_ed25519',
+]);
+const protectedSuffixes = ['.pem', '.key', '.crt', '.p12', '.dump', '.sql'];
+/**
+ * Hard-deny list. The list of destructive substrings now lives in
+ * `bash-classifier.ts::DESTRUCTIVE_PATTERNS`; this function exposes
+ * it as a list for callers (doctor, debug tooling) that need to
+ * audit the rule set without re-running `classifyBash`.
+ *
+ * Code Reviewer P2 retro 2026-05-23: previously this list was
+ * duplicated here as `destructiveBashPatterns`. Sprint α5.2 moves it
+ * into the classifier so the permission engine and the doctor surface
+ * cannot drift.
+ */
+export function destructiveBashPatternsList() {
+    return listDestructivePatterns();
+}
+/**
+ * Class-aware bash permission decision. The matrix:
+ *
+ *                     | plan | ask | acceptEdits | auto       | dontAsk | bypass
+ *  read               | allow| allow| allow      | allow      | allow   | allow
+ *  build_test         | deny | ask  | ask        | allow      | allow*  | allow
+ *  network            | deny | ask  | ask        | ask        | allow*  | allow
+ *  write_workspace    | deny | ask  | allow      | allow      | allow*  | allow
+ *  write_protected    | deny | ask  | ask        | ask        | deny    | ask
+ *  destructive        | deny | deny | deny       | deny       | deny    | deny**
+ *  unknown            | deny | ask  | ask        | ask        | deny    | ask
+ *
+ *  * dontAsk allows non-destructive classes when no settings rule
+ *    contradicts; the bare-mode policy is encoded in the table below.
+ *  ** destructive can be unlocked ONLY when ALL three hold:
+ *      - mode === 'bypassPermissions'
+ *      - PUGI_DESTRUCTIVE_OVERRIDE === '1'
+ *      - source === 'human'
+ *    The agent loop never sets `source: 'human'`, so even a runaway
+ *    agent in bypass mode cannot trigger a destructive deletion.
+ */
+export function evaluateBashPermission(cmd, mode, ctx) {
+    const classification = classifyBash(cmd, {
+        workspaceRoot: ctx.workspaceRoot,
+        additionalDirectories: ctx.additionalDirectories,
+    });
+    return decisionForClass(classification, mode, ctx);
+}
+function decisionForClass(classification, mode, ctx) {
+    const { class: klass, reason, matched } = classification;
+    const explain = `${reason}${matched ? ` [matched=${matched}]` : ''}`;
+    if (klass === 'destructive') {
+        const overrideOk = mode === 'bypassPermissions' &&
+            ctx.source === 'human' &&
+            process.env.PUGI_DESTRUCTIVE_OVERRIDE === '1';
+        if (overrideOk) {
+            return {
+                decision: 'allow',
+                reason: `${explain}; destructive override engaged (PUGI_DESTRUCTIVE_OVERRIDE=1, human source, bypassPermissions)`,
+                source: 'mode.bypassPermissions.destructive_override',
+            };
+        }
+        return {
+            decision: 'deny',
+            reason: `${explain}; destructive class is always denied`,
+            source: 'classifier.destructive',
+        };
+    }
+    switch (klass) {
+        case 'read':
+            return { decision: 'allow', reason: explain, source: `classifier.${klass}` };
+        case 'build_test':
+            return classAwareVerdict(mode, klass, explain, {
+                plan: 'deny',
+                ask: 'ask',
+                acceptEdits: 'ask',
+                auto: 'allow',
+                dontAsk: 'allow',
+                bypassPermissions: 'allow',
+            });
+        case 'network':
+            return classAwareVerdict(mode, klass, explain, {
+                plan: 'deny',
+                ask: 'ask',
+                acceptEdits: 'ask',
+                auto: 'ask',
+                dontAsk: 'allow',
+                bypassPermissions: 'allow',
+            });
+        case 'write_workspace':
+            return classAwareVerdict(mode, klass, explain, {
+                plan: 'deny',
+                ask: 'ask',
+                acceptEdits: 'allow',
+                auto: 'allow',
+                dontAsk: 'allow',
+                bypassPermissions: 'allow',
+            });
+        case 'write_protected':
+            return classAwareVerdict(mode, klass, explain, {
+                plan: 'deny',
+                ask: 'ask',
+                acceptEdits: 'ask',
+                auto: 'ask',
+                dontAsk: 'deny',
+                bypassPermissions: 'ask',
+            });
+        case 'unknown':
+            return classAwareVerdict(mode, klass, explain, {
+                plan: 'deny',
+                ask: 'ask',
+                acceptEdits: 'ask',
+                auto: 'ask',
+                dontAsk: 'deny',
+                bypassPermissions: 'ask',
+            });
+    }
+}
+function classAwareVerdict(mode, klass, reason, table) {
+    const verdict = table[mode];
+    const source = `classifier.${klass}.${mode}`;
+    switch (verdict) {
+        case 'allow':
+            return { decision: 'allow', reason, source };
+        case 'deny':
+            return { decision: 'deny', reason: `${reason}; ${mode} mode denies ${klass}`, source };
+        case 'ask':
+            return { decision: 'ask', reason, risk: riskForClass(klass) };
+    }
+}
+function riskForClass(klass) {
+    switch (klass) {
+        case 'read':
+            return 'low';
+        case 'build_test':
+        case 'write_workspace':
+            return 'medium';
+        case 'network':
+        case 'write_protected':
+        case 'unknown':
+        case 'destructive':
+            return 'high';
+    }
+}
+export function decidePermission(action, settings, root) {
+    if (action.kind === 'bash') {
+        // Legacy callers (file-tools::bashTool, runtime/cli protected-file
+        // probe) still call `decidePermission` for bash. The class-aware
+        // engine is preferred; we route through it here so the hard-deny
+        // gate stays consistent regardless of entry point.
+        //
+        // Source defaults to 'agent' because every code path that calls
+        // `decidePermission({ kind: 'bash' })` today is reached through
+        // the engine loop. Direct human bash invocation goes through the
+        // new `evaluateBashPermission` with `source: 'human'`.
+        const decision = evaluateBashPermission(action.target, settings.permissions.mode, {
+            workspaceRoot: root,
+            additionalDirectories: [],
+            source: 'agent',
+        });
+        if (decision.decision === 'deny' && decision.source === 'classifier.destructive') {
+            // Locked-source identifier for the retro spec — the existing
+            // tests assert `source === 'hard_deny'`. Re-label so the
+            // semantic stays the same: a destructive command was blocked
+            // by the hard-deny gate.
+            return { ...decision, source: 'hard_deny' };
+        }
+        const signature = `${action.kind}:${action.target}`;
+        if (matchesAny(signature, settings.permissions.deny)) {
+            return { decision: 'deny', reason: `Denied by rule: ${signature}`, source: 'settings.deny' };
+        }
+        if (matchesAny(signature, settings.permissions.allow) && decision.decision !== 'deny') {
+            return { decision: 'allow', reason: `Allowed by rule: ${signature}`, source: 'settings.allow' };
+        }
+        return decision;
+    }
+    const protectedReason = protectedTargetReason(action, root);
+    if (protectedReason) {
+        return decisionForMode(settings.permissions.mode, protectedReason, 'protected_file', 'high');
+    }
+    const signature = `${action.kind}:${action.target}`;
+    if (matchesAny(signature, settings.permissions.deny)) {
+        return { decision: 'deny', reason: `Denied by rule: ${signature}`, source: 'settings.deny' };
+    }
+    if (matchesAny(signature, settings.permissions.notAutomatic) || matchesAny(signature, settings.workflow.notAutomatic)) {
+        return { decision: 'ask', reason: `Marked not automatic: ${signature}`, risk: 'medium' };
+    }
+    if (matchesAny(signature, settings.permissions.allow)) {
+        return { decision: 'allow', reason: `Allowed by rule: ${signature}`, source: 'settings.allow' };
+    }
+    return decisionForMode(settings.permissions.mode, `Default ${settings.permissions.mode} policy`, 'mode', riskForAction(action));
+}
+export function protectedTargetReason(action, root) {
+    if (action.kind !== 'edit' && action.kind !== 'read')
+        return null;
+    const target = resolve(root, action.target);
+    const name = basename(target);
+    if (protectedBasenames.has(name) || name.startsWith('.env.')) {
+        return `Protected file: ${action.target}`;
+    }
+    if (protectedSuffixes.some((suffix) => name.endsWith(suffix))) {
+        return `Protected file suffix: ${action.target}`;
+    }
+    if (target.includes('/.ssh/') || target.includes('/.gnupg/') || target.includes('/.aws/')) {
+        return `Protected credential path: ${action.target}`;
+    }
+    return null;
+}
+function decisionForMode(mode, reason, source, risk) {
+    switch (mode) {
+        case 'plan':
+            return risk === 'low'
+                ? { decision: 'allow', reason, source }
+                : { decision: 'deny', reason: `${reason}; plan mode blocks mutating actions`, source: 'mode.plan' };
+        case 'ask':
+            return { decision: 'ask', reason, risk };
+        case 'acceptEdits':
+            return risk === 'medium'
+                ? { decision: 'allow', reason, source: 'mode.acceptEdits' }
+                : { decision: 'ask', reason, risk };
+        case 'auto':
+            return risk === 'high' ? { decision: 'ask', reason, risk } : { decision: 'allow', reason, source: 'mode.auto' };
+        case 'dontAsk':
+            return risk === 'high'
+                ? { decision: 'deny', reason: `${reason}; dontAsk denies high-risk actions`, source: 'mode.dontAsk' }
+                : { decision: 'allow', reason, source: 'mode.dontAsk' };
+        case 'bypassPermissions':
+            return { decision: 'allow', reason, source: 'mode.bypassPermissions' };
+    }
+}
+function riskForAction(action) {
+    if (action.kind === 'read')
+        return 'low';
+    if (action.kind === 'edit')
+        return 'medium';
+    if (action.kind === 'bash')
+        return 'high';
+    if (action.kind === 'workflow')
+        return 'medium';
+    return 'medium';
+}
+function matchesAny(value, rules) {
+    return rules.some((rule) => {
+        if (rule === value)
+            return true;
+        if (rule.endsWith('*'))
+            return value.startsWith(rule.slice(0, -1));
+        return false;
+    });
+}
+//# sourceMappingURL=permission.js.map

package/dist/core/repl/cap-warning.js

@@ -0,0 +1,91 @@
+/**
+ * Client-side concurrent-subagent cap - Sprint α5.7 (ADR-0056
+ * acceptance #6, Mac safety memo
+ * `feedback_max_3_parallel_agents_mac_safety.md`).
+ *
+ * Mac-safety memo caps interactive concurrency at 3 active subagents
+ * per workstation. The REPL has its own client-side gate that mirrors
+ * the global rule for one workstation worth of dispatches:
+ *
+ *   - active count >= 3 → soft warning (operator may still dispatch).
+ *   - active count >= 5 → hard block unless the operator opted in via
+ *     PUGI_FORCE_PARALLEL=1.
+ *
+ * The gate is pure: callers pass the current active count and we return
+ * a verdict. The REPL session module reads the dispatcher event stream,
+ * tracks active dispatches, and consults this function before
+ * forwarding `/brief` to the controller.
+ *
+ * The hard cap matches the absolute ceiling cited in the Mac memo (3
+ * brand-recommended, 5 ABSOLUTE max with the env-flag escape hatch).
+ * Bumping either threshold is a memo update, not a code-only change.
+ */
+/**
+ * Soft warning threshold. At this many active subagents the REPL
+ * surfaces a non-blocking nudge. The operator can confirm and proceed.
+ */
+export const CAP_WARNING_THRESHOLD = 3;
+/**
+ * Hard block threshold. At this many active subagents the REPL refuses
+ * the new dispatch unless `PUGI_FORCE_PARALLEL=1` is in the environment.
+ */
+export const CAP_HARD_BLOCK_THRESHOLD = 5;
+/**
+ * Env flag operators set to override the hard cap. Documented in
+ * `pugi doctor` output and in the Mac safety memo. Set this to `1`,
+ * `true`, or `yes` to bypass. Anything else (including unset) leaves
+ * the cap enforced.
+ */
+export const FORCE_PARALLEL_ENV_VAR = 'PUGI_FORCE_PARALLEL';
+/**
+ * Compute the cap verdict given the current active subagent count and
+ * the operator's environment.
+ *
+ * The function is pure (no global state, no IO). Callers must pass the
+ * env they want considered - production callers pass process.env, tests
+ * pass a fixture so the gate is deterministic.
+ */
+export function evaluateCap(input) {
+    const active = Math.max(0, Math.floor(input.active));
+    const env = input.env ?? {};
+    const forceParallel = isForceParallelSet(env);
+    if (active >= CAP_HARD_BLOCK_THRESHOLD) {
+        if (forceParallel) {
+            return { kind: 'override', active, envVar: FORCE_PARALLEL_ENV_VAR };
+        }
+        return { kind: 'block', active, envVar: FORCE_PARALLEL_ENV_VAR };
+    }
+    if (active >= CAP_WARNING_THRESHOLD) {
+        return { kind: 'warn', active };
+    }
+    return { kind: 'allow' };
+}
+/**
+ * Render a one-line operator nudge for a non-allow verdict. The REPL
+ * appends this line to the conversation pane on its own row so the
+ * cyan colour token survives Ink's whitespace collapsing.
+ *
+ * Brand voice: power words `on watch`, `workforce`. No em dash, no
+ * emoji. Capacity rather than `agents` to avoid colliding with the
+ * `/agents` command name in the same frame.
+ */
+export function describeVerdict(verdict) {
+    switch (verdict.kind) {
+        case 'allow':
+            return '';
+        case 'warn':
+            return `Capacity nudge: ${verdict.active} agents already on watch - keep an eye on workstation load.`;
+        case 'block':
+            return `Capacity block: ${verdict.active} agents on watch is the absolute ceiling. Set ${verdict.envVar}=1 to override.`;
+        case 'override':
+            return `Capacity cap bypassed (${verdict.envVar}=1) - ${verdict.active} agents already on watch.`;
+    }
+}
+function isForceParallelSet(env) {
+    const raw = env[FORCE_PARALLEL_ENV_VAR];
+    if (typeof raw !== 'string')
+        return false;
+    const normalized = raw.trim().toLowerCase();
+    return normalized === '1' || normalized === 'true' || normalized === 'yes';
+}
+//# sourceMappingURL=cap-warning.js.map

package/dist/core/repl/clipboard-read.js

@@ -0,0 +1,174 @@
+/**
+ * Best-effort clipboard READ helper - Sprint α6.14.
+ *
+ * Mirror of the clipboard WRITE helper but for the opposite
+ * direction. Powers Ctrl+V paste in the REPL input box: when the
+ * operator presses Ctrl+V we spawn the platform's paste binary
+ * (pbpaste / wl-paste / xclip -o / PowerShell Get-Clipboard) and
+ * insert the result at the cursor.
+ *
+ * Contract:
+ *   - Returns `{ text }` when the helper exited 0 with non-empty
+ *     stdout. Trailing single newline is stripped (clipboard
+ *     contents authored by the operator rarely include the trailing
+ *     LF the paste helpers append).
+ *   - Returns `{ text: null }` on any failure: missing binary,
+ *     non-zero exit, no $DISPLAY on headless Linux, EAGAIN.
+ *   - Never throws. Caller falls back to "Ctrl+V not available -
+ *     try right-click paste" hint.
+ *   - Targets node >= 20.
+ *
+ * Implementation note: we do NOT optimistically run all three Linux
+ * helpers in parallel - the cost of spawning xclip when wl-copy
+ * already produced text is small but visible (50ms+ each on cold
+ * cache). Ordering: WAYLAND_DISPLAY → wl-paste; otherwise xclip first.
+ */
+import { spawn } from 'node:child_process';
+export async function readClipboard(deps = {}) {
+    const platform = deps.platform ?? process.platform;
+    const spawnRead = deps.spawnRead ?? defaultSpawnRead;
+    const env = deps.env ?? process.env;
+    if (platform === 'darwin') {
+        const text = await spawnRead('pbpaste', []);
+        return { text: normalise(text) };
+    }
+    if (platform === 'win32') {
+        // PowerShell is the universally available path. Get-Clipboard
+        // emits UTF-16 by default; the -Raw flag preserves newlines and
+        // returns one string.
+        const text = await spawnRead('powershell', ['-NoProfile', '-Command', 'Get-Clipboard -Raw']);
+        return { text: normalise(text) };
+    }
+    if (platform === 'linux' || platform === 'freebsd' || platform === 'openbsd') {
+        const order = env.WAYLAND_DISPLAY
+            ? ['wl-paste', 'xclip', 'xsel']
+            : ['xclip', 'wl-paste', 'xsel'];
+        for (const tool of order) {
+            const args = tool === 'xclip'
+                ? ['-selection', 'clipboard', '-o']
+                : tool === 'xsel'
+                    ? ['--clipboard', '--output']
+                    : ['--no-newline'];
+            const text = await spawnRead(tool, args);
+            if (text !== null && text.length > 0) {
+                return { text: normalise(text) };
+            }
+        }
+        return { text: null };
+    }
+    return { text: null };
+}
+function normalise(raw) {
+    if (raw === null)
+        return null;
+    if (raw.length === 0)
+        return null;
+    // Strip a single trailing LF the helpers often append. Multi-line
+    // pastes preserve interior newlines.
+    return raw.endsWith('\n') ? raw.slice(0, -1) : raw;
+}
+/**
+ * Hard cap on clipboard payload size. The paste helper streams stdout
+ * with no upper bound by default, so a pathologically large clipboard
+ * (e.g. a hostile actor's 500 MiB file URL list, or an accidental copy
+ * of a large binary) would OOM the CLI process if we kept appending.
+ * 1 MiB is plenty for any realistic prompt + code snippet paste and
+ * still leaves room in V8's default young-generation heap.
+ */
+const MAX_CLIPBOARD_BYTES = 1024 * 1024; // 1 MiB
+function defaultSpawnRead(cmd, args) {
+    return new Promise((resolve) => {
+        let settled = false;
+        let overflow = false;
+        let totalBytes = 0;
+        const chunks = [];
+        const settle = (value) => {
+            if (settled)
+                return;
+            settled = true;
+            resolve(value);
+        };
+        try {
+            const options = {
+                stdio: ['ignore', 'pipe', 'ignore'],
+                shell: false,
+            };
+            const child = spawn(cmd, args.slice(), options);
+            child.on('error', () => settle(null));
+            child.stdout?.on('data', (b) => {
+                if (overflow)
+                    return;
+                totalBytes += b.length;
+                if (totalBytes > MAX_CLIPBOARD_BYTES) {
+                    overflow = true;
+                    try {
+                        child.kill('SIGTERM');
+                    }
+                    catch {
+                        // Best effort; close handler still settles below.
+                    }
+                    return;
+                }
+                chunks.push(b);
+            });
+            child.on('close', (code) => {
+                if (overflow)
+                    return settle(null);
+                if (code !== 0)
+                    return settle(null);
+                const buf = Buffer.concat(chunks);
+                settle(buf.toString('utf8'));
+            });
+        }
+        catch {
+            settle(null);
+        }
+    });
+}
+/* ------------------------------------------------------------------ */
+/* Bracketed-paste mode helpers                                       */
+/* ------------------------------------------------------------------ */
+/**
+ * Modern terminals (iTerm2, Alacritty, GNOME Terminal, kitty,
+ * Windows Terminal) bracket pasted text with `ESC[200~ ... ESC[201~`
+ * when bracketed-paste mode is enabled. The input box can detect
+ * these markers and disable newline-as-submit during the paste burst
+ * so a multi-line paste does not fire `onSubmit` mid-paste.
+ *
+ * The constants here are exported so the input box and the unit
+ * test can share the byte sequences without re-implementing them.
+ */
+export const PASTE_START = '\x1b[200~';
+export const PASTE_END = '\x1b[201~';
+export const CTRL_V = '\x16';
+export function classifyChunk(chunk, inPaste) {
+    if (inPaste) {
+        const endIdx = chunk.indexOf(PASTE_END);
+        if (endIdx === -1) {
+            return { kind: 'paste-cont', textInPaste: chunk };
+        }
+        return {
+            kind: 'paste-end',
+            textInPaste: chunk.slice(0, endIdx),
+            textAfter: chunk.slice(endIdx + PASTE_END.length),
+        };
+    }
+    const startIdx = chunk.indexOf(PASTE_START);
+    if (startIdx === -1) {
+        return { kind: 'plain', text: chunk };
+    }
+    const afterStart = chunk.slice(startIdx + PASTE_START.length);
+    const endIdx = afterStart.indexOf(PASTE_END);
+    if (endIdx === -1) {
+        return {
+            kind: 'paste-start',
+            textBefore: chunk.slice(0, startIdx),
+            textInPaste: afterStart,
+        };
+    }
+    return {
+        kind: 'paste-only',
+        text: afterStart.slice(0, endIdx),
+    };
+}
+//# sourceMappingURL=clipboard-read.js.map