@pugi/cli 0.1.0-beta.9 → 0.1.0-beta.91

package/dist/core/share/formatter.js

@@ -0,0 +1,271 @@
+/**
+ * Markdown transcript formatter used by `pugi share` ().
+ *
+ * Walks the session's `.pugi/events.jsonl` audit log and reconstructs a
+ * Markdown document the operator (and downstream Gist / pugi.io readers)
+ * can read top-to-bottom. The format is intentionally human-first — turn
+ * headers, code-block-wrapped tool I/O, and a small front-matter block
+ * with session metadata. Machine-readability is a non-goal here; the
+ * JSONL log remains the source of truth for tooling.
+ *
+ * Why we reconstruct from JSONL instead of from the live REPL state:
+ *
+ *  - The CLI top-level `pugi share` command runs from a fresh shell and
+ *    has no in-memory REPL state to read; only the event log is
+ *    persisted.
+ *  - The in-REPL `/share` slash uses the same handler so behaviour is
+ *    identical regardless of entry point. Operators sharing a session
+ *    from inside the REPL get the exact same output they would get from
+ *    a follow-up shell command.
+ *  - The JSONL log is append-only and survives REPL crashes, so a
+ *    `--share` after a crash is the most useful debug surface.
+ *
+ * Event vocabulary the formatter knows about (see
+ * `packages/pugi-sdk/src/audit-trace.ts` for the schema):
+ *
+ *  session.created                 Session boundary; emits front matter.
+ *  session.command_started         One-line "running pugi <cmd>" header.
+ *  session.command_completed       Status line ("success" / "error").
+ *  tool_call                       Markdown turn header + inputSummary
+ *                                   rendered as a fenced block.
+ *  tool_result                     "Result (status):" + outputSummary
+ *                                   rendered as a fenced block.
+ *  file_mutation                   Inline `path` + operation summary.
+ *  subagent.*                      Indented "[subagent <role>] ..." line.
+ *  hook.*                          Quiet "[hook <event>] ..." line.
+ *  compaction.*                    "[compaction <tier>] ..." line.
+ *
+ * Unknown event types are surfaced as a single italic line ("[event
+ * type=...]") so a future event added to the SDK does not silently
+ * vanish from the transcript.
+ *
+ * Performance: the formatter is O(n) over the events file, runs entirely
+ * in memory, and is bounded by the session log size (currently capped at
+ * a few MB per session). No streaming I/O is needed for typical sessions
+ * — the operator does not run /share against multi-GB logs.
+ */
+/**
+ * Format a session's event log as Markdown. Pure — no I/O. The caller
+ * reads `.pugi/events.jsonl` and hands the contents in.
+ */
+export function formatTranscript(input) {
+    const now = input.now ? input.now() : new Date();
+    const events = parseEvents(input.eventsJsonl);
+    const filteredSessionId = pickSessionId(input.sessionId, events);
+    const sessionEvents = events.filter((e) => typeof e.raw.sessionId !== 'string' || e.raw.sessionId === filteredSessionId);
+    const lines = [];
+    // Front matter — a fenced block at the top so downstream readers can
+    // grok the context before any turn content. Not YAML front matter
+    // (`---`) because Gist + pugi.io render Markdown directly; the fenced
+    // approach renders predictably without a parser.
+    lines.push('# Pugi session transcript');
+    lines.push('');
+    lines.push('```');
+    lines.push(`session_id: ${filteredSessionId}`);
+    lines.push(`workspace:  ${input.workspaceRoot}`);
+    lines.push(`cli_version: ${input.cliVersion}`);
+    lines.push(`exported_at: ${now.toISOString()}`);
+    lines.push(`event_count: ${sessionEvents.length}`);
+    lines.push('```');
+    lines.push('');
+    if (sessionEvents.length === 0) {
+        lines.push('_No events recorded for this session._');
+        return {
+            markdown: `${lines.join('\n')}\n`,
+            turnCount: 0,
+            eventCount: 0,
+        };
+    }
+    let turnCount = 0;
+    for (const event of sessionEvents) {
+        const rendered = renderEvent(event);
+        if (rendered === null)
+            continue;
+        lines.push(...rendered.lines);
+        lines.push('');
+        if (rendered.isTurn)
+            turnCount += 1;
+    }
+    return {
+        markdown: `${lines.join('\n').replace(/\n{3,}/g, '\n\n')}\n`,
+        turnCount,
+        eventCount: sessionEvents.length,
+    };
+}
+/**
+ * Parse the JSONL log. Malformed lines are skipped silently — the file
+ * is append-only and may have partial-write tail rows. Returning the
+ * stable typed shape lets the formatter walk without re-checking every
+ * field.
+ */
+function parseEvents(raw) {
+    const out = [];
+    for (const line of raw.split('\n')) {
+        const trimmed = line.trim();
+        if (trimmed.length === 0)
+            continue;
+        try {
+            const parsed = JSON.parse(trimmed);
+            const type = typeof parsed.type === 'string' ? parsed.type : '';
+            const timestamp = typeof parsed.timestamp === 'string' ? parsed.timestamp : '';
+            if (type.length === 0)
+                continue;
+            out.push({ raw: parsed, type, timestamp });
+        }
+        catch {
+            // partial-write or corrupt row; skip without affecting the rest
+        }
+    }
+    return out;
+}
+/**
+ * Resolve the effective session id. When the operator passes a non-empty
+ * value we honour it. When they pass an empty string / placeholder
+ * (`'no-session'`), we fall back to the newest `session.created` event
+ * id in the file. Last-resort fallback is the literal placeholder so the
+ * transcript still renders something meaningful in the front matter.
+ */
+function pickSessionId(provided, events) {
+    if (provided && provided !== 'no-session')
+        return provided;
+    for (let i = events.length - 1; i >= 0; i -= 1) {
+        const e = events[i];
+        if (!e)
+            continue;
+        if (e.type === 'session' && e.raw.name === 'created' && typeof e.raw.sessionId === 'string') {
+            return e.raw.sessionId;
+        }
+    }
+    return provided || 'unknown-session';
+}
+/**
+ * Format one event as a Markdown block. Returns `null` to suppress the
+ * event entirely (e.g. session.created is captured in front matter so we
+ * skip it here).
+ */
+function renderEvent(event) {
+    const ts = event.timestamp || '';
+    switch (event.type) {
+        case 'session': {
+            const name = String(event.raw.name ?? '');
+            if (name === 'created')
+                return null; // captured by front matter
+            if (name === 'command_started') {
+                const command = String(event.raw.command ?? '');
+                return {
+                    lines: [`## ${ts} — command \`${escapeInline(command)}\``],
+                    isTurn: false,
+                };
+            }
+            if (name === 'command_completed') {
+                const command = String(event.raw.command ?? '');
+                const status = String(event.raw.status ?? 'unknown');
+                return {
+                    lines: [`_command \`${escapeInline(command)}\` finished: ${status}_`],
+                    isTurn: false,
+                };
+            }
+            return {
+                lines: [`_session ${name}_`],
+                isTurn: false,
+            };
+        }
+        case 'tool_call': {
+            const tool = String(event.raw.tool ?? 'unknown');
+            const summary = String(event.raw.inputSummary ?? '');
+            const out = [`### ${ts} — tool \`${escapeInline(tool)}\``];
+            if (summary.length > 0) {
+                out.push('');
+                out.push('Input:');
+                out.push(fenced(summary));
+            }
+            return { lines: out, isTurn: true };
+        }
+        case 'tool_result': {
+            const status = String(event.raw.status ?? 'unknown');
+            const summary = String(event.raw.outputSummary ?? '');
+            const out = [`Result (${status}):`];
+            if (summary.length > 0) {
+                out.push(fenced(summary));
+            }
+            return { lines: out, isTurn: false };
+        }
+        case 'file_mutation': {
+            const path = String(event.raw.path ?? '');
+            const op = String(event.raw.operation ?? '');
+            return {
+                lines: [`- file ${op}: \`${escapeInline(path)}\``],
+                isTurn: false,
+            };
+        }
+        case 'subagent.spawned':
+        case 'subagent.tool_call':
+        case 'subagent.completed':
+        case 'subagent.blocked':
+        case 'subagent.failed': {
+            const role = String(event.raw.role ?? '');
+            const persona = String(event.raw.personaSlug ?? '');
+            const detail = String(event.raw.detail ?? event.raw.error ?? event.raw.toolName ?? '');
+            const tail = detail.length > 0 ? ` ${detail}` : '';
+            return {
+                lines: [`_[subagent ${role} / ${persona}] ${event.type}${tail}_`],
+                isTurn: false,
+            };
+        }
+        case 'hook.invoked':
+        case 'hook.result':
+        case 'hook.skipped': {
+            const ev = String(event.raw.event ?? '');
+            const reason = String(event.raw.reason ?? event.raw.runSummary ?? event.raw.matchSummary ?? '');
+            const tail = reason.length > 0 ? ` ${reason}` : '';
+            return {
+                lines: [`_[hook ${ev}] ${event.type.replace('hook.', '')}${tail}_`],
+                isTurn: false,
+            };
+        }
+        case 'compaction.started':
+        case 'compaction.completed':
+        case 'compaction.skipped':
+        case 'compaction.invariant_violated': {
+            const tier = String(event.raw.tier ?? '');
+            return {
+                lines: [`_[compaction ${tier}] ${event.type.replace('compaction.', '')}_`],
+                isTurn: false,
+            };
+        }
+        default: {
+            return {
+                lines: [`_[event type=${event.type}]_`],
+                isTurn: false,
+            };
+        }
+    }
+}
+/**
+ * Wrap a string in a fenced code block. Pick a fence length that does
+ * not collide with backtick runs inside the content. Markdown 0.30 allows
+ * variable-length fences; we pick the shortest that is longer than the
+ * longest run inside the content (min 3, max 7).
+ */
+function fenced(content) {
+    const longestRun = (content.match(/`+/g) ?? [])
+        .map((s) => s.length)
+        .reduce((max, n) => (n > max ? n : max), 0);
+    const fenceLen = Math.min(7, Math.max(3, longestRun + 1));
+    const fence = '`'.repeat(fenceLen);
+    // Trim trailing whitespace inside content so the closing fence sits
+    // tight against the body; preserve leading whitespace (matters for code).
+    return `${fence}\n${content.replace(/\s+$/u, '')}\n${fence}`;
+}
+/**
+ * Escape inline-Markdown specials (backtick, pipe) inside a span that we
+ * are wrapping in inline code. The closing backtick rule says a `<code>`
+ * span can contain backticks as long as the fence length differs — for
+ * simplicity we replace bare backticks with a Unicode look-alike when
+ * they appear in identifier-like positions (e.g. paths or tool names).
+ * Backticks in real content go through `fenced()` instead.
+ */
+function escapeInline(text) {
+    return text.replace(/`/g, 'ˋ');
+}
+//# sourceMappingURL=formatter.js.map

package/dist/core/share/redactor.js

@@ -0,0 +1,221 @@
+/**
+ * PII redactor used by `pugi share --redact` ().
+ *
+ * Zero-dependency regex-based redaction over a Markdown transcript. We
+ * intentionally do NOT pull in `apps/admin-api/src/privacy/regex-scrubber.ts`
+ * because the CLI is a stand-alone npm package: customers install
+ * `@pugi/cli` globally, no admin-api binary is present. The pattern set
+ * here mirrors the high-signal subset of the admin-api `RegexScrubber`
+ * catalog (apps/admin-api/src/privacy/regex-scrubber.ts) so audit downstream
+ * sees the same `[REDACTED:<CATEGORY>:<HASH8>]` token shape regardless of
+ * which side scrubs.
+ *
+ * Coverage (high-signal, low-false-positive):
+ *
+ *  EMAIL             user@example.com (RFC-5322 simplified)
+ *  PHONE             +1-555-123-4567 / (555) 123-4567 / 555 123 4567
+ *  IPV4              1.2.3.4 with octet bounds check
+ *  API_KEY_OPENAI    sk-..., sk-proj-..., sk-svcacct-...
+ *  API_KEY_ANTHROPIC sk-ant-...
+ *  API_KEY_GOOGLE    AIza...
+ *  API_KEY_GITHUB    ghp_/gho_/ghu_/ghs_/ghr_..., github_pat_...
+ *  API_KEY_PUGI      pugi_live_..., pugi_sk_..., anvil_*_...
+ *  API_KEY_AWS       AKIA... / ASIA...
+ *  BEARER_TOKEN      "Bearer <token>" auth headers (also used by the
+ *                     credential heuristic to refuse upload)
+ *  JWT               eyJ...header.eyJ...payload.signature
+ *  STRIPE_ID         sk_live_..., pk_live_..., whsec_...
+ *
+ * Out of scope (matches the admin-api RegexScrubber posture):
+ *
+ *  - PERSON / ORG / GPE named entities (L2 NER, no CLI dep)
+ *  - Free-form addresses
+ *  - Date-of-birth in prose
+ *
+ * Token shape `[REDACTED:<CATEGORY>:<HASH8>]` matches the admin-api L1
+ * convention (SHA-256 first 8 chars of the original match). The hash is
+ * stable across runs so an operator who re-runs `--redact` on the same
+ * transcript sees identical tokens — useful for diffing two exports.
+ */
+import { createHash } from 'node:crypto';
+function hash8(text) {
+    return createHash('sha256').update(text, 'utf8').digest('hex').slice(0, 8);
+}
+function token(category, original) {
+    return `[REDACTED:${category}:${hash8(original)}]`;
+}
+/**
+ * IPv4 octet bounds. The catch-all `\d{1,3}\.\d{1,3}\.\d{1,3}\.\d{1,3}`
+ * matches `999.999.999.999` and version strings like `4.5.6.7`. We reject
+ * any match where an octet exceeds 255. Loopback / placeholder addresses
+ * (`0.0.0.0`) are also rejected so config-doc snippets do not get redacted
+ * into noise.
+ */
+function ipv4Valid(match) {
+    const parts = match.split('.');
+    if (parts.length !== 4)
+        return false;
+    for (const p of parts) {
+        const n = Number.parseInt(p, 10);
+        if (Number.isNaN(n) || n < 0 || n > 255)
+            return false;
+    }
+    if (match === '0.0.0.0')
+        return false;
+    return true;
+}
+/**
+ * Catalog. Order matters: prefixed API-key rules first so the broader
+ * `sk-` pattern does not shadow `sk-ant-` / `sk-proj-`. JWT before
+ * BEARER_TOKEN so a `Bearer eyJ...` header redacts the JWT specifically
+ * rather than the generic bearer prefix.
+ */
+const RULES = [
+    // Stripe IDs (livemode + testmode). Catches the secret-key form too;
+    // operators paste these into chats more often than they should.
+    {
+        category: 'STRIPE_ID',
+        pattern: /\b(?:cus|sub|pi|ch|acct|seti|prod|price|in|re|whsec|sk_live|sk_test|pk_live|pk_test)_[A-Za-z0-9]{14,}\b/g,
+    },
+    // Pugi / Anvil API keys.
+    {
+        category: 'API_KEY_PUGI',
+        pattern: /\b(?:pugi|anvil)_(?:live|test|sk)_[A-Za-z0-9_-]{20,}\b/g,
+    },
+    // Anthropic API keys.
+    {
+        category: 'API_KEY_ANTHROPIC',
+        pattern: /\bsk-ant-[A-Za-z0-9_-]{20,}\b/g,
+    },
+    // OpenAI API keys (classic sk-, project-scoped sk-proj-, service-acct
+    // sk-svcacct-).
+    {
+        category: 'API_KEY_OPENAI',
+        pattern: /\bsk-(?:proj-|svcacct-)?[A-Za-z0-9_-]{32,}\b/g,
+    },
+    // Google API keys (Maps, Gemini, Cloud).
+    {
+        category: 'API_KEY_GOOGLE',
+        pattern: /\bAIza[A-Za-z0-9_-]{35}\b/g,
+    },
+    // GitHub PATs (classic + fine-grained).
+    {
+        category: 'API_KEY_GITHUB',
+        pattern: /\b(?:ghp_|gho_|ghu_|ghs_|ghr_)[A-Za-z0-9]{36}\b|\bgithub_pat_[A-Za-z0-9_]{82}\b/g,
+    },
+    // AWS access keys.
+    {
+        category: 'API_KEY_AWS',
+        pattern: /\b(?:AKIA|ASIA)[A-Z0-9]{16}\b/g,
+    },
+    // JWT (3-segment dot-delimited base64url).
+    {
+        category: 'JWT',
+        pattern: /\beyJ[A-Za-z0-9_-]{10,}\.eyJ[A-Za-z0-9_-]{10,}\.[A-Za-z0-9_-]{10,}\b/g,
+    },
+    // Bearer token. The credential heuristic in `containsActiveCredential`
+    // ALSO fires on this prefix to refuse the upload entirely.
+    {
+        category: 'BEARER_TOKEN',
+        pattern: /Bearer\s+[A-Za-z0-9._~+/=-]{16,}/g,
+    },
+    // Email.
+    {
+        category: 'EMAIL',
+        pattern: /\b[A-Za-z0-9._%+-]+@[A-Za-z0-9.-]+\.[A-Za-z]{2,}\b/g,
+    },
+    // E.164 + permissive US/EU phone. International prefix optional;
+    // separators allowed (-, space, parens).
+    {
+        category: 'PHONE',
+        pattern: /(?<![A-Za-z0-9.])(?:\+?\d{1,3}[\s-])?(?:\(\d{1,4}\)\s?)?\d{2,4}[\s-]\d{2,4}(?:[\s-]\d{2,9})?(?![A-Za-z0-9.])/g,
+        validate: (m) => {
+            const digits = m.replace(/\D+/g, '');
+            return digits.length >= 7 && digits.length <= 15;
+        },
+    },
+    // IPv4 with bounds check. Order: AFTER all alphanumeric-prefixed rules
+    // so a version string like `4.5.6.7` inside a longer SHA-key match
+    // never reaches us here.
+    {
+        category: 'IPV4',
+        pattern: /\b\d{1,3}\.\d{1,3}\.\d{1,3}\.\d{1,3}\b/g,
+        validate: ipv4Valid,
+    },
+];
+/**
+ * Redact PII from a Markdown transcript. The output substitutes high-
+ * signal patterns with `[REDACTED:<CATEGORY>:<HASH8>]` tokens. Findings
+ * are aggregated by category so the privacy gate can surface a
+ * compact "Redacted 3 PII spans (2 EMAIL, 1 API_KEY_OPENAI)" line.
+ *
+ * Idempotency: re-running over an already-redacted transcript will not
+ * double-redact because the token form `[REDACTED:...]` matches none of
+ * the patterns. This makes `--redact --preview` followed by `--redact`
+ * safe — operator can inspect first, then commit to the upload, and the
+ * second redact pass is a no-op.
+ */
+export function redactPii(input) {
+    if (input.length === 0) {
+        return { output: '', findings: [], totalSpans: 0 };
+    }
+    let output = input;
+    const counts = new Map();
+    for (const rule of RULES) {
+        output = output.replace(rule.pattern, (match) => {
+            if (rule.validate && !rule.validate(match))
+                return match;
+            counts.set(rule.category, (counts.get(rule.category) ?? 0) + 1);
+            return token(rule.category, match);
+        });
+    }
+    const findings = [];
+    for (const [category, count] of counts.entries()) {
+        findings.push({ category, count });
+    }
+    // Stable order so the gate banner is deterministic across runs.
+    findings.sort((a, b) => b.count !== a.count ? b.count - a.count : a.category.localeCompare(b.category));
+    const totalSpans = findings.reduce((acc, f) => acc + f.count, 0);
+    return { output, findings, totalSpans };
+}
+/**
+ * Heuristic: does the transcript carry an active credential token that
+ * MUST refuse upload regardless of `--redact`? Surfaces as a hard gate
+ * before any upload path even with redaction enabled — the operator's
+ * intent to share a credential is itself a footgun (the credential
+ * leaves their machine before the redactor runs). The privacy gate calls
+ * this BEFORE running `redactPii`.
+ *
+ * The check is intentionally narrower than the redactor catalog: we only
+ * refuse on `Bearer ` prefix (the most common live-auth-header form) so
+ * we do not block a legitimate share that contains an old expired API
+ * key referenced in a code comment. Operators can disable the heuristic
+ * with `--allow-credentials` (NOT in scope for L20 — the refusal is
+ * absolute today).
+ */
+export function containsActiveCredential(input) {
+    if (input.length === 0)
+        return false;
+    return /Bearer\s+[A-Za-z0-9._~+/=-]{16,}/.test(input);
+}
+/**
+ * Format the findings array as a short human-readable summary used in
+ * the privacy gate banner. Example output:
+ *
+ *  "Redacted 3 PII spans (2 EMAIL, 1 API_KEY_OPENAI)"
+ *
+ * Falls back to "Redacted 0 PII spans" when nothing matched — surfaces
+ * a clean gate so the operator knows the redact pass did run.
+ */
+export function summariseFindings(result) {
+    if (result.totalSpans === 0) {
+        return 'Redacted 0 PII spans (transcript appears clean).';
+    }
+    const top = result.findings
+        .slice(0, 4)
+        .map((f) => `${f.count} ${f.category}`)
+        .join(', ');
+    const tail = result.findings.length > 4 ? `, ${result.findings.length - 4} more` : '';
+    return `Redacted ${result.totalSpans} PII spans (${top}${tail}).`;
+}
+//# sourceMappingURL=redactor.js.map