@pugi/cli 0.1.0-alpha.9 → 0.1.0-beta.2

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (68) hide show
  1. package/README.md +33 -0
  2. package/assets/pugi-mascot.ansi +41 -0
  3. package/dist/commands/deploy.js +439 -0
  4. package/dist/core/agents/loader.js +104 -0
  5. package/dist/core/agents/registry.js +1 -1
  6. package/dist/core/consensus/anvil-fanout.js +276 -0
  7. package/dist/core/consensus/diff-capture.js +382 -0
  8. package/dist/core/consensus/rubric.js +233 -0
  9. package/dist/core/context/index.js +21 -0
  10. package/dist/core/context/pugiignore.js +316 -0
  11. package/dist/core/context/repo-skeleton.js +533 -0
  12. package/dist/core/context/watcher.js +342 -0
  13. package/dist/core/context/working-set.js +165 -0
  14. package/dist/core/edits/dispatch.js +185 -0
  15. package/dist/core/edits/index.js +15 -0
  16. package/dist/core/edits/layer-a-apply.js +217 -0
  17. package/dist/core/edits/layer-b-apply.js +211 -0
  18. package/dist/core/edits/layer-c-apply.js +160 -0
  19. package/dist/core/edits/layer-d-ast.js +29 -0
  20. package/dist/core/edits/marker-parser.js +401 -0
  21. package/dist/core/edits/security-gate.js +223 -0
  22. package/dist/core/edits/worktree.js +229 -0
  23. package/dist/core/engine/native-pugi.js +6 -1
  24. package/dist/core/engine/prompts.js +4 -1
  25. package/dist/core/engine/tool-bridge.js +33 -1
  26. package/dist/core/lsp/client.js +631 -0
  27. package/dist/core/repl/ask.js +512 -0
  28. package/dist/core/repl/cancellation.js +98 -0
  29. package/dist/core/repl/dispatch-fsm.js +220 -0
  30. package/dist/core/repl/privacy-banner.js +71 -0
  31. package/dist/core/repl/session.js +1896 -13
  32. package/dist/core/repl/slash-commands.js +59 -32
  33. package/dist/core/repl/store/index.js +12 -0
  34. package/dist/core/repl/store/jsonl-log.js +321 -0
  35. package/dist/core/repl/store/lockfile.js +155 -0
  36. package/dist/core/repl/store/session-store.js +792 -0
  37. package/dist/core/repl/store/types.js +44 -0
  38. package/dist/core/repl/store/uuid-v7.js +68 -0
  39. package/dist/core/repl/workspace-context.js +72 -1
  40. package/dist/core/skills/loader.js +454 -0
  41. package/dist/core/skills/sources.js +480 -0
  42. package/dist/core/skills/trust.js +172 -0
  43. package/dist/runtime/cli.js +767 -10
  44. package/dist/runtime/commands/agents.js +385 -0
  45. package/dist/runtime/commands/config.js +338 -8
  46. package/dist/runtime/commands/lsp.js +184 -0
  47. package/dist/runtime/commands/patch.js +111 -0
  48. package/dist/runtime/commands/review-consensus.js +399 -0
  49. package/dist/runtime/commands/skills.js +401 -0
  50. package/dist/runtime/commands/worktree.js +133 -0
  51. package/dist/tools/apply-patch.js +314 -0
  52. package/dist/tools/file-tools.js +90 -0
  53. package/dist/tools/lsp-tools.js +189 -0
  54. package/dist/tools/registry.js +18 -0
  55. package/dist/tools/web-fetch.js +1 -1
  56. package/dist/tui/agent-tree-pane.js +9 -0
  57. package/dist/tui/ask-cli.js +52 -0
  58. package/dist/tui/ask-modal.js +211 -0
  59. package/dist/tui/conversation-pane.js +48 -3
  60. package/dist/tui/input-box.js +48 -5
  61. package/dist/tui/markdown-render.js +266 -0
  62. package/dist/tui/repl-render.js +185 -0
  63. package/dist/tui/repl-splash-mascot.js +130 -0
  64. package/dist/tui/repl-splash.js +7 -1
  65. package/dist/tui/repl.js +82 -11
  66. package/dist/tui/status-bar.js +63 -3
  67. package/dist/tui/tool-stream-pane.js +91 -0
  68. package/package.json +11 -5
@@ -0,0 +1,512 @@
1
+ /**
2
+ * Office-hours forcing questions + plan-review tag parser - Sprint α6.3.
3
+ *
4
+ * Pugi's persona prompt teaches Mira to emit two structured XML envelopes
5
+ * when she would otherwise have to guess. Operator chat then pauses on a
6
+ * modal until the operator answers, eliminating the "fabricate a default
7
+ * silently" failure mode that Codex CLI, Claude Code, and Gemini CLI all
8
+ * trip on with low-confidence intents.
9
+ *
10
+ * <pugi-ask>
11
+ * <question>Which deployment target?</question>
12
+ * <option value="vercel" label="Vercel" desc="Static + edge"/>
13
+ * <option value="cloudflare" label="Cloudflare Pages" desc="Edge runtime"/>
14
+ * </pugi-ask>
15
+ *
16
+ * <pugi-plan-review>
17
+ * <step>1. Edit src/foo.ts: add new export</step>
18
+ * <step>2. Write tests/foo.spec.ts: 8 test cases</step>
19
+ * <risk>Touches public API surface.</risk>
20
+ * </pugi-plan-review>
21
+ *
22
+ * This module is a pure, framework-free parser. The session module imports
23
+ * `extractAskTags()` / `extractPlanReviewTags()` and routes the typed
24
+ * records to the Ink modal layer; the REPL UI never sees raw XML.
25
+ *
26
+ * # Why a hand-rolled parser
27
+ *
28
+ * Generic XML libraries (sax, fast-xml-parser, xmldoc) carry a large
29
+ * attack surface (external entity expansion, recursive blowup on
30
+ * malformed input, sloppy attribute handling) and require ~50 KB of
31
+ * runtime dependency. The persona-side grammar here is two tag families
32
+ * with a closed attribute set, so a bounded tokenizer is both safer and
33
+ * smaller. Defence-in-depth choices:
34
+ *
35
+ * - Reject raw `&` outside `&amp;` / `&lt;` / `&gt;` / `&quot;` /
36
+ * `&apos;` (entities are decoded; everything else is malformed).
37
+ * - Forbid nested ask-within-ask (would crash the modal stack).
38
+ * - Cap option count at 4 (Claude Code AskUserQuestion baseline).
39
+ * - Cap label / desc / question / step / risk at 80 chars (terminal
40
+ * rendering budget, also discourages prompt injection via huge
41
+ * payloads).
42
+ * - Reject CDATA, comments, processing instructions, DOCTYPE — none
43
+ * of those appear in the legal grammar.
44
+ * - Reject any attribute that is not in the per-tag allowlist.
45
+ *
46
+ * # Buffering across streaming chunks
47
+ *
48
+ * The session calls `extractAskTags(buffer)` on the accumulated
49
+ * `agent.step.detail` body. If the close tag has not arrived yet, the
50
+ * parser returns `{ tags: [], remainder: buffer }` and the session waits
51
+ * for more chunks. Once `</pugi-ask>` lands, the parser slices the tag
52
+ * out, returns the structured record, and the session continues with the
53
+ * post-tag remainder. The same shape applies to `<pugi-plan-review>`.
54
+ */
55
+ /* ------------------------------------------------------------------ */
56
+ /* Bounded constants */
57
+ /* ------------------------------------------------------------------ */
58
+ /** Hard cap on options per `<pugi-ask>`. Claude Code AskUserQuestion uses 4. */
59
+ export const ASK_MAX_OPTIONS = 4;
60
+ /** Hard cap on question / label / desc length. Terminal-row budget. */
61
+ export const ASK_MAX_TEXT_LEN = 80;
62
+ /** Hard cap on steps per `<pugi-plan-review>`. */
63
+ export const PLAN_REVIEW_MAX_STEPS = 12;
64
+ /** Hard cap on step text length. */
65
+ export const PLAN_REVIEW_MAX_STEP_LEN = 200;
66
+ /** Hard cap on risk callout length. */
67
+ export const PLAN_REVIEW_MAX_RISK_LEN = 240;
68
+ /** Hard cap on the entire tag span. Long enough for 4 options + risk; defends against runaway payloads. */
69
+ const TAG_MAX_SPAN_BYTES = 8 * 1024;
70
+ /* ------------------------------------------------------------------ */
71
+ /* Public extraction API */
72
+ /* ------------------------------------------------------------------ */
73
+ /**
74
+ * Find every well-formed `<pugi-ask>` in `body`. Malformed tags are
75
+ * dropped and surfaced via `hadMalformedTag` so the session can log a
76
+ * warning. Streaming-incomplete tags (open observed, close not yet
77
+ * arrived) are kept in `cleaned` verbatim and reported via
78
+ * `pendingOpenTag`, so the session keeps buffering until the close tag
79
+ * lands or the turn ends.
80
+ */
81
+ export function extractAskTags(body) {
82
+ return extractTags(body, {
83
+ openTag: '<pugi-ask>',
84
+ closeTag: '</pugi-ask>',
85
+ parseInner: parseAskInner,
86
+ });
87
+ }
88
+ /**
89
+ * Find every well-formed `<pugi-plan-review>` in `body`. Same contract
90
+ * as `extractAskTags` — malformed → drop + flag, streaming-incomplete →
91
+ * keep in `cleaned` + flag for buffering.
92
+ */
93
+ export function extractPlanReviewTags(body) {
94
+ return extractTags(body, {
95
+ openTag: '<pugi-plan-review>',
96
+ closeTag: '</pugi-plan-review>',
97
+ parseInner: parsePlanReviewInner,
98
+ });
99
+ }
100
+ function extractTags(body, config) {
101
+ const tags = [];
102
+ const segments = [];
103
+ let cursor = 0;
104
+ let pendingOpenTag = false;
105
+ let hadMalformedTag = false;
106
+ // Hard cap on tags per buffer so a hostile (or accidental) `<pugi-ask>`
107
+ // flood does not pin the parser. 64 is generous — a real session
108
+ // never has more than 1-2 modals queued.
109
+ const MAX_TAGS_PER_BUFFER = 64;
110
+ // Guard counter to prevent a pathological input from looping forever.
111
+ // The body length bounds the iteration count strictly, but we add a
112
+ // belt-and-braces ceiling proportional to body size for clarity.
113
+ let safetyIterations = body.length + 16;
114
+ while (cursor < body.length && tags.length < MAX_TAGS_PER_BUFFER) {
115
+ if (safetyIterations-- <= 0)
116
+ break;
117
+ const openIndex = body.indexOf(config.openTag, cursor);
118
+ if (openIndex === -1) {
119
+ // No more tags. Flush the rest of the body as cleaned prose and exit.
120
+ segments.push(body.slice(cursor));
121
+ cursor = body.length;
122
+ break;
123
+ }
124
+ // Push everything before the opening tag as cleaned prose.
125
+ segments.push(body.slice(cursor, openIndex));
126
+ const closeIndex = body.indexOf(config.closeTag, openIndex + config.openTag.length);
127
+ if (closeIndex === -1) {
128
+ // Open seen, close not yet streamed in. WITHHOLD the partial
129
+ // span from `cleaned` so the raw `<pugi-ask>` envelope cannot
130
+ // leak into the operator-visible transcript if the stream pauses
131
+ // or completes mid-tag. The caller keeps the original buffer for
132
+ // the next chunk merge via pendingOpenTag; if the turn ends with
133
+ // the tag still open, the caller emits a system warning instead
134
+ // of surfacing the raw XML. Codex triple-review P2 (PR #375).
135
+ pendingOpenTag = true;
136
+ cursor = body.length;
137
+ break;
138
+ }
139
+ const tagEnd = closeIndex + config.closeTag.length;
140
+ const span = body.slice(openIndex, tagEnd);
141
+ if (span.length > TAG_MAX_SPAN_BYTES) {
142
+ hadMalformedTag = true;
143
+ cursor = tagEnd;
144
+ continue;
145
+ }
146
+ // Reject nested open tags inside the span before parsing — the
147
+ // generic "find next close" lookup would otherwise pair an outer
148
+ // open with an inner close, producing a corrupt tag.
149
+ const innerOpen = span.indexOf(config.openTag, config.openTag.length);
150
+ if (innerOpen !== -1) {
151
+ hadMalformedTag = true;
152
+ cursor = tagEnd;
153
+ continue;
154
+ }
155
+ const inner = body.slice(openIndex + config.openTag.length, closeIndex);
156
+ const parsed = config.parseInner(inner, { start: openIndex, end: tagEnd });
157
+ if (parsed === null) {
158
+ hadMalformedTag = true;
159
+ cursor = tagEnd;
160
+ continue;
161
+ }
162
+ tags.push(parsed);
163
+ cursor = tagEnd;
164
+ }
165
+ return {
166
+ tags,
167
+ cleaned: segments.join('').replace(/\s+\n/g, '\n').trimEnd(),
168
+ pendingOpenTag,
169
+ hadMalformedTag,
170
+ };
171
+ }
172
+ /* ------------------------------------------------------------------ */
173
+ /* `<pugi-ask>` inner parser */
174
+ /* ------------------------------------------------------------------ */
175
+ function parseAskInner(inner, span) {
176
+ // Reject CDATA, comments, processing instructions, DOCTYPE.
177
+ if (/<!--|<!\[|<\?|<!DOCTYPE/i.test(inner))
178
+ return null;
179
+ // Reject raw `&` not in a known entity. Decoded entities are allowed
180
+ // below in `decodeEntities`; anything outside the closed allowlist is
181
+ // malformed.
182
+ if (containsRawAmpersand(inner))
183
+ return null;
184
+ const question = extractSingleChildText(inner, 'question');
185
+ if (question === null)
186
+ return null;
187
+ if (question.length === 0 || question.length > ASK_MAX_TEXT_LEN)
188
+ return null;
189
+ const options = extractOptionTags(inner);
190
+ if (options === null)
191
+ return null;
192
+ if (options.length === 0 || options.length > ASK_MAX_OPTIONS)
193
+ return null;
194
+ // Reject duplicate option values — collapses to a single modal entry
195
+ // visually but corrupts the dedupe signature. Easier to refuse than
196
+ // to silently rewrite.
197
+ const seen = new Set();
198
+ for (const opt of options) {
199
+ if (seen.has(opt.value))
200
+ return null;
201
+ seen.add(opt.value);
202
+ }
203
+ const signature = signatureForAsk(question, options);
204
+ return { question, options, signature, start: span.start, end: span.end };
205
+ }
206
+ /**
207
+ * Pull the body of a single `<question>...</question>` child. Returns
208
+ * null when the tag is missing OR when more than one occurrence is
209
+ * found (the grammar mandates exactly one question per ask).
210
+ */
211
+ function extractSingleChildText(inner, tagName) {
212
+ const open = `<${tagName}>`;
213
+ const close = `</${tagName}>`;
214
+ const first = inner.indexOf(open);
215
+ if (first === -1)
216
+ return null;
217
+ const end = inner.indexOf(close, first + open.length);
218
+ if (end === -1)
219
+ return null;
220
+ // Ensure no second occurrence.
221
+ if (inner.indexOf(open, end + close.length) !== -1)
222
+ return null;
223
+ const body = inner.slice(first + open.length, end);
224
+ // Reject nested tags inside the question body.
225
+ if (/<[^>]/.test(body))
226
+ return null;
227
+ return stripControlChars(decodeEntities(body)).trim();
228
+ }
229
+ /**
230
+ * Pull every self-closing `<option ... />` element from the inner body.
231
+ * Returns null on any malformed option; the caller drops the whole tag
232
+ * rather than partially accept a corrupt option list.
233
+ */
234
+ function extractOptionTags(inner) {
235
+ const options = [];
236
+ // Match `<option ... />` (self-closing) OR `<option ...></option>`
237
+ // (paired form). The persona prompt teaches the self-closing form
238
+ // for compactness, but a model that emits the paired form should not
239
+ // be punished.
240
+ const re = /<option\b([^>]*?)(\/>|><\/option>)/g;
241
+ let match;
242
+ while ((match = re.exec(inner)) !== null) {
243
+ const attrBlob = match[1] ?? '';
244
+ const parsed = parseOptionAttrs(attrBlob);
245
+ if (parsed === null)
246
+ return null;
247
+ options.push(parsed);
248
+ }
249
+ // Bail if the inner has any `<option` that the regex did NOT match —
250
+ // means an option element was malformed (e.g. unclosed, attribute
251
+ // missing closing quote).
252
+ const stray = inner.match(/<option\b/g);
253
+ if (stray && stray.length !== options.length)
254
+ return null;
255
+ return options;
256
+ }
257
+ function parseOptionAttrs(attrBlob) {
258
+ // Allowed attributes: value, label, desc. Reject any other.
259
+ const attrs = parseAttrBlob(attrBlob);
260
+ if (attrs === null)
261
+ return null;
262
+ for (const key of Object.keys(attrs)) {
263
+ if (key !== 'value' && key !== 'label' && key !== 'desc')
264
+ return null;
265
+ }
266
+ const value = attrs['value'];
267
+ const label = attrs['label'];
268
+ if (typeof value !== 'string' || value.length === 0)
269
+ return null;
270
+ if (typeof label !== 'string' || label.length === 0)
271
+ return null;
272
+ if (value.length > ASK_MAX_TEXT_LEN || label.length > ASK_MAX_TEXT_LEN)
273
+ return null;
274
+ // Forbid quote / angle-bracket characters in value — those would
275
+ // break the operator-side echo "[ASK-RESPONSE:<value>]".
276
+ if (/[<>"'\\]/.test(value))
277
+ return null;
278
+ const desc = attrs['desc'];
279
+ if (desc !== undefined) {
280
+ if (typeof desc !== 'string')
281
+ return null;
282
+ if (desc.length > ASK_MAX_TEXT_LEN)
283
+ return null;
284
+ }
285
+ const opt = { value, label };
286
+ if (desc !== undefined && desc.length > 0)
287
+ opt.desc = desc;
288
+ return opt;
289
+ }
290
+ /**
291
+ * Parse `key="value"` / `key='value'` pairs out of an attribute blob.
292
+ * Returns null on any malformed attribute (unterminated quote, raw
293
+ * entity outside the allowlist, etc).
294
+ */
295
+ function parseAttrBlob(blob) {
296
+ const trimmed = blob.trim();
297
+ if (trimmed.length === 0)
298
+ return {};
299
+ const result = {};
300
+ // Bound the iteration count: every step must consume at least one
301
+ // attribute and one separator, so the loop terminates in O(blob length).
302
+ let cursor = 0;
303
+ const maxIterations = trimmed.length + 4;
304
+ let iterations = 0;
305
+ while (cursor < trimmed.length && iterations++ < maxIterations) {
306
+ // Skip whitespace.
307
+ while (cursor < trimmed.length && /\s/.test(trimmed[cursor] ?? ''))
308
+ cursor += 1;
309
+ if (cursor >= trimmed.length)
310
+ break;
311
+ // Parse attribute name (lowercase letters only — keeps the grammar tight).
312
+ const nameStart = cursor;
313
+ while (cursor < trimmed.length && /[a-z]/.test(trimmed[cursor] ?? ''))
314
+ cursor += 1;
315
+ if (cursor === nameStart)
316
+ return null;
317
+ const name = trimmed.slice(nameStart, cursor);
318
+ // Expect `=`.
319
+ if (trimmed[cursor] !== '=')
320
+ return null;
321
+ cursor += 1;
322
+ // Expect a quote (single or double).
323
+ const quote = trimmed[cursor];
324
+ if (quote !== '"' && quote !== "'")
325
+ return null;
326
+ cursor += 1;
327
+ const valueStart = cursor;
328
+ const valueEnd = trimmed.indexOf(quote, valueStart);
329
+ if (valueEnd === -1)
330
+ return null;
331
+ const rawValue = trimmed.slice(valueStart, valueEnd);
332
+ if (containsRawAmpersand(rawValue))
333
+ return null;
334
+ if (/[<>]/.test(rawValue))
335
+ return null;
336
+ result[name] = stripControlChars(decodeEntities(rawValue));
337
+ cursor = valueEnd + 1;
338
+ }
339
+ return result;
340
+ }
341
+ /* ------------------------------------------------------------------ */
342
+ /* `<pugi-plan-review>` inner parser */
343
+ /* ------------------------------------------------------------------ */
344
+ function parsePlanReviewInner(inner, span) {
345
+ if (/<!--|<!\[|<\?|<!DOCTYPE/i.test(inner))
346
+ return null;
347
+ if (containsRawAmpersand(inner))
348
+ return null;
349
+ const steps = extractStepTags(inner);
350
+ if (steps === null)
351
+ return null;
352
+ if (steps.length === 0 || steps.length > PLAN_REVIEW_MAX_STEPS)
353
+ return null;
354
+ // Risk is optional and at most one occurrence.
355
+ const risk = extractOptionalChildText(inner, 'risk', PLAN_REVIEW_MAX_RISK_LEN);
356
+ if (risk === undefined)
357
+ return null;
358
+ const sig = signatureForPlanReview(steps, risk);
359
+ const tag = {
360
+ steps,
361
+ signature: sig,
362
+ start: span.start,
363
+ end: span.end,
364
+ };
365
+ if (risk !== null && risk.length > 0) {
366
+ tag.risk = risk;
367
+ }
368
+ return tag;
369
+ }
370
+ function extractStepTags(inner) {
371
+ const re = /<step>([\s\S]*?)<\/step>/g;
372
+ const steps = [];
373
+ let match;
374
+ while ((match = re.exec(inner)) !== null) {
375
+ const raw = match[1] ?? '';
376
+ if (/<[^>]/.test(raw))
377
+ return null;
378
+ const text = stripControlChars(decodeEntities(raw)).trim();
379
+ if (text.length === 0 || text.length > PLAN_REVIEW_MAX_STEP_LEN)
380
+ return null;
381
+ steps.push({ text });
382
+ }
383
+ // Detect unbalanced `<step>` occurrences (open with no close, etc).
384
+ const opens = (inner.match(/<step>/g) ?? []).length;
385
+ const closes = (inner.match(/<\/step>/g) ?? []).length;
386
+ if (opens !== steps.length || closes !== steps.length)
387
+ return null;
388
+ return steps;
389
+ }
390
+ /**
391
+ * Optional single-child text. Returns:
392
+ * - `null` when the tag is absent (legal absence)
393
+ * - the trimmed body when exactly one occurrence is present
394
+ * - `undefined` to signal a malformed (rejected) state to the caller
395
+ */
396
+ function extractOptionalChildText(inner, tagName, maxLen) {
397
+ const open = `<${tagName}>`;
398
+ const close = `</${tagName}>`;
399
+ const first = inner.indexOf(open);
400
+ if (first === -1)
401
+ return null;
402
+ const end = inner.indexOf(close, first + open.length);
403
+ if (end === -1)
404
+ return undefined;
405
+ if (inner.indexOf(open, end + close.length) !== -1)
406
+ return undefined;
407
+ const body = inner.slice(first + open.length, end);
408
+ if (/<[^>]/.test(body))
409
+ return undefined;
410
+ const decoded = stripControlChars(decodeEntities(body)).trim();
411
+ if (decoded.length > maxLen)
412
+ return undefined;
413
+ return decoded;
414
+ }
415
+ /* ------------------------------------------------------------------ */
416
+ /* Entity decoding + amp safety */
417
+ /* ------------------------------------------------------------------ */
418
+ const ENTITY_MAP = Object.freeze({
419
+ amp: '&',
420
+ lt: '<',
421
+ gt: '>',
422
+ quot: '"',
423
+ apos: "'",
424
+ });
425
+ function decodeEntities(input) {
426
+ return input.replace(/&([a-z]+);/g, (whole, name) => {
427
+ const decoded = ENTITY_MAP[name];
428
+ return decoded === undefined ? whole : decoded;
429
+ });
430
+ }
431
+ /**
432
+ * Strip C0 control characters (except \t \n \r), DEL, and C1 control
433
+ * characters from decoded text. The persona's grammar is plain ASCII
434
+ * prose; raw control codes are either accidental noise or a deliberate
435
+ * ANSI-escape injection attempt that would corrupt the Ink render.
436
+ *
437
+ * Applied AFTER decodeEntities so an `&` escape cannot smuggle an ESC
438
+ * byte through the entity layer.
439
+ *
440
+ * Claude triple-review P2 (PR #375).
441
+ */
442
+ function stripControlChars(input) {
443
+ // eslint-disable-next-line no-control-regex -- deliberately matching control range
444
+ return input.replace(/[\x00-\x08\x0b\x0c\x0e-\x1f\x7f\x80-\x9f]/g, '');
445
+ }
446
+ /**
447
+ * Reject any `&` that is not the head of a recognised entity. This is
448
+ * the defence-in-depth check from the module header: a raw `&` is
449
+ * legal in HTML but malformed in XML, and the persona is taught to
450
+ * always escape via `&amp;`. Anything outside the allowlist is a sign
451
+ * of either accidental sloppy output or an attempted injection.
452
+ */
453
+ function containsRawAmpersand(input) {
454
+ // Scan once; a recognised entity is `&` + name + `;`. Any `&` that is
455
+ // not followed by an allowed name + `;` is malformed.
456
+ for (let i = 0; i < input.length; i += 1) {
457
+ if (input[i] !== '&')
458
+ continue;
459
+ const semi = input.indexOf(';', i + 1);
460
+ if (semi === -1)
461
+ return true;
462
+ const name = input.slice(i + 1, semi);
463
+ if (!Object.prototype.hasOwnProperty.call(ENTITY_MAP, name))
464
+ return true;
465
+ i = semi;
466
+ }
467
+ return false;
468
+ }
469
+ /* ------------------------------------------------------------------ */
470
+ /* Signatures */
471
+ /* ------------------------------------------------------------------ */
472
+ /**
473
+ * Stable dedupe signature for an ask tag. The session keeps the most
474
+ * recent N signatures in a rolling set so a retry-spammed identical
475
+ * tag does not stack two modals.
476
+ *
477
+ * Algorithm: SHA-256-like collision-resistance is overkill for a
478
+ * single-process modal dedupe; a deterministic lower-case string is
479
+ * enough. We use the literal question + sorted-value join, then base64
480
+ * it for a compact identifier.
481
+ */
482
+ /**
483
+ * Stable dedupe signature for an ask tag. Exported so synthesisers
484
+ * outside the parser (slash-command `/ask`, `pugi ask` shell command)
485
+ * can produce signatures that collision-match parser-produced
486
+ * signatures. Without a single source of truth, an `<pugi-ask>`
487
+ * emitted by the persona with the same question + same option values
488
+ * could share a signature with a local synthesiser even though the
489
+ * computation diverged - dedupe would suppress the persona modal.
490
+ *
491
+ * Claude triple-review P1 (PR #375).
492
+ */
493
+ export function signatureForAsk(question, options) {
494
+ const values = options.map((o) => o.value).sort().join('|');
495
+ const raw = `${question.trim().toLowerCase()}::${values}`;
496
+ return Buffer.from(raw, 'utf8').toString('base64');
497
+ }
498
+ /**
499
+ * Stable dedupe signature for a plan-review tag. Exported for the
500
+ * same reason as signatureForAsk: synthesisers like
501
+ * `synthesiseLocalPlanReview` in cli.ts must produce identical
502
+ * signatures to parser-extracted tags for the same logical input.
503
+ *
504
+ * Codex triple-review P2 (PR #375).
505
+ */
506
+ export function signatureForPlanReview(steps, risk) {
507
+ const stepsJoined = steps.map((s) => s.text.trim()).join('|');
508
+ const riskJoined = risk ?? '';
509
+ const raw = `${stepsJoined}::${riskJoined}`;
510
+ return Buffer.from(raw, 'utf8').toString('base64');
511
+ }
512
+ //# sourceMappingURL=ask.js.map
@@ -0,0 +1,98 @@
1
+ /**
2
+ * Cancellation token — Sprint α6.9 Phase 1 (agent loop FSM + cancellation).
3
+ *
4
+ * A pure-JS one-shot signal that fans out to N listeners. One token is
5
+ * minted per dispatch turn (fresh on each operator brief); when the
6
+ * operator hits Ctrl+C, the REPL calls `abort()` which:
7
+ *
8
+ * 1. Latches `aborted = true` so any future `isAborted` check returns
9
+ * true (a tool that observes the flag mid-execution can short-circuit
10
+ * its loop without waiting for an explicit signal-handler callback).
11
+ * 2. Drains the listener set, firing each callback exactly once. The
12
+ * set is cleared after the drain so a late `onAbort` listener
13
+ * attached AFTER abort does NOT fire — that is the documented
14
+ * contract; late listeners are expected to check `isAborted`
15
+ * explicitly at registration time if they need to know whether the
16
+ * token already tripped.
17
+ *
18
+ * Design choices:
19
+ *
20
+ * - No coupling to `AbortController` / `AbortSignal`. The session +
21
+ * tool path are wrapped around this token; where a Web platform
22
+ * primitive is needed (fetch signal, MCP call), the wrapper bridges
23
+ * `onAbort` → `controller.abort()` at the seam.
24
+ * - Idempotent `abort()`. Calling twice is safe and the second call is
25
+ * a no-op (the listener set is already empty). This matters because
26
+ * two code paths can race to cancel — the Ctrl+C handler and a
27
+ * downstream tool that observed `isAborted` and threw — and both
28
+ * end up calling `dispatch.cancel()` which transitively calls
29
+ * `token.abort()`.
30
+ * - Listener errors do NOT block the drain. A throwing listener
31
+ * stops itself but the next listener still fires. The error is
32
+ * swallowed because the cancellation path is best-effort and
33
+ * surfacing the error mid-drain would leak through the abort
34
+ * pathway into the REPL state (a UI rerender on a half-aborted
35
+ * session is worse than a silent listener crash).
36
+ *
37
+ * Brand voice: no forbidden words. ASCII only. No emoji.
38
+ */
39
+ export class CancellationToken {
40
+ aborted = false;
41
+ listeners = new Set();
42
+ /**
43
+ * Latch the token to aborted and fire every currently-attached
44
+ * listener exactly once. Subsequent `abort()` calls are no-ops
45
+ * (idempotent — the listener set was already cleared on first abort).
46
+ * Listener callbacks that throw are swallowed; the next listener
47
+ * still fires.
48
+ */
49
+ abort() {
50
+ if (this.aborted)
51
+ return;
52
+ this.aborted = true;
53
+ // Snapshot the listener set so a listener that mutates the set
54
+ // (e.g. detaches itself via the returned unsubscribe handle while
55
+ // its own callback is running) does not corrupt the iteration.
56
+ const snapshot = Array.from(this.listeners);
57
+ this.listeners.clear();
58
+ for (const listener of snapshot) {
59
+ try {
60
+ listener();
61
+ }
62
+ catch {
63
+ // Swallow listener errors — see header comment for rationale.
64
+ }
65
+ }
66
+ }
67
+ /**
68
+ * True after `abort()` has been called. Mutation observers and tool
69
+ * inner loops should read this BEFORE each potentially-expensive
70
+ * iteration so they can short-circuit on cancel.
71
+ */
72
+ get isAborted() {
73
+ return this.aborted;
74
+ }
75
+ /**
76
+ * Register a callback that fires on the FIRST `abort()` call. If the
77
+ * token has already aborted at registration time, the callback is
78
+ * NOT auto-fired — the caller is responsible for checking
79
+ * `isAborted` first.
80
+ *
81
+ * Returns an unsubscribe handle. Calling it before abort detaches the
82
+ * listener so it never fires; calling it after abort is a no-op (the
83
+ * set was already drained).
84
+ */
85
+ onAbort(listener) {
86
+ if (this.aborted) {
87
+ // Document the contract by returning a no-op unsubscribe handle.
88
+ // The listener does NOT fire — late subscribers must check
89
+ // isAborted at registration time.
90
+ return () => undefined;
91
+ }
92
+ this.listeners.add(listener);
93
+ return () => {
94
+ this.listeners.delete(listener);
95
+ };
96
+ }
97
+ }
98
+ //# sourceMappingURL=cancellation.js.map