@pugi/cli 0.1.0-beta.5 → 0.1.0-beta.50

package/dist/core/telemetry/emitter.js

@@ -0,0 +1,229 @@
+/**
+ * Telemetry emitter — Wave 6 BIG TRACK 11 (PR-PUGI-OBSERVABILITY-STACK).
+ *
+ * Single entry point used by the REPL + slash dispatcher + tool runner
+ * to record CLI lifecycle events. Honours the L25 telemetry-state
+ * consent verdict — events are dropped silently when the operator chose
+ * `off` (default) and accepted into the queue when they chose
+ * `anonymous` or `community`.
+ *
+ * Opt-out hatches (any one of them stops the emitter cold):
+ *
+ *   1. `~/.pugi/.telemetry-disabled` marker file (per-user kill switch
+ *      the operator can drop with `touch` even when their config got
+ *      corrupted). Hot-path: we stat() this once at boot AND on every
+ *      emit so an emergency operator gesture takes effect immediately
+ *      without a REPL restart.
+ *   2. `PUGI_TELEMETRY=0` (env). Honoured at every emit — CI scripts
+ *      can wrap a one-shot invocation without touching the user's
+ *      config.
+ *   3. L25 `~/.pugi/config.json::telemetry === 'off'`. Default for
+ *      fresh installs — the onboarding wizard flips it to `anonymous`
+ *      or `community` when the operator says yes.
+ *
+ * The emitter is fire-and-forget. Calls never throw, never block the
+ * caller, and never await the network. The queue persists events to a
+ * JSONL spill so a synchronous CLI process can exit before a network
+ * round-trip completes without losing data.
+ *
+ * Allowlisted meta keys — call sites MUST pass only the canonical keys
+ * (see `META_ALLOWLIST` below). Unknown keys are dropped at this layer
+ * AND again at the admin-api ingest layer (defence in depth).
+ */
+import { statSync } from 'node:fs';
+import { homedir } from 'node:os';
+import { resolve } from 'node:path';
+import { readTelemetryChoice, } from '../onboarding/telemetry-state.js';
+import { PUGI_CLI_VERSION } from '../../runtime/version.js';
+import { newSessionId, spillEvent, } from './queue.js';
+/**
+ * Allowed meta keys. Matches the admin-api allowlist verbatim — the two
+ * lists MUST stay in sync. The server is the structural wall; this is
+ * the defence-in-depth at the source. Anything off-list is dropped
+ * before the event lands on disk so a CI grep of the spill file never
+ * surfaces a key that was never supposed to leave the process.
+ */
+export const META_ALLOWLIST = new Set([
+    'platform',
+    'arch',
+    'nodeVersion',
+    'tier',
+    'consent',
+    'pty',
+    'durationCategory',
+    'exitCode',
+    'parentCommand',
+    'subagent',
+    'modelTier',
+    'cacheHit',
+    'retryCount',
+    'quotaTier',
+    'tunedModel',
+    'flagsHash',
+]);
+/**
+ * Single source-of-truth marker the operator can `touch` to kill all
+ * telemetry from a single user account in one gesture. Bypasses the
+ * config file — survives a corrupt `config.json` and is documented in
+ * `pugi help telemetry`.
+ */
+export const KILL_SWITCH_MARKER = '.telemetry-disabled';
+/**
+ * Resolve the kill-switch marker path. Pure — exposed for tests.
+ */
+export function killSwitchPath(env = process.env) {
+    const home = env.PUGI_HOME ?? resolve(homedir(), '.pugi');
+    return resolve(home, KILL_SWITCH_MARKER);
+}
+/**
+ * Is the kill switch armed? Stat the marker on every emit so an
+ * operator gesture (e.g. `touch ~/.pugi/.telemetry-disabled`) takes
+ * effect immediately without a REPL restart.
+ */
+export function isKillSwitchArmed(env = process.env) {
+    const path = killSwitchPath(env);
+    try {
+        statSync(path);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * Is the env-var opt-out set? Honours common falsy literals so a CI
+ * matrix that exports `PUGI_TELEMETRY=false` or `=no` does the right
+ * thing.
+ */
+export function isEnvDisabled(env = process.env) {
+    const raw = (env.PUGI_TELEMETRY ?? '').trim().toLowerCase();
+    if (raw === '')
+        return false;
+    return raw === '0' || raw === 'false' || raw === 'off' || raw === 'no';
+}
+/**
+ * Resolve the current consent verdict. Cached per-call (no module-level
+ * caching) so the onboarding wizard's flip from `off` → `anonymous`
+ * takes effect immediately without a REPL restart.
+ */
+export function currentConsent(ctx = {}) {
+    return readTelemetryChoice({ env: ctx.env });
+}
+/**
+ * Strip unknown keys + truncate long string values. Mirrors the server
+ * sanitiser. Cap is intentionally smaller here (256) than on the wire
+ * (512) — keeps the spill file lean on a long-offline laptop.
+ */
+const META_VALUE_CAP = 256;
+export function sanitiseMeta(value) {
+    const out = {};
+    if (!value || typeof value !== 'object')
+        return out;
+    let kept = 0;
+    for (const [k, v] of Object.entries(value)) {
+        if (kept >= 16)
+            break;
+        if (!META_ALLOWLIST.has(k))
+            continue;
+        if (v === null || v === undefined)
+            continue;
+        if (typeof v === 'string') {
+            out[k] = v.length > META_VALUE_CAP ? v.slice(0, META_VALUE_CAP) : v;
+        }
+        else if (typeof v === 'number' && Number.isFinite(v)) {
+            out[k] = v;
+        }
+        else if (typeof v === 'boolean') {
+            out[k] = v;
+        }
+        else {
+            continue;
+        }
+        kept += 1;
+    }
+    return out;
+}
+/**
+ * Per-process session id. Allocated lazily on first `emit(...)` so a
+ * CLI invocation that never fires telemetry never burns a UUID.
+ */
+let cachedSessionId = null;
+/**
+ * Reset the cached session id. Called by tests AND the REPL `/reset`
+ * path so a long-running REPL can rotate sessions on demand.
+ */
+export function resetSessionId() {
+    cachedSessionId = null;
+}
+/**
+ * Build the outbound event from `EmitInput` + the resolved consent
+ * tier. Pure — exposed for spec parity.
+ */
+export function buildEvent(input, consent, sessionId) {
+    const kind = input.kind ?? 'command-exec';
+    const success = typeof input.success === 'boolean' ? input.success : true;
+    // Anonymous tier strips everything but the bare counts. Community
+    // tier carries the (sanitised) meta payload. Off tier never reaches
+    // this function — the emit() gate rejects before we build.
+    const meta = consent === 'community' ? sanitiseMeta(input.meta) : {};
+    const out = {
+        sessionId,
+        cliVersion: PUGI_CLI_VERSION,
+        command: input.command,
+        kind,
+        ts: new Date().toISOString(),
+        success,
+    };
+    if (typeof input.durationMs === 'number' && Number.isFinite(input.durationMs)) {
+        out.durationMs = Math.max(0, Math.round(input.durationMs));
+    }
+    if (input.errorCode)
+        out.errorCode = input.errorCode;
+    if (input.tool)
+        out.tool = input.tool;
+    if (input.model)
+        out.model = input.model;
+    if (typeof input.tokensIn === 'number' && Number.isFinite(input.tokensIn)) {
+        out.tokensIn = Math.max(0, Math.round(input.tokensIn));
+    }
+    if (typeof input.tokensOut === 'number' && Number.isFinite(input.tokensOut)) {
+        out.tokensOut = Math.max(0, Math.round(input.tokensOut));
+    }
+    if (Object.keys(meta).length > 0)
+        out.meta = meta;
+    return out;
+}
+/**
+ * Fire one telemetry event. Never throws. Returns a discriminated
+ * verdict so callers (the spec, the diagnostic surface) can assert on
+ * the path the emit took.
+ *
+ * Hot-path: opt-out checks → consent check → buildEvent → spillEvent.
+ * The spillEvent step is sync filesystem IO; for CLI surfaces that
+ * cannot tolerate a 1ms stat() (e.g. inner REPL tick) the caller
+ * should queue via `setImmediate(() => emit(...))`.
+ */
+export function emit(input, ctx = {}) {
+    const env = ctx.env ?? process.env;
+    // The three opt-out hatches, cheapest first.
+    if (isEnvDisabled(env))
+        return { kind: 'disabled', reason: 'env' };
+    if (isKillSwitchArmed(env))
+        return { kind: 'disabled', reason: 'marker' };
+    const consent = currentConsent({ env });
+    if (consent === 'off')
+        return { kind: 'disabled', reason: 'consent' };
+    if (!cachedSessionId)
+        cachedSessionId = ctx.sessionId ?? newSessionId();
+    const sessionId = ctx.sessionId ?? cachedSessionId;
+    const event = buildEvent(input, consent, sessionId);
+    try {
+        spillEvent(event, { repoRoot: ctx.repoRoot });
+    }
+    catch {
+        // Spill failure is silent — the emitter is best-effort by contract.
+        // A broken spill is a degraded-but-functional CLI, not a failed one.
+    }
+    return { kind: 'enqueued' };
+}
+//# sourceMappingURL=emitter.js.map

package/dist/core/telemetry/queue.js

@@ -0,0 +1,251 @@
+/**
+ * Telemetry batching queue — Wave 6 BIG TRACK 11 (PR-PUGI-OBSERVABILITY-STACK).
+ *
+ * The emitter (see `emitter.ts`) appends events to an in-memory buffer
+ * and a JSONL spill file. The queue's two-tier strategy:
+ *
+ *   1. In-memory buffer (`MAX_BUFFER`) → flushed every `FLUSH_INTERVAL_MS`
+ *      OR on REPL exit OR when the buffer hits the cap.
+ *   2. JSONL spill (`<repoRoot>/.pugi/telemetry-queue.jsonl`) → drained
+ *      on every flush attempt. Used when the in-memory buffer cannot
+ *      reach the network (offline laptop, admin-api down).
+ *
+ * Failure semantics mirror the `feedback/queue.ts` pattern that landed
+ * in L21:
+ *
+ *   - 200/201/204                → success, drop from spill
+ *   - 404                        → endpoint not deployed yet — keep
+ *   - 5xx / network / abort      → transient — keep + exponential backoff
+ *   - other 4xx                  → permanent — drop (otherwise loop forever)
+ *
+ * The queue is intentionally simple: there are no concurrency primitives
+ * beyond filesystem `O_APPEND`. The CLI is single-process per REPL
+ * session; the JSONL spill survives a crash because every append is
+ * atomic at the OS level for line-sized writes on POSIX (Linux & macOS).
+ *
+ * Privacy:
+ *
+ *   - Events drop into the queue only when telemetry consent ≠ `off`.
+ *     The emitter consults `readTelemetryChoice()` before calling
+ *     `enqueueTelemetry(...)`. This module does NOT re-check — keeping
+ *     the consent gate at the emitter avoids double-decoding and
+ *     centralises the audit point.
+ *
+ *   - The spill file lives under `<repoRoot>/.pugi/` (workspace tier)
+ *     so an operator who deletes the repo also wipes any unfortunate
+ *     events that never made it to the server.
+ */
+import { appendFileSync, existsSync, mkdirSync, readFileSync, writeFileSync, } from 'node:fs';
+import { dirname, resolve } from 'node:path';
+import { randomUUID } from 'node:crypto';
+import { PUGI_CLI_VERSION } from '../../runtime/version.js';
+/** Defaults — tunable via env without redeploy. */
+export const MAX_BUFFER = 50;
+export const FLUSH_INTERVAL_MS = 15_000;
+export const SPILL_FILE_NAME = 'telemetry-queue.jsonl';
+/** Hard cap on the spill file (events, not bytes). Prevents pathologic
+ *  growth on a laptop that is offline for weeks. */
+export const SPILL_MAX_LINES = 5_000;
+/**
+ * Resolve the absolute spill file path. Pure — exposed for spec parity.
+ */
+export function telemetryQueuePath(opts = {}) {
+    const root = opts.repoRoot ?? process.cwd();
+    const name = opts.spillFileName ?? SPILL_FILE_NAME;
+    return resolve(root, '.pugi', name);
+}
+/**
+ * Append one event to the on-disk spill. Atomic at the OS level for
+ * line-sized writes — multiple concurrent appenders never interleave
+ * half-records on POSIX. Caps the file at `SPILL_MAX_LINES` by silently
+ * dropping the OLDEST events (FIFO) on the rare overflow path.
+ */
+export function spillEvent(ev, opts = {}) {
+    const path = telemetryQueuePath(opts);
+    mkdirSync(dirname(path), { recursive: true });
+    const line = `${JSON.stringify(ev)}\n`;
+    // Fast path: append-only. We only check the line count when the file
+    // already exists AND we suspect overflow. Reading + rewriting every
+    // append would dominate the cost.
+    if (existsSync(path)) {
+        const current = readFileSync(path, 'utf8');
+        const lineCount = countLines(current);
+        if (lineCount >= SPILL_MAX_LINES) {
+            // FIFO trim: keep the most-recent SPILL_MAX_LINES/2 events. The
+            // factor 2 amortises the rewrite across many appends.
+            const lines = current.split('\n').filter((l) => l.length > 0);
+            const keep = lines.slice(lines.length - Math.floor(SPILL_MAX_LINES / 2));
+            writeFileSync(path, `${keep.join('\n')}\n${line}`, 'utf8');
+            return;
+        }
+    }
+    appendFileSync(path, line, { encoding: 'utf8', mode: 0o600 });
+}
+/**
+ * Read + parse every spilled event. Returns the events plus a list of
+ * malformed lines (which are dropped silently — we never reject a
+ * parseable line just because an adjacent one is corrupt).
+ */
+export function readSpill(opts = {}) {
+    const path = telemetryQueuePath(opts);
+    if (!existsSync(path))
+        return { events: [], malformed: 0 };
+    const raw = readFileSync(path, 'utf8');
+    if (raw.length === 0)
+        return { events: [], malformed: 0 };
+    const events = [];
+    let malformed = 0;
+    for (const line of raw.split('\n')) {
+        if (line.length === 0)
+            continue;
+        try {
+            const parsed = JSON.parse(line);
+            if (isTelemetryEvent(parsed)) {
+                events.push(parsed);
+            }
+            else {
+                malformed += 1;
+            }
+        }
+        catch {
+            malformed += 1;
+        }
+    }
+    return { events, malformed };
+}
+/**
+ * Atomically rewrite the spill with the given events (the unsubmitted
+ * remainder after a partial-success flush). Writing through a sibling
+ * tempfile + rename keeps the spill consistent across a crash mid-flush.
+ */
+export function rewriteSpill(events, opts = {}) {
+    const path = telemetryQueuePath(opts);
+    mkdirSync(dirname(path), { recursive: true });
+    if (events.length === 0) {
+        // Empty spill — write an empty file so the next read short-circuits.
+        writeFileSync(path, '', { encoding: 'utf8', mode: 0o600 });
+        return;
+    }
+    const body = events.map((e) => JSON.stringify(e)).join('\n');
+    writeFileSync(path, `${body}\n`, { encoding: 'utf8', mode: 0o600 });
+}
+/**
+ * Type guard for inbound spill lines. Keeps the queue robust against a
+ * forward-incompatible event shape (e.g. a future version added a
+ * required field) — anything that fails the guard is treated as
+ * malformed and dropped on parse.
+ */
+export function isTelemetryEvent(value) {
+    if (!value || typeof value !== 'object')
+        return false;
+    const v = value;
+    return (typeof v.sessionId === 'string'
+        && typeof v.cliVersion === 'string'
+        && typeof v.command === 'string'
+        && typeof v.kind === 'string'
+        && typeof v.ts === 'string');
+}
+/**
+ * Exponential-backoff schedule. Returns the next delay (in ms) given an
+ * attempt counter, capped at `MAX_BACKOFF_MS`. Pure — exposed for tests.
+ *
+ *   attempt 0 → 1s
+ *   attempt 1 → 2s
+ *   attempt 2 → 4s
+ *   attempt 5 → 32s
+ *   attempt 7+ → 60s (cap)
+ */
+export const BACKOFF_BASE_MS = 1000;
+export const MAX_BACKOFF_MS = 60_000;
+export function backoffDelay(attempt) {
+    if (!Number.isFinite(attempt) || attempt < 0)
+        return BACKOFF_BASE_MS;
+    const exp = BACKOFF_BASE_MS * Math.pow(2, Math.floor(attempt));
+    return Math.min(MAX_BACKOFF_MS, exp);
+}
+const DEFAULT_FLUSH_TIMEOUT_MS = 8_000;
+export function telemetryIngestUrl(apiUrl) {
+    const base = apiUrl.replace(/\/+$/u, '');
+    return `${base}/api/pugi/telemetry/event`;
+}
+/**
+ * POST one batch. Same result-variant contract as
+ * `feedback/submitter.submitFeedback`. Never throws.
+ */
+export async function postTelemetryBatch(events, config) {
+    if (events.length === 0) {
+        return { kind: 'ok', httpStatus: 204, accepted: 0, dropped: 0 };
+    }
+    const url = telemetryIngestUrl(config.apiUrl);
+    const fetchImpl = config.fetchImpl ?? fetch;
+    const timeoutMs = config.timeoutMs ?? DEFAULT_FLUSH_TIMEOUT_MS;
+    const controller = new AbortController();
+    const timer = setTimeout(() => controller.abort(), timeoutMs);
+    try {
+        const headers = {
+            'content-type': 'application/json',
+            'user-agent': `pugi-cli/${PUGI_CLI_VERSION}`,
+        };
+        if (config.apiKey)
+            headers['authorization'] = `Bearer ${config.apiKey}`;
+        const res = await fetchImpl(url, {
+            method: 'POST',
+            headers,
+            body: JSON.stringify({ events }),
+            signal: controller.signal,
+        });
+        const status = res.status;
+        if (status >= 200 && status < 300) {
+            let accepted = events.length;
+            let dropped = 0;
+            try {
+                const body = (await res.json());
+                if (typeof body.accepted === 'number')
+                    accepted = body.accepted;
+                if (typeof body.dropped === 'number')
+                    dropped = body.dropped;
+            }
+            catch {
+                // Body absent / not JSON — server still acked 2xx, treat as full success.
+            }
+            return { kind: 'ok', httpStatus: status, accepted, dropped };
+        }
+        if (status === 404) {
+            return {
+                kind: 'transient',
+                reason: 'admin-api /api/pugi/telemetry/event not deployed yet',
+                httpStatus: status,
+            };
+        }
+        if (status >= 500) {
+            return { kind: 'transient', reason: `server error ${status}`, httpStatus: status };
+        }
+        return { kind: 'permanent', reason: `client error ${status}`, httpStatus: status };
+    }
+    catch (err) {
+        const message = err instanceof Error ? err.message : String(err);
+        return { kind: 'transient', reason: `network: ${message}` };
+    }
+    finally {
+        clearTimeout(timer);
+    }
+}
+// ---------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------
+function countLines(s) {
+    let n = 0;
+    for (let i = 0; i < s.length; i += 1) {
+        if (s.charCodeAt(i) === 10)
+            n += 1;
+    }
+    return n;
+}
+/**
+ * Generate a session id for the REPL boot. UUID v4 — short enough to
+ * grep, long enough to be globally unique across concurrent processes.
+ */
+export function newSessionId() {
+    return randomUUID();
+}
+//# sourceMappingURL=queue.js.map

package/dist/core/theme/context.js

@@ -0,0 +1,91 @@
+import { jsx as _jsx } from "react/jsx-runtime";
+/**
+ * Leak L30 (2026-05-27) — Theme React context + `useTheme` hook.
+ *
+ * Threads the active theme's color tokens through the Ink component
+ * tree so individual components do not need to call `resolveTheme()`
+ * on every render. The provider is mounted once at the top of the
+ * REPL Ink tree (in `repl-render.tsx`); standalone CLI commands
+ * (`pugi doctor`, `pugi theme`) can mount the provider themselves
+ * when they print colored output.
+ *
+ * Design contract:
+ *
+ *   - The hook returns the resolved `ThemeColors` token set, NOT the
+ *     full `ResolvedTheme`. Component code only needs the color
+ *     values; the slug + source label live on the parent (the
+ *     `/theme` table renders them, individual components do not).
+ *
+ *   - When no provider is mounted, `useTheme()` returns the
+ *     `default` preset's colors. This is intentional — pure render
+ *     components that get imported into a test without a wrapper
+ *     should not crash. The behaviour matches `useContext` semantics
+ *     of every other Pugi context (`SessionContext`, `WorkspaceContext`).
+ *
+ *   - The provider takes the *resolved slug* (not the file path).
+ *     The caller is responsible for calling `resolveTheme()` once at
+ *     mount time and re-mounting on slug change. We deliberately do
+ *     NOT poll the config file from inside the provider — Ink
+ *     re-renders on every prop change would otherwise risk
+ *     reentrancy with the input box's raw-mode handler.
+ *
+ *   - The provider value is memoised against the slug so child
+ *     components see referentially-equal colors across re-renders
+ *     when the slug has not changed. This matters for `useMemo` /
+ *     `useEffect` dependency lists in downstream consumers.
+ *
+ * Test surface: `test/commands/theme-context.spec.tsx` mounts the
+ * provider with each preset slug, asserts the hook returns the
+ * matching color tokens, and asserts the default-when-no-provider
+ * fallback path.
+ */
+import { createContext, useContext, useMemo, } from 'react';
+import { DEFAULT_THEME, getThemeColors, } from './presets.js';
+/**
+ * The context default is the `default` preset's colors. Components
+ * imported into a test or non-REPL render that lack a provider
+ * therefore behave as if the operator never overrode the theme.
+ */
+const ThemeContext = createContext({
+    slug: DEFAULT_THEME,
+    colors: getThemeColors(DEFAULT_THEME),
+});
+/**
+ * Mount the theme provider with a resolved slug. The provider
+ * memoises the color lookup against `slug` so child components see
+ * referentially-stable colors across re-renders.
+ *
+ * Production wiring (`tui/repl-render.tsx`):
+ *
+ *   const resolved = resolveTheme({ workspaceRoot, env: process.env });
+ *   render(<ThemeProvider slug={resolved.slug}><Repl … /></ThemeProvider>);
+ *
+ * The wrapper is intentionally a thin pass-through (no side effects,
+ * no `useEffect`) so it can be mounted from any Ink renderer
+ * including the one-shot CLI surfaces in `runtime/cli.ts`.
+ */
+export function ThemeProvider({ slug, children }) {
+    const value = useMemo(() => ({ slug, colors: getThemeColors(slug) }), [slug]);
+    return _jsx(ThemeContext.Provider, { value: value, children: children });
+}
+/**
+ * Hook that returns the active theme's color tokens.
+ *
+ * Components reference tokens by semantic name (`accent`, `success`,
+ * `error`) instead of literal hex codes so a theme flip is a
+ * single-write operation. Tests can mount any preset without
+ * touching the disk; the production REPL resolves once at mount and
+ * re-mounts on `/theme <name>`.
+ */
+export function useTheme() {
+    return useContext(ThemeContext).colors;
+}
+/**
+ * Debug helper — returns the currently-active slug + colors. Used by
+ * the `/theme` slash command's preview path; production components
+ * should call `useTheme()` so the boundary stays narrow.
+ */
+export function useThemeDebug() {
+    return useContext(ThemeContext);
+}
+//# sourceMappingURL=context.js.map