@pugi/cli 0.1.0-beta.8 → 0.1.0-beta.87

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

package/dist/core/share/uploader.js

@@ -0,0 +1,267 @@
+/**
+ * Upload paths for `pugi share` ().
+ *
+ * Two targets:
+ *
+ *  - `gist` shells out to `gh gist create` (requires the `gh` CLI in
+ *            PATH AND `gh auth status` ok, OR `GITHUB_TOKEN` env). The
+ *            gist is created with a fixed filename so the URL paths
+ *            stay stable across re-shares.
+ *  - `pugi` POSTs to admin-api `/api/pugi/share`. The endpoint is NOT
+ *            present in admin-api today (2026-05-27 audit) — the
+ *            handler degrades gracefully: it surfaces a clear "endpoint
+ *            not yet wired" message and tells the operator to use
+ *            `--gist` for now. The structured payload is otherwise
+ *            ready for the server-side handler to consume; landing the
+ *            endpoint is a separate sprint.
+ *
+ * The two paths share one decision shape (`UploadResult`) so the
+ * command handler renders identical telemetry regardless of which target
+ * was chosen.
+ *
+ * Why we shell out for gist instead of using octokit: octokit would add
+ * a transitive HTTP client + ~200 KB to the npm package surface for a
+ * single feature. `gh gist create` is the operator-friendly form
+ * (already auth'd, public URL on stdout, attribution in the gist
+ * metadata) and degrades cleanly when `gh` is absent.
+ */
+import { spawn } from 'node:child_process';
+/**
+ * Default execa shim. Spawns the binary with `args`, pipes `input` into
+ * stdin if provided, captures stdout + stderr in memory. The CLI ships
+ * with `execa` already pulled for other paths; we use the lighter
+ * `child_process.spawn` here so the share module stays import-clean.
+ */
+export const defaultExecaLike = (file, args, options) => {
+    return new Promise((resolveProm, rejectProm) => {
+        const child = spawn(file, [...args], { stdio: ['pipe', 'pipe', 'pipe'] });
+        let stdout = '';
+        let stderr = '';
+        child.stdout.on('data', (chunk) => {
+            stdout += chunk.toString('utf8');
+        });
+        child.stderr.on('data', (chunk) => {
+            stderr += chunk.toString('utf8');
+        });
+        child.on('error', (err) => {
+            // ENOENT (binary missing) lands here; the caller maps it.
+            rejectProm(err);
+        });
+        child.on('close', (code) => {
+            resolveProm({ exitCode: code ?? 0, stdout, stderr });
+        });
+        if (options?.input) {
+            child.stdin.write(options.input);
+        }
+        child.stdin.end();
+    });
+};
+/**
+ * Top-level upload dispatch. The handler picks the right path and
+ * surfaces a uniform result envelope.
+ */
+export async function uploadShare(req) {
+    if (req.target === 'gist') {
+        return uploadGist(req);
+    }
+    return uploadPugi(req);
+}
+/**
+ * Gist upload. Two-step: probe `gh --version` (fast, costs nothing) to
+ * detect a missing binary cleanly, then run `gh gist create`. We pipe
+ * the markdown into stdin to avoid temp files + the OS-level argv
+ * length cap.
+ */
+async function uploadGist(req) {
+    const exec = req.execaLike ?? defaultExecaLike;
+    const description = req.description ?? `Pugi session ${req.sessionId}`;
+    try {
+        // Probe step. `gh --version` returns 0 quickly and surfaces a
+        // distinctive "command not found" via ENOENT on the reject path.
+        const probe = await exec('gh', ['--version']);
+        if (probe.exitCode !== 0) {
+            return {
+                ok: false,
+                target: 'gist',
+                reason: 'gh_not_installed',
+                message: 'gh CLI not available. Install from https://cli.github.com or use --pugi instead.',
+            };
+        }
+    }
+    catch {
+        return {
+            ok: false,
+            target: 'gist',
+            reason: 'gh_not_installed',
+            message: 'gh CLI not available. Install from https://cli.github.com or use --pugi instead.',
+        };
+    }
+    // Create the gist. `gh` reads stdin when `-` is the filename arg, which
+    // works with our `--filename` override. The `--public` flag is
+    // intentionally omitted — gists default to secret (unlisted URL), which
+    // is the right default for a session transcript. Operators who want a
+    // public gist can run `gh gist edit --add-public <id>` after the fact.
+    const createArgs = [
+        'gist',
+        'create',
+        '--filename',
+        'pugi-session.md',
+        '--desc',
+        description,
+        '-',
+    ];
+    try {
+        const result = await exec('gh', createArgs, { input: req.markdown });
+        if (result.exitCode !== 0) {
+            // Auth failure is the common case. `gh` prints "gh auth login" to
+            // stderr; we tag it specifically so the gate banner can hint.
+            const looksLikeAuth = /auth/i.test(result.stderr) || /authenticated/i.test(result.stderr);
+            return {
+                ok: false,
+                target: 'gist',
+                reason: looksLikeAuth ? 'gh_unauthenticated' : 'gh_failed',
+                message: looksLikeAuth
+                    ? 'gh is installed but not authenticated. Run `gh auth login` first.'
+                    : `gh gist create exited ${result.exitCode}: ${result.stderr.trim().slice(0, 200)}`,
+            };
+        }
+        // gh prints the URL on stdout. Trim newline + any leading whitespace.
+        const url = result.stdout.trim().split('\n').pop() ?? '';
+        if (!/^https?:\/\//.test(url)) {
+            return {
+                ok: false,
+                target: 'gist',
+                reason: 'gh_failed',
+                message: `gh did not return a URL (stdout: "${result.stdout.trim().slice(0, 200)}")`,
+            };
+        }
+        const remoteId = url.split('/').pop() ?? undefined;
+        return remoteId !== undefined
+            ? { ok: true, target: 'gist', url, remoteId }
+            : { ok: true, target: 'gist', url };
+    }
+    catch (err) {
+        const message = err instanceof Error ? err.message : String(err);
+        return {
+            ok: false,
+            target: 'gist',
+            reason: 'gh_failed',
+            message: `gh gist create threw: ${message}`,
+        };
+    }
+}
+/**
+ * Pugi.io upload. POSTs the transcript to admin-api `/api/pugi/share`.
+ * The endpoint is NOT yet wired (audit); when it returns 404
+ * we surface a friendly hint instead of a stack trace. When the operator
+ * is signed-out we surface `pugi_auth_missing` so the gate banner can
+ * point at `pugi login`.
+ *
+ * The wire payload is intentionally minimal so a future server-side
+ * implementation has a stable contract to build against:
+ *
+ *  { sessionId, markdown, description?, cliVersion? }
+ *
+ * Response (when wired):
+ *
+ *  200 { ok: true, url, id }    URL is the pugi.io/share/<id> public link.
+ *  404 / 501                    endpoint not yet implemented — graceful skip.
+ *  401                          auth missing/expired — operator runs `pugi login`.
+ */
+async function uploadPugi(req) {
+    const fetchFn = req.fetchLike ?? globalThis.fetch;
+    if (typeof fetchFn !== 'function') {
+        return {
+            ok: false,
+            target: 'pugi',
+            reason: 'pugi_network_error',
+            message: 'No fetch implementation available (Node >=18 expected).',
+        };
+    }
+    if (!req.apiUrl) {
+        return {
+            ok: false,
+            target: 'pugi',
+            reason: 'pugi_auth_missing',
+            message: 'pugi.io share requires a signed-in session. Run `pugi login` and retry.',
+        };
+    }
+    const url = `${req.apiUrl.replace(/\/+$/u, '')}/api/pugi/share`;
+    const headers = {
+        'content-type': 'application/json',
+        accept: 'application/json',
+    };
+    if (req.apiToken) {
+        headers.authorization = `Bearer ${req.apiToken}`;
+    }
+    const body = JSON.stringify({
+        sessionId: req.sessionId,
+        markdown: req.markdown,
+        description: req.description ?? `Pugi session ${req.sessionId}`,
+    });
+    let res;
+    try {
+        res = await fetchFn(url, { method: 'POST', headers, body });
+    }
+    catch (err) {
+        const message = err instanceof Error ? err.message : String(err);
+        return {
+            ok: false,
+            target: 'pugi',
+            reason: 'pugi_network_error',
+            message: `pugi.io upload failed: ${message}`,
+        };
+    }
+    // 404 / 501 → endpoint not yet wired. Surface a friendly hint instead
+    // of dumping the response body.
+    if (res.status === 404 || res.status === 501) {
+        return {
+            ok: false,
+            target: 'pugi',
+            reason: 'pugi_endpoint_unimplemented',
+            message: 'pugi.io /api/pugi/share is not yet wired in admin-api. ' +
+                'Use `--gist` for now; the pugi.io upload lands in a follow-up sprint.',
+        };
+    }
+    if (res.status === 401 || res.status === 403) {
+        return {
+            ok: false,
+            target: 'pugi',
+            reason: 'pugi_auth_missing',
+            message: 'pugi.io rejected the credentials. Run `pugi login` and retry.',
+        };
+    }
+    if (!res.ok) {
+        return {
+            ok: false,
+            target: 'pugi',
+            reason: 'pugi_network_error',
+            message: `pugi.io upload returned ${res.status} ${res.statusText}.`,
+        };
+    }
+    let payload;
+    try {
+        payload = (await res.json());
+    }
+    catch (err) {
+        const message = err instanceof Error ? err.message : String(err);
+        return {
+            ok: false,
+            target: 'pugi',
+            reason: 'pugi_network_error',
+            message: `pugi.io upload returned non-JSON: ${message}`,
+        };
+    }
+    if (!payload.ok || !payload.url) {
+        return {
+            ok: false,
+            target: 'pugi',
+            reason: 'pugi_network_error',
+            message: 'pugi.io upload succeeded but the response was missing { ok, url }.',
+        };
+    }
+    return payload.id !== undefined
+        ? { ok: true, target: 'pugi', url: payload.url, remoteId: payload.id }
+        : { ok: true, target: 'pugi', url: payload.url };
+}
+//# sourceMappingURL=uploader.js.map