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

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

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

@@ -95,6 +95,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' },
 ]);
 /**
@@ -474,6 +475,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/runtime/cli.js

@@ -2,6 +2,7 @@ import { randomUUID } from 'node:crypto';
 import { execFileSync } from 'node:child_process';
 import { existsSync, mkdirSync, readdirSync, readFileSync, writeFileSync } from 'node:fs';
 import { statSync } from 'node:fs';
+import { homedir } from 'node:os';
 import { dirname, relative, resolve } from 'node:path';
 import { fileURLToPath } from 'node:url';
 import { AnvilEngineLoopClient } from '../core/engine/anvil-client.js';
@@ -151,6 +152,12 @@ const handlers = {
     // handler, same flags. Operators trained on Claude Code expect either
     // verb to surface the per-model token + USD table.
     usage: dispatchCost,
+    // Leak L27 (2026-05-27): `pugi update` — channel-aware npm registry
+    // probe + optional npm install shell-out. Same handler powers the
+    // in-REPL `/update` slash via the session module. R2 atomic swap
+    // deferred to Phase 2 per the sprint plan; npm is the single
+    // distribution channel today.
+    update: dispatchUpdate,
     version,
     web: dispatchWeb,
     whoami,
@@ -1503,6 +1510,32 @@ const COMMAND_HELP_BODIES = {
         'Useful in shell scripts that need a human-confirm before a destructive',
         'step. Exits 0 on yes, 1 on no, 2 on cancel.',
     ],
+    update: [
+        'pugi update — channel-aware @pugi/cli update check + install.',
+        '',
+        'Polls npm registry dist-tags for a newer @pugi/cli on the configured',
+        'channel (stable / beta / canary). Without flags, prints the install',
+        'command and exits. With --apply, shells out to `npm install -g …`.',
+        '',
+        '  --check                 Non-interactive probe + JSON envelope.',
+        '  --channel <name>        Switch channel (stable | beta | canary) and probe.',
+        '                          Persisted to ~/.pugi/config.json::updateChannel.',
+        '  --apply                 Shell out to `npm install -g @pugi/cli@<tag>`',
+        '                          after a y/n confirmation.',
+        '  --yes, -y               Skip the confirmation prompt on --apply.',
+        '  --json                  Force JSON envelope (auto-on with --check).',
+        '',
+        'Channel mapping: stable -> npm `latest`, beta -> npm `beta`,',
+        'canary -> npm `next`. Default channel is `beta` (Pugi currently',
+        'ships beta releases only).',
+        '',
+        'Also available as /update from inside the REPL — slash form NEVER',
+        'spawns npm (would corrupt the running binary); it only prints the',
+        'install command for the operator к run after exit.',
+        '',
+        'R2 atomic swap (sprint plan L27) deferred к Phase 2 — npm is the',
+        'only distribution channel today.',
+    ],
     stickers: [
         'pugi stickers — show a Pugi brand sticker (gimmick).',
         '',
@@ -1668,6 +1701,53 @@ async function doctor(_args, flags, _session) {
         writeOutput: (payload, text) => writeOutput(flags, payload, text),
     });
 }
+/**
+ * `pugi update` — Leak L27 (2026-05-27). Channel-aware npm registry
+ * probe + optional shell-out to `npm install -g @pugi/cli@<tag>`.
+ *
+ * Argument grammar:
+ *   pugi update                       -> probe + offer install command
+ *   pugi update --check               -> probe + JSON envelope (scripted)
+ *   pugi update --channel <name>      -> persist channel + probe
+ *   pugi update --apply [--yes]       -> probe + shell out to npm
+ *   pugi update --json                -> JSON envelope (any subcommand)
+ *
+ * The handler delegates to `runUpdateCommand` in
+ * `runtime/commands/update.ts` so the in-REPL `/update` slash + the
+ * top-level shell command share one channel-resolution + persistence
+ * + probe surface. Exit codes:
+ *
+ *   0 — happy path (no update OR update completed OR probe-only)
+ *   1 — install / probe failure with structured error
+ *   2 — argument error (unknown flag, unknown channel)
+ */
+async function dispatchUpdate(args, flags, _session) {
+    const { parseUpdateArgs, runUpdateCommand, defaultSpawnInstaller } = await import('./commands/update.js');
+    const parsed = parseUpdateArgs(args, { jsonDefault: flags.json });
+    if ('error' in parsed) {
+        writeOutput(flags, { ok: false, error: parsed.error }, parsed.error);
+        process.exitCode = 2;
+        return;
+    }
+    const envelope = await runUpdateCommand({
+        cwd: process.cwd(),
+        home: homedir(),
+        env: process.env,
+        flags: parsed,
+        promptConfirm: async (question) => {
+            const answer = await readSingleChoice(`${question} `);
+            return /^y(es)?$/i.test(answer.trim());
+        },
+        writeOutput: (payload, text) => writeOutput(flags, payload, text),
+        spawnInstaller: defaultSpawnInstaller,
+    });
+    if (!envelope.ok) {
+        // `apply_cancelled_by_operator` is a benign decline; we still
+        // surface a non-zero exit so scripted callers can detect that the
+        // operator did not green-light the install.
+        process.exitCode = 1;
+    }
+}
 /**
  * `pugi status` — Leak L34 (2026-05-27). Concise session-state probe
  * mirroring Claude Code's `/status`. Distinct from `pugi doctor`