@pugi/cli 0.1.0-beta.2 → 0.1.0-beta.20

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