@gobing-ai/spur 0.4.8 → 0.4.10

package/plugins/sp/hooks/pi/guard-extension.ts

@@ -1,304 +0,0 @@
-/**
- * Pi extension for Spur (sp) plugin hooks.
- *
- * Replaces @vahor/pi-hooks with native Pi event handlers — no spinner,
- * no pi.exec overhead, no "Operation aborted" on Esc.
- *
- * Implements:
- *   - task-write-guard  (tool_call → block Write/Edit to Spur task files)
- *   - careful-guard     (tool_call → warn on destructive Bash commands)
- *   - context-post-tool (tool_result → shared recordToolUseEvent)
- *   - context-session-start (session_start → shared recordSessionStart)
- *   - context-session-stop  (session_shutdown → shared recordSessionEnd)
- *   - agent-lifecycle       (agent_start/agent_settled → shared reportLifecycleHook, G73 R4)
- *
- * The ledger and session cores are shared with the Claude hooks (task 0969): this
- * extension only normalizes Pi event shapes and adapts them to those cores.
- *
- * Installation:
- *   Add to ~/.pi/agent/settings.json packages:
- *     "npm:spur"  (when published), or
- *   Copy to ~/.pi/agent/extensions/sp-guard/ and reference via:
- *     "pi": { "extensions": ["path/to/guard-extension.ts"] }
- */
-
-import { spawnSync } from 'node:child_process';
-import { existsSync, realpathSync } from 'node:fs';
-import { homedir } from 'node:os';
-import { isAbsolute, join, resolve } from 'node:path';
-import type { ExtensionAPI, ExtensionContext } from '@earendil-works/pi-coding-agent';
-import type { SessionOwner } from '../../lib/context-owner';
-import { recordToolUseEvent, type ToolPayload } from '../../lib/context-post-tool';
-import { recordSessionStart } from '../../lib/context-session-start';
-import { recordSessionEnd } from '../../lib/context-session-stop';
-import { classifyCommand } from '../../lib/destructive-policy';
-import { getEnvVar, getEnvVars } from '../../lib/env';
-import { couldBeTaskFile } from '../../lib/task-file-policy';
-import { reportLifecycleHook } from '../agent-lifecycle';
-
-// ─── Constants ───────────────────────────────────────────────────────────
-
-// Resolved per call, not cached at module load: Pi's cwd is fixed for the
-// process lifetime, and lazy resolution keeps the extension testable (tests
-// chdir into a temp project before driving handlers).
-const spurContextDir = (): string => join(process.cwd(), '.spur', 'context');
-
-// ─── Helpers ─────────────────────────────────────────────────────────────
-
-/**
- * Pi session owner identity (task 1159): the extension's own session-manager id, stable for the
- * life of the Pi session and distinct from any nested child session. Read here — not from a PID or
- * `SPUR_RUN_ID` — so a nested child's `session_shutdown` cannot claim the parent's pointer.
- */
-function piSessionOwner(ctx: ExtensionContext): SessionOwner | null {
-    const sessionId = ctx.sessionManager.getSessionId().trim();
-    return sessionId.length > 0 ? { host: 'pi', sessionId } : null;
-}
-
-type TaskOwnership = 'owned' | 'unowned' | 'unknown';
-
-/**
- * Extract the target path from a write/edit tool input. Pi uses `path`;
- * Claude Code uses `file_path`. Returns an absolute path when present.
- */
-function resolveInputPath(input: Record<string, unknown> | undefined): string {
-    let raw = '';
-    if (input) {
-        if (typeof input.path === 'string') raw = input.path;
-        else if (typeof input.file_path === 'string') raw = input.file_path;
-    }
-    if (!raw) return '';
-    return isAbsolute(raw) ? raw : resolve(process.cwd(), raw);
-}
-
-/**
- * Candidate `spur` executable locations (symlinks). Pi launched from a GUI
- * may not have `~/.bun/bin` or node/bun on PATH, so we try each in order
- * and finally run spur.js via the current Bun executable directly.
- */
-const SPUR_BIN_CANDIDATES: string[] = [
-    join(homedir(), '.bun', 'bin', 'spur'),
-    '/opt/homebrew/bin/spur',
-    '/usr/local/bin/spur',
-];
-
-/** Resolve a candidate spur symlink to its real spur.js path (for execPath fallback). */
-function resolveSpurJsPath(candidate: string): string | undefined {
-    try {
-        return realpathSync(candidate);
-    } catch {
-        return existsSync(candidate) ? candidate : undefined;
-    }
-}
-
-function resolveSpurTaskOwnership(filePath: string): TaskOwnership {
-    const run = (cmd: string, args: string[]) =>
-        spawnSync(cmd, args, { cwd: process.cwd(), encoding: 'utf-8', timeout: 8000 });
-
-    // 1. SPUR_BIN env override (may include args) or `spur` on PATH
-    const envBin = getEnvVar('SPUR_BIN') || 'spur';
-    const envParts = envBin.split(' ');
-    let res = run(envParts[0] ?? 'spur', [...envParts.slice(1), 'task', 'resolve', filePath, '--strict', '--json']);
-    // Only 0 (owned) / 1 (unowned) are valid spur exit codes; 127 (interpreter
-    // missing) and other codes mean the environment is broken — keep trying.
-    if (!res.error && (res.status === 0 || res.status === 1)) return res.status === 0 ? 'owned' : 'unowned';
-
-    // 2. Absolute symlink paths (needs node/bun on PATH for the shebang)
-    for (const candidate of SPUR_BIN_CANDIDATES) {
-        if (!existsSync(candidate)) continue;
-        res = run(candidate, ['task', 'resolve', filePath, '--strict', '--json']);
-        if (!res.error && (res.status === 0 || res.status === 1)) return res.status === 0 ? 'owned' : 'unowned';
-    }
-
-    // 3. Run spur.js via the current Bun executable (no PATH dependency)
-    for (const candidate of SPUR_BIN_CANDIDATES) {
-        const spurJs = resolveSpurJsPath(candidate);
-        if (!spurJs) continue;
-        res = run(process.execPath, [spurJs, 'task', 'resolve', filePath, '--strict', '--json']);
-        if (!res.error && (res.status === 0 || res.status === 1)) return res.status === 0 ? 'owned' : 'unowned';
-    }
-
-    return 'unknown';
-}
-
-// Destructive-command classification is imported from `../destructive-policy`, the
-// single cross-platform policy. This file previously carried its own regex copy; it
-// diverged from the Claude matrix on 7 of 10 pinned cases (it allowed
-// `rm -rf node_modules /etc/nginx`, `rm -R --force /var/data`, `git push -f` and
-// `git push origin +main`, and warned on `git push --force-with-lease`). Do not
-// re-introduce a local copy — add cases to `destructive-policy.test.ts` instead.
-
-// ─── Pi → Claude payload normalization (task 0969 R1) ─────────────────────
-
-/** Pi tool name → the Claude tool name the shared core records. */
-const PI_TO_CLAUDE: Record<string, string> = {
-    read: 'Read',
-    write: 'Write',
-    edit: 'Edit',
-    bash: 'Bash',
-    grep: 'Grep',
-    find: 'Glob',
-};
-
-/** Join the text parts of a Pi tool_result `content` payload. */
-function piContentText(content: unknown): string {
-    if (typeof content === 'string') return content;
-    if (!Array.isArray(content)) return '';
-    const parts: string[] = [];
-    for (const part of content) {
-        if (part && typeof part === 'object' && typeof (part as { text?: unknown }).text === 'string') {
-            parts.push((part as { text: string }).text);
-        }
-    }
-    return parts.join('\n');
-}
-
-/**
- * Pure Pi-event → Claude-{@link ToolPayload} adapter. An unmapped tool returns null so the
- * shared core writes no row (R1's row filter). Search tools keep `path` (never `file_path`)
- * because the core treats `file_path` as the written file, not a search root.
- */
-export function normalizePiToolEvent(
-    toolName: string,
-    input: Record<string, unknown> | undefined,
-    content?: unknown,
-): ToolPayload | null {
-    const mapped = PI_TO_CLAUDE[toolName];
-    if (mapped === undefined) return null;
-    const i = input ?? {};
-    const str = (value: unknown): string => (typeof value === 'string' ? value : '');
-    const path = str(i.path) || str(i.file_path);
-    const text = piContentText(content);
-    const tool_response = text.length > 0 ? { content: text } : undefined;
-
-    switch (mapped) {
-        case 'Read':
-            return { tool_name: mapped, tool_input: { file_path: path }, tool_response };
-        case 'Write':
-            return { tool_name: mapped, tool_input: { file_path: path, content: str(i.content) }, tool_response };
-        case 'Edit': {
-            const edits = Array.isArray(i.edits) ? (i.edits as Array<Record<string, unknown>>) : [];
-            return {
-                tool_name: mapped,
-                tool_input: {
-                    file_path: path,
-                    old_string: edits.map((e) => str(e.oldText)).join(''),
-                    new_string: edits.map((e) => str(e.newText)).join(''),
-                },
-                tool_response,
-            };
-        }
-        case 'Grep':
-            return {
-                tool_name: mapped,
-                tool_input: {
-                    pattern: str(i.pattern),
-                    ...(path ? { path } : {}),
-                    ...(str(i.glob) ? { glob: str(i.glob) } : {}),
-                },
-                tool_response,
-            };
-        case 'Glob':
-            return {
-                tool_name: mapped,
-                tool_input: { pattern: str(i.pattern), ...(path ? { path } : {}) },
-                tool_response,
-            };
-        case 'Bash':
-            return { tool_name: mapped, tool_input: { command: str(i.command) }, tool_response };
-        default:
-            return null;
-    }
-}
-
-// ─── Extension entry point ───────────────────────────────────────────────
-
-export default function (pi: ExtensionAPI): void {
-    // ── task-write-guard + careful-guard ──────────────────────────────
-    pi.on('tool_call', async (event, ctx) => {
-        // task-write-guard: block Write/Edit to Spur task files.
-        // Both guards honor the same `off` escape hatches as the Claude hooks.
-        if ((event.toolName === 'write' || event.toolName === 'edit') && getEnvVar('SPUR_WRITE_GUARD') !== 'off') {
-            const input = event.input as Record<string, unknown> | undefined;
-            // Pi's write/edit tools use `path` (not Claude Code's `file_path`)
-            const filePath = resolveInputPath(input);
-            // Skip the `spur task resolve` subprocess for paths that cannot name a
-            // task file (shared predicate — see task-file-policy.ts).
-            if (filePath && couldBeTaskFile(filePath) && resolveSpurTaskOwnership(filePath) === 'owned') {
-                const msg = `Denied: ${filePath} is a Spur task file. Use 'spur task update' instead.`;
-                ctx.ui.notify(msg, 'error');
-                return { block: true, reason: msg };
-            }
-        }
-
-        // careful-guard: warn on destructive Bash commands
-        if (event.toolName === 'bash' && getEnvVar('SPUR_CAREFUL') !== 'off') {
-            const input = event.input as Record<string, unknown> | undefined;
-            const command = typeof input?.command === 'string' ? input.command : '';
-            const hit = command ? classifyCommand(command) : null;
-            if (hit !== null) {
-                const msg = `Warning: destructive command — ${hit}: ${command.slice(0, 120)}`;
-                ctx.ui.notify(msg, 'warning');
-                // Ask for confirmation
-                const ok = await ctx.ui.confirm('Destructive command', msg);
-                if (!ok) return { block: true, reason: 'Cancelled by user' };
-            }
-        }
-
-        return {};
-    });
-
-    // ── context-post-tool: shared recordToolUseEvent (task 0969 R1) ──
-    pi.on('tool_result', async (event, ctx) => {
-        try {
-            const payload = normalizePiToolEvent(
-                event.toolName,
-                event.input as Record<string, unknown> | undefined,
-                (event as { content?: unknown }).content,
-            );
-            // Host-native session id, as Claude's payload carries (H21 parity).
-            const sessionId = piSessionOwner(ctx)?.sessionId;
-            if (payload)
-                recordToolUseEvent(spurContextDir(), sessionId ? { ...payload, session_id: sessionId } : payload);
-        } catch {
-            // fail-open
-        }
-    });
-
-    // ── context-session-start: shared recordSessionStart (R2) ────────
-    pi.on('session_start', async (_event, ctx) => {
-        try {
-            recordSessionStart(spurContextDir(), getEnvVars(), undefined, 'pi', piSessionOwner(ctx) ?? undefined);
-        } catch {
-            // fail-open
-        }
-    });
-
-    // ── context-session-stop: shared recordSessionEnd (R3) ──────────
-    pi.on('session_shutdown', async (_event, ctx) => {
-        try {
-            recordSessionEnd(spurContextDir(), undefined, piSessionOwner(ctx) ?? undefined);
-        } catch {
-            // fail-open
-        }
-    });
-
-    // ── agent-lifecycle: fleet lifecycle reporting (G73 R4, task 1080) ──
-    // Pi has no native `blocked` signal (herdr finding P2), so only working/idle are
-    // reported here; a no-op outside a fleet, like every other hook path.
-    pi.on('agent_start', async () => {
-        try {
-            reportLifecycleHook({ hook_event_name: 'agent_start' });
-        } catch {
-            // fail-open
-        }
-    });
-
-    pi.on('agent_settled', async () => {
-        try {
-            reportLifecycleHook({ hook_event_name: 'agent_settled' });
-        } catch {
-            // fail-open
-        }
-    });
-}

package/plugins/sp/lib/dogfood-pipeline.ts

@@ -1,265 +0,0 @@
-/**
- * dogfood pipeline-driving detection — the pure detector core.
- *
- * Extracted from `plugins/sp/scripts/dogfood-testing/detect-pipeline-driving.ts` (task 1173, plan
- * P7/ADR-130): the reusable detection logic lives in lib, and the script keeps only the live
- * Phase 1.0 CLI gate. Callers and tests may keep importing the script — it re-exports this module.
- *
- * Contract (0274 §3 dogfood-pipeline-detect, 0277 R1):
- *   - Word-boundary matchers with `-` treated as a word char (NOT a boundary).
- *     A token counts only when it is a distinct hyphen-word, not when it is a
- *     substring of a longer alphanumeric or hyphen run. This removes the
- *     leading-space dependency of the @1.1 prose detector.
- *   - Two token shapes, both with strict `[^\w-]` boundaries:
- *       (a) complete tokens — `--next`, `dev-run`, `dev-runall`, `dev-wrap`,
- *           `dev-wrapall`, `dev-idea` — matched as whole hyphen-words so the
- *           slash form `/sp:dev-run` matches on its `dev-run` tail whether or
- *           not it is preceded by a space, but `--next` does NOT match inside
- *           `--next-gen` (the trailing `-gen` breaks the boundary).
- *       (b) bare nouns — `run`, `runall`, `wrap`, `wrapall`, `idea` — matched
- *           only as standalone words, so `run` matches in
- *           `bun ... task run 0042` but NOT inside `runaway`/`prerun`, and
- *           `idea` does NOT match inside `idealist`/`ideal`.
- *   - Listing both shapes is what makes the detector leading-space invariant
- *     (the slash form is caught by its `dev-*` tail; the bare noun is caught
- *     when it appears as its own word) without letting `run` leak into every
- *     `-run-` identifier.
- *
- * Non-goals of detectPipelineDriving: decides ambiguity only. It does NOT decide
- * observe vs fix — any explicit `--max-retry` value proceeds regardless.
- * Implement-heavy advisory is a separate helper (detectImplementHeavy).
- */
-
-/**
- * Tokens whose presence makes a testee pipeline-driving. Ordered for stable
- * diagnostics. Two shapes per the contract above: complete `dev-*` / `--next`
- * tokens first, then bare nouns.
- */
-const PIPELINE_TOKENS = [
-    '--next',
-    'dev-runall',
-    'dev-wrapall',
-    'dev-refineall',
-    'dev-verifyall',
-    'dev-run',
-    'dev-wrap',
-    'dev-idea',
-    'refineall',
-    'verifyall',
-    'runall',
-    'wrapall',
-    'run',
-    'wrap',
-    'idea',
-] as const;
-
-/** Refuse message when pipeline-driving and `--max-retry` was not passed (exact string). */
-export const PIPELINE_DRIVING_REFUSE_MESSAGE =
-    '⚠ pipeline-driving testee detected; pass --max-retry 0 (observe-only) or --max-retry N (fix mode, tree mutation acknowledged)';
-
-/**
- * Refuse message when the testee carries a mutating `--fix` mode (`--fix all` /
- * `--fix blockers-first`) and `--max-retry` was not passed. A mutating fix mode
- * mutates the working tree independent of pipeline-driving (task 0293 R1/R2):
- * `--max-retry 0` bounds the **driver** only — the testee's own `--fix` pass
- * still mutates the tree — so the message must not imply otherwise.
- */
-export const MUTATING_FIX_REFUSE_MESSAGE =
-    '⚠ mutating --fix mode detected (--fix all | --fix blockers-first); pass --max-retry 0 (observe-only for the driver; the testee still mutates the tree) or --max-retry N (fix mode, driver + testee both mutate)';
-
-/** Advisory when pipeline-driving + implement-heavy derived steps (exact string). */
-export const IMPLEMENT_HEAVY_ADVISORY_MESSAGE =
-    '⚠ implement-heavy pipeline dogfood: prefer --max-retry 0 (observe-only) or step-split; operator --max-retry N overrides';
-
-/**
- * Tokens that mark a derived step as implement-heavy (mutates product/code or
- * drives a mutating pipeline leg). Deliberately excludes verify/review/unit-only
- * surfaces even when they carry `--next`.
- */
-const IMPLEMENT_HEAVY_TOKENS = [
-    'dev-runall',
-    'dev-wrapall',
-    'dev-run',
-    'dev-wrap',
-    'dev-idea',
-    'runall',
-    'wrapall',
-    // bare `run` / `wrap` / `idea` — only when not clearly a non-mutating surface
-    'run',
-    'wrap',
-    'idea',
-    'implement',
-] as const;
-
-/**
- * A verify/review surface stops being non-mutating the moment it carries a
- * repair mode: `--fix all` / `--fix blockers-first` applies Edit/Write repairs
- * to the working tree (0280 dogfood, finding P2). `--fix none` stays
- * observational. Boundary-guarded so `--prefix all` / `--focus all` never match.
- * Exported so the Phase 1.0 gate and tests share one matcher (task 0293 R1/R4).
- */
-export function hasMutatingFixMode(step: string): boolean {
-    return /(?<![\w-])--fix[=\s]+(all|blockers-first)(?![\w-])/i.test(step);
-}
-
-/**
- * Match a token at a word boundary. A "word boundary" here is the position
- * between a non-`[\w-]` char (or string start) and the token, and between the
- * token and a non-`[\w-]` char (or string end). Treating `-` as a word char
- * is what makes `--next` reject `--next-gen` and `dev-run` reject `dev-runner`.
- */
-function tokenMatches(testee: string, token: string): boolean {
-    const escaped = token.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
-    // (?<![\w-]) — not preceded by a word char or hyphen.
-    // (?![\w-])  — not followed by a word char or hyphen.
-    const re = new RegExp(`(?<![\\w-])${escaped}(?![\\w-])`, 'i');
-    return re.test(testee);
-}
-
-/**
- * Returns whether the testee string is pipeline-driving (contains any of the
- * pipeline-driving tokens as a distinct hyphen-word). Machine-checked
- * counterpart of the prose list in SKILL.md §Pipeline-driving detection and
- * dev-dogfood.md.
- */
-export function detectPipelineDriving(testee: string): boolean {
-    if (typeof testee !== 'string' || testee.length === 0) {
-        return false;
-    }
-    return PIPELINE_TOKENS.some((token) => tokenMatches(testee, token));
-}
-
-/**
- * True when a single step label (or the whole testee) is implement-heavy —
- * it chains into real implementation / wrap / idea work, not verify-only.
- *
- * Non-mutating surfaces (`dev-verify`, `dev-review`, `dev-unit`, plain
- * `dev-refine` without a further run) are never implement-heavy even if
- * pipeline-driving via `--next` — UNLESS they carry a mutating repair mode
- * (`--fix all` / `--fix blockers-first`), which turns the verify/review leg
- * into a tree-mutating fix pass (0280 dogfood, finding P2).
- */
-export function isImplementHeavyStep(step: string): boolean {
-    if (typeof step !== 'string' || step.length === 0) return false;
-    // Explicit non-mutating surfaces win unless a mutating token co-occurs.
-    const nonMutatingOnly =
-        tokenMatches(step, 'dev-verify') || tokenMatches(step, 'dev-review') || tokenMatches(step, 'dev-unit');
-    const hasMutating = IMPLEMENT_HEAVY_TOKENS.some((token) => tokenMatches(step, token)) || hasMutatingFixMode(step);
-    if (nonMutatingOnly && !hasMutating) return false;
-    // refine alone is planning, not implement-heavy; refine+run/--next chain is.
-    if (tokenMatches(step, 'dev-refine') && !hasMutating && !tokenMatches(step, '--next')) {
-        return false;
-    }
-    if (tokenMatches(step, 'dev-refine') && tokenMatches(step, '--next')) {
-        // refine --next chains into run → implement-heavy
-        return true;
-    }
-    return hasMutating;
-}
-
-/**
- * True when the testee is implement-heavy: it carries a pipeline-driving token,
- * a mutating `--fix` mode, OR at least one derived step (or the testee itself
- * when no steps given) is implement-heavy. Used for the W8 Phase 1 advisory
- * after step derivation.
- *
- * Task 0293 R3: a mutating `--fix` mode alone is implement-heavy even with no
- * pipeline token — the verify/review leg itself becomes a tree-mutating fix
- * pass.
- */
-export function detectImplementHeavy(testee: string, derivedSteps: string[] = []): boolean {
-    if (isImplementHeavyStep(testee)) return true;
-    if (!detectPipelineDriving(testee)) return false;
-    return derivedSteps.some((step) => isImplementHeavyStep(step));
-}
-
-export interface GateResult {
-    pipelineDriving: boolean;
-    mutatingFix: boolean;
-    maxRetryPresent: boolean;
-    implementHeavy: boolean;
-    refuse: boolean;
-    advisory: boolean;
-    message: string | null;
-    exitCode: 0 | 1 | 2;
-}
-
-/**
- * Phase 1.0 + W8 gate decision. Pure — no I/O. The CLI wrapper prints and exits.
- *
- * Refuse condition (task 0293 R1) is the union of two **independent** mutation
- * sources, each gated on `!maxRetryPresent`:
- *
- *   1. pipeline-driving testee (`--next`, `dev-run`, …) — refuses because the
- *      testee chains lifecycle legs whose cumulative blast radius the driver
- *      cannot pre-attribute.
- *   2. mutating `--fix` mode (`--fix all` / `--fix blockers-first`) — refuses
- *      because the testee itself applies Edit/Write repairs even with no
- *      pipeline token. `--max-retry 0` bounds the **driver** only; the testee
- *      still mutates (honesty note in MUTATING_FIX_REFUSE_MESSAGE).
- *
- * Pipeline-driving is reported first when both co-occur (its refuse message is
- * the superset — chain + tree mutation).
- */
-export function evaluateDogfoodGate(
-    testee: string,
-    options: { maxRetryPresent?: boolean; steps?: string[] } = {},
-): GateResult {
-    const maxRetryPresent = options.maxRetryPresent === true;
-    const steps = options.steps ?? [];
-    const pipelineDriving = detectPipelineDriving(testee);
-    const mutatingFix = hasMutatingFixMode(testee);
-    const implementHeavy = detectImplementHeavy(testee, steps);
-
-    if (pipelineDriving && !maxRetryPresent) {
-        return {
-            pipelineDriving,
-            mutatingFix,
-            maxRetryPresent,
-            implementHeavy,
-            refuse: true,
-            advisory: false,
-            message: PIPELINE_DRIVING_REFUSE_MESSAGE,
-            exitCode: 2,
-        };
-    }
-
-    if (mutatingFix && !maxRetryPresent) {
-        return {
-            pipelineDriving,
-            mutatingFix,
-            maxRetryPresent,
-            implementHeavy,
-            refuse: true,
-            advisory: false,
-            message: MUTATING_FIX_REFUSE_MESSAGE,
-            exitCode: 2,
-        };
-    }
-
-    if (implementHeavy) {
-        return {
-            pipelineDriving,
-            mutatingFix,
-            maxRetryPresent,
-            implementHeavy,
-            refuse: false,
-            advisory: true,
-            message: IMPLEMENT_HEAVY_ADVISORY_MESSAGE,
-            exitCode: 0,
-        };
-    }
-
-    return {
-        pipelineDriving,
-        mutatingFix,
-        maxRetryPresent,
-        implementHeavy,
-        refuse: false,
-        advisory: false,
-        message: null,
-        exitCode: 0,
-    };
-}
-
-export { PIPELINE_TOKENS };