@pugi/cli 0.1.0-beta.98 → 1.0.0-alpha.1

package/dist/core/context/watcher.js

@@ -1,342 +0,0 @@
-/**
- * chokidar-based filewatch - Phase 1 (three-tier context).
- *
- * The REPL needs a live signal when files change so the operator's
- * agent can re-read a stale file, and so the status bar can surface a
- * "file changed" badge. chokidar wraps fsevents / inotify / kqueue so
- * the cross-platform surface stays sane.
- *
- * Design choices:
- *
- *  1. **Ignore-aware**: every watched path is filtered through the
- *     same `PugiIgnore` matcher the skeleton walker uses. We pass the
- *     matcher into chokidar's `ignored` option so `node_modules/`,
- *     `dist/`, `.git/`, and secret files are never watched at all -
- *     this matters because chokidar's resource bound is the number
- *     of watched paths, not the number of total files in the repo.
- *
- *  2. **Throttle**: chokidar can fire dozens of `change` events when
- *     a code formatter rewrites a directory. We batch events in a
- *     `THROTTLE_WINDOW_MS` window and emit a single aggregated event
- *     so the REPL system line / status bar do not flicker.
- *
- *  3. **Watch cap**: per spec, the watcher caps watched paths at
- *     `MAX_WATCHED_PATHS`. Once the count crosses the cap we close
- *     the watcher and fall back to "no live updates this session" -
- *     better to silently lose the badge than to consume thousands of
- *     file descriptors. The fallback path emits one warning event so
- *     the operator knows live updates are off.
- *
- *  4. **Lifecycle**: `start()` is async (chokidar's `ready` event)
- *     so the caller can `await` the initial scan. `close()` is also
- *     async (chokidar's close is async). The watcher is reusable
- *     across multiple `start` / `close` pairs, but Phase 1 expects
- *     one-watcher-per-REPL-session.
- *
- *  5. **Testability**: the chokidar handle is injectable via the
- *     `watchFactory` option. Production wires `chokidar.watch`;
- *     tests pass a fake emitter that lets the spec drive `add` /
- *     `change` / `unlink` events synchronously.
- */
-import { EventEmitter } from 'node:events';
-import chokidar from 'chokidar';
-/** Per-spec watch-path cap. */
-export const MAX_WATCHED_PATHS = 10_000;
-/** Batching window for the change throttle. */
-export const THROTTLE_WINDOW_MS = 250;
-/**
- * Number of `add` events between cap-check re-evaluations. The ready
- * handler triggers the FIRST cap check, but a `git checkout` of a
- * giant subtree post-ready can blow past the cap without ever
- * re-evaluating. Sample every N adds so the cap fires within a
- * bounded window even on post-ready growth. Cheap: one Map
- * iteration per N adds. triple-review P2 (PR).
- */
-export const CAP_CHECK_ADD_INTERVAL = 1_000;
-/**
- * Concrete watcher. Construct, then `await start()`. Subscribe via
- * `.on('batch', cb)`. `await close()` to tear down.
- */
-export class PugiWatcher extends EventEmitter {
-    cwd;
-    ignore;
-    maxWatchedPaths;
-    throttleWindowMs;
-    now;
-    watchFactory;
-    setTimeoutImpl;
-    clearTimeoutImpl;
-    handle = null;
-    buffer = [];
-    windowStart = null;
-    timer = null;
-    closed = false;
-    capExceededEmitted = false;
-    capCheckTimer = null;
-    /**
-     * Counter of `add` events received since the last cap-check sample.
-     * When it crosses CAP_CHECK_ADD_INTERVAL we schedule another check.
-     * Resets on every cap-check run. triple-review P2 (PR).
-     */
-    addsSinceLastCapCheck = 0;
-    constructor(options) {
-        super();
-        this.cwd = options.cwd;
-        this.ignore = options.ignore;
-        this.maxWatchedPaths = options.maxWatchedPaths ?? MAX_WATCHED_PATHS;
-        this.throttleWindowMs = options.throttleWindowMs ?? THROTTLE_WINDOW_MS;
-        this.now = options.now ?? (() => Date.now());
-        this.watchFactory = options.watchFactory ?? defaultWatchFactory;
-        this.setTimeoutImpl = options.setTimeoutImpl ?? ((fn, ms) => setTimeout(fn, ms));
-        this.clearTimeoutImpl = options.clearTimeoutImpl ?? ((h) => clearTimeout(h));
-        // Default no-op error listener - Node's EventEmitter.emit('error', ...)
-        // THROWS synchronously when no listener is registered. Production
-        // bootstrap awaits start() before constructing ReplSession, so there
-        // is no listener on the watcher at the moment chokidar may surface
-        // an error during the initial scan. The default listener swallows
-        // the event so emit() does not crash the CLI; any real consumer
-        // that subscribes later receives the events as normal because
-        // EventEmitter delivers to every registered listener, not just one.
-        // Codex P1 (PR).
-        this.on('error', () => {
-            /* defensive no-op so emit('error') never throws */
-        });
-    }
-    /**
-     * Open the chokidar handle and wait for the `ready` event. Resolves
-     * once the initial scan completes. Rejects when the underlying
-     * watcher errors out before `ready`.
-     */
-    async start() {
-        if (this.handle)
-            return;
-        if (this.closed) {
-            throw new Error('PugiWatcher: cannot start a closed watcher');
-        }
-        const opts = {
-            // chokidar does not tell the predicate whether the path is a
-            // file or a directory, so we ask the matcher both ways. If
-            // either form matches, the path is excluded. This catches
-            // gitignore-style dir patterns (`node_modules/`) that would
-            // otherwise only match descendants, leaving the dir itself
-            // visible to chokidar's recursion.
-            ignored: (path) => this.ignore.isIgnored(path) || this.ignore.isIgnored(path, true),
-            ignoreInitial: true,
-            persistent: true,
-            // Disable polling - we want fsevents / inotify / kqueue speed.
-            usePolling: false,
-            // Aggregate events so we get one `change` per save, not three.
-            awaitWriteFinish: {
-                stabilityThreshold: 50,
-                pollInterval: 25,
-            },
-            // Keep the depth shallow at the chokidar layer too - even after
-            // ignore filtering, a multi-million file dir could exhaust file
-            // descriptors. The skeleton walker has its own depth cap; this
-            // one is a safety net.
-            depth: 12,
-        };
-        const watcher = this.watchFactory(this.cwd, opts);
-        this.handle = watcher;
-        return new Promise((resolveReady, rejectReady) => {
-            let settled = false;
-            watcher.on('ready', () => {
-                if (settled)
-                    return;
-                settled = true;
-                this.emit('ready');
-                this.scheduleCapCheck();
-                resolveReady();
-            });
-            watcher.on('error', (err) => {
-                const error = err instanceof Error ? err : new Error(String(err));
-                this.emit('error', error);
-                if (!settled) {
-                    settled = true;
-                    rejectReady(error);
-                }
-            });
-            watcher.on('add', (path) => {
-                this.queue('add', path);
-                // Re-evaluate the cap every CAP_CHECK_ADD_INTERVAL adds so a
-                // post-ready burst (e.g. `git checkout` of a giant subtree)
-                // does not silently blow past the watched-paths cap. The
-                // ready-time check is preserved; this is the missing follow-up
-                // sampler the comment promised. triple-review P2 (PR).
-                this.addsSinceLastCapCheck += 1;
-                if (this.addsSinceLastCapCheck >= CAP_CHECK_ADD_INTERVAL) {
-                    this.addsSinceLastCapCheck = 0;
-                    this.scheduleCapCheck();
-                }
-            });
-            watcher.on('change', (path) => this.queue('change', path));
-            watcher.on('unlink', (path) => this.queue('unlink', path));
-        });
-    }
-    /** Close the underlying watcher and clear the throttle timer. */
-    async close() {
-        this.closed = true;
-        if (this.timer !== null) {
-            this.clearTimeoutImpl(this.timer);
-            this.timer = null;
-        }
-        if (this.capCheckTimer !== null) {
-            this.clearTimeoutImpl(this.capCheckTimer);
-            this.capCheckTimer = null;
-        }
-        if (this.handle) {
-            try {
-                await this.handle.close();
-            }
-            catch {
-                /* idempotent - chokidar may already be closed */
-            }
-            this.handle = null;
-        }
-        this.buffer = [];
-        this.windowStart = null;
-    }
-    /**
-     * Force-flush any pending events. Exposed primarily for tests that
-     * want to assert the batched payload without waiting for the
-     * timeout. Production code can also use this on REPL teardown so
-     * pending events are surfaced before close.
-     */
-    flush() {
-        if (this.buffer.length === 0)
-            return;
-        if (this.timer !== null) {
-            this.clearTimeoutImpl(this.timer);
-            this.timer = null;
-        }
-        const events = this.buffer;
-        this.buffer = [];
-        const start = this.windowStart ?? this.now();
-        const end = this.now();
-        this.windowStart = null;
-        this.emit('batch', {
-            events: dedupeBatch(events),
-            windowStartEpochMs: start,
-            windowEndEpochMs: end,
-        });
-    }
-    /** Test surface - returns the current pending buffer. */
-    pendingCount() {
-        return this.buffer.length;
-    }
-    /* ------------------------------------------------------------ */
-    /* Internals                                                   */
-    /* ------------------------------------------------------------ */
-    queue(kind, path) {
-        if (this.closed)
-            return;
-        // Defensive double-check: even if chokidar's `ignored` predicate
-        // accepted the path, the matcher gets the last word. Same dir-aware
-        // double-call as the predicate above.
-        if (this.ignore.isIgnored(path) || this.ignore.isIgnored(path, true))
-            return;
-        const atEpochMs = this.now();
-        const event = {
-            path: relPathPosix(this.cwd, path),
-            absPath: path,
-            kind,
-            atEpochMs,
-        };
-        if (this.windowStart === null)
-            this.windowStart = atEpochMs;
-        this.buffer.push(event);
-        if (this.timer === null) {
-            this.timer = this.setTimeoutImpl(() => this.flush(), this.throttleWindowMs);
-        }
-    }
-    /**
-     * Lazy cap check - chokidar reports its watched paths via
-     * `getWatched()`. We sample once on ready, and again every
-     * CAP_CHECK_ADD_INTERVAL `add` events thereafter (e.g. a `git
-     * checkout` of a giant subtree post-ready). The cost is one Map
-     * iteration; the payoff is silent fallback when an operator targets
-     * a giant repo. Guarded against double-scheduling so the add-handler
-     * cannot stack multiple timers.
-     */
-    scheduleCapCheck() {
-        if (this.closed || this.capExceededEmitted)
-            return;
-        if (this.capCheckTimer !== null)
-            return;
-        this.capCheckTimer = this.setTimeoutImpl(() => this.runCapCheck(), 100);
-    }
-    runCapCheck() {
-        this.capCheckTimer = null;
-        if (this.closed || this.capExceededEmitted || !this.handle)
-            return;
-        try {
-            const watched = this.handle.getWatched();
-            let count = 0;
-            for (const entries of Object.values(watched)) {
-                count += entries.length;
-            }
-            if (count > this.maxWatchedPaths) {
-                this.capExceededEmitted = true;
-                this.emit('capExceeded', {
-                    watchedCount: count,
-                    cap: this.maxWatchedPaths,
-                });
-                // Stop watching so we do not consume more file descriptors.
-                void this.close();
-            }
-        }
-        catch {
-            /* chokidar threw on getWatched - safe to ignore, cap check is best-effort */
-        }
-    }
-}
-/* ------------------------------------------------------------------ */
-/* Helpers                                                           */
-/* ------------------------------------------------------------------ */
-/**
- * Convert an absolute path to a repo-relative POSIX path. chokidar
- * already uses forward slashes on Windows because it normalises
- * internally, but we run the same fix unconditionally so the contract
- * is platform-agnostic.
- */
-function relPathPosix(cwd, abs) {
-    // chokidar may report paths already relative to cwd. Normalise both
-    // sides to forward slashes for the prefix compare.
-    const cwdPosix = cwd.replace(/\\/g, '/');
-    const absPosix = abs.replace(/\\/g, '/');
-    if (absPosix.startsWith(`${cwdPosix}/`)) {
-        return absPosix.slice(cwdPosix.length + 1);
-    }
-    if (absPosix === cwdPosix)
-        return '';
-    return absPosix;
-}
-/**
- * Collapse consecutive (path, kind) duplicates inside a batch. We
- * keep the FIRST occurrence so the order is "first-touch first".
- * Different kinds for the same path are preserved (`add` then
- * `change`) - the model wants both signals.
- */
-function dedupeBatch(events) {
-    const seen = new Set();
-    const out = [];
-    for (const event of events) {
-        const key = `${event.kind}:${event.path}`;
-        if (seen.has(key))
-            continue;
-        seen.add(key);
-        out.push(event);
-    }
-    return out;
-}
-/**
- * Production chokidar factory. Returns the real `FSWatcher` cast to
- * the minimal interface so the watcher class never directly imports
- * chokidar types beyond `WatchOptions`. The cast is safe - chokidar's
- * `FSWatcher` is a superset of `ChokidarLike`.
- */
-function defaultWatchFactory(cwd, opts) {
-    const watcher = chokidar.watch(cwd, opts);
-    return watcher;
-}
-//# sourceMappingURL=watcher.js.map

package/dist/core/context/working-set.js

@@ -1,165 +0,0 @@
-/**
- * Tier 1 working-set tracker - Phase 1 (three-tier context).
- *
- * The model context window is finite. Tier 0 (repo skeleton, ~5KB) is
- * always loaded; Tier 2 (RAG, Anvil-side, deferred to ) answers
- * queries on demand. Tier 1 - the working set - lives between them: the
- * subset of files the agent has touched THIS session, bounded so a
- * long REPL session does not unbounded-grow the system prompt.
- *
- * Design choices:
- *
- *  1. **LRU semantics**: the most-recently-touched file stays in the
- *     window; the oldest is evicted when the cap is hit. We use a
- *     `Map` so insertion order doubles as recency order (delete +
- *     re-set bubbles the entry to the tail).
- *
- *  2. **Source tracking**: every `track()` call records the source -
- *     `read` (agent fetched the file), `edit` (agent modified it),
- *     `write` (agent created it). The source seeds future heuristics
- *     (e.g. always pin edited files near the cap, never evict files
- *     written this session) but Phase 1 keeps the policy simple:
- *     pure LRU.
- *
- *  3. **No persistence**: working set is in-memory only. A REPL
- *     restart rebuilds from scratch (and from `/resume` SessionStore
- *     replay if/when we wire that). Per spec: "node:sqlite NOT
- *     needed for this sprint."
- *
- *  4. **Path normalisation**: we resolve every path to an absolute
- *     form on insert so two `track()` calls with `./foo.ts` and
- *     `/abs/cwd/foo.ts` collapse to one entry.
- *
- *  5. **Defensive cap**: `MAX_WORKING_SET = 50` per spec. We hold the
- *     cap as a configurable option so tests can dial it down to
- *     exercise eviction without 51 fixture files.
- */
-import { resolve } from 'node:path';
-/** Spec-mandated default cap. Mirrors the doc string in the sprint plan. */
-export const DEFAULT_WORKING_SET_CAPACITY = 50;
-export class WorkingSet {
-    entries = new Map();
-    capacity;
-    now;
-    constructor(options = {}) {
-        this.capacity = options.capacity ?? DEFAULT_WORKING_SET_CAPACITY;
-        if (!Number.isInteger(this.capacity) || this.capacity <= 0) {
-            throw new Error(`WorkingSet capacity must be a positive integer, got ${options.capacity}`);
-        }
-        this.now = options.now ?? (() => Date.now());
-    }
-    /**
-     * Record that the agent touched `path`. The path is normalised to an
-     * absolute form so duplicate calls with different relative paths
-     * collapse. Returns the entry as stored.
-     *
-     * LRU bump: an existing entry is deleted and re-inserted so insertion
-     * order tracks recency. The oldest entry is evicted when the
-     * insertion would breach `capacity`.
-     */
-    track(path, source, sizeBytes = 0) {
-        const absPath = resolve(path);
-        const previous = this.entries.get(absPath);
-        const touchCount = previous ? previous.touchCount + 1 : 1;
-        // Prefer the new size when the caller supplies one; otherwise keep
-        // the previous reading so we do not "forget" the file's footprint
-        // just because the second track() call did not stat the file.
-        const nextSize = sizeBytes > 0
-            ? sizeBytes
-            : (previous?.sizeBytes ?? 0);
-        const entry = Object.freeze({
-            absPath,
-            source,
-            touchedAtEpochMs: this.now(),
-            touchCount,
-            sizeBytes: nextSize,
-        });
-        // Delete first so re-insert lands at the tail (most-recent).
-        if (previous)
-            this.entries.delete(absPath);
-        this.entries.set(absPath, entry);
-        this.evictExcess();
-        return entry;
-    }
-    /**
-     * Drop a single path from the set. Returns `true` when the entry
-     * existed. Used by the file watcher's `unlink` event - a removed
-     * file is no longer in the working set.
-     */
-    forget(path) {
-        const absPath = resolve(path);
-        return this.entries.delete(absPath);
-    }
-    /** Clear the entire set - used by `/clear` slash + REPL teardown. */
-    clear() {
-        this.entries.clear();
-    }
-    /** True when the path is currently retained. */
-    has(path) {
-        return this.entries.has(resolve(path));
-    }
-    /** Live count - O(1). */
-    size() {
-        return this.entries.size;
-    }
-    /** Configured cap - surfaced so `/context` can render `12/50`. */
-    capacityLimit() {
-        return this.capacity;
-    }
-    /**
-     * Snapshot of the set ordered MOST RECENT first. Suitable for
-     * direct injection into the agent's system prompt; the oldest
-     * entries are the least relevant and trail the list so the model's
-     * recency bias works in our favour.
-     */
-    forSerialization() {
-        // `Map` iterates in insertion order = LRU order with oldest first.
-        // We want recency-first so reverse.
-        const all = Array.from(this.entries.values());
-        all.reverse();
-        return all;
-    }
-    /** Aggregate summary used by `/context` slash + status bar. */
-    summary() {
-        let totalSize = 0;
-        let oldest = null;
-        for (const entry of this.entries.values()) {
-            totalSize += entry.sizeBytes;
-            if (oldest === null || entry.touchedAtEpochMs < oldest) {
-                oldest = entry.touchedAtEpochMs;
-            }
-        }
-        return {
-            count: this.entries.size,
-            capacity: this.capacity,
-            totalSizeBytes: totalSize,
-            oldestTouchedAtEpochMs: oldest,
-        };
-    }
-    /**
-     * Public LRU eviction trigger - called automatically on every
-     * `track()` but exposed so callers (tests, future memory-pressure
-     * hook) can force a sweep without inserting a sentinel entry.
-     * Returns the count of evicted entries.
-     */
-    evict() {
-        return this.evictExcess();
-    }
-    /**
-     * Walk the head of the insertion-ordered map (oldest first) and
-     * delete entries until size <= capacity. Returns the number of
-     * entries dropped.
-     */
-    evictExcess() {
-        let removed = 0;
-        while (this.entries.size > this.capacity) {
-            const oldestKey = this.entries.keys().next().value;
-            if (oldestKey === undefined)
-                break;
-            this.entries.delete(oldestKey);
-            removed += 1;
-        }
-        return removed;
-    }
-}
-//# sourceMappingURL=working-set.js.map

package/dist/core/coordinator/agent-tools.js

@@ -1,77 +0,0 @@
-function snapshot(task) {
-    return { ...task };
-}
-function isTerminal(status) {
-    return status === 'completed' || status === 'cancelled' || status === 'failed';
-}
-export function createAgentCoordinator(options) {
-    const tasks = new Map();
-    return {
-        async createTask(agentType, prompt) {
-            const { taskId } = await options.spawn(agentType, prompt);
-            const task = {
-                id: taskId,
-                agentType,
-                prompt,
-                status: 'queued',
-                createdAt: Date.now(),
-            };
-            tasks.set(task.id, task);
-            task.status = 'running';
-            task.startedAt = Date.now();
-            return snapshot(task);
-        },
-        async sendMessage(taskId, message) {
-            const task = tasks.get(taskId);
-            if (!task) {
-                throw new Error(`agent task ${taskId} not found`);
-            }
-            if (task.status !== 'running') {
-                throw new Error(`agent task ${taskId} is not running (status=${task.status})`);
-            }
-            await options.send(taskId, message);
-        },
-        async stopTask(taskId) {
-            const task = tasks.get(taskId);
-            if (!task) {
-                throw new Error(`agent task ${taskId} not found`);
-            }
-            if (isTerminal(task.status)) {
-                return;
-            }
-            await options.stop(taskId);
-            task.status = 'cancelled';
-            task.completedAt = Date.now();
-        },
-        listTasks() {
-            return Array.from(tasks.values())
-                .sort((a, b) => b.createdAt - a.createdAt)
-                .map(snapshot);
-        },
-        getTask(taskId) {
-            const task = tasks.get(taskId);
-            return task ? snapshot(task) : null;
-        },
-        markCompleted(taskId, output) {
-            const task = tasks.get(taskId);
-            if (!task) {
-                return;
-            }
-            task.status = 'completed';
-            task.completedAt = Date.now();
-            task.output = output;
-            delete task.error;
-        },
-        markFailed(taskId, error) {
-            const task = tasks.get(taskId);
-            if (!task) {
-                return;
-            }
-            task.status = 'failed';
-            task.completedAt = Date.now();
-            task.error = error;
-            delete task.output;
-        },
-    };
-}
-//# sourceMappingURL=agent-tools.js.map

package/dist/core/coordinator/agent-toolset.js

@@ -1,65 +0,0 @@
-// apps/pugi-cli/src/core/coordinator/agent-toolset.ts
-import { randomUUID } from 'node:crypto';
-export class AgentCoordinator {
-    agents = new Map();
-    spawnAgent(subagentType, prompt) {
-        const handle = {
-            id: randomUUID(),
-            subagentType,
-            prompt,
-            status: 'spawned',
-            spawnedAt: new Date().toISOString(),
-        };
-        this.agents.set(handle.id, handle);
-        return handle;
-    }
-    sendMessage(agentId, _message) {
-        const agent = this.agents.get(agentId);
-        if (!agent) {
-            return { ok: false, reason: `agent ${agentId} not found` };
-        }
-        if (agent.status !== 'spawned' && agent.status !== 'running') {
-            return { ok: false, reason: `agent ${agentId} not accepting messages (status=${agent.status})` };
-        }
-        return { ok: true };
-    }
-    taskStop(agentId) {
-        const agent = this.agents.get(agentId);
-        if (!agent) {
-            return { ok: false, reason: `agent ${agentId} not found` };
-        }
-        agent.status = 'stopped';
-        agent.completedAt = new Date().toISOString();
-        return { ok: true };
-    }
-    markCompleted(agentId, result) {
-        const agent = this.agents.get(agentId);
-        if (!agent) {
-            return;
-        }
-        agent.status = 'completed';
-        agent.completedAt = new Date().toISOString();
-        agent.result = result;
-    }
-    markFailed(agentId, reason) {
-        const agent = this.agents.get(agentId);
-        if (!agent) {
-            return;
-        }
-        agent.status = 'failed';
-        agent.completedAt = new Date().toISOString();
-        agent.result = reason;
-    }
-    listAgents(filter) {
-        const all = Array.from(this.agents.values());
-        if (!filter?.status) {
-            return all;
-        }
-        const wanted = filter.status;
-        return all.filter((a) => a.status === wanted);
-    }
-    getAgent(id) {
-        return this.agents.get(id);
-    }
-}
-//# sourceMappingURL=agent-toolset.js.map