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

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

@@ -1,303 +0,0 @@
-/**
- * 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,44 +0,0 @@
-#!/usr/bin/env node
-import { runCli } from './runtime/cli.js';
-import { PugiCliUpgradeRequiredError } from './core/transport/version-interceptor.js';
-import { installSigintGuard } from './runtime/sigint-guard.js';
-// PUGI-469 — install the top-level double-press Ctrl+C exit guard
-// BEFORE any other init. Operators reported single ^C exiting the
-// CLI; the guard requires a second press inside a 2s window (or
-// emits a clean session-end envelope on the headless path) so a
-// stray keystroke never kills the session. See the module header
-// in `runtime/sigint-guard.ts` for the full behavior spec.
-installSigintGuard();
-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;
-});
-//# sourceMappingURL=index.js.map

package/dist/runtime/bootstrap.js

@@ -1,190 +0,0 @@
-/**
- * Bootstrap helpers — β1b U7 / U8 .
- *
- * Two related contracts:
- *
- *  - U7: when `pugi` runs in a bare directory (no `.pugi/` and no
- *    project-marker file like `package.json` / `Cargo.toml` / `go.mod`)
- *    AND we have a TTY, offer an interactive `pugi init`.
- *
- *  - U8: when `pugi` runs in a sub-directory of one or more parent
- *    projects (each carrying a `.pugi/settings.json` OR a git root),
- *    present a picker — "Found N projects: <list>. Pick OR /init here".
- *
- * Both checks are pure file-system queries; the interactive bridge
- * lives one layer up (REPL bootstrap, slash-command palette). This
- * module surfaces the structured result and the caller decides UX.
- *
- * Project markers we recognise (first match wins):
- *  - `.pugi/settings.json` (highest priority — Pugi-aware project)
- *  - `package.json` (Node / TypeScript / pnpm monorepo)
- *  - `Cargo.toml`
- *  - `go.mod`
- *  - `pyproject.toml` / `requirements.txt` / `setup.py`
- *  - `Gemfile`
- *  - `composer.json`
- *  - `pom.xml` / `build.gradle` / `build.gradle.kts`
- *  - `.git/` directory (last resort — git repo root)
- *
- * Walk depth is capped at 12 ancestors. Anything deeper is operator
- * error (running `pugi` from `/Users/x/Library/.../node_modules/...`)
- * and a deeper walk would be slow + surprising.
- *
- * Brand voice: ASCII only.
- */
-import { existsSync, statSync } from 'node:fs';
-import { dirname, resolve, basename } from 'node:path';
-const PROJECT_MARKER_FILES = [
-    '.pugi/settings.json',
-    'package.json',
-    'Cargo.toml',
-    'go.mod',
-    'pyproject.toml',
-    'requirements.txt',
-    'setup.py',
-    'Gemfile',
-    'composer.json',
-    'pom.xml',
-    'build.gradle',
-    'build.gradle.kts',
-];
-const MAX_PARENT_WALK = 12;
-/**
- * Detect the workspace state at `cwd`. Pure file-system query; never
- * throws. The caller pairs this with the TTY / --no-tty / --json flags
- * to decide whether to prompt the operator.
- */
-export function detectWorkspaceState(cwd) {
-    const absCwd = resolve(cwd);
-    // `.pugi/` at cwd always wins — we are already initialised.
-    if (hasPugiDir(absCwd)) {
-        return { kind: 'existing_pugi', root: absCwd };
-    }
-    // Project marker at cwd → proceed without prompting.
-    const cwdMarker = findMarkerAt(absCwd);
-    if (cwdMarker) {
-        return { kind: 'existing_project', root: absCwd, marker: cwdMarker };
-    }
-    // Walk parents — collect every ancestor that looks like a project.
-    const parents = findParentProjects(absCwd);
-    if (parents.length > 0) {
-        return { kind: 'inside_parent_projects', parents };
-    }
-    return { kind: 'bare' };
-}
-/**
- * Walk parent directories up to MAX_PARENT_WALK ancestors, collecting
- * every directory that has a project marker. Nearest-first. Stops at
- * the filesystem root. Exported for U8 spec coverage + for callers
- * that want the raw list (e.g. a /workspaces shell command).
- */
-export function findParentProjects(cwd) {
-    const out = [];
-    let current = dirname(resolve(cwd));
-    let last = '';
-    let hops = 0;
-    while (current && current !== last && hops < MAX_PARENT_WALK) {
-        const marker = findMarkerAt(current);
-        if (marker) {
-            out.push({ root: current, marker });
-        }
-        last = current;
-        current = dirname(current);
-        hops += 1;
-    }
-    return out;
-}
-/**
- * Return the first matching project marker filename inside `dir`, or
- * null when none of the candidates exist. `.pugi/settings.json` is a
- * file (not the directory), so we test both for symmetry — if the
- * operator has `.pugi/` but no settings.json yet, we treat it as a
- * Pugi-aware project (the directory itself is the signal).
- */
-function findMarkerAt(dir) {
-    for (const marker of PROJECT_MARKER_FILES) {
-        const path = resolve(dir, marker);
-        try {
-            if (existsSync(path))
-                return marker;
-        }
-        catch {
-            /* permission error — treat as missing */
-        }
-    }
-    // `.git/` last — costly because it touches the FS but only when no
-    // other marker hit. Skip if `.git/` is a file (worktree shim) since
-    // we still want the worktree path.
-    const gitPath = resolve(dir, '.git');
-    try {
-        if (existsSync(gitPath))
-            return '.git';
-    }
-    catch {
-        /* ignore */
-    }
-    return null;
-}
-/**
- * True iff the directory has a `.pugi/` subdirectory. We check the
- * directory itself (not the settings.json inside) because the moment
- * `.pugi/` exists Pugi is "set up here" from the operator's POV —
- * settings.json may be empty / lazily written.
- */
-function hasPugiDir(dir) {
-    const path = resolve(dir, '.pugi');
-    try {
-        if (!existsSync(path))
-            return false;
-        return statSync(path).isDirectory();
-    }
-    catch {
-        return false;
-    }
-}
-/**
- * Build a human-friendly label for a project root: prefer the basename
- * suffixed with the marker (`pugi (package.json)`). Used by the U8
- * picker to render the list. Exported for spec coverage.
- */
-export function projectLabel(root, marker) {
-    const name = basename(root) || root;
-    return `${name} (${marker})`;
-}
-/**
- * Should we proactively offer `pugi init` in this invocation?
- *
- *  - kind === 'bare' → yes (U7)
- *  - kind === 'inside_parent_projects' → yes (U8 picker, "or init here")
- *  - existing_pugi / existing_project → no
- *
- * Caller must additionally gate on TTY + non-json mode. Exported so a
- * UI layer can reuse the same decision rule without re-implementing
- * the state switch.
- */
-export function shouldOfferInit(state) {
-    return state.kind === 'bare' || state.kind === 'inside_parent_projects';
-}
-/**
- * Convenience formatter: synthesize the prompt text U7 / U8 callers
- * surface to the operator on the bare/inside-parents paths. The text
- * is plain ASCII; the UI layer wraps it in Ink as needed.
- */
-export function formatInitPrompt(state, cwd) {
-    switch (state.kind) {
-        case 'bare':
-            return `No project detected at ${cwd}. Run \`pugi init\` here?`;
-        case 'inside_parent_projects': {
-            const lines = state.parents.map((p) => ` - ${projectLabel(p.root, p.marker)} (${p.root})`);
-            return `Found ${state.parents.length} parent project(s):\n${lines.join('\n')}\nPick one above or run \`pugi init\` here.`;
-        }
-        default:
-            return '';
-    }
-}
-/* β1b r1: dropped the `_internal` re-export. It was a leftover from
- * an earlier spec that asserted module load order; the test was
- * removed but the export lingered. No callers consume it inside the
- * monorepo (verified via repo-wide grep), and `verbatimModuleSyntax`
- * is happy with the module's regular exports. */
-//# sourceMappingURL=bootstrap.js.map