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

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)