@pugi/cli 0.1.0-beta.7 → 0.1.0-beta.87

package/dist/core/watch-markers/marker-watcher.js

@@ -0,0 +1,133 @@
+/**
+ * Watch-mode inline marker scanner — Aider AI?/AI! pattern.
+ *
+ * Watches a directory tree via chokidar (already в deps — used by
+ * VS Code и most JS file-watchers). When a file changes, scans the
+ * delta для inline markers и emits structured events. Pugi-flavoured
+ * marker pair:
+ *
+ *  // PUGI?  → operator asks Pugi a question right here
+ *  // PUGI!  → operator instructs Pugi to act right here
+ *
+ * Also accepts Aider-compatible `// AI?` / `// AI!` for muscle-memory
+ * parity. Block comments and `# PUGI?` (Python / shell) are recognised
+ * too — language is detected from extension, NOT parsed properly. The
+ * goal is opportunistic ergonomics, not a precise parser.
+ *
+ * No tool dispatch happens here — this module emits events; downstream
+ * code (engine integration follow-up) decides what to do.
+ */
+import chokidar from 'chokidar';
+import { readFile } from 'node:fs/promises';
+import { EventEmitter } from 'node:events';
+import path from 'node:path';
+const DEFAULT_IGNORED = [
+    '**/node_modules/**',
+    '**/.git/**',
+    '**/dist/**',
+    '**/build/**',
+    '**/coverage/**',
+    '**/.next/**',
+    '**/.pugi/**',
+];
+const DEFAULT_MAX_FILE_BYTES = 256 * 1024;
+// Recognises `// PUGI?`, `# PUGI!`, `/* AI? ... */`, `<!-- PUGI! ... -->` and equivalents.
+// Capture group 1 = comment prefix, 2 = tag (PUGI | AI), 3 = symbol (? | !), 4 = trailing text.
+const MARKER_RE = /(?:\/\/|#|\/\*|<!--)\s*(PUGI|AI)([?!])\s*([^\n*-]*?)(?:\*\/|-->|$)/g;
+export class MarkerWatcher extends EventEmitter {
+    options;
+    watcher = null;
+    maxFileBytes;
+    constructor(options = {}) {
+        super();
+        this.options = options;
+        this.maxFileBytes = options.maxFileBytes ?? DEFAULT_MAX_FILE_BYTES;
+    }
+    /**
+     * Start watching `patterns`. Multiple calls without close() throw —
+     * one instance, one active watcher.
+     */
+    start(patterns) {
+        if (this.watcher) {
+            throw new Error('MarkerWatcher already started — call close() first');
+        }
+        const ignored = [...(this.options.ignored ?? DEFAULT_IGNORED)];
+        const opts = {
+            ignored,
+            ignoreInitial: this.options.ignoreInitial ?? true,
+            persistent: true,
+        };
+        if (this.options.cwd !== undefined) {
+            opts.cwd = this.options.cwd;
+        }
+        this.watcher = chokidar.watch(patterns, opts);
+        this.watcher.on('add', p => void this.scan(p));
+        this.watcher.on('change', p => void this.scan(p));
+        this.watcher.on('error', err => this.emit('error', err));
+    }
+    /** Stop watching и release file handles. Safe to call multiple times. */
+    async close() {
+        if (!this.watcher)
+            return;
+        await this.watcher.close();
+        this.watcher = null;
+    }
+    /**
+     * Scan a single file synchronously — bypasses the watcher entirely.
+     * Useful для one-shot scans / tests / initial-load passes.
+     */
+    async scanOnce(file) {
+        return this.collectFromFile(file);
+    }
+    async scan(file) {
+        const hits = await this.collectFromFile(file);
+        for (const hit of hits) {
+            this.emit('marker', hit);
+        }
+    }
+    async collectFromFile(file) {
+        let content;
+        // chokidar emits paths relative to its `cwd` option when set. Resolve
+        // so readFile doesn't fall back to the process CWD и miss the file.
+        const resolved = this.options.cwd && !path.isAbsolute(file)
+            ? path.join(this.options.cwd, file)
+            : file;
+        try {
+            const buf = await readFile(resolved);
+            if (buf.byteLength > this.maxFileBytes)
+                return [];
+            content = buf.toString('utf8');
+        }
+        catch (err) {
+            // File deleted between event and read, permissions, etc.
+            this.emit('error', err);
+            return [];
+        }
+        const hits = [];
+        const lines = content.split('\n');
+        for (let i = 0; i < lines.length; i += 1) {
+            const lineText = lines[i] ?? '';
+            MARKER_RE.lastIndex = 0;
+            let match;
+            while ((match = MARKER_RE.exec(lineText)) !== null) {
+                const tag = match[1] ?? 'PUGI';
+                const symbol = match[2] ?? '?';
+                const text = (match[3] ?? '').trim();
+                hits.push({
+                    file,
+                    line: i + 1,
+                    kind: symbol === '!' ? 'instruction' : 'question',
+                    tag,
+                    text,
+                });
+            }
+        }
+        return hits;
+    }
+}
+/** Standalone scan helper для callers that don't want a long-lived watcher. */
+export async function scanFileForMarkers(file, options = {}) {
+    const watcher = new MarkerWatcher({ maxFileBytes: options.maxFileBytes });
+    return watcher.scanOnce(file);
+}
+//# sourceMappingURL=marker-watcher.js.map

package/dist/core/worktree-manager/cleanup.js

@@ -0,0 +1,123 @@
+/**
+ * Stale-worktree sweep — .
+ *
+ * Pairs with `WorktreeManager` to find worktrees whose agent has either:
+ *
+ *  1. No corresponding progress JSON under `.pugi/agent-progress/` (the
+ *     writer never wrote one, OR the file was archived away), OR
+ *  2. A progress JSON whose `status` is `completed` or `failed` (the
+ *     agent finished — the worktree is no longer load-bearing).
+ *
+ * Crashed agents (status `running` with a stale lastUpdate) are NOT
+ * swept; the leak-research contract says we LEAVE worktrees of crashed
+ * agents in place for forensics. The operator can `pugi worktrees
+ * cleanup <id>` manually after the post-mortem.
+ *
+ * Implementation notes:
+ *
+ *  - The cleanup is read-then-write: list the manager state, classify
+ *    each entry, then call `manager.cleanup()` per stale id. Errors per
+ *    entry never abort the loop — they accumulate in the report.
+ *  - The progress directory we look at is the SAME `.pugi/agent-progress/`
+ *    root the writer uses (resolved via the writer's env-aware helper).
+ *  - `runStaleCleanup` is the only public entry point. The internal
+ *    classifier is exported as `classifyStale` for spec coverage.
+ *
+ * Brand voice: ASCII only, no emoji, no banned words.
+ */
+import { existsSync, readFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { resolveProgressDir } from '../agent-progress/writer.js';
+import { validateAgentProgress } from '../agent-progress/schema.js';
+import { WorktreeManager, } from './manager.js';
+/**
+ * Classify a single worktree listing against the on-disk progress JSON.
+ * Pure-ish — only reads from the progress file when one exists. Exposed
+ * for the spec; production callers go through `runStaleCleanup`.
+ */
+export function classifyStale(listing, progressDir, options = {}) {
+    const grace = options.crashedGraceMs ?? 30 * 60 * 1000;
+    const now = options.now ?? Date.now;
+    const progressPath = join(progressDir, `${listing.agentId}.json`);
+    if (!existsSync(progressPath)) {
+        return 'orphan_no_progress';
+    }
+    let raw;
+    try {
+        raw = readFileSync(progressPath, 'utf8');
+    }
+    catch {
+        // Unreadable progress file — treat as orphan so the operator can
+        // see it in the cleanup report. We never act on it silently.
+        return 'orphan_no_progress';
+    }
+    let parsed;
+    try {
+        parsed = JSON.parse(raw);
+    }
+    catch {
+        return 'orphan_no_progress';
+    }
+    const validation = validateAgentProgress(parsed);
+    if (!validation.ok)
+        return 'orphan_no_progress';
+    const progress = validation.value;
+    if (progress.status === 'completed')
+        return 'stale_completed';
+    if (progress.status === 'failed')
+        return 'stale_failed';
+    // status === 'running' — check for crashed (stale lastUpdate)
+    const lastTs = Date.parse(progress.lastUpdate);
+    if (Number.isFinite(lastTs) && now() - lastTs > grace) {
+        return 'crashed_running';
+    }
+    return 'active';
+}
+/**
+ * Run a single stale-worktree sweep. Removes only `stale_completed`,
+ * `stale_failed`, and `orphan_no_progress` entries. Crashed-running
+ * entries are LEFT IN PLACE per the L23 forensics contract, but they
+ * appear in the report so the operator can act on them manually.
+ */
+export function runStaleCleanup(managerOpts, options = {}) {
+    const manager = new WorktreeManager(managerOpts);
+    const report = {
+        scanned: 0,
+        classified: [],
+        removed: [],
+        preserved: [],
+        errors: [],
+    };
+    const listResult = manager.list();
+    if (!listResult.ok) {
+        report.errors.push({ agentId: '', detail: `list failed: ${listResult.detail}` });
+        return report;
+    }
+    const progressDir = options.progressDir ?? resolveProgressDir();
+    const listings = listResult.value;
+    report.scanned = listings.length;
+    for (const entry of listings) {
+        const cls = classifyStale(entry, progressDir, options);
+        report.classified.push({ agentId: entry.agentId, path: entry.path, class: cls });
+        if (cls === 'active' || cls === 'crashed_running') {
+            report.preserved.push({ agentId: entry.agentId, reason: cls });
+            continue;
+        }
+        if (options.dryRun) {
+            // Dry-run reports the classification only — no cleanup, no remove.
+            continue;
+        }
+        const cleanup = manager.cleanup(entry.agentId);
+        if (cleanup.ok) {
+            report.removed.push(entry.path);
+        }
+        else {
+            report.errors.push({
+                agentId: entry.agentId,
+                detail: `${cleanup.reason}: ${cleanup.detail}`,
+            });
+        }
+    }
+    return report;
+}
+//# sourceMappingURL=cleanup.js.map

package/dist/core/worktree-manager/manager.js

@@ -0,0 +1,303 @@
+/**
+ * WorktreeManager — .
+ *
+ * the upstream tool spawns a separate git worktree per dispatched sub-agent so
+ * parallel agents never collide on the filesystem. This module is Pugi's
+ * parity surface: it binds a worktree to an `agentId` (the same kebab-case
+ * id the agent-progress JSON uses) and exposes a tiny CRUD-shaped API
+ * the dispatcher can call before/after spawning a sub-persona.
+ *
+ * Differences from the existing `core/edits/worktree.ts` primitive:
+ *
+ *  - The edits primitive keys worktrees by UUID and serves the manual
+ *    `pugi worktree create/promote/drop` operator surface (one-shot
+ *    scratch trees that get promoted back to the operator's tree).
+ *  - This manager keys worktrees by AGENT ID so the dispatcher (and any
+ *    observer like `pugi worktrees list`) can correlate a worktree
+ *    with the in-flight agent driving it.
+ *
+ * The two namespaces coexist safely because the directory shapes differ:
+ *
+ *  - manager: `<cwd>/.pugi/worktrees/<agent-id>/`       (kebab-case)
+ *  - primitive `<cwd>/.pugi/worktrees/<uuid>/`           (dashed hex)
+ *
+ * The manager refuses to operate on a path whose basename does not match
+ * the agent-id regex `[a-zA-Z0-9_-]+` and does NOT collide with the UUID
+ * shape (`^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$`).
+ *
+ * Concurrency:
+ *
+ *  - `create(agentId)` is mutex'd per agent-id in process so two
+ *    concurrent dispatch hooks racing on the same id resolve to the
+ *    same handle (the second call awaits the first).
+ *  - At the filesystem level the worktree dir's existence is the lock:
+ *    if a stale dir for an agent-id survives from a previous process
+ *    `create` returns `already_exists` so the caller can decide to
+ *    reuse-or-cleanup explicitly (avoids `git worktree add` racing on
+ *    the same path which surfaces a noisy git error).
+ *
+ * Brand voice: ASCII only, no emoji, no banned words.
+ */
+import { spawnSync } from 'node:child_process';
+import { existsSync, mkdirSync, readdirSync, statSync } from 'node:fs';
+import { resolve, sep } from 'node:path';
+/**
+ * Filename-safe + dispatcher-safe agent id.
+ *
+ * Mirrors the regex on `AgentProgress.agentId` so an id that can write a
+ * progress file is exactly the id this manager will accept. The UUID
+ * exclusion below makes sure a caller never accidentally collides with
+ * the existing UUID-based scratch worktrees managed by
+ * `core/edits/worktree.ts`.
+ */
+const AGENT_ID_RE = /^[a-zA-Z0-9_-]+$/;
+const UUID_RE = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
+/** Validate an agent id. Exported for spec coverage + caller pre-checks. */
+export function isValidAgentId(id) {
+    if (typeof id !== 'string' || id.length === 0 || id.length > 128)
+        return false;
+    if (!AGENT_ID_RE.test(id))
+        return false;
+    if (UUID_RE.test(id))
+        return false;
+    // Disallow `.` / `..` and the archive subdir name reserved by
+    // agent-progress cleanup so list/scan never crosses paths.
+    if (id === '.' || id === '..' || id === 'archive')
+        return false;
+    return true;
+}
+/**
+ * Build the absolute path for an agent's worktree without touching the
+ * filesystem. Exposed so the dispatcher can compute a `cwd` for the
+ * spawned child without invoking the manager (useful in dry-run paths).
+ */
+export function worktreePathFor(cwd, agentId) {
+    return resolve(cwd, '.pugi', 'worktrees', agentId);
+}
+/** Shape an agent-id + slug into the canonical branch name. */
+export function branchNameFor(agentId, slug) {
+    const clean = (slug ?? '')
+        .toLowerCase()
+        .replace(/[^a-z0-9-]+/g, '-')
+        .replace(/^-+|-+$/g, '')
+        .slice(0, 24);
+    return clean.length > 0 ? `agent/${agentId}-${clean}` : `agent/${agentId}`;
+}
+/**
+ * Class wrapping git worktree operations for a single workspace root.
+ * Stateless across instances except for the per-agent-id mutex map.
+ */
+export class WorktreeManager {
+    cwd;
+    spawnGit;
+    inFlight = new Map();
+    constructor(options) {
+        this.cwd = options.cwd;
+        this.spawnGit = options.spawnGit ?? defaultSpawnGit;
+    }
+    /**
+     * Create a worktree bound to `agentId`. Idempotent under concurrent
+     * callers: the second concurrent `create(<same id>)` awaits the first.
+     * A subsequent `create()` after a process restart on an EXISTING dir
+     * returns `already_exists` so the caller can choose to cleanup-then-
+     * recreate explicitly.
+     */
+    async create(agentId, options = {}) {
+        if (!isValidAgentId(agentId)) {
+            return { ok: false, reason: 'invalid_agent_id', detail: `agent id ${String(agentId)} does not match ${AGENT_ID_RE} or collides with UUID shape` };
+        }
+        const pending = this.inFlight.get(agentId);
+        if (pending)
+            return pending;
+        const promise = this.createUnlocked(agentId, options);
+        this.inFlight.set(agentId, promise);
+        try {
+            return await promise;
+        }
+        finally {
+            this.inFlight.delete(agentId);
+        }
+    }
+    async createUnlocked(agentId, options) {
+        const gitDir = this.spawnGit(['rev-parse', '--git-dir'], this.cwd);
+        if (gitDir.status !== 0) {
+            return { ok: false, reason: 'not_a_git_repo', detail: `not a git repo: ${this.cwd}` };
+        }
+        const target = worktreePathFor(this.cwd, agentId);
+        if (existsSync(target)) {
+            return {
+                ok: false,
+                reason: 'already_exists',
+                detail: `worktree already exists at ${target}; call cleanup(${agentId}) first if reuse intended`,
+            };
+        }
+        const baseRef = options.baseRef ?? 'HEAD';
+        const baseShaResult = this.spawnGit(['rev-parse', baseRef], this.cwd);
+        if (baseShaResult.status !== 0) {
+            return {
+                ok: false,
+                reason: 'git_command_failed',
+                detail: `cannot resolve base ref ${baseRef}: ${baseShaResult.stderr}`,
+            };
+        }
+        const baseSha = baseShaResult.stdout.trim();
+        const branch = branchNameFor(agentId, options.slug);
+        // Ensure the parent exists before git creates the leaf. git worktree
+        // add will create the leaf itself; pre-creating .pugi/worktrees/ keeps
+        // the failure mode local to git (we never have to mkdir the leaf).
+        const worktreesRoot = resolve(this.cwd, '.pugi', 'worktrees');
+        mkdirSync(worktreesRoot, { recursive: true });
+        // `-b <branch> <path> <base>` creates a NEW branch off `base`,
+        // checked out at `path`. We deliberately do NOT use `--detach` here
+        // (unlike the scratch primitive) so the branch survives across
+        // process restarts and the operator can `git push agent/<id>-<slug>`
+        // if they want to inspect the child's work outside the worktree.
+        const create = this.spawnGit(['worktree', 'add', '-b', branch, target, baseSha], this.cwd);
+        if (create.status !== 0) {
+            return {
+                ok: false,
+                reason: 'git_command_failed',
+                detail: `git worktree add failed: ${create.stderr || create.stdout}`,
+            };
+        }
+        return {
+            ok: true,
+            value: { agentId, path: target, branch, baseSha },
+        };
+    }
+    /**
+     * Remove the worktree bound to `agentId`. Idempotent: a missing path
+     * surfaces `worktree_missing` rather than throwing, so a double-call
+     * during dispatch teardown never crashes the parent.
+     */
+    cleanup(agentId) {
+        if (!isValidAgentId(agentId)) {
+            return { ok: false, reason: 'invalid_agent_id', detail: `agent id ${String(agentId)} is invalid` };
+        }
+        const target = worktreePathFor(this.cwd, agentId);
+        // Guard: never let cleanup touch a path that escapes the worktrees
+        // root (defensive — the worktreePathFor builder is already bounded
+        // because the agent id regex rejects '..', but containment check
+        // is cheap and gives us a second line of defense).
+        const root = resolve(this.cwd, '.pugi', 'worktrees');
+        if (!target.startsWith(root + sep)) {
+            return { ok: false, reason: 'invalid_agent_id', detail: `resolved path ${target} escapes ${root}` };
+        }
+        if (!existsSync(target)) {
+            // Best-effort prune so a metadata-only orphan goes away too.
+            this.spawnGit(['worktree', 'prune'], this.cwd);
+            return { ok: false, reason: 'worktree_missing', detail: `no worktree at ${target}` };
+        }
+        const remove = this.spawnGit(['worktree', 'remove', '--force', target], this.cwd);
+        if (remove.status !== 0) {
+            return {
+                ok: false,
+                reason: 'git_command_failed',
+                detail: `git worktree remove failed: ${remove.stderr || remove.stdout}`,
+            };
+        }
+        return { ok: true, value: { removed: target } };
+    }
+    /**
+     * Enumerate worktrees the manager knows about. Read-only and never
+     * touches git metadata; the optional `gitTracked` flag on each entry
+     * surfaces the cross-check against `git worktree list --porcelain`.
+     */
+    list() {
+        const root = resolve(this.cwd, '.pugi', 'worktrees');
+        if (!existsSync(root)) {
+            return { ok: true, value: [] };
+        }
+        let entries;
+        try {
+            entries = readdirSync(root);
+        }
+        catch (err) {
+            return {
+                ok: false,
+                reason: 'git_command_failed',
+                detail: `readdir ${root} failed: ${err.message}`,
+            };
+        }
+        const tracked = this.collectGitTrackedWorktrees();
+        const out = [];
+        for (const name of entries) {
+            if (!isValidAgentId(name))
+                continue;
+            const path = resolve(root, name);
+            let isDir = false;
+            try {
+                isDir = statSync(path).isDirectory();
+            }
+            catch {
+                continue;
+            }
+            if (!isDir)
+                continue;
+            const meta = tracked.get(path);
+            const branch = meta?.branch ?? branchNameFor(name);
+            const baseSha = meta?.head ?? '';
+            out.push({
+                agentId: name,
+                path,
+                branch,
+                baseSha,
+                gitTracked: meta !== undefined,
+            });
+        }
+        return { ok: true, value: out };
+    }
+    /**
+     * Parse `git worktree list --porcelain` into a `path → {branch, head}`
+     * map. Errors degrade to an empty map — `list()` still surfaces the
+     * directory entries; the caller sees `gitTracked: false` rows and can
+     * decide.
+     */
+    collectGitTrackedWorktrees() {
+        const out = new Map();
+        const list = this.spawnGit(['worktree', 'list', '--porcelain'], this.cwd);
+        if (list.status !== 0)
+            return out;
+        let currentPath = null;
+        let currentHead = '';
+        let currentBranch = '';
+        const commit = () => {
+            if (currentPath) {
+                out.set(currentPath, { branch: currentBranch, head: currentHead });
+            }
+            currentPath = null;
+            currentHead = '';
+            currentBranch = '';
+        };
+        for (const raw of list.stdout.split('\n')) {
+            const line = raw.trimEnd();
+            if (line.length === 0) {
+                commit();
+                continue;
+            }
+            if (line.startsWith('worktree ')) {
+                // New record — flush the previous one if any.
+                commit();
+                currentPath = line.slice('worktree '.length);
+            }
+            else if (line.startsWith('HEAD ')) {
+                currentHead = line.slice('HEAD '.length);
+            }
+            else if (line.startsWith('branch ')) {
+                // `branch refs/heads/agent/foo` → `agent/foo`
+                const ref = line.slice('branch '.length);
+                currentBranch = ref.replace(/^refs\/heads\//, '');
+            }
+        }
+        commit();
+        return out;
+    }
+}
+function defaultSpawnGit(args, cwd) {
+    return spawnSync('git', args, {
+        cwd,
+        encoding: 'utf8',
+        maxBuffer: 16 * 1024 * 1024,
+    });
+}
+//# sourceMappingURL=manager.js.map

package/dist/index.js

@@ -1,6 +1,34 @@
 #!/usr/bin/env node
 import { runCli } from './runtime/cli.js';
+import { PugiCliUpgradeRequiredError } from './core/transport/version-interceptor.js';
 runCli(process.argv.slice(2)).catch((error) => {
+    // PR-CLI-SERVER-VERSION-HANDSHAKE . When the admin-api returns
+    // 426 Upgrade Required, the engine transport throws a typed
+    // PugiCliUpgradeRequiredError. Render an operator-friendly banner
+    // (vs. the bland `pugi: <message>` default) so the upgrade command
+    // is obvious + copy-pasteable. Plain console.error rather than Ink
+    // here because the error may surface during one-shot commands where
+    // no Ink renderer is mounted (REPL paths catch via runtime/cli.ts).
+    if (error instanceof PugiCliUpgradeRequiredError) {
+        const lines = [
+            '',
+            'Pugi CLI upgrade required',
+            '',
+            ` Your installed version: ${error.installedVersion}`,
+            ` Server requires minimum: ${error.minClientVersion}`,
+            ` Latest recommended:    ${error.recommendedVersion}`,
+            '',
+            ` Upgrade: ${error.upgradeCommand}`,
+            ` Docs:   ${error.upgradeUrl}`,
+            '',
+            ' Until you upgrade, the server will reject your requests.',
+            ' This protects you from silent protocol-drift bugs.',
+            '',
+        ];
+        console.error(lines.join('\n'));
+        process.exitCode = 1;
+        return;
+    }
     const message = error instanceof Error ? error.message : String(error);
     console.error(`pugi: ${message}`);
     process.exitCode = 1;