@pugi/cli 0.1.0-beta.31 → 0.1.0-beta.36

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

@@ -1,297 +0,0 @@
-/**
- * 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/runtime/commands/memory.spec.js

@@ -1,174 +0,0 @@
-import { strict as assert } from 'node:assert';
-import { afterEach, beforeEach, describe, it } from 'node:test';
-import { mkdtempSync, rmSync } from 'node:fs';
-import { tmpdir } from 'node:os';
-import { resolve } from 'node:path';
-import { runMemoryCommand } from './memory.js';
-import { countPending } from '../../core/memory-sync/queue.js';
-/**
- * Integration tests for the `pugi memory` runner.
- *
- * Authenticated server paths require mocking undici's `MockAgent`; the
- * specs below focus on the un-authenticated + arg-parsing branches
- * (which fully exercise the routing + queue interactions). The shared
- * `runMemoryCommand` is decoupled from the network for those paths
- * because `resolveActiveCredential` returns null without a configured
- * credential file under PUGI_HOME.
- */
-let tmpHome = '';
-const originalPugiHome = process.env.PUGI_HOME;
-const originalHome = process.env.HOME;
-const originalApiKey = process.env.PUGI_API_KEY;
-const originalApiUrl = process.env.PUGI_API_URL;
-function makeCtx() {
-    const capture = { payloads: [], texts: [] };
-    const ctx = {
-        workspaceRoot: process.cwd(),
-        json: false,
-        writeOutput: (payload, text) => {
-            capture.payloads.push(payload);
-            capture.texts.push(text);
-        },
-    };
-    return { ctx, capture };
-}
-beforeEach(() => {
-    tmpHome = mkdtempSync(resolve(tmpdir(), 'pugi-memory-cli-'));
-    // Both PUGI_HOME (used by the queue) AND HOME (used by
-    // resolveActiveCredential -> os.homedir()) must point at the temp
-    // dir so the spec is hermetic from the operator's real
-    // ~/.pugi/credentials.json.
-    process.env.PUGI_HOME = tmpHome;
-    process.env.HOME = tmpHome;
-    // The test machine may export real prod credentials — strip them so
-    // the unauthenticated-paths block actually sees no credential.
-    delete process.env.PUGI_API_KEY;
-    delete process.env.PUGI_API_URL;
-});
-afterEach(() => {
-    if (originalPugiHome === undefined)
-        delete process.env.PUGI_HOME;
-    else
-        process.env.PUGI_HOME = originalPugiHome;
-    if (originalHome === undefined)
-        delete process.env.HOME;
-    else
-        process.env.HOME = originalHome;
-    if (originalApiKey === undefined)
-        delete process.env.PUGI_API_KEY;
-    else
-        process.env.PUGI_API_KEY = originalApiKey;
-    if (originalApiUrl === undefined)
-        delete process.env.PUGI_API_URL;
-    else
-        process.env.PUGI_API_URL = originalApiUrl;
-    try {
-        rmSync(tmpHome, { recursive: true, force: true });
-    }
-    catch {
-        // ignore
-    }
-});
-describe('runMemoryCommand — unauthenticated paths', () => {
-    it('prints usage on empty subcommand', async () => {
-        const { ctx, capture } = makeCtx();
-        const result = await runMemoryCommand([], ctx);
-        assert.equal(result.sub, 'help');
-        assert.ok(capture.texts[0]?.includes('pugi memory'));
-    });
-    it('rejects unknown subcommand with status unknown_sub', async () => {
-        const { ctx } = makeCtx();
-        const result = await runMemoryCommand(['blarg'], ctx);
-        assert.equal(result.status, 'unknown_sub');
-    });
-    it('returns unauthenticated for list when no credential', async () => {
-        const { ctx } = makeCtx();
-        const result = await runMemoryCommand(['list'], ctx);
-        assert.equal(result.status, 'unauthenticated');
-    });
-    it('returns unauthenticated for sync when no credential', async () => {
-        const { ctx } = makeCtx();
-        const result = await runMemoryCommand(['sync'], ctx);
-        assert.equal(result.status, 'unauthenticated');
-    });
-    it('queues offline writes when no credential present', async () => {
-        const { ctx } = makeCtx();
-        const result = await runMemoryCommand(['write', 'preference', 'pnpm', '--persona', 'mira'], ctx);
-        assert.equal(result.status, 'queued_offline');
-        assert.equal(result.pending, 1);
-        // Confirm the queue file actually grew.
-        assert.equal(countPending(resolve(tmpHome, 'memory-queue.jsonl')), 1);
-    });
-    it('queues offline forget when no credential present', async () => {
-        const { ctx } = makeCtx();
-        const result = await runMemoryCommand(['forget', 'mem-abc'], ctx);
-        assert.equal(result.status, 'queued_offline');
-        assert.equal(result.pending, 1);
-    });
-    it('rejects write missing kind', async () => {
-        const { ctx } = makeCtx();
-        const result = await runMemoryCommand(['write'], ctx);
-        assert.equal(result.status, 'invalid_args');
-    });
-    it('rejects write with unknown kind', async () => {
-        const { ctx } = makeCtx();
-        const result = await runMemoryCommand(['write', 'notakind', 'content here'], ctx);
-        assert.equal(result.status, 'invalid_args');
-        assert.equal(result.reason, 'unknown_kind');
-    });
-    it('rejects write with empty content', async () => {
-        const { ctx } = makeCtx();
-        const result = await runMemoryCommand(['write', 'fact', '   '], ctx);
-        assert.equal(result.status, 'invalid_args');
-    });
-    it('rejects forget without id', async () => {
-        const { ctx } = makeCtx();
-        const result = await runMemoryCommand(['forget'], ctx);
-        assert.equal(result.status, 'invalid_args');
-    });
-    it('rejects recall without query', async () => {
-        const { ctx } = makeCtx();
-        const result = await runMemoryCommand(['recall'], ctx);
-        assert.equal(result.status, 'invalid_args');
-    });
-    it('sync with no pending ops returns sync_noop when offline-then-online flow', async () => {
-        // Two writes queued offline (no credential present), then sync called
-        // — sync without credential still returns unauthenticated, but the
-        // queued ops persist. After credential lands, sync would push them.
-        const { ctx } = makeCtx();
-        await runMemoryCommand(['write', 'fact', 'queued one'], ctx);
-        await runMemoryCommand(['write', 'fact', 'queued two'], ctx);
-        assert.equal(countPending(resolve(tmpHome, 'memory-queue.jsonl')), 2);
-        const { ctx: ctx2 } = makeCtx();
-        const result = await runMemoryCommand(['sync'], ctx2);
-        // Without an active credential, sync returns unauthenticated.
-        assert.equal(result.status, 'unauthenticated');
-        // The queued ops are still on disk for a later authenticated sync.
-        assert.equal(countPending(resolve(tmpHome, 'memory-queue.jsonl')), 2);
-    });
-    it('write+sync flow keeps queue intact across calls', async () => {
-        const { ctx } = makeCtx();
-        await runMemoryCommand(['write', 'workflow', 'sample workflow'], ctx);
-        const path = resolve(tmpHome, 'memory-queue.jsonl');
-        assert.equal(countPending(path), 1);
-        // A second call should append, not overwrite.
-        await runMemoryCommand(['write', 'fact', 'another fact'], ctx);
-        assert.equal(countPending(path), 2);
-    });
-});
-describe('runMemoryCommand — flag parsing', () => {
-    it('parses --persona and --kind flags on list', async () => {
-        const { ctx, capture } = makeCtx();
-        // list path requires auth — we only verify the flag-parsing path
-        // does not throw + surfaces the unauth status.
-        const result = await runMemoryCommand(['list', '--persona', 'marcus', '--kind', 'pattern', '--limit', '5'], ctx);
-        assert.equal(result.status, 'unauthenticated');
-        assert.equal(capture.payloads.length, 1);
-    });
-    it('parses --top-k on recall', async () => {
-        const { ctx } = makeCtx();
-        const result = await runMemoryCommand(['recall', 'what is pugi', '--top-k', '3'], ctx);
-        assert.equal(result.status, 'unauthenticated');
-    });
-});
-//# sourceMappingURL=memory.spec.js.map