@pugi/cli 0.1.0-beta.1 → 0.1.0-beta.11

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

@@ -577,6 +577,18 @@ export class ReplSession {
                 await this.dispatchStop(verdict.persona);
                 return verdict;
             }
+            case 'delegate': {
+                // α7.5 Phase 1: surface the dispatch intent inline. The actual
+                // wire shape (POST /api/pugi/sessions/:id/delegate) requires the
+                // SDK transport extension that ships alongside this PR; the
+                // REPL session module wires the call when the matching transport
+                // method lands (paired CLI follow-up). Today we surface the
+                // delegation intent in the transcript so the operator sees the
+                // verdict echo for muscle-memory before the round-trip lights up.
+                this.appendSystemLine(`delegate ${verdict.persona}: ${verdict.brief.length > 80 ? `${verdict.brief.slice(0, 77)}...` : verdict.brief}`);
+                this.appendSystemLine('Run `pugi delegate <slug> "<brief>"` from a fresh shell while the REPL transport wiring lands.');
+                return verdict;
+            }
             case 'dispatch': {
                 await this.dispatchBrief(verdict.brief);
                 return verdict;
@@ -651,6 +663,52 @@ export class ReplSession {
                 await this.dispatchPrivacy();
                 return verdict;
             }
+            case 'init': {
+                // β1 Sl11 → β1a r1 (real inline scaffold, 2026-05-26): invoke
+                // `scaffoldPugiWorkspace` directly so the operator gets the
+                // same .pugi/ setup they would from `pugi init` on a fresh
+                // shell. Already-initialised workspaces (every artifact already
+                // present) get the "Already initialised" copy; partial / fresh
+                // workspaces get the full Created+Skipped breakdown. Default
+                // skills install is best-effort — any error from the bundled
+                // pack is surfaced as a system line and does not break the
+                // REPL session. The dynamic import keeps the slash dispatcher
+                // free of a runtime/cli.ts cycle on every keystroke.
+                try {
+                    const { scaffoldPugiWorkspace } = await import('../../runtime/cli.js');
+                    const lines = [];
+                    const result = await scaffoldPugiWorkspace({
+                        cwd: process.cwd(),
+                        // Slash callers default to the full default-skills pack so
+                        // the in-REPL experience matches `pugi init`. Operators who
+                        // want a minimal scaffold still have the shell command.
+                        noDefaults: false,
+                        log: (line) => {
+                            const trimmed = line.replace(/\n+$/u, '');
+                            if (trimmed.length > 0)
+                                lines.push(trimmed);
+                        },
+                    });
+                    if (result.alreadyInitialized) {
+                        this.appendSystemLine(`.pugi/ already initialised at ${result.root}. ${result.skipped.length} artefact(s) verified.`);
+                    }
+                    else {
+                        this.appendSystemLine(`Pugi initialised at ${result.root}. Created ${result.created.length} artefact(s), skipped ${result.skipped.length}.`);
+                    }
+                    if (result.defaultSkills.length > 0) {
+                        const installed = result.defaultSkills.filter((s) => s.status === 'installed').length;
+                        const skippedSkills = result.defaultSkills.filter((s) => s.status === 'skipped-existing').length;
+                        this.appendSystemLine(`Default skills: ${installed} installed, ${skippedSkills} already present.`);
+                    }
+                    for (const line of lines)
+                        this.appendSystemLine(line);
+                }
+                catch (error) {
+                    const message = error instanceof Error ? error.message : String(error);
+                    this.appendSystemLine(`/init failed: ${message}`);
+                }
+                return verdict;
+            }
             case 'stub': {
                 this.appendSystemLine(verdict.message);
                 return verdict;
@@ -1382,8 +1440,21 @@ export class ReplSession {
                     void this.recreateSessionSilently();
                     return;
                 }
+                // α6.14.4 CEO dogfood 2026-05-25 (parity with Claude Code):
+                // collapse the repeated "Stream interrupted (fetch failed).
+                // Reconnecting." spam. The status bar already shows
+                // connection='reconnecting' AND the attempt counter; pushing
+                // a fresh transcript row per attempt fills the screen with
+                // noise. Only emit the system line for the FIRST drop of a
+                // run; subsequent reconnects update the status bar silently
+                // until either success (clears the connection state) or the
+                // give-up path in scheduleReconnect prints the final hint.
+                const wasOnline = this.state.connection === 'on_watch'
+                    || this.state.connection === 'connecting';
                 this.patch({ connection: 'reconnecting' });
-                this.appendSystemLine(`Stream interrupted (${this.errorMessage(error)}). Reconnecting.`);
+                if (wasOnline) {
+                    this.appendSystemLine(`Stream interrupted (${this.errorMessage(error)}). Reconnecting...`);
+                }
                 this.scheduleReconnect();
             },
         });

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

@@ -52,6 +52,7 @@ export const SLASH_COMMAND_HELP = Object.freeze([
     // Workforce dispatch
     { name: 'brief', args: '<text>', gloss: 'Dispatch a brief to the workforce', group: 'Workforce dispatch' },
     { name: 'agents', args: '', gloss: 'List the on-watch agent roster', group: 'Workforce dispatch' },
+    { name: 'delegate', args: '<slug> <brief>', gloss: 'Dispatch a brief to one Tier 1 specialist (α7.5)', group: 'Workforce dispatch' },
     { name: 'stop', args: '<persona>', gloss: 'Stop one agent by persona slug', group: 'Workforce dispatch' },
     { name: 'jobs', args: '', gloss: 'List background jobs', group: 'Workforce dispatch' },
     { name: 'ask', args: '<question>', gloss: 'Surface a yes/no modal locally (α6.3 forcing question)', group: 'Workforce dispatch' },
@@ -61,6 +62,7 @@ export const SLASH_COMMAND_HELP = Object.freeze([
     { name: 'context', args: '', gloss: 'Show three-tier context summary (Tier 0 skeleton + Tier 1 working set)', group: 'Session' },
     { name: 'compact', args: '', gloss: 'Manual context compaction  (α6.5b)', group: 'Session', stub: true },
     { name: 'memory', args: '', gloss: 'Session memory editor  (α6.5b)', group: 'Session', stub: true },
+    { name: 'init', args: '', gloss: 'Scaffold .pugi/ in the current workspace (β1 Sl11)', group: 'Session' },
     // Pugi tools
     { name: 'web', args: '<url>', gloss: 'Fetch a URL into context', group: 'Pugi tools' },
     { name: 'diff', args: '', gloss: 'Show pending diff', group: 'Pugi tools' },
@@ -135,6 +137,38 @@ export function parseSlashCommand(input) {
         case 'roster': {
             return { kind: 'roster' };
         }
+        case 'delegate': {
+            // tail must start with the persona slug followed by the brief.
+            // Slug accepts only the closed-set lowercase ASCII pattern the
+            // server-side persona registry enforces; anything else surfaces
+            // as a usage error so the operator sees the typo before the
+            // round-trip.
+            const innerSpace = tail.indexOf(' ');
+            if (innerSpace === -1 || innerSpace === 0) {
+                return {
+                    kind: 'error',
+                    message: 'Usage: /delegate <slug> <one-sentence brief>',
+                };
+            }
+            const persona = tail.slice(0, innerSpace).toLowerCase();
+            const brief = tail.slice(innerSpace + 1).trim();
+            // Pattern intentionally mirrors server-side PUGI_DELEGATE_REGEX in
+            // sessions.controller.ts (^[a-z]+$). Keeping them lockstep means
+            // the REPL surfaces typos locally instead of round-tripping a 4xx.
+            if (!/^[a-z]+$/.test(persona)) {
+                return {
+                    kind: 'error',
+                    message: `/delegate slug must be lowercase ASCII (a-z only); got '${persona}'`,
+                };
+            }
+            if (brief.length === 0) {
+                return {
+                    kind: 'error',
+                    message: 'Usage: /delegate <slug> <one-sentence brief>',
+                };
+            }
+            return { kind: 'delegate', persona, brief };
+        }
         case 'stop':
         case 'kill': {
             if (tail.length === 0) {
@@ -215,6 +249,13 @@ export function parseSlashCommand(input) {
             // device flow + audit identity are wired correctly).
             return { kind: 'privacy' };
         }
+        case 'init': {
+            // β1 Sl11: surface the init flow inside the REPL. Tail args
+            // are ignored — the init handler is parameterless today; `pugi
+            // init --no-defaults` is the CLI surface for skipping bundled
+            // skills.
+            return { kind: 'init' };
+        }
         case 'compact':
         case 'memory':
         case 'config':

package/dist/core/settings.js

@@ -47,6 +47,34 @@ const pugiSettingsSchema = z.object({
             .optional(),
     })
         .optional(),
+    // β1 Pl9 (#74) — per-command budget overrides. Optional. Partial
+    // overrides merge against the β1 defaults in
+    // `core/engine/budgets.ts::beta1DefaultBudgets`. The schema is
+    // intentionally loose at the leaf (positive integers) so a typo lands
+    // a deterministic `BudgetConfigError` at `resolveBudget()` instead of
+    // a Zod parse error two layers up.
+    budgets: z
+        .object({
+        code: z
+            .object({ maxTokens: z.number().int().positive().optional(), maxToolCalls: z.number().int().positive().optional() })
+            .optional(),
+        fix: z
+            .object({ maxTokens: z.number().int().positive().optional(), maxToolCalls: z.number().int().positive().optional() })
+            .optional(),
+        build: z
+            .object({ maxTokens: z.number().int().positive().optional(), maxToolCalls: z.number().int().positive().optional() })
+            .optional(),
+        plan: z
+            .object({ maxTokens: z.number().int().positive().optional(), maxToolCalls: z.number().int().positive().optional() })
+            .optional(),
+        explain: z
+            .object({ maxTokens: z.number().int().positive().optional(), maxToolCalls: z.number().int().positive().optional() })
+            .optional(),
+        review_triple: z
+            .object({ maxTokens: z.number().int().positive().optional(), maxToolCalls: z.number().int().positive().optional() })
+            .optional(),
+    })
+        .optional(),
 });
 export function loadSettings(root) {
     const settingsPath = resolve(root, '.pugi/settings.json');