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

package/dist/core/repl/store/types.js

@@ -1,44 +0,0 @@
-/**
- * Persistent REPL session store — Sprint .
- *
- * Public types consumed by the REPL session module + the `pugi sessions`
- * / `pugi resume` dispatchers. Wire format is stable:
- *
- *  - `SessionRow` mirrors the SQLite `sessions` table one-to-one and is
- *    also the JSON shape returned by `pugi sessions --json`. Field names
- *    are camelCase (PascalCase types, camelCase fields per CLAUDE.md
- *    conventions). The SQL columns themselves stay snake_case because
- *    they originate from raw SQL.
- *
- *  - `SessionEvent` is the on-disk shape of one line in
- *    `events.<n>.jsonl`. `kind` is a closed union; `payload` is an
- *    opaque JSON value so the producer can attach whatever fields the
- *    event type requires without forcing the store to change.
- *
- *  - `SessionListOptions` / `SessionLoadEventsOptions` /
- *    `SessionSearchOptions` are inputs the store accepts. Defaults are
- *    spec'd inline so the test plan can pin them without reading the
- *    implementation.
- *
- * The blob store + `pugi undo` + named checkpoints are follow-ups
- * — out of scope for THIS PR per spec. The types here intentionally do
- * NOT model blob refs so a future blob-store landing can extend without
- * a wire break.
- */
-/**
- * Concrete shape of the lock detection error so the caller can branch
- * on `error.code === 'EBUSY_SESSION_LOCK'` rather than parsing the
- * message. The store is the only thrower of this error.
- */
-export class SessionLockBusyError extends Error {
-    code = 'EBUSY_SESSION_LOCK';
-    holderPid;
-    lockPath;
-    constructor(holderPid, lockPath) {
-        super(`Another pugi process (pid ${holderPid}) holds the session lock at ${lockPath}.`);
-        this.name = 'SessionLockBusyError';
-        this.holderPid = holderPid;
-        this.lockPath = lockPath;
-    }
-}
-//# sourceMappingURL=types.js.map

package/dist/core/repl/store/uuid-v7.js

@@ -1,68 +0,0 @@
-/**
- * UUID v7 generator — Sprint .
- *
- * uuid v7 (RFC 9562 draft) is a time-sortable 128-bit identifier whose
- * first 48 bits are the unix-epoch milliseconds, the next 4 bits are
- * the version (0b0111), the next 12 bits are sub-millisecond random
- * entropy, the next 2 bits are the IETF variant (0b10), and the last
- * 62 bits are random.
- *
- * Why v7 and not v4 (random) or v6 (gregorian time):
- *
- *  - The session id IS the primary key of the SQLite table. We want
- *    inserts to land at the end of the b-tree to keep page fanout
- *    small. v4 fragments the tree (uniformly random keys); v7 sorts
- *    in time order so inserts are append-only.
- *  - `pugi sessions` sorts by `updated_at DESC` for display, but the
- *    pagination cursor uses the session id directly — a v7 id IS the
- *    creation timestamp, so the cursor is a single column compare
- *    instead of (updated_at, id) tuple.
- *  - Operators see ids in `/resume` picker; v7 prefix is monotonically
- *    increasing so the most recent session lands at the bottom of an
- *    id sort, matching the human expectation of "newest last".
- *
- * Node 22 does not ship a v7 generator (`crypto.randomUUID()` is v4
- * only). We implement it inline with `crypto.randomBytes(10)` for the
- * entropy bits — 10 bytes covers the 12-bit random + 62-bit random
- * fields with one syscall.
- *
- * Format: `xxxxxxxx-xxxx-7xxx-yxxx-xxxxxxxxxxxx` where `y` is 8/9/a/b.
- */
-import { randomBytes } from 'node:crypto';
-/**
- * Mint a fresh uuid v7. The `now` parameter is injectable for tests so
- * the generated id is deterministic when the test fixes the clock.
- * Production callers pass `Date.now`.
- */
-export function uuidV7(now = Date.now) {
-    const ms = Math.floor(now());
-    // 48-bit timestamp (6 bytes).
-    const tsHex = ms.toString(16).padStart(12, '0');
-    // 10 bytes of entropy: 12 random bits go into octet 6 (after the 4
-    // version bits), 2 variant bits go into octet 8 (high nibble 8/9/a/b),
-    // the remaining 62 bits fill octets 9..15.
-    const rand = randomBytes(10);
-    // Set version (high nibble of octet 6) to 7.
-    rand[0] = ((rand[0] ?? 0) & 0x0f) | 0x70;
-    // Set IETF variant (high two bits of octet 8) to 0b10.
-    rand[2] = ((rand[2] ?? 0) & 0x3f) | 0x80;
-    const hex = Array.from(rand, (b) => b.toString(16).padStart(2, '0')).join('');
-    // Assemble: 8-4-4-4-12.
-    return (`${tsHex.slice(0, 8)}-${tsHex.slice(8, 12)}-${hex.slice(0, 4)}-`
-        + `${hex.slice(4, 8)}-${hex.slice(8, 20)}`);
-}
-/**
- * Extract the unix-ms timestamp from a uuid v7. Returns null when the
- * input is not a v7 id (wrong version nibble, wrong shape). Used by
- * `pugi sessions` to render "created N seconds ago" without reading
- * the SQLite row.
- */
-export function uuidV7Timestamp(id) {
-    if (!/^[0-9a-f]{8}-[0-9a-f]{4}-7[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/i
-        .test(id)) {
-        return null;
-    }
-    const hex = id.slice(0, 8) + id.slice(9, 13);
-    return Number.parseInt(hex, 16);
-}
-//# sourceMappingURL=uuid-v7.js.map

package/dist/core/repl/tool-route.js

@@ -1,382 +0,0 @@
-/**
- * PUGI-538b () — `<pugi-tool-route>` envelope parser.
- *
- * The admin-api Pugi coordinator persona emits an
- * `<pugi-tool-route command="code|fix|build" persona="<slug>" brief="…"/>`
- * envelope on her turn when the operator's brief requires workspace
- * tool use (write/edit/read a file, run a script, install a package,
- * build, test). The CLI consumer parses the envelope, strips it from
- * operator-visible detail, and routes the brief through the local
- * `NativePugiEngineAdapter` → `runEngineLoop` → `POST /api/pugi/engine`
- * flow that already drives `pugi code/fix/build` end-to-end with real
- * tool calls and atomic file writes.
- *
- * Without this envelope the REPL chat path is a single-shot text
- * streamer: customer says "make tic-tac-toe", Pugi responds with a
- * bash heredoc dump as prose, no file is written.  (PUGI-538a)
- * lays out the architecture; this parser is the CLI half of the bridge.
- *
- * # Grammar (self-closing form is preferred; paired form also accepted)
- *
- *   <pugi-tool-route command="code" persona="dev" brief="One sentence…"/>
- *   <pugi-tool-route command="fix"  persona="dev" brief="…"></pugi-tool-route>
- *
- * Attributes:
- *   - command  (required) — exactly one of `code`, `fix`, `build`.
- *   - persona  (optional) — Tier-1 persona slug hint; defaults to `dev`
- *              when omitted. The value `main` is rejected (the REPL
- *              coordinator IS Pugi already, routing back to herself
- *              would not change behaviour).
- *   - brief    (required) — single-sentence operational brief,
- *              <= 400 chars after entity decoding.
- *
- * # Why a hand-rolled parser, not a generic XML library
- *
- * Same rationale as `ask.ts`: 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 one tag with a closed three-attribute
- * set, so a bounded tokenizer is both safer and smaller. The defences
- * mirror ask.ts: closed entity allowlist, control-char strip, refusal
- * on raw `&` outside `&amp;` / `&lt;` / `&gt;` / `&quot;` / `&apos;`,
- * refusal on nested tags inside attribute blob, hard span cap.
- *
- * # Buffering across streaming chunks
- *
- * The session calls `extractToolRouteTags(buffer)` on the accumulated
- * `agent.step.detail` body. If the close tag (or self-close `/>`) has
- * not arrived yet, the parser returns `{ tags: [], pendingOpenTag: true }`
- * and the session waits for more chunks. This mirrors the
- * `extractAskTags` / `extractPlanReviewTags` shape so `session.ts`
- * routes the three envelope families through one buffer-and-strip
- * machinery.
- */
-/* ------------------------------------------------------------------ */
-/* Bounded constants                                                  */
-/* ------------------------------------------------------------------ */
-/** Hard cap on the brief length after entity decoding. */
-export const TOOL_ROUTE_MAX_BRIEF_LEN = 400;
-/** Hard cap on the persona slug length. */
-export const TOOL_ROUTE_MAX_PERSONA_LEN = 32;
-/** Hard cap on the entire tag span. Long enough for full attrs + a
- * worst-case 400-char brief plus closing form; defends against runaway
- * payloads. */
-const TAG_MAX_SPAN_BYTES = 4 * 1024;
-/** Tag families exhaustively enumerated for the closed-attribute gate. */
-const ALLOWED_ATTRS = new Set([
-    'command',
-    'persona',
-    'brief',
-]);
-/** Accepted `command` literals — locked to the engine adapter contract. */
-const ALLOWED_COMMANDS = new Set(['code', 'fix', 'build']);
-/** Refused personas. `main` would route Pugi back to herself; the engine
- * adapter rejects the slug anyway, so we filter at parse time for clarity. */
-const REFUSED_PERSONAS = new Set(['main', 'pugi']);
-/** Default persona slug when the attribute is omitted. Matches the
- * ENVELOPES_BODY prompt copy ("Defaults to 'dev' when omitted"). */
-const DEFAULT_PERSONA = 'dev';
-/* ------------------------------------------------------------------ */
-/* Public extraction API                                              */
-/* ------------------------------------------------------------------ */
-/**
- * Find every well-formed `<pugi-tool-route>` envelope in `body`.
- * Malformed envelopes are dropped and surfaced via `hadMalformedTag`
- * so the session can log a warning. Streaming-incomplete envelopes
- * (open observed, close/self-close not yet arrived) are withheld from
- * `cleaned` so the raw envelope cannot leak into the transcript if the
- * stream pauses mid-tag.
- */
-export function extractToolRouteTags(body) {
-    const tags = [];
-    const segments = [];
-    let cursor = 0;
-    let pendingOpenTag = false;
-    let hadMalformedTag = false;
-    // Hard cap on tags per buffer so a hostile (or accidental) flood
-    // does not pin the parser. 16 is generous — a real session never
-    // has more than one envelope queued per turn.
-    const MAX_TAGS_PER_BUFFER = 16;
-    // Belt-and-braces safety counter — the body length bounds the
-    // iteration count strictly, but a pathological input could otherwise
-    // loop until the per-buffer cap fires.
-    let safetyIterations = body.length + 16;
-    const OPEN_PREFIX = '<pugi-tool-route';
-    const PAIR_CLOSE = '</pugi-tool-route>';
-    while (cursor < body.length && tags.length < MAX_TAGS_PER_BUFFER) {
-        if (safetyIterations-- <= 0)
-            break;
-        const openIndex = body.indexOf(OPEN_PREFIX, cursor);
-        if (openIndex === -1) {
-            // No more envelopes. Flush the rest of the body as cleaned prose.
-            segments.push(body.slice(cursor));
-            cursor = body.length;
-            break;
-        }
-        // Push everything before the opening tag as cleaned prose.
-        segments.push(body.slice(cursor, openIndex));
-        // Locate the end of the opening tag. The envelope may be self-
-        // closing (`/>`) or paired (`>` then `</pugi-tool-route>`).
-        // Search for the FIRST unquoted `>` after the OPEN_PREFIX position
-        // so a quoted attribute value with an embedded `>` (escaped as
-        // `&gt;` per the grammar; raw `>` is rejected below) cannot
-        // confuse the boundary scan.
-        const openEnd = findUnquotedGt(body, openIndex + OPEN_PREFIX.length);
-        if (openEnd === -1) {
-            // Open seen, no terminator yet. Withhold from `cleaned` so the
-            // raw envelope cannot leak. Same posture as ask.ts.
-            pendingOpenTag = true;
-            cursor = body.length;
-            break;
-        }
-        const selfClosed = body[openEnd - 1] === '/';
-        let tagEnd;
-        if (selfClosed) {
-            tagEnd = openEnd + 1; // include the closing `>`
-        }
-        else {
-            // Paired form — look for `</pugi-tool-route>`.
-            const closeAt = body.indexOf(PAIR_CLOSE, openEnd + 1);
-            if (closeAt === -1) {
-                pendingOpenTag = true;
-                cursor = body.length;
-                break;
-            }
-            tagEnd = closeAt + PAIR_CLOSE.length;
-        }
-        const span = body.slice(openIndex, tagEnd);
-        if (span.length > TAG_MAX_SPAN_BYTES) {
-            hadMalformedTag = true;
-            cursor = tagEnd;
-            continue;
-        }
-        // Reject nested envelopes — the generic "find next close" would
-        // otherwise pair an outer open with an inner close.
-        const innerOpen = span.indexOf(OPEN_PREFIX, OPEN_PREFIX.length);
-        if (innerOpen !== -1) {
-            hadMalformedTag = true;
-            cursor = tagEnd;
-            continue;
-        }
-        // Slice the attribute blob between OPEN_PREFIX and the closing
-        // `>` (excluding the trailing `/` on the self-closed form).
-        const attrBlobEnd = selfClosed ? openEnd - 1 : openEnd;
-        const attrBlob = body.slice(openIndex + OPEN_PREFIX.length, attrBlobEnd);
-        const parsed = parseToolRouteInner(attrBlob, {
-            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,
-    };
-}
-/* ------------------------------------------------------------------ */
-/* Inner parser                                                       */
-/* ------------------------------------------------------------------ */
-function parseToolRouteInner(attrBlob, span) {
-    // Reject CDATA, comments, processing instructions, DOCTYPE inside
-    // the attribute blob — none of those appear in the legal grammar.
-    if (/<!--|<!\[|<\?|<!DOCTYPE/i.test(attrBlob))
-        return null;
-    // Reject raw `&` not in a known entity (decoded entities are allowed
-    // via decodeEntities below).
-    if (containsRawAmpersand(attrBlob))
-        return null;
-    // Reject raw `<` / `>` inside the attribute blob — they should always
-    // be escaped as `&lt;` / `&gt;`. The presence of a raw bracket is a
-    // sign of either accidental sloppy output or an injection attempt.
-    if (/[<>]/.test(attrBlob))
-        return null;
-    const attrs = parseAttrBlob(attrBlob);
-    if (attrs === null)
-        return null;
-    // Closed-attribute gate — refuse anything outside the allowlist.
-    for (const key of Object.keys(attrs)) {
-        if (!ALLOWED_ATTRS.has(key))
-            return null;
-    }
-    const command = attrs['command'];
-    if (typeof command !== 'string' || command.length === 0)
-        return null;
-    if (!ALLOWED_COMMANDS.has(command))
-        return null;
-    const briefRaw = attrs['brief'];
-    if (typeof briefRaw !== 'string')
-        return null;
-    const brief = briefRaw.trim();
-    if (brief.length === 0 || brief.length > TOOL_ROUTE_MAX_BRIEF_LEN)
-        return null;
-    // Persona is optional → default to `dev`. Any explicit non-empty
-    // value runs through the slug shape check + refused-persona gate.
-    const personaRaw = attrs['persona'];
-    let persona = DEFAULT_PERSONA;
-    if (typeof personaRaw === 'string' && personaRaw.length > 0) {
-        const trimmed = personaRaw.trim();
-        if (trimmed.length === 0 || trimmed.length > TOOL_ROUTE_MAX_PERSONA_LEN)
-            return null;
-        // Slug shape: lowercase ASCII letters + digits + hyphens, must
-        // start with a letter. Same shape as the `<pugi-delegate>` slug
-        // gate in admin-api so a future engine adapter can reuse the slug
-        // verbatim without re-validating.
-        if (!/^[a-z][a-z0-9-]*$/.test(trimmed))
-            return null;
-        if (REFUSED_PERSONAS.has(trimmed))
-            return null;
-        persona = trimmed;
-    }
-    const signature = signatureForToolRoute(command, persona, brief);
-    return {
-        command: command,
-        persona,
-        brief,
-        signature,
-        start: span.start,
-        end: span.end,
-    };
-}
-/**
- * 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). Mirrors the bounded tokenizer
- * in ask.ts so the parsing posture is uniform across envelope families.
- */
-function parseAttrBlob(blob) {
-    const trimmed = blob.trim();
-    if (trimmed.length === 0)
-        return {};
-    const result = {};
-    let cursor = 0;
-    const maxIterations = trimmed.length + 4;
-    let iterations = 0;
-    while (cursor < trimmed.length && iterations++ < maxIterations) {
-        while (cursor < trimmed.length && /\s/.test(trimmed[cursor] ?? ''))
-            cursor += 1;
-        if (cursor >= trimmed.length)
-            break;
-        const nameStart = cursor;
-        // Attribute names are lowercase letters; allow `-` for consistency
-        // with the rest of the persona grammar even though our allowlist is
-        // hyphen-free. Mismatch is caught by the ALLOWED_ATTRS gate.
-        while (cursor < trimmed.length &&
-            /[a-z-]/.test(trimmed[cursor] ?? '')) {
-            cursor += 1;
-        }
-        if (cursor === nameStart)
-            return null;
-        const name = trimmed.slice(nameStart, cursor);
-        if (trimmed[cursor] !== '=')
-            return null;
-        cursor += 1;
-        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);
-        // Raw `&` outside a known entity is malformed; raw angle brackets
-        // are forbidden inside quoted values (must be escaped). The closed
-        // entity allowlist + control-char strip mirrors ask.ts.
-        if (containsRawAmpersand(rawValue))
-            return null;
-        if (/[<>]/.test(rawValue))
-            return null;
-        result[name] = stripControlChars(decodeEntities(rawValue));
-        cursor = valueEnd + 1;
-    }
-    return result;
-}
-/* ------------------------------------------------------------------ */
-/* Streaming helper — find an unquoted `>` after `from`               */
-/* ------------------------------------------------------------------ */
-/**
- * Walk `body` from index `from` looking for the first `>` that is NOT
- * inside a quoted attribute value. Returns the index of the `>` or -1
- * when no such position is found.
- *
- * Quote tracking is necessary because a `brief="…contains > as &gt;…"`
- * value should never confuse the boundary scan. The grammar already
- * forbids raw `>` inside quoted values (escape as `&gt;`) — this is
- * belt-and-braces against a sloppy model emission.
- */
-function findUnquotedGt(body, from) {
-    let quote = null;
-    for (let i = from; i < body.length; i += 1) {
-        const ch = body[i];
-        if (quote !== null) {
-            if (ch === quote)
-                quote = null;
-            continue;
-        }
-        if (ch === '"' || ch === "'") {
-            quote = ch;
-            continue;
-        }
-        if (ch === '>')
-            return i;
-    }
-    return -1;
-}
-/* ------------------------------------------------------------------ */
-/* Entity decoding + amp safety + control strip                       */
-/* ------------------------------------------------------------------ */
-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;
-    });
-}
-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, '');
-}
-function containsRawAmpersand(input) {
-    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;
-}
-/* ------------------------------------------------------------------ */
-/* Signature                                                          */
-/* ------------------------------------------------------------------ */
-/**
- * Stable dedupe signature for a tool-route tag. Exported so future
- * synthesisers (slash command, local fallback) can produce signatures
- * that collision-match parser-produced ones — without a single source
- * of truth a local synth could share a signature with a persona-emitted
- * envelope and the rolling-seen set would suppress one of them.
- */
-export function signatureForToolRoute(command, persona, brief) {
-    const raw = `${command}::${persona.toLowerCase()}::${brief.trim().toLowerCase()}`;
-    return Buffer.from(raw, 'utf8').toString('base64');
-}
-//# sourceMappingURL=tool-route.js.map