@pugi/cli 0.1.0-beta.23 → 0.1.0-beta.25

package/dist/core/repl/onboarding-state.js

@@ -0,0 +1,297 @@
+/**
+ * Project onboarding state for the Pugi REPL.
+ *
+ * Inspired by Claude Code's projectOnboardingState pattern (the leaked
+ * upstream file ships a 4-flag memoized check called on every prompt
+ * submit). Independent implementation: the storage location, the steps,
+ * the reset path, and the cap counter are all Pugi-shaped.
+ *
+ * # Why this exists
+ *
+ * The REPL's status bar can flash a `setup needed: run /init` hint when
+ * a workspace is still ungoverned (no PUGI.md, no skills installed). The
+ * hint must NEVER show on a workspace where the operator already ran the
+ * interview - otherwise the prompt becomes nag-noise. Three layered
+ * short-circuits guarantee that:
+ *
+ *   1. `hasCompletedOnboarding === true` in `~/.pugi/state.json` -> stop.
+ *      The interview's final phase writes this flag once; subsequent
+ *      REPL boots short-circuit at the global ledger and never even
+ *      stat the workspace.
+ *   2. `onboardingSeenCount >= 4` -> stop. If the operator dismissed
+ *      the hint four times without finishing the interview, assume they
+ *      do not want it. The bar stays clean from boot 5 onward.
+ *   3. `PUGI_IS_DEMO=1` -> stop. The demo / snapshot recorder sets this
+ *      so the screen capture stays free of onboarding chrome.
+ *
+ * If none short-circuit, the function checks the per-workspace steps
+ * (`PUGI.md` present, at least one skill installed, auth ok, workspace
+ * dir bound) and returns `true` only when at least one step is still
+ * incomplete.
+ *
+ * # Storage shape
+ *
+ * The global state file is JSON-on-disk at
+ * `~/.pugi/state.json`. It carries two scalars:
+ *
+ *   {
+ *     "hasCompletedOnboarding": boolean,
+ *     "onboardingSeenCount": integer >= 0
+ *   }
+ *
+ * The file is read at most once per process (memoized) so the hot path
+ * is in-memory. `incrementSeenCount()` re-reads the file before
+ * mutating to avoid clobbering a sibling Pugi process's increment
+ * (concurrent REPLs in two terminals). Atomic-ish: we write to
+ * `state.json.tmp` then rename. A race that overwrites another
+ * increment is benign - the worst case is a single missed +1 across
+ * two siblings.
+ *
+ * # Reset path
+ *
+ * `rm ~/.pugi/state.json` resets every flag. Tests rely on this:
+ * `resetOnboardingStateForTests(stateDir)` is the public helper that
+ * removes the file and clears the memoization cache.
+ */
+import { existsSync, mkdirSync, readdirSync, readFileSync, renameSync, rmSync, writeFileSync } from 'node:fs';
+import { homedir } from 'node:os';
+import { join } from 'node:path';
+const DEFAULT_STATE = Object.freeze({
+    hasCompletedOnboarding: false,
+    onboardingSeenCount: 0,
+});
+/** Hard cap; once the operator has seen the hint this many times we stop. */
+export const ONBOARDING_SEEN_CAP = 4;
+/**
+ * Singleton memoization cache - cleared by `resetMemoizationForTests`.
+ * Keyed by stateDir so concurrent specs in the same process do not
+ * interfere with each other.
+ */
+const SHOULD_SHOW_CACHE = new Map();
+const PERSISTED_STATE_CACHE = new Map();
+/**
+ * Default fs implementation - the real `node:fs` module wrapped into
+ * the minimal surface this file uses.
+ */
+const REAL_FS = {
+    existsSync,
+    readFileSync: (path, encoding) => readFileSync(path, encoding),
+    writeFileSync: (path, data, options) => writeFileSync(path, data, options),
+    mkdirSync: (path, opts) => {
+        mkdirSync(path, opts);
+    },
+    renameSync,
+    rmSync: (path, opts) => rmSync(path, opts),
+    readdirSync: (path) => readdirSync(path),
+};
+/**
+ * Compute the four Pugi-specific onboarding steps for the given
+ * workspace. Pure: the only side effect is the filesystem probe (which
+ * tests stub via `probes.fs`).
+ */
+export function getSteps(probes) {
+    const fs = probes.fs ?? REAL_FS;
+    const pugiDirPath = join(probes.cwd, '.pugi');
+    const hasWorkspaceDir = fs.existsSync(pugiDirPath);
+    const hasPugiMd = fs.existsSync(join(probes.cwd, 'PUGI.md')) ||
+        fs.existsSync(join(pugiDirPath, 'PUGI.md'));
+    const skillsDir = join(pugiDirPath, 'skills');
+    const hasSkill = fs.existsSync(skillsDir) && !isEmptyDir(skillsDir, fs);
+    return [
+        {
+            key: 'workspace',
+            text: 'Bind a workspace by running pugi init',
+            isComplete: hasWorkspaceDir,
+            isEnabled: true,
+        },
+        {
+            key: 'pugimd',
+            text: 'Run /init to write PUGI.md with project context',
+            isComplete: hasPugiMd,
+            isEnabled: hasWorkspaceDir,
+        },
+        {
+            key: 'skills',
+            text: 'Install at least one skill under .pugi/skills/',
+            isComplete: hasSkill,
+            isEnabled: hasWorkspaceDir,
+        },
+        {
+            key: 'auth',
+            text: 'Run pugi login to authenticate',
+            isComplete: probes.authOk,
+            isEnabled: true,
+        },
+    ];
+}
+/**
+ * Roll-up over the steps. True when every ENABLED step is complete -
+ * disabled steps (e.g. `pugimd` before `workspace` is set up) are
+ * excluded so the operator does not get stuck on a step they cannot
+ * action yet.
+ */
+export function isOnboardingComplete(probes) {
+    const steps = getSteps(probes);
+    return steps
+        .filter((s) => s.isEnabled)
+        .every((s) => s.isComplete);
+}
+/**
+ * The exported gate the REPL status bar consults. Memoized per
+ * stateDir; the hot path is one map lookup once the first call has run.
+ */
+export function shouldShowOnboarding(probes) {
+    const stateDir = probes.stateDir ?? defaultStateDir();
+    const cached = SHOULD_SHOW_CACHE.get(stateDir);
+    if (cached !== undefined)
+        return cached;
+    const persisted = loadPersistedState(stateDir, probes.fs ?? REAL_FS);
+    const isDemo = probes.isDemoOverride ?? (process.env.PUGI_IS_DEMO === '1');
+    if (persisted.hasCompletedOnboarding) {
+        SHOULD_SHOW_CACHE.set(stateDir, false);
+        return false;
+    }
+    if (persisted.onboardingSeenCount >= ONBOARDING_SEEN_CAP) {
+        SHOULD_SHOW_CACHE.set(stateDir, false);
+        return false;
+    }
+    if (isDemo) {
+        SHOULD_SHOW_CACHE.set(stateDir, false);
+        return false;
+    }
+    const verdict = !isOnboardingComplete(probes);
+    SHOULD_SHOW_CACHE.set(stateDir, verdict);
+    return verdict;
+}
+/**
+ * Idempotent setter: if the workspace is now fully onboarded, flip the
+ * persisted flag. Cheap to call on every prompt submit because the
+ * fast path short-circuits on the in-memory cache.
+ *
+ * The "maybe" prefix mirrors the upstream pattern: a no-op is the
+ * common case; the write only fires once when the operator's most
+ * recent action just completed the ladder.
+ */
+export function maybeMarkOnboardingComplete(probes) {
+    const stateDir = probes.stateDir ?? defaultStateDir();
+    const fs = probes.fs ?? REAL_FS;
+    const persisted = loadPersistedState(stateDir, fs);
+    if (persisted.hasCompletedOnboarding)
+        return;
+    if (!isOnboardingComplete(probes))
+        return;
+    persistState(stateDir, fs, { ...persisted, hasCompletedOnboarding: true });
+    // Invalidate the cache so the next `shouldShowOnboarding` call sees
+    // the new value without restarting the process.
+    SHOULD_SHOW_CACHE.delete(stateDir);
+}
+/**
+ * Increment the seen counter. The REPL status bar calls this once per
+ * boot where it actually rendered the hint. After
+ * `ONBOARDING_SEEN_CAP` increments the cap guard in
+ * `shouldShowOnboarding` flips the gate off permanently for this user.
+ */
+export function incrementOnboardingSeenCount(probes) {
+    const stateDir = probes.stateDir ?? defaultStateDir();
+    const fs = probes.fs ?? REAL_FS;
+    const persisted = loadPersistedState(stateDir, fs);
+    const next = {
+        ...persisted,
+        onboardingSeenCount: persisted.onboardingSeenCount + 1,
+    };
+    persistState(stateDir, fs, next);
+    SHOULD_SHOW_CACHE.delete(stateDir);
+}
+/**
+ * Reset every persisted flag. Tests use this via the public helper; an
+ * operator can achieve the same effect by `rm ~/.pugi/state.json`.
+ */
+export function resetOnboardingStateForTests(probes) {
+    const stateDir = probes.stateDir ?? defaultStateDir();
+    const fs = probes.fs ?? REAL_FS;
+    const file = stateFilePath(stateDir);
+    if (fs.existsSync(file)) {
+        fs.rmSync(file, { force: true });
+    }
+    SHOULD_SHOW_CACHE.delete(stateDir);
+    PERSISTED_STATE_CACHE.delete(stateDir);
+}
+/**
+ * Clear the in-memory memoization without touching the disk. The
+ * spec uses this between assertions when it wants to force a re-read.
+ */
+export function resetMemoizationForTests(stateDir) {
+    if (stateDir) {
+        SHOULD_SHOW_CACHE.delete(stateDir);
+        PERSISTED_STATE_CACHE.delete(stateDir);
+        return;
+    }
+    SHOULD_SHOW_CACHE.clear();
+    PERSISTED_STATE_CACHE.clear();
+}
+/* ------------------------------------------------------------------ */
+/* Internal helpers                                                   */
+/* ------------------------------------------------------------------ */
+function defaultStateDir() {
+    return join(homedir(), '.pugi');
+}
+function stateFilePath(stateDir) {
+    return join(stateDir, 'state.json');
+}
+function loadPersistedState(stateDir, fs) {
+    const cached = PERSISTED_STATE_CACHE.get(stateDir);
+    if (cached !== undefined)
+        return cached;
+    const file = stateFilePath(stateDir);
+    if (!fs.existsSync(file)) {
+        PERSISTED_STATE_CACHE.set(stateDir, DEFAULT_STATE);
+        return DEFAULT_STATE;
+    }
+    try {
+        const raw = fs.readFileSync(file, 'utf8');
+        const parsed = JSON.parse(raw);
+        const normalized = {
+            hasCompletedOnboarding: parsed.hasCompletedOnboarding === true,
+            onboardingSeenCount: typeof parsed.onboardingSeenCount === 'number' &&
+                Number.isFinite(parsed.onboardingSeenCount) &&
+                parsed.onboardingSeenCount >= 0
+                ? Math.floor(parsed.onboardingSeenCount)
+                : 0,
+        };
+        PERSISTED_STATE_CACHE.set(stateDir, normalized);
+        return normalized;
+    }
+    catch {
+        // Corrupt file - treat as if it were absent. The next persist
+        // overwrites with a clean shape; we never crash the REPL boot on
+        // an unreadable state file.
+        PERSISTED_STATE_CACHE.set(stateDir, DEFAULT_STATE);
+        return DEFAULT_STATE;
+    }
+}
+function persistState(stateDir, fs, next) {
+    if (!fs.existsSync(stateDir)) {
+        fs.mkdirSync(stateDir, { recursive: true });
+    }
+    const file = stateFilePath(stateDir);
+    const tmp = `${file}.tmp`;
+    fs.writeFileSync(tmp, `${JSON.stringify(next, null, 2)}\n`, { encoding: 'utf8', mode: 0o600 });
+    fs.renameSync(tmp, file);
+    PERSISTED_STATE_CACHE.set(stateDir, next);
+}
+function isEmptyDir(path, fs) {
+    // An empty `skills/` directory counts as "no skill installed yet" so
+    // the onboarding step stays incomplete. The injected fs shim may
+    // omit `readdirSync` - in that case we conservatively report
+    // non-empty (the dir existed, so the operator likely did something
+    // intentional) to avoid false-positive nag.
+    if (!fs.readdirSync)
+        return false;
+    try {
+        return fs.readdirSync(path).length === 0;
+    }
+    catch {
+        return true;
+    }
+}
+//# sourceMappingURL=onboarding-state.js.map

package/dist/core/repl/session.js

@@ -27,6 +27,7 @@
  * verbatim - the brand gate on those happens at the controller.
  */
 import { randomUUID } from 'node:crypto';
+import { homedir } from 'node:os';
 import { getPersona } from '@pugi/personas';
 import { listRoles, getPersonaForRole } from '../agents/registry.js';
 import { evaluateCap, describeVerdict } from './cap-warning.js';
@@ -1167,6 +1168,54 @@ export class ReplSession {
                 }
                 return verdict;
             }
+            case 'update': {
+                // Leak L27 (2026-05-27): /update probes the npm registry for a
+                // newer @pugi/cli version on the configured channel and prints
+                // the install command. The slash form NEVER spawns `npm install
+                // -g` — that would corrupt the binary we are currently running.
+                // Operators see the install command + run it manually (or run
+                // `pugi update --apply` from a fresh shell after the REPL
+                // exits). The slash + top-level paths share the dispatcher so
+                // channel resolution + last-check persistence stay single-
+                // sourced.
+                try {
+                    const { parseUpdateArgs, runUpdateCommand } = await import('../../runtime/commands/update.js');
+                    const parsed = parseUpdateArgs(verdict.args);
+                    if ('error' in parsed) {
+                        this.appendSystemLine(parsed.error);
+                        return verdict;
+                    }
+                    // Force `apply=false` on the slash path — see comment above.
+                    const slashFlags = { ...parsed, apply: false };
+                    const lines = [];
+                    await runUpdateCommand({
+                        cwd: process.cwd(),
+                        home: homedir(),
+                        env: process.env,
+                        flags: slashFlags,
+                        promptConfirm: async () => false,
+                        writeOutput: (_payload, text) => {
+                            for (const line of text.split('\n')) {
+                                const trimmed = line.replace(/\s+$/u, '');
+                                if (trimmed.length > 0)
+                                    lines.push(trimmed);
+                            }
+                        },
+                    });
+                    if (lines.length === 0) {
+                        this.appendSystemLine('/update: no output.');
+                    }
+                    else {
+                        for (const line of lines)
+                            this.appendSystemLine(line);
+                    }
+                }
+                catch (error) {
+                    const message = error instanceof Error ? error.message : String(error);
+                    this.appendSystemLine(`/update failed: ${message}`);
+                }
+                return verdict;
+            }
             case 'feedback': {
                 // Leak L21 (2026-05-27): in-CLI feedback collector. The wizard
                 // mounts a fresh Ink tree (renderFeedbackPrompt) outside the
@@ -1184,6 +1233,41 @@ export class ReplSession {
                 }
                 return verdict;
             }
+            case 'repo-map': {
+                // Leak L28 (2026-05-27): AST-light workspace summary. Delegate
+                // к the shared `runRepoMapCommand` so the slash + top-level
+                // paths stay single-sourced. The rendered text lands on the
+                // system pane via `appendSystemLine` (no fresh Ink mount) so
+                // the listing flows into the conversation transcript like
+                // any other command output.
+                try {
+                    const { runRepoMapCommand } = await import('../../runtime/commands/repo-map.js');
+                    const lines = [];
+                    await runRepoMapCommand({
+                        cwd: process.cwd(),
+                        refresh: verdict.refresh,
+                        json: false,
+                        writeOutput: (_payload, text) => {
+                            for (const line of text.split('\n')) {
+                                const trimmed = line.replace(/\s+$/u, '');
+                                lines.push(trimmed);
+                            }
+                        },
+                    });
+                    if (lines.length === 0) {
+                        this.appendSystemLine('/repo-map: no output.');
+                    }
+                    else {
+                        for (const line of lines)
+                            this.appendSystemLine(line);
+                    }
+                }
+                catch (error) {
+                    const message = error instanceof Error ? error.message : String(error);
+                    this.appendSystemLine(`/repo-map failed: ${message}`);
+                }
+                return verdict;
+            }
             case 'stub': {
                 this.appendSystemLine(verdict.message);
                 return verdict;

package/dist/core/repl/slash-commands.js

@@ -75,6 +75,7 @@ export const SLASH_COMMAND_HELP = Object.freeze([
     { name: 'quota', args: '', gloss: 'Plan tier + monthly usage caps (sync / review / engine)', group: 'Pugi tools' },
     { name: 'status', args: '', gloss: 'Session snapshot — id · cwd · mode · tokens · dispatches · auth', group: 'Pugi tools' },
     { name: 'consensus', args: '[ref]', gloss: '3-model consensus review (codex · claude · deepseek)', group: 'Pugi tools' },
+    { name: 'repo-map', args: '[refresh]', gloss: 'AST-light symbol summary of the workspace (leak L28)', group: 'Pugi tools' },
     // Settings
     { name: 'config', args: '', gloss: 'Show config', group: 'Settings', stub: true },
     { name: 'privacy', args: '', gloss: 'Show privacy mode + contract', group: 'Settings' },
@@ -95,6 +96,7 @@ export const SLASH_COMMAND_HELP = Object.freeze([
     { name: 'feedback', args: '', gloss: 'file a bug / feature / general comment without leaving the REPL', group: 'Meta' },
     { name: 'share', args: '[--gist|--pugi] [--redact] [--preview]', gloss: 'Export session transcript to gist / pugi.io (leak L20)', group: 'Meta' },
     { name: 'release-notes', args: '[--reset]', gloss: 'Show changelog diff since last upgrade (leak L24)', group: 'Meta' },
+    { name: 'update', args: '[--check|--apply [--yes]] [--channel <name>]', gloss: 'Check for / apply CLI update on stable / beta / canary (leak L27)', group: 'Meta' },
     { name: 'quit', args: '', gloss: 'Exit the REPL', group: 'Meta' },
 ]);
 /**
@@ -461,6 +463,15 @@ export function parseSlashCommand(input) {
             const tokens = tail.length === 0 ? [] : tail.split(/\s+/).filter((s) => s.length > 0);
             return { kind: 'share', args: tokens };
         }
+        case 'repo-map':
+        case 'repomap': {
+            // Leak L28 (2026-05-27): build + show the AST-light symbol
+            // summary. Accepts `refresh` as a positional или `--refresh`
+            // flag so muscle memory from both shells lands the same way.
+            const tokens = tail.length === 0 ? [] : tail.split(/\s+/).filter((s) => s.length > 0);
+            const refresh = tokens.includes('--refresh') || tokens.includes('refresh') || tokens.includes('-r');
+            return { kind: 'repo-map', refresh };
+        }
         case 'release-notes':
         case 'releasenotes':
         case 'changelog': {
@@ -474,6 +485,20 @@ export function parseSlashCommand(input) {
             const reset = tokens.includes('--reset') || tokens.includes('-r');
             return { kind: 'release-notes', reset };
         }
+        case 'update': {
+            // Leak L27 (2026-05-27): forward the tokenized argv to the
+            // session module which delegates to `runUpdateCommand`. The
+            // dispatcher owns argv validation (unknown channel / flag) so
+            // the slash parser stays as thin as the rest of the surface.
+            // The slash form does NOT support `--apply` because spawning
+            // `npm install -g` from inside a running REPL session would
+            // corrupt the operator's running binary — the dispatcher treats
+            // `--apply` from a slash as a non-interactive offer (probe +
+            // install command, no shell-out). Top-level `pugi update --apply`
+            // remains the recommended path for the actual install.
+            const tokens = tail.length === 0 ? [] : tail.split(/\s+/).filter((s) => s.length > 0);
+            return { kind: 'update', args: tokens };
+        }
         case 'memory':
         case 'config':
         case 'budget':

package/dist/core/repo-map/build.js

@@ -0,0 +1,125 @@
+/**
+ * Repo-map build orchestrator — Leak L28 (2026-05-27).
+ *
+ * Single entry point that the CLI command + the engine boot path both
+ * call. Wires the scanner → extractor → cache → formatter pipeline
+ * together and surfaces a structured result the caller can render or
+ * inject without knowing the inner module shapes.
+ *
+ * The orchestrator is split out от cache.ts and the command handler
+ * so:
+ *
+ *   1. The CLI command + the engine system-prompt injector share one
+ *      code path. Drift between the two would silently change what
+ *      the model sees vs. what the operator sees.
+ *
+ *   2. The spec can exercise the full pipeline against a temp dir
+ *      without mounting Ink or the engine.
+ *
+ * Pure-ish: reads from disk (the source files + the cache), but never
+ * mutates anything outside `.pugi/repo-map.json` and never logs. The
+ * caller decides whether к persist the cache (`writeCache: true`) or
+ * к compute the map в-memory (`writeCache: false` — useful for
+ * non-interactive `--json` invocations on read-only fs).
+ */
+import { readFileSync } from 'node:fs';
+import { loadPugiIgnore } from '../context/pugiignore.js';
+import { defaultCachePath, diffCacheAgainstScan, mergeCache, readRepoMapCache, writeRepoMapCache, } from './cache.js';
+import { extractFromFile } from './extractor.js';
+import { scanRepoForMap } from './scanner.js';
+import { formatRepoMap } from './formatter.js';
+/**
+ * Run the full pipeline. Returns a structured verdict; never throws.
+ * The 'too-large' branch fires when the workspace exceeds the file
+ * cap — callers surface a hint к the operator ("repo too large for
+ * inline map — try .pugiignore") and skip injection.
+ */
+export function buildRepoMap(options) {
+    const root = options.root;
+    const refresh = options.refresh === true;
+    const writeCache = options.writeCache !== false;
+    const cachePath = options.cachePath ?? defaultCachePath(root);
+    const readFile = options.readFile ?? ((path) => readFileSync(path, 'utf8'));
+    const ignore = loadPugiIgnore(root);
+    const scan = scanRepoForMap({ root, ignore });
+    if (!scan.ok) {
+        return {
+            ok: false,
+            root,
+            reason: scan.skipped.reason,
+            walked: scan.skipped.walked,
+        };
+    }
+    const prior = refresh ? null : readCacheOrNull(cachePath);
+    const diff = diffCacheAgainstScan(prior, scan.files);
+    const freshExtracts = new Map();
+    for (const file of diff.toRebuild) {
+        let source;
+        try {
+            source = readFile(file.absPath);
+        }
+        catch {
+            // File vanished или became unreadable mid-build — skip. The
+            // cache layer will just not have an entry for it; next refresh
+            // picks it up if it reappears.
+            continue;
+        }
+        freshExtracts.set(file.relPath, extractFromFile(file, source));
+    }
+    const cache = mergeCache({
+        root,
+        prior,
+        scanned: scan.files,
+        freshExtracts,
+    });
+    let cacheWritten = false;
+    if (writeCache) {
+        const writeResult = writeRepoMapCache(cachePath, cache);
+        cacheWritten = writeResult.ok;
+    }
+    // Surface the extracts в the same order the scanner produced (sorted
+    // by POSIX path) so callers iterating the result render deterministic
+    // output. The formatter does its own priority sort, so a different
+    // order here would only affect callers that iterate manually.
+    const extracts = [];
+    for (const file of scan.files) {
+        const entry = cache.entries[file.relPath];
+        if (entry)
+            extracts.push(entry.extract);
+    }
+    return {
+        ok: true,
+        root,
+        cache,
+        extracts,
+        scanStats: scan.stats,
+        diffStats: {
+            rebuilt: diff.toRebuild.length,
+            reused: diff.reuse.length,
+            dropped: diff.toDrop.length,
+        },
+        cachePath,
+        cacheWritten,
+    };
+}
+/**
+ * Convenience wrapper: build + format в one call. The engine boot
+ * path uses this so it does not have к know the formatter shape.
+ */
+export function buildAndFormatRepoMap(options) {
+    const build = buildRepoMap(options);
+    if (!build.ok)
+        return { build };
+    const format = formatRepoMap(build.extracts, {
+        maxBytes: options.formatBytesCap,
+        omitHeader: options.omitHeader,
+    });
+    return { build, format };
+}
+function readCacheOrNull(path) {
+    const verdict = readRepoMapCache(path);
+    if (verdict.ok)
+        return verdict.cache;
+    return null;
+}
+//# sourceMappingURL=build.js.map