@north-light/crouter 0.3.197 → 0.3.199

package/dist/core/human/__tests__/serial/inbox-core.test.js

@@ -12,20 +12,10 @@ const temp = mkdtempSync(join(tmpdir(), 'crtr-inbox-core-'));
 process.env['CRTR_HOME'] = temp;
 const source = join(temp, 'source.md');
 writeFileSync(source, '# Source\n');
-const pageSource = join(temp, 'page.md');
-writeFileSync(pageSource, [
-    '---',
-    'title: A page',
-    'subtitle: Go? requires your attention.',
-    '---',
-    '',
-    '```slot:text',
-    '{ "id": "go", "initialText": "", "editable": true }',
-    '```',
-    '',
-].join('\n'));
-const page = (id, blockedSince) => submitPage({ dir: ticketDir(id), sourceFile: pageSource, dialect: 'md', source: { blockedSince, nodeId: 'node-1' } });
-const answer = { go: { text: 'yes', edited: true, comments: [] } };
+const pageSource = join(temp, 'page.tsx');
+writeFileSync(pageSource, 'export default () => (\n  <Page title="A page" subtitle="Go? requires your attention.">\n    <UserText id="go" initialText="" />\n  </Page>\n);\n');
+const page = (id, emittedAt) => submitPage({ dir: ticketDir(id), sourceFile: pageSource, source: { emittedAt, nodeId: 'node-1' }, delivery: { placement: 'inline', inbox: true, reply: true } });
+const answer = { go: { text: 'yes', edited: true } };
 async function waitFor(paths) {
     for (let attempts = 0; !paths.every(existsSync); attempts++) {
         if (attempts > 1_000)
@@ -42,7 +32,7 @@ assert.equal(existsSync(ticketDir('bad-review')), false, 'invalid submission doe
 const prepared = ticketDir('prepared');
 mkdirSync(prepared);
 writeFileSync(join(prepared, 'asset.png'), 'prepared asset');
-const preparedTicket = submitPage({ dir: prepared, sourceFile: pageSource, dialect: 'md', source: { blockedSince: '2025-01-02T00:00:00.000Z', nodeId: 'node-1' } });
+const preparedTicket = submitPage({ dir: prepared, sourceFile: pageSource, source: { emittedAt: '2025-01-02T00:00:00.000Z', nodeId: 'node-1' }, delivery: { placement: 'inline', inbox: true, reply: true } });
 assert.equal(preparedTicket.dir, realpathSync(prepared), 'submission accepts a crouter-precreated direct child and colocated assets');
 // Same timestamp is stable by id; progress is resumable work, never a hidden lease.
 atomicWriteJson(progressPath(newPage.dir), { kind: 'page', responses: {}, savedAt: new Date().toISOString() });
@@ -104,7 +94,7 @@ for (const [index, fixture] of rejectFixtures.entries()) {
 const protocolDir = ticketDir('stale-protocol');
 mkdirSync(protocolDir);
 writeFileSync(responsePath(protocolDir), '{}');
-assert.throws(() => submitPage({ dir: protocolDir, sourceFile: pageSource, dialect: 'md' }), /protocol state/, 'precreated assets may not include humanloop lifecycle state');
+assert.throws(() => submitPage({ dir: protocolDir, sourceFile: pageSource }), /protocol state/, 'precreated assets may not include humanloop lifecycle state');
 const cancelDir = page('cancel-race', '2025-01-03T00:00:00.000Z').dir;
 const canceled = cancelTicket(cancelDir, { reason: 'stop' });
 assert.equal(canceled.status, 'canceled');

package/dist/core/human/answer-text.d.ts

@@ -0,0 +1,3 @@
+import type { PageAnswer } from './answer.js';
+/** Render a PageAnswer as the deterministic Markdown report delivered to its asking agent. */
+export declare function renderAnswerText(answer: PageAnswer, responsePath: string): string;

package/dist/core/human/answer-text.js

@@ -0,0 +1,98 @@
+function inline(value) {
+    return `“${value}”`;
+}
+function verbatim(prefix, value) {
+    if (value === '')
+        return [`${prefix}(left empty)`];
+    if (!value.includes('\n'))
+        return [`${prefix}${inline(value)}`];
+    return [...(prefix === '' ? [] : [prefix.trimEnd()]), ...value.split('\n').map((line) => `> ${line}`)];
+}
+function code(value) {
+    const fence = '`'.repeat(Math.max(0, ...(value.match(/`+/g)?.map((run) => run.length) ?? [0])) + 1);
+    return `${fence}${value}${fence}`;
+}
+function item(item) {
+    return `${item.label} (${code(item.id)})`;
+}
+function groupName(group) {
+    if (group.group === 'option')
+        return 'Chose';
+    if (group.group === 'card')
+        return 'Cards';
+    return group.group === 'row' ? 'Rows' : 'Columns';
+}
+function groupLines(group) {
+    return [`${groupName(group)}: ${group.picked.length === 0 ? 'none' : group.picked.map(item).join(', ')}`];
+}
+function commentLines(comment) {
+    const prefix = comment.anchor.kind === 'whole' ? 'Comment: ' : `Comment on ${inline(comment.anchorLabel)}: `;
+    return verbatim(prefix, comment.text);
+}
+function shape(slot) {
+    if (slot.kind === 'options')
+        return `options, ${slot.groups[0]?.mode === 'single' ? 'pick one' : 'pick any'}`;
+    if (slot.kind === 'text') {
+        if (slot.text?.singleLine === true)
+            return `one-line text, ${slot.text.edited ? 'edited' : 'unchanged'}`;
+        return `text, ${slot.text?.edited === true ? 'edited' : 'accepted as written'}`;
+    }
+    if (slot.kind === 'table') {
+        const group = slot.groups.find((candidate) => candidate.group === 'row') ?? slot.groups.find((candidate) => candidate.group === 'column');
+        return `table, ${group === undefined ? 'no selection' : group.total > 0 ? `${group.picked.length} of ${group.total} ${group.group}s` : `${group.picked.length} ${group.group}${group.picked.length === 1 ? '' : 's'}`}`;
+    }
+    if (slot.kind === 'cards') {
+        const cards = slot.groups[0];
+        return `cards, ${cards?.total && cards.total > 0 ? `${cards.picked.length} of ${cards.total} cards` : `${cards?.picked.length ?? 0} cards`}`;
+    }
+    return slot.kind;
+}
+function slotHeading(slot, totalSlots) {
+    if (slot.label !== undefined && slot.label !== '')
+        return `**${slot.label}** — ${shape(slot)}`;
+    if (totalSlots === 1)
+        return undefined;
+    return `${code(slot.id)} — ${shape(slot)}`;
+}
+function slotLines(slot, totalSlots) {
+    const lines = [];
+    const heading = slotHeading(slot, totalSlots);
+    if (heading !== undefined)
+        lines.push(heading);
+    if (slot.raw !== undefined) {
+        lines.push(`Custom component (${code(slot.kind)}) response: ${JSON.stringify(slot.raw)}`);
+    }
+    else if (slot.text !== undefined) {
+        // A one-line field always shows its value inline — quoted, or "(left empty)" — because the
+        // whole answer is that one string; the heading already carries whether it was edited.
+        if (slot.text.singleLine === true || slot.text.edited)
+            lines.push(...verbatim('', slot.text.value));
+        else
+            lines.push('Accepted as written, unchanged');
+    }
+    else {
+        for (const group of slot.groups)
+            lines.push(...groupLines(group));
+        if (slot.freetext !== undefined)
+            lines.push(...verbatim('Other: ', slot.freetext));
+    }
+    for (const comment of slot.comments)
+        lines.push(...commentLines(comment));
+    return lines;
+}
+/** Render a PageAnswer as the deterministic Markdown report delivered to its asking agent. */
+export function renderAnswerText(answer, responsePath) {
+    if (answer.kind === 'acknowledgement') {
+        return [
+            `The user saw **${answer.title}** and dismissed it. The page asked for nothing, so the acknowledgement is the whole answer.`,
+            '',
+            `Acknowledged ${answer.completedAt}. Response record: ${responsePath}`,
+        ].join('\n');
+    }
+    const answered = answer.slots.filter((slot) => slot.state === 'answered');
+    const lines = [`The user answered **${answer.title}**.`];
+    for (const slot of answered)
+        lines.push('', ...slotLines(slot, answer.slots.length));
+    lines.push('', `Answered ${answer.completedAt}. Typed responses: ${responsePath}`);
+    return lines.join('\n');
+}

package/dist/core/human/answer.d.ts

@@ -0,0 +1,53 @@
+import { type CommentAnchor, type PageResponses, type PageSlot } from './page-schema.js';
+export type PageAnswer = {
+    title: string;
+    subtitle?: string;
+    completedAt: string;
+    kind: 'answer' | 'acknowledgement';
+    digest: string;
+    slots: PageAnswerSlot[];
+};
+export type PageAnswerSlot = {
+    id: string;
+    kind: string;
+    label?: string;
+    state: 'answered' | 'unanswered';
+    blank: boolean;
+    groups: PageAnswerGroup[];
+    freetext?: string;
+    /** `singleLine` marks a one-line input, whose value is worth echoing even when unchanged. */
+    text?: {
+        value: string;
+        edited: boolean;
+        singleLine?: boolean;
+    };
+    comments: PageAnswerComment[];
+    raw?: Record<string, unknown>;
+};
+export type PageAnswerGroup = {
+    group: 'option' | 'card' | 'row' | 'column';
+    mode: 'single' | 'multi';
+    total: number;
+    picked: {
+        id: string;
+        label: string;
+    }[];
+};
+/** Stored responses predating the `whole` anchor's removal still carry it; answers keep rendering them. */
+export type LegacyCommentAnchor = CommentAnchor | {
+    kind: 'whole';
+};
+export type PageAnswerComment = {
+    anchor: LegacyCommentAnchor;
+    anchorLabel: string;
+    text: string;
+};
+export interface DescribePageAnswerOptions {
+    completedAt: string;
+}
+export declare function answerCommentAnchorLabel(slot: PageSlot, anchor: LegacyCommentAnchor): string;
+/** Derive the one shared answer model from the immutable page manifest and a response map. */
+/** `manifest` is unknown deliberately: this boundary validates persisted JSON before deriving. */
+export declare function describePageAnswer(manifest: unknown, responses: PageResponses, opts: DescribePageAnswerOptions): PageAnswer;
+/** The stable one-line digest stored in response.json and shown in history. */
+export declare function buildAnswerDigest(slots: PageAnswerSlot[]): string;

package/dist/core/human/answer.js

@@ -0,0 +1,119 @@
+import { isResponseBearingSlot, validatePageManifest, } from './page-schema.js';
+function hasOwn(object, key) {
+    return Object.prototype.hasOwnProperty.call(object, key);
+}
+function responseRecord(response) {
+    return response !== null && typeof response === 'object' ? response : {};
+}
+function strings(value) {
+    return Array.isArray(value) ? value.filter((item) => typeof item === 'string') : [];
+}
+function comments(value) {
+    return Array.isArray(value) ? value.filter((item) => item !== null && typeof item === 'object' && 'anchor' in item && 'text' in item) : [];
+}
+function picked(ids, items) {
+    const labels = new Map(items.map((item) => [item.id, item.label]));
+    return ids.map((id) => ({ id, label: labels.get(id) ?? id }));
+}
+function rowLabel(config, id) {
+    const row = config.rows?.find((candidate) => candidate.id === id);
+    const firstColumn = config.columns[0];
+    if (row === undefined || firstColumn === undefined || !hasOwn(row.cells, firstColumn.id))
+        return id;
+    return String(row.cells[firstColumn.id]);
+}
+function slotLabel(slot) {
+    const label = slot.config.label;
+    return typeof label === 'string' && label !== '' ? label : slot.id ?? slot.kind;
+}
+export function answerCommentAnchorLabel(slot, anchor) {
+    if (anchor.kind === 'whole')
+        return slotLabel(slot); // legacy stored data only; new anchors are option/row
+    if (anchor.kind === 'option')
+        return slot.config.options.find((option) => option.id === anchor.optionId)?.label ?? anchor.optionId;
+    return rowLabel(slot.config, anchor.rowId);
+}
+function describeComments(slot, response) {
+    return comments(response.comments).map((comment) => ({ anchor: comment.anchor, anchorLabel: answerCommentAnchorLabel(slot, comment.anchor), text: comment.text }));
+}
+function describeSlot(slot, response) {
+    const state = response === undefined ? 'unanswered' : 'answered';
+    const value = responseRecord(response);
+    const configLabel = slot.config.label;
+    const base = {
+        id: slot.id,
+        kind: slot.kind,
+        ...(typeof configLabel === 'string' && configLabel !== '' ? { label: configLabel } : {}),
+        state,
+    };
+    if (slot.unvalidated === true) {
+        return { ...base, blank: response === undefined, groups: [], comments: [], ...(response === undefined ? {} : { raw: value }) };
+    }
+    if (slot.kind === 'options') {
+        const config = slot.config;
+        const freetext = typeof value.freetext === 'string' && value.freetext !== '' ? value.freetext : undefined;
+        const group = { group: 'option', mode: config.mode, total: config.options.length, picked: picked(strings(value.selectedOptionIds), config.options) };
+        return { ...base, blank: group.picked.length === 0 && freetext === undefined, groups: [group], ...(freetext === undefined ? {} : { freetext }), comments: describeComments(slot, value) };
+    }
+    if (slot.kind === 'text') {
+        const text = value;
+        const written = typeof text.text === 'string' ? text.text : '';
+        const singleLine = slot.config.singleLine === true;
+        return { ...base, blank: singleLine && written === '', groups: [], text: { value: written, edited: text.edited === true, ...(singleLine ? { singleLine: true } : {}) }, comments: [] };
+    }
+    if (slot.kind === 'table') {
+        const config = slot.config;
+        const groups = [];
+        if (config.rowSelect === 'single' || config.rowSelect === 'multi')
+            groups.push({ group: 'row', mode: config.rowSelect, total: config.rows?.length ?? 0, picked: strings(value.selectedRowIds).map((id) => ({ id, label: rowLabel(config, id) })) });
+        if (config.columnSelect === 'single' || config.columnSelect === 'multi')
+            groups.push({ group: 'column', mode: config.columnSelect, total: config.columns.length, picked: picked(strings(value.selectedColumnIds), config.columns) });
+        return { ...base, blank: groups.every((group) => group.picked.length === 0), groups, comments: describeComments(slot, value) };
+    }
+    if (slot.kind === 'cards') {
+        const config = slot.config;
+        const cards = (config.cards ?? []).map((card) => ({ id: card.id, label: card.title }));
+        const group = { group: 'card', mode: config.mode, total: cards.length, picked: picked(strings(value.selectedCardIds), cards) };
+        return { ...base, blank: group.picked.length === 0, groups: [group], comments: [] };
+    }
+    throw new Error(`slot "${slot.id}" kind "${slot.kind}" does not accept a response`);
+}
+/** Derive the one shared answer model from the immutable page manifest and a response map. */
+/** `manifest` is unknown deliberately: this boundary validates persisted JSON before deriving. */
+export function describePageAnswer(manifest, responses, opts) {
+    const page = validatePageManifest(manifest);
+    const slots = page.slots.filter(isResponseBearingSlot).map((slot) => describeSlot(slot, hasOwn(responses, slot.id) ? responses[slot.id] : undefined));
+    const answered = slots.filter((slot) => slot.state === 'answered');
+    return {
+        title: page.title,
+        ...(page.subtitle === undefined ? {} : { subtitle: page.subtitle }),
+        completedAt: opts.completedAt,
+        kind: slots.length === 0 ? 'acknowledgement' : 'answer',
+        digest: buildAnswerDigest(answered),
+        slots,
+    };
+}
+function groupDigest(group) {
+    if (group.picked.length === 0)
+        return 'no selection';
+    if (group.group === 'option' || group.group === 'card')
+        return group.picked.map((item) => item.label).join(', ');
+    return group.total > 0 ? `${group.picked.length} of ${group.total} ${group.group}s` : `${group.picked.length} ${group.group}${group.picked.length === 1 ? '' : 's'}`;
+}
+/** The stable one-line digest stored in response.json and shown in history. */
+export function buildAnswerDigest(slots) {
+    return slots.map((slot) => {
+        if (slot.raw !== undefined)
+            return `${slot.kind} response`;
+        // A one-line answer IS its value; "edited" would say nothing about what was typed.
+        if (slot.text !== undefined) {
+            if (slot.text.singleLine === true)
+                return slot.text.value === '' ? 'empty' : slot.text.value;
+            return slot.text.edited ? 'edited' : 'unchanged';
+        }
+        const groups = slot.groups.map(groupDigest);
+        if (slot.freetext !== undefined)
+            groups.push(slot.freetext);
+        return groups.join(', ') || 'no selection';
+    }).join(' · ');
+}

package/dist/core/human/component-docs.d.ts

@@ -0,0 +1,18 @@
+import type { PageComponentRegistration } from '../../types.js';
+export interface ComponentDoc {
+    /** Registry names this doc covers. A family (Card, CardHeader, …) shares one contract. */
+    names: readonly string[];
+    /** `structural` builds the page, `slot` is a registry component that gets its own manifest
+     * record (and, unless display-only, its own response), `display` is presentation only. */
+    group: 'structural' | 'slot' | 'display';
+    selectionLine: string;
+    contract: string;
+}
+export declare const BUILTIN_COMPONENT_DOCS: readonly ComponentDoc[];
+/** The structural and response-bearing rows — the ones that decide what a page can ask. `human -h` carries these;
+ * the display set is one line there and the full catalog is `human components list`. */
+export declare const CORE_COMPONENT_SELECTION_LINES: string[];
+export declare function componentDoc(name: string): ComponentDoc | undefined;
+export declare function componentNames(productComponents: readonly PageComponentRegistration[]): string[];
+export declare function renderComponentCatalog(productComponents: readonly PageComponentRegistration[]): string;
+export declare function renderComponentContract(name: string, productComponents: readonly PageComponentRegistration[]): string | undefined;