@north-light/crouter 0.3.192 → 0.3.194

package/dist/core/human/page-schema.js

@@ -0,0 +1,291 @@
+import { z } from 'zod';
+import { BUILTIN_PAGE_KINDS, isRegisteredPageKind } from './page-catalog.js';
+export const PAGE_SLOT_ID_PATTERN = /^[A-Za-z0-9_-]{1,64}$/;
+const idSchema = z.string().regex(PAGE_SLOT_ID_PATTERN, { error: 'slot id must match /^[A-Za-z0-9_-]{1,64}$/' });
+const itemIdSchema = z.string().min(1);
+const selectModeSchema = z.enum(['none', 'single', 'multi']);
+const jsonObjectSchema = z.record(z.string(), z.unknown());
+function uniqueIds(items, ctx, label) {
+    const seen = new Set();
+    items.forEach((item, index) => {
+        if (seen.has(item.id))
+            ctx.addIssue({ code: 'custom', path: [index, 'id'], message: `duplicate ${label} id "${item.id}"` });
+        seen.add(item.id);
+    });
+}
+export const commentAnchorSchema = z.discriminatedUnion('kind', [
+    z.object({ kind: z.literal('whole') }).strict(),
+    z.object({ kind: z.literal('option'), optionId: itemIdSchema }).strict(),
+    z.object({ kind: z.literal('row'), rowId: itemIdSchema }).strict(),
+    z.object({ kind: z.literal('column'), columnId: itemIdSchema }).strict(),
+    z.object({ kind: z.literal('card'), cardId: itemIdSchema }).strict(),
+    z.object({ kind: z.literal('range'), start: z.number().int().nonnegative(), end: z.number().int().nonnegative(), quote: z.string() }).strict().superRefine((anchor, ctx) => {
+        if (anchor.end < anchor.start)
+            ctx.addIssue({ code: 'custom', path: ['end'], message: 'range end must be greater than or equal to start' });
+    }),
+]);
+export const commentSchema = z.object({ id: z.string().min(1), anchor: commentAnchorSchema, text: z.string() }).strict();
+export const optionSchema = z.object({ id: itemIdSchema, label: z.string().min(1), description: z.string().optional() }).strict();
+export const optionsConfigSchema = z.object({
+    options: z.array(optionSchema).min(1).superRefine((items, ctx) => uniqueIds(items, ctx, 'option')),
+    mode: z.enum(['single', 'multi']),
+    allowFreetext: z.boolean().optional(),
+    freetextLabel: z.string().optional(),
+    freetextPlaceholder: z.string().optional(),
+}).strict();
+export const optionsResponseSchema = z.object({ selectedOptionIds: z.array(itemIdSchema), comments: z.array(commentSchema), freetext: z.string().optional() }).strict();
+export const textConfigSchema = z.object({ initialText: z.string(), editable: z.boolean().optional(), placeholder: z.string().optional() }).strict();
+export const textResponseSchema = z.object({ text: z.string(), edited: z.boolean(), comments: z.array(commentSchema) }).strict();
+export const tableColumnSchema = z.object({ id: itemIdSchema, label: z.string().min(1), align: z.enum(['left', 'right']).optional(), mono: z.boolean().optional() }).strict();
+export const tableCellSchema = z.union([z.string(), z.number(), z.boolean(), z.null()]);
+export const tableRowSchema = z.object({ id: itemIdSchema, cells: z.record(z.string(), tableCellSchema) }).strict();
+export const tableConfigSchema = z.object({
+    columns: z.array(tableColumnSchema).min(1).superRefine((items, ctx) => uniqueIds(items, ctx, 'column')),
+    rows: z.array(tableRowSchema).superRefine((items, ctx) => uniqueIds(items, ctx, 'row')).optional(),
+    source: z.string().optional(),
+    rowSelect: selectModeSchema.default('none'),
+    columnSelect: selectModeSchema.default('none'),
+    caption: z.string().optional(),
+}).strict().superRefine((config, ctx) => {
+    if (config.rows !== undefined && config.source !== undefined)
+        ctx.addIssue({ code: 'custom', message: 'table rows and source are mutually exclusive' });
+});
+export const tableResponseSchema = z.object({ selectedRowIds: z.array(itemIdSchema), selectedColumnIds: z.array(itemIdSchema), comments: z.array(commentSchema) }).strict();
+export const cardSchema = z.object({ id: itemIdSchema, title: z.string().min(1), subtitle: z.string().optional(), body: z.string().optional(), tag: z.string().optional() }).strict();
+export const cardsConfigSchema = z.object({
+    cards: z.array(cardSchema).superRefine((items, ctx) => uniqueIds(items, ctx, 'card')).optional(),
+    source: z.string().optional(),
+    mode: z.enum(['single', 'multi']),
+    columns: z.union([z.literal(2), z.literal(3)]).optional(),
+}).strict().superRefine((config, ctx) => {
+    if (config.cards !== undefined && config.source !== undefined)
+        ctx.addIssue({ code: 'custom', message: 'cards data and source are mutually exclusive' });
+});
+export const cardsResponseSchema = z.object({ selectedCardIds: z.array(itemIdSchema), comments: z.array(commentSchema) }).strict();
+export const chartSeriesSchema = z.object({ field: z.string().min(1), label: z.string().optional() }).strict();
+export const chartConfigSchema = z.object({
+    kind: z.enum(['line', 'bar', 'area']),
+    x: z.string().min(1),
+    y: z.array(chartSeriesSchema).min(1),
+    title: z.string().optional(),
+    data: z.unknown().optional(),
+    source: z.string().optional(),
+}).strict();
+const sourceSchema = z.object({ sessionName: z.string().optional(), askedBy: z.string().optional(), blockedSince: z.string().optional(), nodeId: z.string().optional() }).strict();
+const rawSlotSchema = z.object({ id: idSchema.optional(), kind: z.string().min(1), step: z.number().int().nonnegative(), config: jsonObjectSchema, unvalidated: z.literal(true).optional() }).strict();
+const rawPageManifestSchema = z.object({
+    schema: z.literal('crtr.page/v1'),
+    dialect: z.enum(['md', 'html']),
+    title: z.string().trim().min(1),
+    subtitle: z.string().optional(),
+    placement: z.enum(['inline', 'panel']),
+    document: z.enum(['page.md', 'page.html']),
+    steps: z.number().int().positive(),
+    slots: z.array(rawSlotSchema),
+    source: sourceSchema.optional(),
+}).strict();
+const configSchemas = {
+    options: optionsConfigSchema,
+    text: textConfigSchema,
+    table: tableConfigSchema,
+    cards: cardsConfigSchema,
+    chart: chartConfigSchema,
+};
+function issueText(error) {
+    return error.issues.map((issue) => `${issue.path.length === 0 ? 'value' : issue.path.join('.')}: ${issue.message}`).join('; ');
+}
+/** The canonical response-bearing predicate used by every page consumer. */
+export function isResponseBearingSlot(slot) {
+    if (slot.unvalidated === true)
+        return true;
+    if (slot.kind === 'options' || slot.kind === 'text' || slot.kind === 'cards')
+        return true;
+    if (slot.kind !== 'table')
+        return false;
+    const config = slot.config;
+    return (config.rowSelect ?? 'none') !== 'none' || (config.columnSelect ?? 'none') !== 'none';
+}
+/** Validate and normalize a derived or stored manifest against the resolved product catalog. */
+export function validatePageManifest(parsed, productKinds = []) {
+    const manifest = rawPageManifestSchema.parse(parsed);
+    if (manifest.document !== (manifest.dialect === 'md' ? 'page.md' : 'page.html'))
+        throw new Error(`page document "${manifest.document}" does not match ${manifest.dialect} dialect`);
+    if (manifest.dialect === 'md' && manifest.steps !== 1)
+        throw new Error(`md page steps must be 1; received ${manifest.steps}`);
+    const seen = new Set();
+    const slots = manifest.slots.map((raw, index) => {
+        if (raw.step >= manifest.steps)
+            throw new Error(`slot ${raw.id === undefined ? `#${index}` : `"${raw.id}"`} has step ${raw.step}, outside page steps ${manifest.steps}`);
+        let slot;
+        if (BUILTIN_PAGE_KINDS.includes(raw.kind)) {
+            if (raw.unvalidated === true)
+                throw new Error(`built-in slot kind "${raw.kind}" cannot be unvalidated`);
+            const result = configSchemas[raw.kind].safeParse(raw.config);
+            if (!result.success)
+                throw new Error(`invalid config for slot ${raw.id === undefined ? `#${index}` : `"${raw.id}"`} (${raw.kind}): ${issueText(result.error)}`);
+            slot = { ...(raw.id === undefined ? {} : { id: raw.id }), kind: raw.kind, step: raw.step, config: result.data };
+        }
+        else {
+            if (!isRegisteredPageKind(raw.kind, productKinds))
+                throw new Error(`unregistered page slot kind "${raw.kind}" at slot #${index}`);
+            if (raw.unvalidated !== true)
+                throw new Error(`registered product slot kind "${raw.kind}" must set unvalidated: true`);
+            slot = { ...(raw.id === undefined ? {} : { id: raw.id }), kind: raw.kind, step: raw.step, config: raw.config, unvalidated: true };
+        }
+        if (isResponseBearingSlot(slot) && slot.id === undefined)
+            throw new Error(`response-bearing slot kind "${slot.kind}" at slot #${index} requires an id`);
+        if (slot.id !== undefined) {
+            if (seen.has(slot.id))
+                throw new Error(`duplicate slot id "${slot.id}"`);
+            seen.add(slot.id);
+        }
+        return slot;
+    });
+    return { ...manifest, slots };
+}
+export function createPageManifestSchema(productKinds = []) {
+    return z.custom((value) => {
+        try {
+            validatePageManifest(value, productKinds);
+            return true;
+        }
+        catch {
+            return false;
+        }
+    }, { error: 'invalid page manifest' }).transform((value) => validatePageManifest(value, productKinds));
+}
+/** Built-in-only manifest schema; product-aware callers use createPageManifestSchema. */
+export const pageManifestSchema = createPageManifestSchema();
+function assertUnique(values, slotId, field) {
+    if (new Set(values).size !== values.length)
+        throw new Error(`slot "${slotId}" has duplicate id in ${field}`);
+}
+function validateComments(slot, comments) {
+    const config = slot.config;
+    for (const comment of comments) {
+        const anchor = comment.anchor;
+        if (anchor.kind === 'whole')
+            continue;
+        if (slot.kind === 'options' && anchor.kind === 'option') {
+            if (!config.options.some((option) => option.id === anchor.optionId))
+                throw new Error(`slot "${slot.id}" comment names unknown option id "${anchor.optionId}"`);
+            continue;
+        }
+        if (slot.kind === 'text' && anchor.kind === 'range')
+            continue;
+        if (slot.kind === 'table' && anchor.kind === 'row') {
+            if (!(config.rows ?? []).some((row) => row.id === anchor.rowId))
+                throw new Error(`slot "${slot.id}" comment names unknown row id "${anchor.rowId}"`);
+            continue;
+        }
+        if (slot.kind === 'table' && anchor.kind === 'column') {
+            if (!config.columns.some((column) => column.id === anchor.columnId))
+                throw new Error(`slot "${slot.id}" comment names unknown column id "${anchor.columnId}"`);
+            continue;
+        }
+        if (slot.kind === 'cards' && anchor.kind === 'card') {
+            if (!(config.cards ?? []).some((card) => card.id === anchor.cardId))
+                throw new Error(`slot "${slot.id}" comment names unknown card id "${anchor.cardId}"`);
+            continue;
+        }
+        throw new Error(`slot "${slot.id}" does not allow comment anchor kind "${anchor.kind}"`);
+    }
+}
+function parseResponse(slot, raw) {
+    if (slot.unvalidated === true) {
+        const result = jsonObjectSchema.safeParse(raw);
+        if (!result.success)
+            throw new Error(`response for unvalidated slot "${slot.id}" must be an object`);
+        return result.data;
+    }
+    if (slot.kind === 'options') {
+        const result = optionsResponseSchema.safeParse(raw);
+        if (!result.success)
+            throw new Error(`invalid response for slot "${slot.id}": ${issueText(result.error)}`);
+        const response = result.data;
+        const config = slot.config;
+        assertUnique(response.selectedOptionIds, slot.id, 'selectedOptionIds');
+        for (const id of response.selectedOptionIds)
+            if (!config.options.some((option) => option.id === id))
+                throw new Error(`slot "${slot.id}" selects unknown option id "${id}"`);
+        if (response.freetext !== undefined && config.allowFreetext !== true)
+            throw new Error(`slot "${slot.id}" does not allow freetext`);
+        if (config.mode === 'single' && response.selectedOptionIds.length > 1)
+            throw new Error(`slot "${slot.id}" is single-select but received ${response.selectedOptionIds.length} option ids`);
+        const hasFreetext = config.allowFreetext === true && (response.freetext?.trim() ?? '') !== '';
+        if (config.mode === 'single' && response.selectedOptionIds.length !== 1 && !hasFreetext)
+            throw new Error(`single-select slot "${slot.id}" requires exactly one selection or nonempty allowed freetext`);
+        if (config.mode === 'multi' && response.selectedOptionIds.length === 0 && response.comments.length === 0 && !hasFreetext)
+            throw new Error(`multi-select slot "${slot.id}" requires a selection, comment, or nonempty allowed freetext`);
+        validateComments(slot, response.comments);
+        return response;
+    }
+    if (slot.kind === 'text') {
+        const result = textResponseSchema.safeParse(raw);
+        if (!result.success)
+            throw new Error(`invalid response for slot "${slot.id}": ${issueText(result.error)}`);
+        validateComments(slot, result.data.comments);
+        return result.data;
+    }
+    if (slot.kind === 'table') {
+        const result = tableResponseSchema.safeParse(raw);
+        if (!result.success)
+            throw new Error(`invalid response for slot "${slot.id}": ${issueText(result.error)}`);
+        const response = result.data;
+        const config = slot.config;
+        assertUnique(response.selectedRowIds, slot.id, 'selectedRowIds');
+        assertUnique(response.selectedColumnIds, slot.id, 'selectedColumnIds');
+        const rowIds = new Set((config.rows ?? []).map((row) => row.id));
+        const columnIds = new Set(config.columns.map((column) => column.id));
+        for (const id of response.selectedRowIds)
+            if (!rowIds.has(id))
+                throw new Error(`slot "${slot.id}" selects unknown row id "${id}"`);
+        for (const id of response.selectedColumnIds)
+            if (!columnIds.has(id))
+                throw new Error(`slot "${slot.id}" selects unknown column id "${id}"`);
+        if ((config.rowSelect === 'none' && response.selectedRowIds.length > 0) || (config.rowSelect === 'single' && response.selectedRowIds.length > 1))
+            throw new Error(`slot "${slot.id}" response violates row select mode "${config.rowSelect}"`);
+        if ((config.columnSelect === 'none' && response.selectedColumnIds.length > 0) || (config.columnSelect === 'single' && response.selectedColumnIds.length > 1))
+            throw new Error(`slot "${slot.id}" response violates column select mode "${config.columnSelect}"`);
+        validateComments(slot, response.comments);
+        return response;
+    }
+    if (slot.kind === 'cards') {
+        const result = cardsResponseSchema.safeParse(raw);
+        if (!result.success)
+            throw new Error(`invalid response for slot "${slot.id}": ${issueText(result.error)}`);
+        const response = result.data;
+        const config = slot.config;
+        assertUnique(response.selectedCardIds, slot.id, 'selectedCardIds');
+        for (const id of response.selectedCardIds)
+            if (!(config.cards ?? []).some((card) => card.id === id))
+                throw new Error(`slot "${slot.id}" selects unknown card id "${id}"`);
+        if (config.mode === 'single' && response.selectedCardIds.length > 1)
+            throw new Error(`slot "${slot.id}" is single-select but received ${response.selectedCardIds.length} card ids`);
+        validateComments(slot, response.comments);
+        return response;
+    }
+    throw new Error(`slot "${slot.id}" kind "${slot.kind}" does not accept a response`);
+}
+function validateResponses(manifest, raw, partial) {
+    const result = jsonObjectSchema.safeParse(raw);
+    if (!result.success)
+        throw new Error('page responses must be an object keyed by slot id');
+    const expected = new Map(manifest.slots.filter(isResponseBearingSlot).map((slot) => [slot.id, slot]));
+    const responses = {};
+    for (const [id, value] of Object.entries(result.data)) {
+        const slot = expected.get(id);
+        if (slot === undefined)
+            throw new Error(`response names unknown or non-response-bearing slot id "${id}"`);
+        responses[id] = parseResponse(slot, value);
+    }
+    if (!partial)
+        for (const id of expected.keys())
+            if (!(id in responses))
+                throw new Error(`final page response is missing response-bearing slot id "${id}"`);
+    return responses;
+}
+/** Validate a complete final response map. */
+export function validatePageResponses(manifest, responses) { return validateResponses(manifest, responses, false); }
+/** Validate an autosaved response map, permitting omitted response-bearing slots. */
+export function validatePartialPageResponses(manifest, responses) { return validateResponses(manifest, responses, true); }

package/dist/core/human/page-synth.d.ts

@@ -0,0 +1,9 @@
+/** The single response slot every synthesized question page carries. */
+export declare const ASK_RESPONSE_SLOT = "```slot:text\n{ \"id\": \"response\", \"initialText\": \"\", \"editable\": true }\n```";
+/** Build a page document from title/subtitle/body — the shape crtr synthesizes when no page file is authored. */
+export declare function synthesizedPageDocument(title: string, subtitle: string, body: string, responseBearing: boolean): string;
+/** Materialize a synthesized document into a private temp dir; the caller removes that dir once submitted. */
+export declare function writeSynthesizedPage(document: string): {
+    dir: string;
+    path: string;
+};

package/dist/core/human/page-synth.js

@@ -0,0 +1,17 @@
+import { join } from 'node:path';
+import { mkdtempSync, writeFileSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+/** The single response slot every synthesized question page carries. */
+export const ASK_RESPONSE_SLOT = '```slot:text\n{ "id": "response", "initialText": "", "editable": true }\n```';
+/** Build a page document from title/subtitle/body — the shape crtr synthesizes when no page file is authored. */
+export function synthesizedPageDocument(title, subtitle, body, responseBearing) {
+    const slot = responseBearing ? `\n\n${ASK_RESPONSE_SLOT}` : '';
+    return `---\ntitle: ${title}\nsubtitle: ${subtitle}\n---\n\n${body}${slot}\n`;
+}
+/** Materialize a synthesized document into a private temp dir; the caller removes that dir once submitted. */
+export function writeSynthesizedPage(document) {
+    const dir = mkdtempSync(join(tmpdir(), 'crtr-human-page-'));
+    const path = join(dir, 'page.md');
+    writeFileSync(path, document, { encoding: 'utf8', mode: 0o600 });
+    return { dir, path };
+}

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

@@ -0,0 +1,22 @@
+import { type PageManifest, type PageSource } from './page-schema.js';
+export type PageDialect = 'md' | 'html';
+export type PageSourceBlock = {
+    kind: 'prose';
+    markdown: string;
+} | {
+    kind: 'slot';
+    slotIndex: number;
+};
+export type PageSourceProjection = PageSourceBlock[];
+/** A page failed authoring or validation; the caller can report it as bad page input. */
+export declare class PageAuthoringError extends Error {
+    constructor(message: string);
+}
+/** Derive the transport manifest from one authored page document. */
+export declare function derivePageManifestFromDocument(document: string, dialect: PageDialect, productKinds?: string[], source?: PageSource): PageManifest;
+/** Derive the transport manifest from one authored page source file. */
+export declare function derivePageManifest(sourceFile: string, dialect: PageDialect, productKinds?: string[], source?: PageSource): PageManifest;
+/** Read and validate page.json from a ticket directory. */
+export declare function parsePage(dir: string, productKinds?: string[]): PageManifest;
+/** Project authored source for local rendering and verify its slot references against the manifest. */
+export declare function parsePageSource(document: string, manifest: PageManifest, productKinds?: string[]): PageSourceProjection;