@pugi/cli 0.1.0-beta.9 → 0.1.0-beta.91

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/include-parser.js

@@ -0,0 +1,249 @@
+/**
+ * `.worktreeinclude` parser - PUGI-487.
+ *
+ * The `.worktreeinclude` file lives at the repository root and carries
+ * gitignore-syntax patterns. Files that:
+ *
+ *   1. Match at least one pattern in `.worktreeinclude`, AND
+ *   2. Are git-ignored (untracked-and-ignored OR explicitly ignored),
+ *
+ * get COPIED into a fresh `pugi --worktree <name>` tree right after
+ * `git worktree add` finishes. Tracked files are NEVER copied because
+ * git already brings them along on its own, and double-writing would
+ * corrupt the worktree index.
+ *
+ * Why a separate include file instead of `.gitignore` negation
+ * patterns?
+ *
+ *  - The common case is "I have an untracked `.env` with API keys that
+ *    every parallel session needs". Listing it in `.gitignore` with
+ *    a negation would force-add it to the repo, defeating the point.
+ *  - Operators want a single-file, copy-pasteable manifest of WHAT
+ *    leaves the main tree, not a derived view across `.gitignore`
+ *    semantics.
+ *
+ * Pattern grammar (subset of gitignore):
+ *
+ *  - Lines starting with `#` are comments. Blank lines are skipped.
+ *  - Trailing `/` means directory-only and applies recursively to
+ *    every file under the directory.
+ *  - Leading `!` is a negation pattern that REMOVES matches from
+ *    prior includes. Multiple negations are processed in order.
+ *  - `*` matches any character except `/`.
+ *  - `**` matches any number of path segments.
+ *  - `?` matches a single non-`/` character.
+ *  - Patterns with NO `/` match anywhere in the tree (e.g. `.env`
+ *    matches both `./.env` and `./apps/foo/.env`).
+ *  - Patterns starting with `/` are anchored to the repository root.
+ *
+ * Brand voice: ASCII only, no emoji, no banned words.
+ */
+import { spawnSync } from 'node:child_process';
+import { existsSync, readFileSync, statSync } from 'node:fs';
+import { resolve, sep, posix } from 'node:path';
+/** Default file name. */
+export const WORKTREE_INCLUDE_FILENAME = '.worktreeinclude';
+/**
+ * Parse the textual contents of a `.worktreeinclude` file into a rule
+ * list. Pure function - does not touch the filesystem. Exposed for
+ * spec coverage and the cleanup/dry-run path.
+ */
+export function parseWorktreeIncludeText(text, source = WORKTREE_INCLUDE_FILENAME) {
+    const rules = [];
+    const lines = text.split(/\r?\n/);
+    for (const raw of lines) {
+        const line = raw.trim();
+        if (line.length === 0)
+            continue;
+        if (line.startsWith('#'))
+            continue;
+        let body = line;
+        let negate = false;
+        if (body.startsWith('!')) {
+            negate = true;
+            body = body.slice(1);
+        }
+        if (body.length === 0)
+            continue;
+        let directoryOnly = false;
+        if (body.endsWith('/')) {
+            directoryOnly = true;
+            body = body.slice(0, -1);
+        }
+        let anchored = false;
+        if (body.startsWith('/')) {
+            anchored = true;
+            body = body.slice(1);
+        }
+        else if (body.includes('/')) {
+            // a non-leading slash also anchors per gitignore semantics
+            anchored = true;
+        }
+        if (body.length === 0)
+            continue;
+        rules.push({
+            raw: line,
+            pattern: body,
+            negate,
+            directoryOnly,
+            anchored,
+        });
+    }
+    return { rules, source };
+}
+/**
+ * Load + parse `.worktreeinclude` from a repository root. Returns an
+ * empty rule set when the file is absent or unreadable - a missing
+ * include file is the normal case (no extras to copy).
+ */
+export function loadWorktreeInclude(repoRoot) {
+    const path = resolve(repoRoot, WORKTREE_INCLUDE_FILENAME);
+    if (!existsSync(path)) {
+        return { rules: [], source: path };
+    }
+    try {
+        const text = readFileSync(path, 'utf8');
+        return parseWorktreeIncludeText(text, path);
+    }
+    catch {
+        return { rules: [], source: path };
+    }
+}
+const REGEX_ESCAPE = /[.+^${}()|[\]\\]/;
+/**
+ * Convert a gitignore-style glob pattern into a regex source string.
+ * Subset implementation: covers `*`, `**`, `?`, and escapes the rest.
+ *
+ * Uses index-based scanning so `**` is detected and consumed before a
+ * single `*` substitution could eat the doubled form.
+ */
+function globToRegexSource(pattern) {
+    let out = '';
+    for (let i = 0; i < pattern.length; i += 1) {
+        const ch = pattern.charAt(i);
+        if (ch === '*') {
+            if (pattern.charAt(i + 1) === '*') {
+                out += '.*';
+                i += 1;
+                continue;
+            }
+            out += '[^/]*';
+            continue;
+        }
+        if (ch === '?') {
+            out += '[^/]';
+            continue;
+        }
+        if (REGEX_ESCAPE.test(ch)) {
+            out += '\\' + ch;
+            continue;
+        }
+        out += ch;
+    }
+    return out;
+}
+/**
+ * Decide whether `relPath` (a forward-slash, no-leading-slash path
+ * relative to the repo root) is matched by the given rule list. The
+ * last matching rule wins so a negation after an include drops the
+ * entry and an include after a negation re-adds it.
+ */
+export function matchesWorktreeInclude(relPath, rules, isDirectory = false) {
+    const normalized = relPath.replace(/\\+/g, '/');
+    let matched = false;
+    for (const rule of rules) {
+        if (rule.directoryOnly && !isDirectory) {
+            // directory-only rule still matches files UNDER the dir (handled
+            // below). Falls through to the file-match attempt.
+        }
+        const source = buildRegex(rule);
+        const re = new RegExp('^' + source + '$');
+        if (re.test(normalized)) {
+            matched = !rule.negate;
+            continue;
+        }
+        if (rule.directoryOnly) {
+            const reUnder = new RegExp('^' + source + '/.*$');
+            if (reUnder.test(normalized)) {
+                matched = !rule.negate;
+            }
+        }
+    }
+    return matched;
+}
+function buildRegex(rule) {
+    const body = globToRegexSource(rule.pattern);
+    if (rule.anchored) {
+        return body;
+    }
+    // Unanchored pattern matches anywhere in the tree. Allow a
+    // segment-aligned match by accepting either start-of-string or a
+    // `/` boundary before the pattern body.
+    return '(?:.*/)?' + body;
+}
+/**
+ * Walk `repoRoot` and return every git-ignored file path that matches
+ * the include rules. Tracked files are excluded because they ride
+ * along with git automatically.
+ *
+ * Implementation note: rather than re-implement gitignore evaluation
+ * the default lister shells out to
+ * `git ls-files --others --ignored --exclude-standard` to get the
+ * authoritative ignored-untracked list. Tracked files never appear in
+ * that output, so the result is exactly the safe-to-copy candidate
+ * pool.
+ */
+export function collectWorktreeIncludeFiles(repoRoot, rules, options = {}) {
+    if (rules.length === 0)
+        return [];
+    const lister = options.listIgnored ?? defaultListIgnored;
+    const stat = options.isDirectory ?? defaultIsDirectory;
+    const candidates = lister(resolve(repoRoot));
+    const out = [];
+    for (const candidate of candidates) {
+        const rel = candidate.replace(/\\+/g, '/').replace(/^\.\//, '');
+        if (rel.length === 0)
+            continue;
+        if (rel.startsWith('.pugi/') || rel.startsWith('.claude/')) {
+            // Never copy Pugi or .claude state into the worktree. Those
+            // dirs are owned by the runtime and the include file should
+            // not be able to leak audit logs or stale session state.
+            continue;
+        }
+        const absPath = resolve(repoRoot, rel);
+        const isDir = stat(absPath);
+        if (matchesWorktreeInclude(rel, rules, isDir)) {
+            out.push(rel);
+        }
+    }
+    return out;
+}
+function defaultListIgnored(repoRoot) {
+    // `-z` emits NUL-separated paths, the only safe form when filenames
+    // may contain spaces or newlines.
+    const result = spawnSync('git', ['ls-files', '--others', '--ignored', '--exclude-standard', '-z'], {
+        cwd: repoRoot,
+        encoding: 'buffer',
+        shell: false,
+        maxBuffer: 64 * 1024 * 1024,
+    });
+    if (result.status !== 0 || !result.stdout)
+        return [];
+    const text = result.stdout.toString('utf8');
+    return text.split('\u0000').filter((s) => s.length > 0);
+}
+function defaultIsDirectory(absPath) {
+    try {
+        return statSync(absPath).isDirectory();
+    }
+    catch {
+        return false;
+    }
+}
+/** Cross-platform path-join in posix form (for matching semantics). */
+export function joinRel(parent, child) {
+    return posix.join(parent.replace(/\\+/g, '/'), child);
+}
+/** Re-export the system separator so consumers do not have to import it. */
+export const PATH_SEP = sep;
+//# sourceMappingURL=include-parser.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