@pugi/cli 0.1.0-alpha.10 → 0.1.0-alpha.15

package/dist/core/repl/ask.js

@@ -0,0 +1,512 @@
+/**
+ * Office-hours forcing questions + plan-review tag parser - Sprint α6.3.
+ *
+ * Pugi's persona prompt teaches Mira to emit two structured XML envelopes
+ * when she would otherwise have to guess. Operator chat then pauses on a
+ * modal until the operator answers, eliminating the "fabricate a default
+ * silently" failure mode that Codex CLI, Claude Code, and Gemini CLI all
+ * trip on with low-confidence intents.
+ *
+ *   <pugi-ask>
+ *     <question>Which deployment target?</question>
+ *     <option value="vercel"    label="Vercel"          desc="Static + edge"/>
+ *     <option value="cloudflare" label="Cloudflare Pages" desc="Edge runtime"/>
+ *   </pugi-ask>
+ *
+ *   <pugi-plan-review>
+ *     <step>1. Edit src/foo.ts: add new export</step>
+ *     <step>2. Write tests/foo.spec.ts: 8 test cases</step>
+ *     <risk>Touches public API surface.</risk>
+ *   </pugi-plan-review>
+ *
+ * This module is a pure, framework-free parser. The session module imports
+ * `extractAskTags()` / `extractPlanReviewTags()` and routes the typed
+ * records to the Ink modal layer; the REPL UI never sees raw XML.
+ *
+ * # Why a hand-rolled parser
+ *
+ * Generic XML libraries (sax, fast-xml-parser, xmldoc) carry a large
+ * attack surface (external entity expansion, recursive blowup on
+ * malformed input, sloppy attribute handling) and require ~50 KB of
+ * runtime dependency. The persona-side grammar here is two tag families
+ * with a closed attribute set, so a bounded tokenizer is both safer and
+ * smaller. Defence-in-depth choices:
+ *
+ *   - Reject raw `&` outside `&amp;` / `&lt;` / `&gt;` / `&quot;` /
+ *     `&apos;` (entities are decoded; everything else is malformed).
+ *   - Forbid nested ask-within-ask (would crash the modal stack).
+ *   - Cap option count at 4 (Claude Code AskUserQuestion baseline).
+ *   - Cap label / desc / question / step / risk at 80 chars (terminal
+ *     rendering budget, also discourages prompt injection via huge
+ *     payloads).
+ *   - Reject CDATA, comments, processing instructions, DOCTYPE — none
+ *     of those appear in the legal grammar.
+ *   - Reject any attribute that is not in the per-tag allowlist.
+ *
+ * # Buffering across streaming chunks
+ *
+ * The session calls `extractAskTags(buffer)` on the accumulated
+ * `agent.step.detail` body. If the close tag has not arrived yet, the
+ * parser returns `{ tags: [], remainder: buffer }` and the session waits
+ * for more chunks. Once `</pugi-ask>` lands, the parser slices the tag
+ * out, returns the structured record, and the session continues with the
+ * post-tag remainder. The same shape applies to `<pugi-plan-review>`.
+ */
+/* ------------------------------------------------------------------ */
+/* Bounded constants                                                  */
+/* ------------------------------------------------------------------ */
+/** Hard cap on options per `<pugi-ask>`. Claude Code AskUserQuestion uses 4. */
+export const ASK_MAX_OPTIONS = 4;
+/** Hard cap on question / label / desc length. Terminal-row budget. */
+export const ASK_MAX_TEXT_LEN = 80;
+/** Hard cap on steps per `<pugi-plan-review>`. */
+export const PLAN_REVIEW_MAX_STEPS = 12;
+/** Hard cap on step text length. */
+export const PLAN_REVIEW_MAX_STEP_LEN = 200;
+/** Hard cap on risk callout length. */
+export const PLAN_REVIEW_MAX_RISK_LEN = 240;
+/** Hard cap on the entire tag span. Long enough for 4 options + risk; defends against runaway payloads. */
+const TAG_MAX_SPAN_BYTES = 8 * 1024;
+/* ------------------------------------------------------------------ */
+/* Public extraction API                                              */
+/* ------------------------------------------------------------------ */
+/**
+ * Find every well-formed `<pugi-ask>` in `body`. Malformed tags are
+ * dropped and surfaced via `hadMalformedTag` so the session can log a
+ * warning. Streaming-incomplete tags (open observed, close not yet
+ * arrived) are kept in `cleaned` verbatim and reported via
+ * `pendingOpenTag`, so the session keeps buffering until the close tag
+ * lands or the turn ends.
+ */
+export function extractAskTags(body) {
+    return extractTags(body, {
+        openTag: '<pugi-ask>',
+        closeTag: '</pugi-ask>',
+        parseInner: parseAskInner,
+    });
+}
+/**
+ * Find every well-formed `<pugi-plan-review>` in `body`. Same contract
+ * as `extractAskTags` — malformed → drop + flag, streaming-incomplete →
+ * keep in `cleaned` + flag for buffering.
+ */
+export function extractPlanReviewTags(body) {
+    return extractTags(body, {
+        openTag: '<pugi-plan-review>',
+        closeTag: '</pugi-plan-review>',
+        parseInner: parsePlanReviewInner,
+    });
+}
+function extractTags(body, config) {
+    const tags = [];
+    const segments = [];
+    let cursor = 0;
+    let pendingOpenTag = false;
+    let hadMalformedTag = false;
+    // Hard cap on tags per buffer so a hostile (or accidental) `<pugi-ask>`
+    // flood does not pin the parser. 64 is generous — a real session
+    // never has more than 1-2 modals queued.
+    const MAX_TAGS_PER_BUFFER = 64;
+    // Guard counter to prevent a pathological input from looping forever.
+    // The body length bounds the iteration count strictly, but we add a
+    // belt-and-braces ceiling proportional to body size for clarity.
+    let safetyIterations = body.length + 16;
+    while (cursor < body.length && tags.length < MAX_TAGS_PER_BUFFER) {
+        if (safetyIterations-- <= 0)
+            break;
+        const openIndex = body.indexOf(config.openTag, cursor);
+        if (openIndex === -1) {
+            // No more tags. Flush the rest of the body as cleaned prose and exit.
+            segments.push(body.slice(cursor));
+            cursor = body.length;
+            break;
+        }
+        // Push everything before the opening tag as cleaned prose.
+        segments.push(body.slice(cursor, openIndex));
+        const closeIndex = body.indexOf(config.closeTag, openIndex + config.openTag.length);
+        if (closeIndex === -1) {
+            // Open seen, close not yet streamed in. WITHHOLD the partial
+            // span from `cleaned` so the raw `<pugi-ask>` envelope cannot
+            // leak into the operator-visible transcript if the stream pauses
+            // or completes mid-tag. The caller keeps the original buffer for
+            // the next chunk merge via pendingOpenTag; if the turn ends with
+            // the tag still open, the caller emits a system warning instead
+            // of surfacing the raw XML. Codex triple-review P2 (PR #375).
+            pendingOpenTag = true;
+            cursor = body.length;
+            break;
+        }
+        const tagEnd = closeIndex + config.closeTag.length;
+        const span = body.slice(openIndex, tagEnd);
+        if (span.length > TAG_MAX_SPAN_BYTES) {
+            hadMalformedTag = true;
+            cursor = tagEnd;
+            continue;
+        }
+        // Reject nested open tags inside the span before parsing — the
+        // generic "find next close" lookup would otherwise pair an outer
+        // open with an inner close, producing a corrupt tag.
+        const innerOpen = span.indexOf(config.openTag, config.openTag.length);
+        if (innerOpen !== -1) {
+            hadMalformedTag = true;
+            cursor = tagEnd;
+            continue;
+        }
+        const inner = body.slice(openIndex + config.openTag.length, closeIndex);
+        const parsed = config.parseInner(inner, { start: openIndex, end: tagEnd });
+        if (parsed === null) {
+            hadMalformedTag = true;
+            cursor = tagEnd;
+            continue;
+        }
+        tags.push(parsed);
+        cursor = tagEnd;
+    }
+    return {
+        tags,
+        cleaned: segments.join('').replace(/\s+\n/g, '\n').trimEnd(),
+        pendingOpenTag,
+        hadMalformedTag,
+    };
+}
+/* ------------------------------------------------------------------ */
+/* `<pugi-ask>` inner parser                                          */
+/* ------------------------------------------------------------------ */
+function parseAskInner(inner, span) {
+    // Reject CDATA, comments, processing instructions, DOCTYPE.
+    if (/<!--|<!\[|<\?|<!DOCTYPE/i.test(inner))
+        return null;
+    // Reject raw `&` not in a known entity. Decoded entities are allowed
+    // below in `decodeEntities`; anything outside the closed allowlist is
+    // malformed.
+    if (containsRawAmpersand(inner))
+        return null;
+    const question = extractSingleChildText(inner, 'question');
+    if (question === null)
+        return null;
+    if (question.length === 0 || question.length > ASK_MAX_TEXT_LEN)
+        return null;
+    const options = extractOptionTags(inner);
+    if (options === null)
+        return null;
+    if (options.length === 0 || options.length > ASK_MAX_OPTIONS)
+        return null;
+    // Reject duplicate option values — collapses to a single modal entry
+    // visually but corrupts the dedupe signature. Easier to refuse than
+    // to silently rewrite.
+    const seen = new Set();
+    for (const opt of options) {
+        if (seen.has(opt.value))
+            return null;
+        seen.add(opt.value);
+    }
+    const signature = signatureForAsk(question, options);
+    return { question, options, signature, start: span.start, end: span.end };
+}
+/**
+ * Pull the body of a single `<question>...</question>` child. Returns
+ * null when the tag is missing OR when more than one occurrence is
+ * found (the grammar mandates exactly one question per ask).
+ */
+function extractSingleChildText(inner, tagName) {
+    const open = `<${tagName}>`;
+    const close = `</${tagName}>`;
+    const first = inner.indexOf(open);
+    if (first === -1)
+        return null;
+    const end = inner.indexOf(close, first + open.length);
+    if (end === -1)
+        return null;
+    // Ensure no second occurrence.
+    if (inner.indexOf(open, end + close.length) !== -1)
+        return null;
+    const body = inner.slice(first + open.length, end);
+    // Reject nested tags inside the question body.
+    if (/<[^>]/.test(body))
+        return null;
+    return stripControlChars(decodeEntities(body)).trim();
+}
+/**
+ * Pull every self-closing `<option ... />` element from the inner body.
+ * Returns null on any malformed option; the caller drops the whole tag
+ * rather than partially accept a corrupt option list.
+ */
+function extractOptionTags(inner) {
+    const options = [];
+    // Match `<option ... />` (self-closing) OR `<option ...></option>`
+    // (paired form). The persona prompt teaches the self-closing form
+    // for compactness, but a model that emits the paired form should not
+    // be punished.
+    const re = /<option\b([^>]*?)(\/>|><\/option>)/g;
+    let match;
+    while ((match = re.exec(inner)) !== null) {
+        const attrBlob = match[1] ?? '';
+        const parsed = parseOptionAttrs(attrBlob);
+        if (parsed === null)
+            return null;
+        options.push(parsed);
+    }
+    // Bail if the inner has any `<option` that the regex did NOT match —
+    // means an option element was malformed (e.g. unclosed, attribute
+    // missing closing quote).
+    const stray = inner.match(/<option\b/g);
+    if (stray && stray.length !== options.length)
+        return null;
+    return options;
+}
+function parseOptionAttrs(attrBlob) {
+    // Allowed attributes: value, label, desc. Reject any other.
+    const attrs = parseAttrBlob(attrBlob);
+    if (attrs === null)
+        return null;
+    for (const key of Object.keys(attrs)) {
+        if (key !== 'value' && key !== 'label' && key !== 'desc')
+            return null;
+    }
+    const value = attrs['value'];
+    const label = attrs['label'];
+    if (typeof value !== 'string' || value.length === 0)
+        return null;
+    if (typeof label !== 'string' || label.length === 0)
+        return null;
+    if (value.length > ASK_MAX_TEXT_LEN || label.length > ASK_MAX_TEXT_LEN)
+        return null;
+    // Forbid quote / angle-bracket characters in value — those would
+    // break the operator-side echo "[ASK-RESPONSE:<value>]".
+    if (/[<>"'\\]/.test(value))
+        return null;
+    const desc = attrs['desc'];
+    if (desc !== undefined) {
+        if (typeof desc !== 'string')
+            return null;
+        if (desc.length > ASK_MAX_TEXT_LEN)
+            return null;
+    }
+    const opt = { value, label };
+    if (desc !== undefined && desc.length > 0)
+        opt.desc = desc;
+    return opt;
+}
+/**
+ * Parse `key="value"` / `key='value'` pairs out of an attribute blob.
+ * Returns null on any malformed attribute (unterminated quote, raw
+ * entity outside the allowlist, etc).
+ */
+function parseAttrBlob(blob) {
+    const trimmed = blob.trim();
+    if (trimmed.length === 0)
+        return {};
+    const result = {};
+    // Bound the iteration count: every step must consume at least one
+    // attribute and one separator, so the loop terminates in O(blob length).
+    let cursor = 0;
+    const maxIterations = trimmed.length + 4;
+    let iterations = 0;
+    while (cursor < trimmed.length && iterations++ < maxIterations) {
+        // Skip whitespace.
+        while (cursor < trimmed.length && /\s/.test(trimmed[cursor] ?? ''))
+            cursor += 1;
+        if (cursor >= trimmed.length)
+            break;
+        // Parse attribute name (lowercase letters only — keeps the grammar tight).
+        const nameStart = cursor;
+        while (cursor < trimmed.length && /[a-z]/.test(trimmed[cursor] ?? ''))
+            cursor += 1;
+        if (cursor === nameStart)
+            return null;
+        const name = trimmed.slice(nameStart, cursor);
+        // Expect `=`.
+        if (trimmed[cursor] !== '=')
+            return null;
+        cursor += 1;
+        // Expect a quote (single or double).
+        const quote = trimmed[cursor];
+        if (quote !== '"' && quote !== "'")
+            return null;
+        cursor += 1;
+        const valueStart = cursor;
+        const valueEnd = trimmed.indexOf(quote, valueStart);
+        if (valueEnd === -1)
+            return null;
+        const rawValue = trimmed.slice(valueStart, valueEnd);
+        if (containsRawAmpersand(rawValue))
+            return null;
+        if (/[<>]/.test(rawValue))
+            return null;
+        result[name] = stripControlChars(decodeEntities(rawValue));
+        cursor = valueEnd + 1;
+    }
+    return result;
+}
+/* ------------------------------------------------------------------ */
+/* `<pugi-plan-review>` inner parser                                  */
+/* ------------------------------------------------------------------ */
+function parsePlanReviewInner(inner, span) {
+    if (/<!--|<!\[|<\?|<!DOCTYPE/i.test(inner))
+        return null;
+    if (containsRawAmpersand(inner))
+        return null;
+    const steps = extractStepTags(inner);
+    if (steps === null)
+        return null;
+    if (steps.length === 0 || steps.length > PLAN_REVIEW_MAX_STEPS)
+        return null;
+    // Risk is optional and at most one occurrence.
+    const risk = extractOptionalChildText(inner, 'risk', PLAN_REVIEW_MAX_RISK_LEN);
+    if (risk === undefined)
+        return null;
+    const sig = signatureForPlanReview(steps, risk);
+    const tag = {
+        steps,
+        signature: sig,
+        start: span.start,
+        end: span.end,
+    };
+    if (risk !== null && risk.length > 0) {
+        tag.risk = risk;
+    }
+    return tag;
+}
+function extractStepTags(inner) {
+    const re = /<step>([\s\S]*?)<\/step>/g;
+    const steps = [];
+    let match;
+    while ((match = re.exec(inner)) !== null) {
+        const raw = match[1] ?? '';
+        if (/<[^>]/.test(raw))
+            return null;
+        const text = stripControlChars(decodeEntities(raw)).trim();
+        if (text.length === 0 || text.length > PLAN_REVIEW_MAX_STEP_LEN)
+            return null;
+        steps.push({ text });
+    }
+    // Detect unbalanced `<step>` occurrences (open with no close, etc).
+    const opens = (inner.match(/<step>/g) ?? []).length;
+    const closes = (inner.match(/<\/step>/g) ?? []).length;
+    if (opens !== steps.length || closes !== steps.length)
+        return null;
+    return steps;
+}
+/**
+ * Optional single-child text. Returns:
+ *   - `null` when the tag is absent (legal absence)
+ *   - the trimmed body when exactly one occurrence is present
+ *   - `undefined` to signal a malformed (rejected) state to the caller
+ */
+function extractOptionalChildText(inner, tagName, maxLen) {
+    const open = `<${tagName}>`;
+    const close = `</${tagName}>`;
+    const first = inner.indexOf(open);
+    if (first === -1)
+        return null;
+    const end = inner.indexOf(close, first + open.length);
+    if (end === -1)
+        return undefined;
+    if (inner.indexOf(open, end + close.length) !== -1)
+        return undefined;
+    const body = inner.slice(first + open.length, end);
+    if (/<[^>]/.test(body))
+        return undefined;
+    const decoded = stripControlChars(decodeEntities(body)).trim();
+    if (decoded.length > maxLen)
+        return undefined;
+    return decoded;
+}
+/* ------------------------------------------------------------------ */
+/* Entity decoding + amp safety                                       */
+/* ------------------------------------------------------------------ */
+const ENTITY_MAP = Object.freeze({
+    amp: '&',
+    lt: '<',
+    gt: '>',
+    quot: '"',
+    apos: "'",
+});
+function decodeEntities(input) {
+    return input.replace(/&([a-z]+);/g, (whole, name) => {
+        const decoded = ENTITY_MAP[name];
+        return decoded === undefined ? whole : decoded;
+    });
+}
+/**
+ * Strip C0 control characters (except \t \n \r), DEL, and C1 control
+ * characters from decoded text. The persona's grammar is plain ASCII
+ * prose; raw control codes are either accidental noise or a deliberate
+ * ANSI-escape injection attempt that would corrupt the Ink render.
+ *
+ * Applied AFTER decodeEntities so an `&` escape cannot smuggle an ESC
+ * byte through the entity layer.
+ *
+ * Claude triple-review P2 (PR #375).
+ */
+function stripControlChars(input) {
+    // eslint-disable-next-line no-control-regex -- deliberately matching control range
+    return input.replace(/[\x00-\x08\x0b\x0c\x0e-\x1f\x7f\x80-\x9f]/g, '');
+}
+/**
+ * Reject any `&` that is not the head of a recognised entity. This is
+ * the defence-in-depth check from the module header: a raw `&` is
+ * legal in HTML but malformed in XML, and the persona is taught to
+ * always escape via `&amp;`. Anything outside the allowlist is a sign
+ * of either accidental sloppy output or an attempted injection.
+ */
+function containsRawAmpersand(input) {
+    // Scan once; a recognised entity is `&` + name + `;`. Any `&` that is
+    // not followed by an allowed name + `;` is malformed.
+    for (let i = 0; i < input.length; i += 1) {
+        if (input[i] !== '&')
+            continue;
+        const semi = input.indexOf(';', i + 1);
+        if (semi === -1)
+            return true;
+        const name = input.slice(i + 1, semi);
+        if (!Object.prototype.hasOwnProperty.call(ENTITY_MAP, name))
+            return true;
+        i = semi;
+    }
+    return false;
+}
+/* ------------------------------------------------------------------ */
+/* Signatures                                                         */
+/* ------------------------------------------------------------------ */
+/**
+ * Stable dedupe signature for an ask tag. The session keeps the most
+ * recent N signatures in a rolling set so a retry-spammed identical
+ * tag does not stack two modals.
+ *
+ * Algorithm: SHA-256-like collision-resistance is overkill for a
+ * single-process modal dedupe; a deterministic lower-case string is
+ * enough. We use the literal question + sorted-value join, then base64
+ * it for a compact identifier.
+ */
+/**
+ * Stable dedupe signature for an ask tag. Exported so synthesisers
+ * outside the parser (slash-command `/ask`, `pugi ask` shell command)
+ * can produce signatures that collision-match parser-produced
+ * signatures. Without a single source of truth, an `<pugi-ask>`
+ * emitted by the persona with the same question + same option values
+ * could share a signature with a local synthesiser even though the
+ * computation diverged - dedupe would suppress the persona modal.
+ *
+ * Claude triple-review P1 (PR #375).
+ */
+export function signatureForAsk(question, options) {
+    const values = options.map((o) => o.value).sort().join('|');
+    const raw = `${question.trim().toLowerCase()}::${values}`;
+    return Buffer.from(raw, 'utf8').toString('base64');
+}
+/**
+ * Stable dedupe signature for a plan-review tag. Exported for the
+ * same reason as signatureForAsk: synthesisers like
+ * `synthesiseLocalPlanReview` in cli.ts must produce identical
+ * signatures to parser-extracted tags for the same logical input.
+ *
+ * Codex triple-review P2 (PR #375).
+ */
+export function signatureForPlanReview(steps, risk) {
+    const stepsJoined = steps.map((s) => s.text.trim()).join('|');
+    const riskJoined = risk ?? '';
+    const raw = `${stepsJoined}::${riskJoined}`;
+    return Buffer.from(raw, 'utf8').toString('base64');
+}
+//# sourceMappingURL=ask.js.map

package/dist/core/repl/privacy-banner.js

@@ -0,0 +1,71 @@
+/**
+ * Privacy mode REPL surface — α6.13 (Phase 1).
+ *
+ * Two surfaces:
+ *
+ *   1. `renderPrivacyBanner(mode)` — one-line banner shown on REPL
+ *      bootstrap (mirrors `apps/admin-api/src/privacy/privacy-mode.ts`
+ *      `PRIVACY_MODE_BANNER` verbatim — keep in sync, the unit spec
+ *      asserts they match).
+ *
+ *   2. `renderPrivacyContractDoc(mode)` — multi-line contract doc the
+ *      `/privacy` slash command prints. Shows the active mode header
+ *      + the full 3-mode contract so the operator can compare their
+ *      current posture to the alternatives without leaving the REPL.
+ *
+ * The strings are pinned client-side so the contract doc is
+ * available even when the operator is offline / has not authenticated
+ * yet. The mode value itself is server-side authoritative (resolved
+ * via /api/admin/privacy/mode); the banner falls back to "(unknown)"
+ * when the round-trip fails.
+ *
+ * Brand voice: ASCII hyphens only, no em-dashes, no emoji decoration.
+ */
+export const PRIVACY_MODES = ['strict', 'balanced', 'permissive'];
+export function isPrivacyMode(value) {
+    return (typeof value === 'string' && PRIVACY_MODES.includes(value));
+}
+/**
+ * One-line banner. Mirrors `PRIVACY_MODE_BANNER` on the server.
+ */
+const BANNERS = Object.freeze({
+    strict: 'Privacy: strict (no upstream LLM, no external tool egress)',
+    balanced: 'Privacy: balanced (PII scrubbed before upstream LLM)',
+    permissive: 'Privacy: permissive (raw prompts forwarded upstream)',
+});
+export function renderPrivacyBanner(mode) {
+    if (!mode || !isPrivacyMode(mode)) {
+        return 'Privacy: (unknown - mode lookup pending)';
+    }
+    return BANNERS[mode];
+}
+/**
+ * Full mode contract doc. Printed by the `/privacy` slash command.
+ * Keep in sync with `PRIVACY_MODE_CONTRACT_DOC` on the server.
+ */
+const CONTRACT_DOC = `
+Pugi privacy mode contract (alpha 6.13):
+
+  strict      Maximum privacy. Nothing leaves tenant infra.
+              - Upstream LLM calls REFUSED (use self-hosted Ollama / llama.cpp).
+              - External tool calls require per-call confirm.
+              - Session.db, blobs, transcripts stay on operator disk.
+              - No telemetry. No error reporting.
+
+  balanced    Default. PII-scrubbed content goes to the upstream LLM.
+              - 3-layer PII scrubber runs before egress (regex + NER + LLM).
+              - Tool calls to external services allowed (logged).
+              - Anonymized telemetry only (counts + error categories).
+
+  permissive  Verbatim. Power-user mode.
+              - Raw prompts forwarded to upstream provider (no scrubbing).
+              - Tool calls to external services allowed.
+              - Full error reporting (may include prompt fragments).
+              - Accepts the upstream provider's data retention policy.
+
+Switch with: pugi config set privacy=strict|balanced|permissive
+`.trim();
+export function renderPrivacyContractDoc(currentMode) {
+    return `${renderPrivacyBanner(currentMode)}\n\n${CONTRACT_DOC}`;
+}
+//# sourceMappingURL=privacy-banner.js.map