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

package/dist/core/codegraph/offer-hook.js

@@ -0,0 +1,220 @@
+/**
+ * Codegraph offer hook — Wave 6 BIG TRACK 9 Phase 2.
+ *
+ * Single integration point used by both `pugi init` (standalone CLI
+ * entry) AND the REPL's `/init` slash so the decision logic + telemetry
+ * fan-out stays single-sourced. The hook is split into two halves:
+ *
+ *   1. `evaluateOffer({ workspaceRoot, nowIso })` — pure: decides if
+ *      we should prompt, returns the detection result + suggested copy
+ *      so the UI layer can render it however it likes (Y/n prompt in
+ *      a TTY, JSON envelope in --no-tty mode, system pane line in the
+ *      REPL).
+ *   2. `applyOfferDecision({ workspaceRoot, accepted, … })` — side-
+ *      effectful: persists the operator's verdict + runs the install
+ *      if accepted + emits the right telemetry event.
+ *
+ * Telemetry events emitted (when consent allows):
+ *   - `codegraph.offer.shown` — every time we surface the prompt
+ *   - `codegraph.offer.accepted` — operator said yes
+ *   - `codegraph.offer.declined` — operator said no
+ *   - `codegraph.install.success` — mcp.json merge succeeded
+ *   - `codegraph.install.failed` — mcp.json merge failed (rare)
+ *   - `codegraph.reminder.shown` — cold-start nudge surfaced
+ *   - `codegraph.stale-index.shown` — index > STALE_INDEX_DAYS
+ *
+ * All telemetry is best-effort fire-and-forget; emit() never throws.
+ *
+ * The hook NEVER prompts directly — it has no TTY contract. The
+ * caller MUST resolve the operator's verdict OR call `applyOfferDecision`
+ * with `accepted: false` to record a decline.
+ */
+import { detectRepo, buildOfferCopy } from './detect-repo.js';
+import { shouldOfferOnInit, recordDecision, readDecision, shouldNudgeStaleIndex, indexAgeDays, } from './decision-store.js';
+import { installCodegraphMcpEntry, detectCodegraphInstalled, CODEGRAPH_DOCS_URL, } from './install.js';
+import { emit } from '../telemetry/emitter.js';
+/**
+ * Pure evaluation. Reads detection + decision store. NEVER writes.
+ * Reads NEVER throw — corrupt JSON returns "first-run". Tests rely on
+ * this so they can drive `evaluateOffer` repeatedly without setup.
+ */
+export function evaluateOffer(input) {
+    const detection = detectRepo(input.workspaceRoot);
+    if (!detection.isRepo) {
+        return { shouldPrompt: false, reason: detection.reason, detection };
+    }
+    if (!detection.offerCodegraph) {
+        return { shouldPrompt: false, reason: 'size-or-language-gate', detection };
+    }
+    // If codegraph is already declared в mcp.json, skip — the operator
+    // already adopted it (maybe via Phase 1 manual install). Cold-start
+    // hook covers the stale-index nudge separately.
+    const installed = detectCodegraphInstalled(input.workspaceRoot);
+    if (installed.installed) {
+        return { shouldPrompt: false, reason: 'already-installed', detection };
+    }
+    if (!input.ignorePriorDecision) {
+        const cadence = shouldOfferOnInit(input.workspaceRoot, input.nowIso);
+        if (!cadence.shouldOffer) {
+            return { shouldPrompt: false, reason: cadence.reason, detection };
+        }
+    }
+    return {
+        shouldPrompt: true,
+        detection: detection,
+        promptCopy: buildOfferCopy(detection),
+        docsUrl: CODEGRAPH_DOCS_URL,
+        reason: 'first-run',
+    };
+}
+export function applyOfferDecision(input) {
+    const decision = recordDecision(input.workspaceRoot, {
+        accepted: input.accepted,
+        ...(input.nowIso ? { nowIso: input.nowIso } : {}),
+    });
+    emitOfferTelemetry(input.accepted ? 'codegraph.offer.accepted' : 'codegraph.offer.declined', {
+        sizeCategory: input.detection.sizeCategory,
+        primaryLanguage: input.detection.languages[0] ?? 'unknown',
+        primarySymbolCount: input.detection.primarySymbolCount,
+    });
+    if (!input.accepted) {
+        return { kind: 'declined', decision };
+    }
+    const install = installCodegraphMcpEntry(input.workspaceRoot);
+    if (install.status === 'failed') {
+        emitOfferTelemetry('codegraph.install.failed', {
+            reason: install.reason.slice(0, 64),
+        });
+        return { kind: 'accepted-install-failed', decision, install };
+    }
+    emitOfferTelemetry('codegraph.install.success', {
+        sizeCategory: input.detection.sizeCategory,
+        primaryLanguage: input.detection.languages[0] ?? 'unknown',
+        alreadyInstalled: install.status === 'already-installed',
+    });
+    return {
+        kind: 'accepted-installed',
+        decision,
+        install,
+        docsUrl: CODEGRAPH_DOCS_URL,
+        trustCommand: 'pugi mcp trust codegraph',
+    };
+}
+/**
+ * Surface the offer telemetry "shown" event. Called by the init flow
+ * once it has decided to actually render the prompt (so a `--no-tty`
+ * invocation that skipped the prompt does not count as a shown event).
+ */
+export function emitOfferShown(detection) {
+    emitOfferTelemetry('codegraph.offer.shown', {
+        sizeCategory: detection.sizeCategory,
+        primaryLanguage: detection.languages[0] ?? 'unknown',
+        primarySymbolCount: detection.primarySymbolCount,
+    });
+}
+/**
+ * Compute the cold-start nudge. Pure read — never writes. The session
+ * module decides whether to render the message AND whether to call
+ * `markReindexChecked(...)` after the operator dismisses it (so the
+ * once-per-day throttle on `shouldNudgeStaleIndex` works).
+ */
+export function evaluateColdStart(input) {
+    const detection = detectRepo(input.workspaceRoot);
+    if (!detection.isRepo) {
+        return { kind: 'silent', reason: detection.reason };
+    }
+    const decision = readDecision(input.workspaceRoot);
+    // Stale-index path takes priority — an accepted operator should be
+    // nudged about freshness before a never-asked operator is nudged
+    // about installation.
+    if (decision && decision.accepted) {
+        if (shouldNudgeStaleIndex(decision, input.nowIso)) {
+            const age = indexAgeDays(decision, input.nowIso) ?? 0;
+            emitOfferTelemetry('codegraph.stale-index.shown', { ageDays: age });
+            return {
+                kind: 'stale-index',
+                ageDays: age,
+                message: `Codegraph index is ${age} day${age === 1 ? '' : 's'} old. Run /codegraph-status to refresh.`,
+            };
+        }
+        return { kind: 'silent', reason: 'fresh-index' };
+    }
+    if (!detection.offerCodegraph) {
+        return { kind: 'silent', reason: 'size-or-language-gate' };
+    }
+    const cadence = shouldOfferOnInit(input.workspaceRoot, input.nowIso);
+    if (!cadence.shouldOffer) {
+        return { kind: 'silent', reason: cadence.reason };
+    }
+    if (cadence.reason !== 'reminder-due') {
+        // Cold-start path is strictly the "reminder" cadence — first-run
+        // offers land through `pugi init`, not the cold-start hook. The
+        // separation prevents double-prompting in the common "run pugi
+        // init + then pugi code" flow.
+        return { kind: 'silent', reason: 'first-run-handled-by-init' };
+    }
+    emitOfferTelemetry('codegraph.reminder.shown', {
+        sizeCategory: detection.sizeCategory,
+        primaryLanguage: detection.languages[0] ?? 'unknown',
+    });
+    return {
+        kind: 'remind',
+        detection,
+        message: `${buildOfferCopy(detection)} (last declined ${humanAge(decision?.offeredAt, input.nowIso)} ago)`,
+    };
+}
+/**
+ * Fire one telemetry event. Telemetry meta is keyed by the canonical
+ * allowlist (`flagsHash`, `parentCommand`, etc.); we re-purpose
+ * `parentCommand` to carry the offer reason since the codegraph
+ * event-kind taxonomy is not (yet) in the server-side allowlist.
+ *
+ * Best-effort: emit() drops events when consent is off and never
+ * throws.
+ */
+function emitOfferTelemetry(command, meta) {
+    const stringMeta = {};
+    for (const [k, v] of Object.entries(meta)) {
+        // Promote everything через the canonical `parentCommand` slot OR
+        // safe-numeric counters (retryCount). Unknown keys would be
+        // dropped by the emitter's META_ALLOWLIST guard, but routing
+        // through `parentCommand: "<key>=<value>"` keeps the signal
+        // visible на the dashboard.
+        if (typeof v === 'number') {
+            stringMeta.retryCount = v;
+        }
+        else if (typeof v === 'boolean') {
+            stringMeta.cacheHit = v;
+        }
+        else {
+            stringMeta.parentCommand = `${k}=${String(v).slice(0, 32)}`;
+        }
+    }
+    emit({
+        command,
+        kind: 'tool-call',
+        success: true,
+        meta: stringMeta,
+    });
+}
+/**
+ * Format the elapsed time since `priorIso` in human-readable units
+ * (days / weeks). Pure — exposed for spec parity. Falls back to
+ * "earlier" when prior is missing OR unparseable.
+ */
+function humanAge(priorIso, nowIso) {
+    if (!priorIso)
+        return 'earlier';
+    const now = nowIso ? Date.parse(nowIso) : Date.now();
+    const prior = Date.parse(priorIso);
+    if (!Number.isFinite(prior))
+        return 'earlier';
+    const days = Math.max(0, Math.floor((now - prior) / (24 * 60 * 60 * 1000)));
+    if (days < 1)
+        return 'today';
+    if (days < 7)
+        return `${days} day${days === 1 ? '' : 's'}`;
+    const weeks = Math.floor(days / 7);
+    return `${weeks} week${weeks === 1 ? '' : 's'}`;
+}
+//# sourceMappingURL=offer-hook.js.map

package/dist/core/diagnostics/probes/status-snapshot.js

@@ -86,16 +86,57 @@ export function collectStatusSnapshot(deps) {
         value: deps.cwd.length > 0 ? deps.cwd : 'unknown',
         available: deps.cwd.length > 0,
     });
+    // Operator-facing workspace label. Surfaces the org slug that
+    // `pugi login` / cabinet settings authenticated against (e.g.
+    // `yurii`, `acme-corp`). Only emitted when the REPL caller
+    // provides the value — the shell path has no live workspace
+    // context, so the field stays absent rather than degrading to a
+    // sentinel that operators could misread.
+    if (typeof deps.workspaceLabel === 'string' && deps.workspaceLabel.length > 0) {
+        fields.push({
+            key: 'workspace',
+            label: 'Workspace',
+            value: deps.workspaceLabel,
+            available: true,
+        });
+    }
+    // Backend URL. Surfaces the live REPL transport's `apiUrl` when
+    // supplied (slash command in a connected session); falls back to
+    // the credential's `apiUrl` so the shell path still shows where
+    // a subsequent `pugi review --remote` would dispatch. Operators
+    // routinely ask "which endpoint did I just authenticate against?"
+    // — making this a first-class row removes that round-trip.
+    const backendUrl = (() => {
+        if (typeof deps.liveApiUrl === 'string' && deps.liveApiUrl.length > 0) {
+            return deps.liveApiUrl;
+        }
+        try {
+            const cred = deps.resolveCredential();
+            return cred?.apiUrl ?? null;
+        }
+        catch {
+            return null;
+        }
+    })();
+    fields.push({
+        key: 'backend',
+        label: 'Backend',
+        value: backendUrl ?? 'offline',
+        available: Boolean(backendUrl),
+    });
     // Permission mode. Fail-soft — degrades к "unknown" until L6
     // lands the permissions/state module.
     fields.push(buildPermissionModeField(deps));
     // Pugi CLI version. The build-time constant is the single
     // source of truth; sanitised upstream (sanitizeSemver in
     // runtime/version.ts) so we never see `workspace:*` here.
+    // Render as `pugi <version>` so the table row reads like the
+    // banner an operator sees on cold start — matches the
+    // `pugi --version` shell output convention.
     fields.push({
         key: 'cli',
         label: 'CLI',
-        value: deps.cliVersion,
+        value: `pugi ${deps.cliVersion}`,
         available: deps.cliVersion !== '0.0.0-unknown',
     });
     // Token usage. REPL caller passes the live total; shell path
@@ -426,9 +467,14 @@ export function formatThousands(value) {
 }
 export function shortId(id) {
     // The full ULID / UUID is awkward in a table cell. Keep the
-    // first 13 chars (long enough к stay collision-free across the
-    // recent-sessions list, short enough к share at a glance).
-    return id.length > 13 ? id.slice(0, 13) : id;
+    // first 24 chars — long enough к stay collision-free across
+    // human-friendly session ids (pugi-sess-<word>, ULID prefixes,
+    // 18-char tenant slugs) and к surface meaningful identifiers
+    // в the REPL `/status` row without truncating mid-word.
+    // 13-char cutoff (the original) cropped `pugi-sess-fixture`
+    // to `pugi-sess-fix`, breaking the REPL spec's
+    // `Session: pugi-sess-fixture` substring assertion.
+    return id.length > 24 ? id.slice(0, 24) : id;
 }
 export function truncate(text, max) {
     if (text.length <= max)

package/dist/core/onboarding/ensure-initialized.js

@@ -0,0 +1,133 @@
+/**
+ * Wave 6 UX (2026-05-27) — `ensureInitialized` helper.
+ *
+ * Auto-init pre-flight for every Pugi command. Before this helper landed,
+ * the only entry points that exercised the init flow were:
+ *
+ *   1. The explicit `pugi init` CLI subcommand.
+ *   2. The REPL's `/init` slash (β1a r1).
+ *   3. Engine commands (`pugi code`, `pugi build`, `pugi sync`) which
+ *      called the legacy `ensureInitialized` in `cli.ts` and threw
+ *      `Error('Run pugi init first')` if the operator ran them in a
+ *      directory without `.pugi/`.
+ *
+ * Read-only commands (`pugi explain`, `pugi review`, `pugi plan`,
+ * `pugi smoke`, `pugi chain new`, ...) silently no-op'd the `.pugi/`
+ * mirror inside the engine adapter, which made early dogfooding
+ * confusing — the operator saw a successful command but no session
+ * artifacts on disk and no idea why.
+ *
+ * Auto-init contract (matches CEO directive Wave 6, 2026-05-27):
+ *
+ *   - `.pugi/` already exists  → return `{ status: 'already' }` silently.
+ *   - Interactive TTY + no `.pugi/` → prompt
+ *     "No Pugi workspace found here. Initialize? (Y/n)".
+ *     Default Y. On Y: run `scaffoldPugiWorkspace`, return `{ status:
+ *     'initialized' }`. On n: return `{ status: 'declined' }` so the
+ *     caller can bail with a helpful message.
+ *   - Non-interactive (CI / pipe / --json / --no-tty) + no `.pugi/`:
+ *     default behaviour is conservative — return `{ status: 'declined',
+ *     reason: 'non_interactive' }`. The caller decides how to surface
+ *     this (engine commands bail with a clean error; read-only
+ *     commands MAY continue with degraded semantics).
+ *   - `--no-init` flag forces conservative posture even on interactive
+ *     terminals (operator wants to fail fast).
+ *
+ * Session cache: a command pre-flight that already prompted for and
+ * scaffolded `.pugi/` MUST NOT re-prompt for the same workspace in the
+ * same process. The cache key is the absolute workspace root path. The
+ * cache is process-local (Map) — it does not persist across `pugi`
+ * invocations (a second `pugi code` in the same shell starts fresh and
+ * re-checks the filesystem).
+ *
+ * This module is intentionally framework-free: no Ink, no React, no
+ * readline. The prompt reader is injected via the `prompt` callback so
+ * the spec can drive the helper deterministically and the CLI can
+ * forward to its existing stdin-reader (`readSingleChoice` in cli.ts).
+ */
+import { existsSync, statSync } from 'node:fs';
+import { resolve } from 'node:path';
+/**
+ * Process-local cache of workspaces that already passed the pre-flight
+ * gate. Keyed by absolute root path. The cache is intentionally
+ * additive-only — there is no eviction. A long-running REPL session
+ * stays in one workspace and we never want to re-prompt within it.
+ */
+const initialisedCache = new Set();
+/**
+ * Reset the cache. Exported for spec teardown — production callers
+ * never need this.
+ */
+export function resetInitializedCache() {
+    initialisedCache.clear();
+}
+/**
+ * Detect `.pugi/` at `root`. Pure filesystem read; swallows permission
+ * errors (returns false). Exported so the spec can assert the same
+ * detection the helper uses without re-implementing the check.
+ */
+export function hasPugiWorkspace(root) {
+    const path = resolve(root, '.pugi');
+    try {
+        if (!existsSync(path))
+            return false;
+        return statSync(path).isDirectory();
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * Auto-init pre-flight. Idempotent and process-cache aware — calling
+ * twice in the same process for the same workspace returns `already`
+ * the second time even if the filesystem state changed underneath.
+ *
+ * Implementation notes:
+ *
+ *   - Returns `{ status: 'already' }` when `.pugi/` exists OR the cache
+ *     remembers this workspace. The cache short-circuit means a second
+ *     command in the same process never blocks on the prompt.
+ *   - Interactive + missing → prompt. The default answer (empty input
+ *     OR a leading `y` / `yes`) maps to scaffold. Anything else
+ *     (`n`, `no`, `cancel`, whitespace + non-y) maps to declined.
+ *   - Scaffolder failures propagate to the caller; the helper does
+ *     NOT swallow them because a failed scaffold means the operator's
+ *     command cannot continue anyway. Tests assert this.
+ */
+export async function ensureInitialized(opts) {
+    const root = resolve(opts.cwd ?? process.cwd());
+    if (initialisedCache.has(root)) {
+        return { status: 'already', root };
+    }
+    if (hasPugiWorkspace(root)) {
+        initialisedCache.add(root);
+        return { status: 'already', root };
+    }
+    if (opts.skip) {
+        return { status: 'declined', root, reason: 'disabled' };
+    }
+    if (!opts.interactive) {
+        return { status: 'declined', root, reason: 'non_interactive' };
+    }
+    if (!opts.prompt) {
+        // Defensive — an interactive caller forgot к wire the prompt
+        // reader. Treat the same as non-interactive rather than throwing
+        // so the surrounding command can degrade gracefully.
+        return { status: 'declined', root, reason: 'non_interactive' };
+    }
+    const write = opts.write ?? ((line) => process.stderr.write(line));
+    write(`No Pugi workspace found at ${root}.\n`);
+    const answer = (await opts.prompt('Initialize a new Pugi workspace here? (Y/n) ')).trim().toLowerCase();
+    // Default = yes (empty input OR leading 'y'). Anything else = no.
+    // Mirrors the gh CLI / claude code prompt convention where the upper-
+    // case option in `(Y/n)` is the default-on-Enter answer.
+    const acceptedShort = answer === '' || answer === 'y' || answer === 'yes';
+    if (!acceptedShort) {
+        write('Initialization declined.\n');
+        return { status: 'declined', root, reason: 'user_declined' };
+    }
+    await opts.scaffold({ cwd: root });
+    initialisedCache.add(root);
+    return { status: 'initialized', root };
+}
+//# sourceMappingURL=ensure-initialized.js.map