@pugi/cli 0.1.0-beta.99 → 1.0.0-alpha.1

package/dist/core/repl/ask.js

@@ -1,512 +0,0 @@
-/**
- * Office-hours forcing questions + plan-review tag parser - Sprint .
- *
- * Pugi's persona prompt teaches Pugi 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 peer CLI, the upstream tool, 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 (the upstream tool 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>`. the upstream tool 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).
-            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).
- */
-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).
- */
-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).
- */
-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/cancellation.js

@@ -1,98 +0,0 @@
-/**
- * Cancellation token — Sprint Phase 1 (agent loop FSM + cancellation).
- *
- * A pure-JS one-shot signal that fans out to N listeners. One token is
- * minted per dispatch turn (fresh on each operator brief); when the
- * operator hits Ctrl+C, the REPL calls `abort()` which:
- *
- *  1. Latches `aborted = true` so any future `isAborted` check returns
- *     true (a tool that observes the flag mid-execution can short-circuit
- *     its loop without waiting for an explicit signal-handler callback).
- *  2. Drains the listener set, firing each callback exactly once. The
- *     set is cleared after the drain so a late `onAbort` listener
- *     attached AFTER abort does NOT fire — that is the documented
- *     contract; late listeners are expected to check `isAborted`
- *     explicitly at registration time if they need to know whether the
- *     token already tripped.
- *
- * Design choices:
- *
- *  - No coupling to `AbortController` / `AbortSignal`. The session +
- *    tool path are wrapped around this token; where a Web platform
- *    primitive is needed (fetch signal, MCP call), the wrapper bridges
- *    `onAbort` → `controller.abort()` at the seam.
- *  - Idempotent `abort()`. Calling twice is safe and the second call is
- *    a no-op (the listener set is already empty). This matters because
- *    two code paths can race to cancel — the Ctrl+C handler and a
- *    downstream tool that observed `isAborted` and threw — and both
- *    end up calling `dispatch.cancel()` which transitively calls
- *    `token.abort()`.
- *  - Listener errors do NOT block the drain. A throwing listener
- *    stops itself but the next listener still fires. The error is
- *    swallowed because the cancellation path is best-effort and
- *    surfacing the error mid-drain would leak through the abort
- *    pathway into the REPL state (a UI rerender on a half-aborted
- *    session is worse than a silent listener crash).
- *
- * Brand voice: no forbidden words. ASCII only. No emoji.
- */
-export class CancellationToken {
-    aborted = false;
-    listeners = new Set();
-    /**
-     * Latch the token to aborted and fire every currently-attached
-     * listener exactly once. Subsequent `abort()` calls are no-ops
-     * (idempotent — the listener set was already cleared on first abort).
-     * Listener callbacks that throw are swallowed; the next listener
-     * still fires.
-     */
-    abort() {
-        if (this.aborted)
-            return;
-        this.aborted = true;
-        // Snapshot the listener set so a listener that mutates the set
-        // (e.g. detaches itself via the returned unsubscribe handle while
-        // its own callback is running) does not corrupt the iteration.
-        const snapshot = Array.from(this.listeners);
-        this.listeners.clear();
-        for (const listener of snapshot) {
-            try {
-                listener();
-            }
-            catch {
-                // Swallow listener errors — see header comment for rationale.
-            }
-        }
-    }
-    /**
-     * True after `abort()` has been called. Mutation observers and tool
-     * inner loops should read this BEFORE each potentially-expensive
-     * iteration so they can short-circuit on cancel.
-     */
-    get isAborted() {
-        return this.aborted;
-    }
-    /**
-     * Register a callback that fires on the FIRST `abort()` call. If the
-     * token has already aborted at registration time, the callback is
-     * NOT auto-fired — the caller is responsible for checking
-     * `isAborted` first.
-     *
-     * Returns an unsubscribe handle. Calling it before abort detaches the
-     * listener so it never fires; calling it after abort is a no-op (the
-     * set was already drained).
-     */
-    onAbort(listener) {
-        if (this.aborted) {
-            // Document the contract by returning a no-op unsubscribe handle.
-            // The listener does NOT fire — late subscribers must check
-            // isAborted at registration time.
-            return () => undefined;
-        }
-        this.listeners.add(listener);
-        return () => {
-            this.listeners.delete(listener);
-        };
-    }
-}
-//# sourceMappingURL=cancellation.js.map