@north-light/cli 0.0.0 → 0.3.414

package/dist/core/host-exports/builtins.js

@@ -0,0 +1,9 @@
+var s=Object.defineProperty;var t=(r,n)=>s(r,"name",{value:n,configurable:!0});import{userFilesRoot as e}from"../layout.js";import{join as o}from"node:path";import{collectSlashSpecs as c}from"../command.js";import{piAgentDir as l}from"../runtime/package-health.js";const u="<!-- crtr-mode-cmd v1 -->",a="<!-- crtr-mode-cmd v";function m(r){const n=r.argumentHint!==void 0?`argument-hint: ${JSON.stringify(r.argumentHint)}
+`:"";return`---
+description: ${r.description}
+${n}---
+
+${u}
+
+${r.body}
+`}t(m,"renderSlashTemplate");function d(){return o(e(),".claude","skills")}t(d,"claudeSkillsRoot");function p(){return o(l(),"skills")}t(p,"piSkillsRoot");function f(){return o(e(),".claude","commands")}t(f,"claudeCommandsRoot");function R(){return o(l(),"prompts")}t(R,"piPromptsRoot");const S="<!-- crtr-boot-skill v";function A(){return[{id:"@legacy/crtr-skills",name:"crtr-skills",markerPrefix:S,targets:[{host:"claude",dir:d,layout:"bundle"},{host:"pi",dir:p,layout:"bundle"}]}]}t(A,"legacyExportArtifacts");function E(r){const n=[];for(const i of c(r))n.push({id:`@cmd/${i.name}`,name:i.name,markerPrefix:a,render:t(()=>m(i),"render"),targets:[{host:"claude",dir:f,layout:"file"},{host:"pi",dir:R,layout:"file"}]});return n}t(E,"builtinExportPairs");export{a as SLASH_CMD_MARKER_PREFIX,E as builtinExportPairs,A as legacyExportArtifacts};

package/dist/core/host-exports/export.d.ts

@@ -0,0 +1,31 @@
+/**
+ * One-way export of crtr-generated host artifacts — the sole writer of
+ * generated slash-command templates to `~/.claude/commands` and
+ * `~/.pi/agent/prompts`.
+ *
+ * crouter exports no Agent Skills / SKILL.md bundles. The export pass prunes
+ * marker-bearing `crtr-skills` bundles so hosts stop surfacing pi/Claude native
+ * skills. Markerless files are user-owned and never removed.
+ *
+ * Triggered per-run by cli.ts (argv-gated) so
+ * first-run provisioning is preserved. Best-effort: a provisioning fault must
+ * never break an unrelated `crtr` command (the deliberate, pre-existing
+ * behavior of the deleted writers).
+ */
+import type { RootDef } from '../command.js';
+/** Write `content` to `path` unless a user-customized file is already there.
+ *  Rolls forward our own (marker-bearing) versions; skips if identical. Creates
+ *  only the leaf dir, never the host root. The single generalization of
+ *  bootstrap.ts's two clobber-guards. */
+export declare function writeIfOurs(path: string, content: string, markerPrefix: string): void;
+/** Render and write every built-in export artifact to every present host, while
+ *  pruning legacy generated artifacts that should no longer be surfaced.
+ *  Best-effort: reports errors without breaking an unrelated `crtr` command.
+ *  Kill switch: `CRTR_NO_EXPORTS=1`. */
+export declare function pruneLegacyExports(argv?: string[]): void;
+/** Write every built-in export artifact to every present host. Split from the
+ *  prune above because the prune must run BEFORE the front door boots (stale
+ *  artifacts must not reach the prompt) while it needs no command tree, and
+ *  bare `crtr` skips the writes outright — so the front door never has to pay
+ *  for building the full command tree just to reach a no-op. */
+export declare function provisionExports(root: RootDef, argv?: string[]): void;

package/dist/core/host-exports/export.js

@@ -0,0 +1,3 @@
+var g=Object.defineProperty;var o=(r,t)=>g(r,"name",{value:t,configurable:!0});import{writeFileSync as l}from"node:fs";import{userFilesRoot as x}from"../layout.js";import{piAgentDir as S}from"../runtime/package-health.js";import{dirname as u,join as s}from"node:path";import{ensureDir as v,pathExists as i,readText as c,removePath as E}from"../fs-utils.js";import{envNoExports as m}from"../../shared/env.js";import{builtinExportPairs as h,legacyExportArtifacts as y}from"./builtins.js";const A=new Set(["help","--help","-h","--version","-v"]);function a(r){const t=r[2];return t!==void 0&&A.has(t)}o(a,"shouldSkipAllForArgv");function P(r){return r[2]===void 0}o(P,"shouldSkipWritesForArgv");function p(r){return r==="claude"?i(s(x(),".claude")):i(S())}o(p,"hostRootExists");function d(r,t){const e=r.dir();return r.layout==="bundle"?s(e,t,"SKILL.md"):s(e,`${t}.md`)}o(d,"targetPath");function w(r,t,e){if(i(r)){const n=c(r);if(!n.includes(e)||n===t)return}v(u(r)),l(r,t,"utf8")}o(w,"writeIfOurs");function b(r,t,e){!i(r)||!c(r).includes(e)||E(t.layout==="bundle"?u(r):r)}o(b,"removeIfOurs");function M(r=process.argv){try{if(m()||a(r))return;for(const t of y())for(const e of t.targets)p(e.host)&&b(d(e,t.name),e,t.markerPrefix)}catch(t){const e=t instanceof Error?t.message:String(t);process.stderr.write(`crtr: exports prune error: ${e}
+`)}}o(M,"pruneLegacyExports");function N(r,t=process.argv){try{if(m()||a(t)||P(t))return;for(const e of h(r)){const n=e.render();for(const f of e.targets)p(f.host)&&w(d(f,e.name),n,e.markerPrefix)}}catch(e){const n=e instanceof Error?e.message:String(e);process.stderr.write(`crtr: exports error: ${n}
+`)}}o(N,"provisionExports");export{N as provisionExports,M as pruneLegacyExports,w as writeIfOurs};

package/dist/core/human/action-binding.d.ts

@@ -0,0 +1,23 @@
+export declare const HUMAN_ACTION_NAME_PATTERN: RegExp;
+export interface TicketActionBinding {
+    schema: 'crtr.human-action-binding/v1';
+    /** Declared action name, matching HUMAN_ACTION_NAME_PATTERN. */
+    name: string;
+    /** Frozen creation payload; opaque JSON, never inspected. */
+    payload: unknown;
+    /** The creator's absolute cwd, captured verbatim. */
+    creatorCwd: string;
+    /** Absolute path of the config file that won resolution. */
+    configOrigin: string;
+    /** Fully resolved argv; argv[0] is an absolute executable path. */
+    argv: string[];
+    /** Fully resolved absolute working directory. */
+    cwd: string;
+    /** Originating app, retained when its node is later deleted. */
+    app?: string;
+}
+/** Publish the binding before the page exists, so a visible request is never
+ * unbound. A second write is a caller bug, not a race to tolerate. */
+export declare function publishTicketActionBinding(dir: string, binding: TicketActionBinding): void;
+/** The frozen binding, or null for a request with no completion action. */
+export declare function readTicketActionBinding(dir: string): TicketActionBinding | null;

package/dist/core/human/action-binding.js

@@ -0,0 +1 @@
+var e=Object.defineProperty;var t=(r,i)=>e(r,"name",{value:i,configurable:!0});import{readFileSync as c}from"node:fs";import{z as n}from"zod";import{actionBindingPath as o,publishJsonExclusive as s}from"./convention.js";const p=/^[A-Za-z0-9][A-Za-z0-9._-]{0,127}$/,d=n.object({schema:n.literal("crtr.human-action-binding/v1"),name:n.string().regex(p),payload:n.unknown(),creatorCwd:n.string().min(1),configOrigin:n.string().min(1),argv:n.array(n.string().min(1)).min(1),cwd:n.string().min(1),app:n.string().min(1).optional()}).strict();function h(r,i){if(!s(o(r),i))throw new Error(`action binding already exists: ${o(r)}`)}t(h,"publishTicketActionBinding");function A(r){let i;try{i=JSON.parse(c(o(r),"utf8"))}catch(a){if(a.code==="ENOENT")return null;throw a}return{...d.parse(i),payload:i.payload??null}}t(A,"readTicketActionBinding");export{p as HUMAN_ACTION_NAME_PATTERN,h as publishTicketActionBinding,A as readTicketActionBinding};

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

@@ -0,0 +1,5 @@
+import type { PageAnswer } from './answer.js';
+/** Render a PageAnswer as the deterministic Markdown report delivered to its asking agent.
+ *  The person sees this same prose in their own chat surface, so it carries the answer
+ *  itself and nothing addressed only to the agent. */
+export declare function renderAnswerText(answer: PageAnswer): string;

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

@@ -0,0 +1,5 @@
+var s=Object.defineProperty;var i=(e,n)=>s(e,"name",{value:n,configurable:!0});function c(e){return`\u201C${e}\u201D`}i(c,"inline");function u(e,n){return n===""?[`${e}(left empty)`]:n.includes(`
+`)?[...e===""?[]:[e.trimEnd()],...n.split(`
+`).map(t=>`> ${t}`)]:[`${e}${c(n)}`]}i(u,"verbatim");function o(e){const n="`".repeat(Math.max(0,...e.match(/`+/g)?.map(t=>t.length)??[0])+1);return`${n}${e}${n}`}i(o,"code");function p(e){return`${e.label} (${o(e.id)})`}i(p,"item");function a(e){return e.group==="option"?"Chose":e.group==="card"?"Cards":e.group==="row"?"Rows":"Columns"}i(a,"groupName");function $(e){return[`${a(e)}: ${e.picked.length===0?"none":e.picked.map(p).join(", ")}`]}i($,"groupLines");function h(e){const n=e.anchor.kind==="whole"?"Comment: ":`Comment on ${c(e.anchorLabel)}: `;return u(n,e.text)}i(h,"commentLines");function f(e){if(e.kind==="options")return`options, ${e.groups[0]?.mode==="single"?"pick one":"pick any"}`;if(e.kind==="text")return e.text?.singleLine===!0?`one-line text, ${e.text.edited?"edited":"unchanged"}`:`text, ${e.text?.edited===!0?"edited":"accepted as written"}`;if(e.kind==="table"){const n=e.groups.find(t=>t.group==="row")??e.groups.find(t=>t.group==="column");return`table, ${n===void 0?"no selection":n.total>0?`${n.picked.length} of ${n.total} ${n.group}s`:`${n.picked.length} ${n.group}${n.picked.length===1?"":"s"}`}`}if(e.kind==="cards"){const n=e.groups[0];return`cards, ${n?.total&&n.total>0?`${n.picked.length} of ${n.total} cards`:`${n?.picked.length??0} cards`}`}return e.kind}i(f,"shape");function g(e,n){if(e.label!==void 0&&e.label!=="")return`**${e.label}** \u2014 ${f(e)}`;if(n!==1)return`${o(e.id)} \u2014 ${f(e)}`}i(g,"slotHeading");function l(e,n){const t=[],r=g(e,n);if(r!==void 0&&t.push(r),e.raw!==void 0)t.push(`Custom component (${o(e.kind)}) response: ${JSON.stringify(e.raw)}`);else if(e.text!==void 0)e.text.singleLine===!0||e.text.edited?t.push(...u("",e.text.value)):t.push("Accepted as written, unchanged");else{for(const d of e.groups)t.push(...$(d));e.freetext!==void 0&&t.push(...u("Other: ",e.freetext))}for(const d of e.comments)t.push(...h(d));return t}i(l,"slotLines");function k(e){if(e.kind==="acknowledgement")return[`The user saw **${e.title}** and dismissed it. The page asked for nothing, so the acknowledgement is the whole answer.`,"",`Acknowledged ${e.completedAt}.`].join(`
+`);const n=e.slots.filter(r=>r.state==="answered"),t=[`The user answered **${e.title}**.`];for(const r of n)t.push("",...l(r,e.slots.length));return t.push("",`Answered ${e.completedAt}.`),t.join(`
+`)}i(k,"renderAnswerText");export{k as renderAnswerText};

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

@@ -0,0 +1,53 @@
+import { type PageCommentAnchor, 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 = PageCommentAnchor | {
+    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 the terminal request result and shown in history. */
+export declare function buildAnswerDigest(slots: PageAnswerSlot[]): string;

package/dist/core/human/answer.js

@@ -0,0 +1 @@
+var b=Object.defineProperty;var d=(e,n)=>b(e,"name",{value:n,configurable:!0});import{isResponseBearingSlot as k,validatePageManifest as w}from"./page-schema.js";function p(e,n){return Object.prototype.hasOwnProperty.call(e,n)}d(p,"hasOwn");function h(e){return e!==null&&typeof e=="object"?e:{}}d(h,"responseRecord");function s(e){return Array.isArray(e)?e.filter(n=>typeof n=="string"):[]}d(s,"strings");function x(e){return Array.isArray(e)?e.filter(n=>n!==null&&typeof n=="object"&&"anchor"in n&&"text"in n):[]}d(x,"comments");function a(e,n){const r=new Map(n.map(t=>[t.id,t.label]));return e.map(t=>({id:t,label:r.get(t)??t}))}d(a,"picked");function g(e,n){const r=e.rows?.find(u=>u.id===n),t=e.columns[0];return r===void 0||t===void 0||!p(r.cells,t.id)?n:String(r.cells[t.id])}d(g,"rowLabel");function y(e){const n=e.config.label;return typeof n=="string"&&n!==""?n:e.id??e.kind}d(y,"slotLabel");function A(e,n){return n.kind==="whole"?y(e):n.kind==="option"?e.config.options.find(r=>r.id===n.optionId)?.label??n.optionId:g(e.config,n.rowId)}d(A,"answerCommentAnchorLabel");function m(e,n){return x(n.comments).map(r=>({anchor:r.anchor,anchorLabel:A(e,r.anchor),text:r.text}))}d(m,"describeComments");function L(e,n){const r=n===void 0?"unanswered":"answered",t=h(n),u=e.config.label,l={id:e.id,kind:e.kind,...typeof u=="string"&&u!==""?{label:u}:{},state:r};if(e.unvalidated===!0)return{...l,blank:n===void 0,groups:[],comments:[],...n===void 0?{}:{raw:t}};if(e.kind==="options"){const i=e.config,o=typeof t.freetext=="string"&&t.freetext!==""?t.freetext:void 0,c={group:"option",mode:i.mode,total:i.options.length,picked:a(s(t.selectedOptionIds),i.options)};return{...l,blank:c.picked.length===0&&o===void 0,groups:[c],...o===void 0?{}:{freetext:o},comments:m(e,t)}}if(e.kind==="text"){const i=t,o=typeof i.text=="string"?i.text:"",c=e.config.singleLine===!0;return{...l,blank:c&&o==="",groups:[],text:{value:o,edited:i.edited===!0,...c?{singleLine:!0}:{}},comments:[]}}if(e.kind==="table"){const i=e.config,o=[];return(i.rowSelect==="single"||i.rowSelect==="multi")&&o.push({group:"row",mode:i.rowSelect,total:i.rows?.length??0,picked:s(t.selectedRowIds).map(c=>({id:c,label:g(i,c)}))}),(i.columnSelect==="single"||i.columnSelect==="multi")&&o.push({group:"column",mode:i.columnSelect,total:i.columns.length,picked:a(s(t.selectedColumnIds),i.columns)}),{...l,blank:o.every(c=>c.picked.length===0),groups:o,comments:m(e,t)}}if(e.kind==="cards"){const i=e.config,o=(i.cards??[]).map(f=>({id:f.id,label:f.title})),c={group:"card",mode:i.mode,total:o.length,picked:a(s(t.selectedCardIds),o)};return{...l,blank:c.picked.length===0,groups:[c],comments:[]}}throw new Error(`slot "${e.id}" kind "${e.kind}" does not accept a response`)}d(L,"describeSlot");function v(e,n,r){const t=w(e),u=t.slots.filter(k).map(i=>L(i,p(n,i.id)?n[i.id]:void 0)),l=u.filter(i=>i.state==="answered");return{title:t.title,...t.subtitle===void 0?{}:{subtitle:t.subtitle},completedAt:r.completedAt,kind:u.length===0?"acknowledgement":"answer",digest:$(l),slots:u}}d(v,"describePageAnswer");function S(e){return e.picked.length===0?"no selection":e.group==="option"||e.group==="card"?e.picked.map(n=>n.label).join(", "):e.total>0?`${e.picked.length} of ${e.total} ${e.group}s`:`${e.picked.length} ${e.group}${e.picked.length===1?"":"s"}`}d(S,"groupDigest");function $(e){return e.map(n=>{if(n.raw!==void 0)return`${n.kind} response`;if(n.text!==void 0)return n.text.singleLine===!0?n.text.value===""?"empty":n.text.value:n.text.edited?"edited":"unchanged";const r=n.groups.map(S);return n.freetext!==void 0&&r.push(n.freetext),r.join(", ")||"no selection"}).join(" \xB7 ")}d($,"buildAnswerDigest");export{A as answerCommentAnchorLabel,$ as buildAnswerDigest,v as describePageAnswer};

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

@@ -0,0 +1,23 @@
+export interface TicketClaim {
+    token: string;
+    host: string;
+    pid: number;
+    claimedAt: string;
+    heartbeatAt: string;
+    tmuxClient?: string;
+}
+export interface ClaimOptions {
+    host?: string;
+    pid?: number;
+    tmuxClient?: string;
+    now?: Date;
+}
+export declare function readTicketClaim(dir: string): TicketClaim | null;
+export declare function isStaleClaim(claim: TicketClaim, now?: number, localHost?: string): boolean;
+/** Exclude another live presenter; the daemon owns whether the request can settle. */
+export declare function claimTicket(dir: string, opts?: ClaimOptions): TicketClaim | null;
+export declare function heartbeatClaim(dir: string, token: string, now?: Date): boolean;
+export declare function releaseClaimLocked(dir: string, token: string): boolean;
+export declare function releaseClaim(dir: string, token: string): boolean;
+export declare function claimExists(dir: string): boolean;
+export declare function withTicketLock<T>(dir: string, operation: () => T): T;

package/dist/core/human/claim.js

@@ -0,0 +1,3 @@
+var x=Object.defineProperty;var n=(t,e)=>x(t,"name",{value:e,configurable:!0});import{existsSync as f,renameSync as y,unlinkSync as p,writeFileSync as h}from"node:fs";import{hostname as l}from"node:os";import{randomUUID as g}from"node:crypto";import{claimPath as o}from"./convention.js";import{readJsonOrNull as S}from"../fs-utils.js";import{withExclusiveDirectoryLock as a}from"../exclusive-lock.js";const b=3e4;function C(t){if(typeof t!="object"||t===null)return null;const e=t;return typeof e.token!="string"||typeof e.host!="string"||!Number.isInteger(e.pid)||typeof e.claimedAt!="string"||typeof e.heartbeatAt!="string"?null:{token:e.token,host:e.host,pid:e.pid,claimedAt:e.claimedAt,heartbeatAt:e.heartbeatAt,...typeof e.tmuxClient=="string"?{tmuxClient:e.tmuxClient}:{}}}n(C,"parseClaim");function u(t){return C(S(o(t)))}n(u,"readTicketClaim");function d(t){try{return process.kill(t,0),!0}catch{return!1}}n(d,"isLiveLocalPid");function A(t,e=Date.now(),r=l()){if(t.host===r)return!d(t.pid);const i=Date.parse(t.heartbeatAt);return!Number.isFinite(i)||e-i>b}n(A,"isStaleClaim");function I(t,e={}){return a(`${t}/.ticket-lock`,()=>{const r=o(t),i=u(t);if(i!==null&&!A(i,Date.now(),e.host??l()))return null;f(r)&&p(r);const c=e.host??l(),k=e.pid??process.pid,s=(e.now??new Date).toISOString(),m={token:g(),host:c,pid:k,claimedAt:s,heartbeatAt:s,...e.tmuxClient?{tmuxClient:e.tmuxClient}:{}};return h(r,`${JSON.stringify(m)}
+`,{flag:"wx",mode:384}),m})}n(I,"claimTicket");function J(t,e,r=new Date){return a(`${t}/.ticket-lock`,()=>{const i=u(t);if(i===null||i.token!==e)return!1;const c=`${o(t)}.${e}.heartbeat`;return h(c,`${JSON.stringify({...i,heartbeatAt:r.toISOString()})}
+`,{flag:"wx",mode:384}),y(c,o(t)),!0})}n(J,"heartbeatClaim");function w(t,e){const r=u(t);return r===null||r.token!==e?!1:(p(o(t)),!0)}n(w,"releaseClaimLocked");function _(t,e){return a(`${t}/.ticket-lock`,()=>w(t,e))}n(_,"releaseClaim");function v(t){return f(o(t))}n(v,"claimExists");function F(t,e){return a(`${t}/.ticket-lock`,e)}n(F,"withTicketLock");export{v as claimExists,I as claimTicket,J as heartbeatClaim,A as isStaleClaim,u as readTicketClaim,_ as releaseClaim,w as releaseClaimLocked,F as withTicketLock};

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

@@ -0,0 +1,38 @@
+import type { TicketActionBinding } from './action-binding.js';
+import type { PageSource } from './page-schema.js';
+import type { TicketResult } from './types.js';
+export type HumanCompletionEvent = 'answered' | 'dismissed' | 'canceled';
+export interface HumanCompletionV1 {
+    schema: 'crtr.human-completion/v1';
+    requestId: string;
+    event: HumanCompletionEvent;
+    settledAt: string;
+    /** Present only when `event` is `answered`; absent, never empty, otherwise. */
+    responses?: Record<string, Record<string, unknown>>;
+    action: {
+        name: string;
+        payload: unknown;
+    };
+    provenance: {
+        source: PageSource;
+        actor?: string;
+    };
+    /** The lane overwrites this with the real attempt before writing stdin. */
+    delivery: {
+        attempt: number;
+    };
+}
+/** The one place a cancellation record without `disposition` reads as
+ * `canceled`. Every other reader treats both dispositions alike. */
+export declare function completionEventFor(result: TicketResult): HumanCompletionEvent;
+/** Build the complete document with `delivery.attempt` as the lane's placeholder. */
+export declare function composeHumanCompletion(args: {
+    requestId: string;
+    result: PageTerminalResult;
+    binding: TicketActionBinding;
+    source: PageSource;
+}): HumanCompletionV1;
+/** A review result can never carry an action binding; the composer is total over the rest. */
+export type PageTerminalResult = Extract<TicketResult, {
+    kind: 'page' | 'canceled';
+}>;

package/dist/core/human/completion.js

@@ -0,0 +1 @@
+var i=Object.defineProperty;var o=(n,t)=>i(n,"name",{value:t,configurable:!0});function s(n){return n.kind==="canceled"?n.disposition??"canceled":"answered"}o(s,"completionEventFor");function l(n){const{requestId:t,result:e,binding:c,source:r}=n,d=s(e),a=e.actor;return{schema:"crtr.human-completion/v1",requestId:t,event:d,settledAt:e.kind==="page"?e.completedAt:e.canceledAt,...e.kind==="page"?{responses:e.responses}:{},action:{name:c.name,payload:c.payload},provenance:{source:r,...a===void 0?{}:{actor:a}},delivery:{attempt:0}}}o(l,"composeHumanCompletion");export{s as completionEventFor,l as composeHumanCompletion};

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;

package/dist/core/human/component-docs.js

@@ -0,0 +1,248 @@
+var m=Object.defineProperty;var r=(t,n)=>m(t,"name",{value:n,configurable:!0});import{pageComponentCatalog as b}from"./page-catalog.js";function p(t){return new Map(b(t).filter(n=>!n.builtin).map(n=>[n.kind,n.tag]))}r(p,"productTags");const c='Component contract\n- Props are the component\'s config, spread flat as JSX attributes; the component registers itself with the host at mount and enforces its own response shape.\n- `id` is required, must match `^[A-Za-z0-9_-]{1,64}$`, and must be unique across the page.\n- When a page has two or more response-bearing components, every one needs a nonempty `label`.\n- Config objects and every documented nested object reject unknown fields.\n- A quoted JSX attribute does not interpret escape sequences, so `body="one.\\n\\ntwo."` reaches the reader as one run-on paragraph with a literal backslash-n in the middle of it. Write any markdown body that has a line or paragraph break as a braced string \u2014 `body={"one.\\n\\ntwo."}` \u2014 where the escape is real.\n- The page is rendered once at submit to build the ticket manifest, so every prop reaches it whatever its shape \u2014 mapped data, a helper component, a value from `useState`. Event handlers are dropped, because a manifest is JSON. The user\'s answer is stored in the request\'s terminal result under this `id`.',h='Comments are `{id:string (nonempty), text:string, anchor:Anchor}` and qualify the answer itself. `Anchor` is `{kind:"option",optionId:string}` or `{kind:"row",rowId:string}`; each component accepts only the anchors named next. The reader writes one against a specific option or row in whatever host they read in \u2014 in the terminal inbox, `c` on the selected one \u2014 so every option and row needs a label that reads on its own. Feedback on the page\'s own prose is a separate channel, offered only by hosts that render the page, and never part of a response.',s="Display-only: it is not recorded in the page manifest and contributes nothing to the response. Every display component also takes `className` for Tailwind utilities, and standard shadcn props otherwise.",i=[{names:["Page"],group:"structural",selectionLine:"`Page` \u2014 the page root. Every module default-exports a component whose root element is `<Page>`; it carries title and subtitle.",contract:`\`<Page>\`
+
+Structural root. The \`.tsx\` module's default export returns exactly one \`<Page>\`; it takes no \`id\` and contributes no response.
+
+Props
+- \`title\` \u2014 required nonempty string. The headline the user sees in their inbox and in the terminal summary.
+- \`subtitle?:string\` \u2014 one line under the title.
+
+Rules
+- Children are page content: registry components, plain elements with Tailwind classes, or \`<Step>\` elements for a multi-step page.
+- Never render submit or dismiss chrome \u2014 the host owns it.
+
+Example
+\`\`\`jsx
+export default function ShipGate() {
+  return (
+    <Page title="Ship 0.4.0?" subtitle="Two gates left.">
+      <UserQuestion id="lane" label="Release lane" body="The audit closes tomorrow." mode="single"
+        options={[{ id: 'now', label: 'Ship now' }, { id: 'hold', label: 'Hold for the audit' }]} />
+    </Page>
+  );
+}
+\`\`\``},{names:["Step"],group:"structural",selectionLine:"`Step` \u2014 one step of a multi-step page. Use as a direct child of `<Page>` when the user works through content in sequence.",contract:'`<Step>`\n\nStructural. One step of a multi-step page. It takes no `id` and contributes no response.\n\nProps\n- `title?:string` \u2014 the step heading.\n\nRules\n- `<Step>` elements are children of `<Page>`; step order is source order, and the ticket manifest records the step count.\n- A single-step page needs no `<Step>` at all \u2014 put the content directly in `<Page>`.\n- The reader sees one step at a time, so hold each step to one question or request for action, with the context that decision needs beside it. Several decisions means several steps, never one long scroll.\n\nExample\n```jsx\n<Page title="Migration plan">\n  <Step title="What changes"><Card>\u2026</Card></Step>\n  <Step title="Approve"><UserQuestion id="go" label="Proceed?" body="Applies on the next deploy." mode="single" options={lanes} /></Step>\n</Page>\n```'},{names:["UserQuestion"],group:"slot",selectionLine:"`UserQuestion` \u2014 known-alternative picker (wire kind `options`). Use when the user picks among known alternatives.",contract:`\`<UserQuestion>\` \u2014 wire kind \`options\`
+
+Response-bearing. The response is \`{selectedOptionIds:string[], comments:Comment[], freetext?:string}\`.
+
+${c}
+
+Props
+- \`id\` \u2014 required component id.
+- \`options\` \u2014 required nonempty array of \`{id:string (nonempty, unique), label:string (nonempty), description?:string, recommended?:boolean}\`.
+- \`recommended\` on one option marks it the suggested answer. At most one option per question may set it. The inbox shows it on the row, and when this question is the page's only response-bearing component the user can accept it from the list with one keystroke, without opening the page. Recommend when you have a view worth acting on; leave it off when the choice is genuinely theirs.
+- \`mode\` \u2014 required: \`single\` or \`multi\`.
+- \`required?:boolean\` \u2014 whether an empty answer is refused. Defaults to the mode: a \`single\` question must be answered, a \`multi\` one need not be, because leaving every box unticked says "none of these apply". Set \`required\` when the mode's default is wrong \u2014 \`required={false}\` on a \`single\` question the user may skip, \`required\` on a \`multi\` one where at least one tick is the point.
+- \`label\` \u2014 required nonempty string: the question itself, drawn as the bold first line.
+- \`body\` \u2014 required nonempty string: markdown rendered above the choices \u2014 the context under the question a label cannot carry. Display-only; contributes nothing to the response.
+- \`allowFreetext?:boolean\`, \`freetextLabel?:string\`, \`freetextPlaceholder?:string\` \u2014 adds a final "something else" choice, drawn as one more row with its own control and a field to write in rather than as a note on the question. It is exclusive on a \`single\` question (choosing it clears the selection, and choosing an option clears what was written) and just another box on a \`multi\` one. \`freetextLabel\` names that row, default "Something else".
+
+Response rules
+- \`selectedOptionIds\` contains unique known option ids; a \`single\` response has at most one. When the question is required, a \`single\` response needs exactly one selection or nonempty allowed \`freetext\`, and a \`multi\` response needs a selection, comment, or nonempty allowed \`freetext\`.
+- \`freetext\` is accepted only when \`allowFreetext:true\`.
+- ${h} UserQuestion accepts only \`option\` anchors; \`optionId\` must name a configured option.
+
+Example
+\`\`\`jsx
+<UserQuestion id="lane" label="Release lane" mode="single" allowFreetext
+  body={"The audit closes tomorrow.\\n\\nBoth release gates are green as of this morning."}
+  freetextLabel="Something else"
+  options={[
+    { id: 'now', label: 'Ship now', description: 'Both gates are green.', recommended: true },
+    { id: 'hold', label: 'Hold for the audit' },
+  ]} />
+\`\`\``},{names:["UserText"],group:"slot",selectionLine:"`UserText` \u2014 writing surface (wire kind `text`). Use whenever the answer is written rather than chosen: a value, a paragraph, or a draft you seeded for them to revise; `singleLine` for a subject, name, or URL. This is the page's surface for freeform input \u2014 a picker's `allowFreetext` is an escape hatch beside its options, not a way to collect prose. Prose the user only reads is a plain element.",contract:`\`<UserText>\` \u2014 wire kind \`text\`
+
+Response-bearing. The response is \`{text:string, edited:boolean}\`: the text the user hands back, and whether they changed what you drafted.
+
+Reach for it whenever what you need back is written rather than picked \u2014 a value, a paragraph, or a draft you seeded with \`initialText\` for them to revise. It is the page's one writing surface: \`allowFreetext\` on a picker adds a single "something else" row beside the options, so prose you actually want belongs here instead. It collects text, it does not present it \u2014 text the user only reads is a plain element with Tailwind classes, \`<p className="whitespace-pre-wrap">\`, which renders the same and asks nothing of them.
+
+${c}
+
+Props
+- \`id\` \u2014 required component id.
+- \`initialText\` \u2014 required string, including an empty string.
+- \`label?:string\` \u2014 the component's label; required by the multi-response page rule.
+- \`placeholder?:string\` \u2014 the hint shown while the field is empty.
+- \`singleLine?:boolean\` \u2014 swaps the writing surface for one compact form field.
+- \`required?:boolean\` \u2014 defaults false. When set, a field left empty (whitespace only) is refused, and the inbox marks it unanswered rather than sending it.
+
+The field is always writable; there is no read-only mode, and the config rejects an \`editable\` prop.
+
+Example
+\`\`\`jsx
+<UserText id="subject" label="Subject line" singleLine initialText="Following up on the audit" />
+\`\`\``},{names:["UserTable"],group:"slot",selectionLine:"`UserTable` \u2014 selectable rows and columns (wire kind `table`). Use when the user inspects or selects tabular data; for a table the user only reads, `Table` is lighter.",contract:`\`<UserTable>\` \u2014 wire kind \`table\`
+
+Display-only when both selection modes are \`none\`; response-bearing when \`rowSelect\` or \`columnSelect\` is \`single\` or \`multi\`. Its response when selectable is \`{selectedRowIds:string[], selectedColumnIds:string[], comments:Comment[]}\`.
+
+${c}
+
+Props
+- \`id\` \u2014 required component id.
+- \`columns\` \u2014 required nonempty array of \`{id:string (nonempty, unique), label:string (nonempty), align?:"left"|"right", mono?:boolean}\`.
+- \`rows?:\` array of \`{id:string (nonempty, unique), cells:Record<string,string|number|boolean|null>}\`. Rows are inline \u2014 map your data into this array in the module.
+- \`rowSelect?:"none"|"single"|"multi"\` \u2014 defaults to \`none\`.
+- \`columnSelect?:"none"|"single"|"multi"\` \u2014 defaults to \`none\`.
+- \`required?:boolean\` \u2014 defaults false. When set on a selectable table, a response selecting no row and no column is refused.
+- \`label?:string\` \u2014 the component's label; required by the multi-response page rule when the table is selectable.
+- \`body?:string\` \u2014 optional markdown rendered above the table. Display-only; it contributes nothing to the response.
+
+Response rules when selectable
+- Selected row and column ids are unique and must name configured ids. \`none\` permits no corresponding selected ids; \`single\` permits at most one.
+- ${h} UserTable accepts only \`row\` anchors, which must name configured row ids.
+
+Example
+\`\`\`jsx
+<UserTable id="picks" label="Which findings do we fix?" rowSelect="multi"
+  columns={[{ id: 'finding', label: 'Finding' }, { id: 'severity', label: 'Severity' }]}
+  rows={findings.map((f) => ({ id: f.id, cells: { finding: f.title, severity: f.severity } }))} />
+\`\`\``},{names:["UserCards"],group:"slot",selectionLine:"`UserCards` \u2014 visual item picker (wire kind `cards`). Use when the user chooses among rich, card-shaped alternatives.",contract:`\`<UserCards>\` \u2014 wire kind \`cards\`
+
+Response-bearing. The response is \`{selectedCardIds:string[]}\` \u2014 the selection alone; cards carry no comments.
+
+${c}
+
+Props
+- \`id\` \u2014 required component id.
+- \`cards?:\` array of \`{id:string (nonempty, unique), title:string (nonempty), subtitle?:string, body?:string, tag?:string}\`. Cards are inline \u2014 map your data into this array in the module.
+- \`mode\` \u2014 required: \`single\` or \`multi\`.
+- \`columns?:2|3\` \u2014 optional layout column count.
+- \`required?:boolean\` \u2014 defaults false. When set, a response selecting no card is refused.
+- \`label?:string\` \u2014 the component's label; required by the multi-response page rule.
+- \`body?:string\` \u2014 optional markdown rendered above the cards. Display-only; it contributes nothing to the response.
+
+Response rules
+- \`selectedCardIds\` contains unique configured card ids. \`single\` permits at most one selected card.
+
+Example
+\`\`\`jsx
+<UserCards id="candidate" label="Who do we interview next?" mode="single" columns={3}
+  cards={[{ id: 'a', title: 'Dana Whitfield', subtitle: 'Staff eng', tag: 'referral' }]} />
+\`\`\``},{names:["Chart"],group:"slot",selectionLine:"`Chart` \u2014 data visualization (wire kind `chart`, display-only). Use when a trend or comparison reads better than prose or a table.",contract:'`<Chart>` \u2014 wire kind `chart`\n\nDisplay-only; it has no response. It still takes an `id` when you want the chart recorded in the ticket manifest.\n\nProps\n- `kind` \u2014 required: `line`, `bar`, or `area`.\n- `x` \u2014 required nonempty string naming the x field.\n- `y` \u2014 required nonempty array of `{field:string (nonempty), label?:string}` series.\n- `title?:string`, `data?:` array of JSON row objects. Rows are inline \u2014 build them in the module.\n- `id?:string` \u2014 component id, subject to the same id rules as a response-bearing component when present.\n\nExample\n```jsx\n<Chart kind="line" title="Build minutes" x="day"\n  y={[{ field: \'minutes\', label: \'CI minutes\' }]}\n  data={days.map((d) => ({ day: d.label, minutes: d.minutes }))} />\n```'},{names:["Card","CardHeader","CardTitle","CardDescription","CardContent","CardFooter"],group:"display",selectionLine:"`Card`, `CardHeader`, `CardTitle`, `CardDescription`, `CardContent`, `CardFooter` \u2014 the standard surface for grouping a block of page content.",contract:`\`<Card>\` family \u2014 \`Card\`, \`CardHeader\`, \`CardTitle\`, \`CardDescription\`, \`CardContent\`, \`CardFooter\`
+
+${s}
+
+Props
+- All six take \`className\` and children only; the nesting carries the meaning.
+- Order inside \`<Card>\`: \`<CardHeader>\` (holding \`<CardTitle>\` and optional \`<CardDescription>\`), then \`<CardContent>\`, then optional \`<CardFooter>\`.
+
+Example
+\`\`\`jsx
+<Card>
+  <CardHeader><CardTitle>Release gates</CardTitle><CardDescription>Two left.</CardDescription></CardHeader>
+  <CardContent><Chart kind="bar" x="gate" y={[{ field: 'minutes' }]} data={gates} /></CardContent>
+</Card>
+\`\`\``},{names:["Badge"],group:"display",selectionLine:"`Badge` \u2014 small status or category chip.",contract:`\`<Badge>\`
+
+${s}
+
+Props
+- \`variant?:"default"|"secondary"|"destructive"|"outline"\`.
+- \`className\`, children.
+
+Example
+\`\`\`jsx
+<Badge variant="destructive">blocked</Badge>
+\`\`\``},{names:["Button"],group:"display",selectionLine:"`Button` \u2014 an in-page control. Never a submit: the host owns submit and dismiss.",contract:`\`<Button>\`
+
+${s} A page never renders its own submit or dismiss \u2014 use it for in-page interaction only (revealing detail, switching a local view).
+
+Props \u2014 this Button does NOT take shadcn's \`variant\`; a \`variant\` prop is silently ignored.
+- \`tone?:"brand"|"neutral"|"danger"\` \u2014 what the action means. Unstated, it resolves to \`brand\` on a solid button and \`neutral\` at every other weight.
+- \`weight?:"solid"|"outline"|"quiet"|"link"\` \u2014 how loudly it reads. Default \`solid\`. \`tone="danger"\` has no \`link\` weight \u2014 that pair warns and renders untoned.
+- \`size?:"xs"|"sm"|"default"|"lg"\` (icon-only circles: \`"icon-xs"|"icon-sm"|"icon"|"icon-lg"\`). Default \`default\`.
+- \`width?:"auto"|"full"\`. Default \`auto\`.
+- \`loading?:boolean\`, \`onClick?:(event) => void\`, \`disabled?:boolean\`, \`className\`, children.
+
+Example
+\`\`\`jsx
+<Button tone="neutral" weight="outline" size="sm" onClick={() => setShowAll(true)}>Show all 12</Button>
+\`\`\``},{names:["Table","TableHeader","TableBody","TableRow","TableHead","TableCell","TableCaption"],group:"display",selectionLine:"`Table`, `TableHeader`, `TableBody`, `TableRow`, `TableHead`, `TableCell`, `TableCaption` \u2014 read-only tabular layout. Use `UserTable` when the user must select rows or columns.",contract:`\`<Table>\` family \u2014 \`Table\`, \`TableHeader\`, \`TableBody\`, \`TableRow\`, \`TableHead\`, \`TableCell\`, \`TableCaption\`
+
+${s} It is layout only: nothing in it is selectable and nothing reaches the response. For selection, use \`UserTable\`.
+
+Props
+- All take \`className\` and children. \`TableHead\` and \`TableCell\` additionally take \`colSpan\`.
+- Structure: \`<Table>\` wraps optional \`<TableCaption>\`, \`<TableHeader>\` (rows of \`<TableHead>\`), and \`<TableBody>\` (rows of \`<TableCell>\`).
+
+Example
+\`\`\`jsx
+<Table>
+  <TableHeader><TableRow><TableHead>Gate</TableHead><TableHead>State</TableHead></TableRow></TableHeader>
+  <TableBody>{gates.map((g) => (
+    <TableRow key={g.id}><TableCell>{g.name}</TableCell><TableCell>{g.state}</TableCell></TableRow>
+  ))}</TableBody>
+</Table>
+\`\`\``},{names:["Tabs","TabsList","TabsTrigger","TabsContent"],group:"display",selectionLine:"`Tabs`, `TabsList`, `TabsTrigger`, `TabsContent` \u2014 parallel views of the same subject behind one control.",contract:`\`<Tabs>\` family \u2014 \`Tabs\`, \`TabsList\`, \`TabsTrigger\`, \`TabsContent\`
+
+${s} Which tab the user opened is not part of the response.
+
+Props
+- \`Tabs\`: \`defaultValue?:string\`, \`value?:string\`, \`onValueChange?:(value:string) => void\`, \`className\`.
+- \`TabsTrigger\` and \`TabsContent\`: \`value\` \u2014 required, and the two match by that value.
+- \`TabsList\`: \`className\` and children.
+
+Example
+\`\`\`jsx
+<Tabs defaultValue="diff">
+  <TabsList><TabsTrigger value="diff">Diff</TabsTrigger><TabsTrigger value="risk">Risk</TabsTrigger></TabsList>
+  <TabsContent value="diff">\u2026</TabsContent>
+  <TabsContent value="risk">\u2026</TabsContent>
+</Tabs>
+\`\`\``},{names:["Separator"],group:"display",selectionLine:"`Separator` \u2014 a rule between sections.",contract:`\`<Separator>\`
+
+${s}
+
+Props
+- \`orientation?:"horizontal"|"vertical"\` \u2014 defaults to \`horizontal\`.
+- \`className\`.
+
+Example
+\`\`\`jsx
+<Separator className="my-4" />
+\`\`\``},{names:["Alert","AlertTitle","AlertDescription"],group:"display",selectionLine:"`Alert`, `AlertTitle`, `AlertDescription` \u2014 a callout for the one thing the user must not miss.",contract:`\`<Alert>\` family \u2014 \`Alert\`, \`AlertTitle\`, \`AlertDescription\`
+
+${s}
+
+Props
+- \`Alert\`: \`variant?:"default"|"destructive"\`, \`className\`.
+- \`AlertTitle\` and \`AlertDescription\`: \`className\` and children.
+
+Example
+\`\`\`jsx
+<Alert variant="destructive">
+  <AlertTitle>Migration is irreversible</AlertTitle>
+  <AlertDescription>The old rows are dropped, not archived.</AlertDescription>
+</Alert>
+\`\`\``},{names:["Progress"],group:"display",selectionLine:"`Progress` \u2014 a completion bar for a known ratio.",contract:`\`<Progress>\`
+
+${s}
+
+Props
+- \`value?:number\` \u2014 0 to 100.
+- \`className\`.
+
+Example
+\`\`\`jsx
+<Progress value={Math.round((done / total) * 100)} />
+\`\`\``},{names:["Accordion","AccordionItem","AccordionTrigger","AccordionContent"],group:"display",selectionLine:"`Accordion`, `AccordionItem`, `AccordionTrigger`, `AccordionContent` \u2014 supporting detail the user opens only if they want it.",contract:`\`<Accordion>\` family \u2014 \`Accordion\`, \`AccordionItem\`, \`AccordionTrigger\`, \`AccordionContent\`
+
+${s}
+
+Props
+- \`Accordion\`: \`type\` \u2014 required: \`single\` or \`multiple\`; \`collapsible?:boolean\`, \`defaultValue?:string|string[]\`, \`className\`.
+- \`AccordionItem\`: \`value\` \u2014 required, unique within the accordion.
+- \`AccordionTrigger\` and \`AccordionContent\`: \`className\` and children.
+
+Example
+\`\`\`jsx
+<Accordion type="single" collapsible>
+  <AccordionItem value="why">
+    <AccordionTrigger>Why this is blocked</AccordionTrigger>
+    <AccordionContent>The audit job has not run since Tuesday.</AccordionContent>
+  </AccordionItem>
+</Accordion>
+\`\`\``}],w=new Map(i.flatMap(t=>t.names.map(n=>[n,t]))),x=[...i.filter(t=>t.group!=="display").map(t=>t.selectionLine),"`usePageHost` \u2014 reserved host hook. Its product-supplied members are opaque to crouter; consult the owning product documentation."];function f(t){return w.get(t)}r(f,"componentDoc");function k(t){return[...i.flatMap(n=>[...n.names]),...p(t).values()]}r(k,"componentNames");const y={structural:"Structural \u2014 every page is built from these.",slot:"Response \u2014 each is recorded in the page manifest under its wire kind, and their answers are the page response.",display:"Display \u2014 shadcn components with their standard props, plus `className` for Tailwind. They contribute nothing to the response."};function v(t){const a=[`<components count="${i.reduce((e,o)=>e+o.names.length,0)+t.length}">`];for(const e of["structural","slot","display"])a.push(y[e],...i.filter(o=>o.group===e).map(o=>o.selectionLine),"");const l=p(t);t.length>0?a.push("Product-registered \u2014 registry components this product ships. Write each one under the tag shown; a `(kind \u2026)` suffix names its lowercase-hyphen wire kind."):a.pop();for(const e of t){const o=l.get(e.kind)??e.kind,u=o===e.kind?`\`${o}\``:`\`${o}\` (kind \`${e.kind}\`)`;if(e.description===void 0&&e.useWhen===void 0){a.push(`${u} \u2014 ${e.display===!0?"product-registered; display-only":"product-registered"}`);continue}const d=[e.description,e.useWhen===void 0?void 0:`${e.useWhen[0].toUpperCase()}${e.useWhen.slice(1)}`,...e.display===!0?["Display-only"]:[]].filter(g=>g!==void 0);a.push(`${u} \u2014 ${d.join(". ")}`)}return a.push("</components>"),a.join(`
+`)}r(v,"renderComponentCatalog");function A(t,n){const a=f(t);if(a!==void 0)return a.contract;const l=p(n),e=n.find(d=>d.kind===t||l.get(d.kind)===t);return e===void 0?void 0:`${`\`<${l.get(e.kind)??e.kind}>\` \u2014 product-registered, wire kind \`${e.kind}\``}
+
+${e.doc??`product-registered${e.display===!0?"; display-only":"; config is passed through unvalidated (unvalidated: true)"} \u2014 see the product's own docs`}`}r(A,"renderComponentContract");export{i as BUILTIN_COMPONENT_DOCS,x as CORE_COMPONENT_SELECTION_LINES,f as componentDoc,k as componentNames,v as renderComponentCatalog,A as renderComponentContract};

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

@@ -0,0 +1,31 @@
+import { atomicWriteJson, atomicWriteText } from '../fs-utils.js';
+export { atomicWriteJson, atomicWriteText };
+/** The authored page source path, derived from the persisted dialect. */
+export declare function pagePath(dir: string, dialect?: 'jsx' | 'html'): string;
+/** The compiled module the Gateway evaluates for JSX pages. */
+export declare function pageModulePath(dir: string): string;
+export declare function pageManifestPath(dir: string): string;
+export declare function reviewPath(dir: string): string;
+export declare function responsePath(dir: string): string;
+export declare function progressPath(dir: string): string;
+export declare function claimPath(dir: string): string;
+export declare function replyRoutePath(dir: string): string;
+/** The frozen completion-action binding, written once at request creation. */
+export declare function actionBindingPath(dir: string): string;
+export interface TicketReplyRoute {
+    bridge_node_id: string;
+}
+/** A reply route exists only when completing the ticket must finish a human
+ * bridge and fan its result back to subscribers. Its absence is the complete
+ * representation of a standalone page. */
+export declare function readTicketReplyRoute(dir: string): TicketReplyRoute | null;
+export declare function bindTicketReplyRoute(dir: string, bridgeNodeId: string): void;
+export type InteractionState = 'pending' | 'claimed' | 'resolved' | 'missing';
+export declare function interactionState(dir: string): InteractionState;
+export declare function isResolved(dir: string): boolean;
+export declare function isClaimed(dir: string): boolean;
+/** Resolve and verify a ticket directory without a registry. */
+export declare function requireTicket(dir: string): string;
+/** Publish one immutable JSON record without replacing an existing winner. */
+export declare function publishJsonExclusive(path: string, value: unknown): boolean;
+export declare function clearProgress(dir: string): void;

package/dist/core/human/convention.js

@@ -0,0 +1,2 @@
+var d=Object.defineProperty;var t=(r,e)=>d(r,"name",{value:e,configurable:!0});import{existsSync as n,linkSync as x,mkdirSync as h,readFileSync as m,realpathSync as g,unlinkSync as c,writeFileSync as y}from"node:fs";import{dirname as $}from"node:path";import{atomicWriteJson as u,atomicWriteText as w}from"../fs-utils.js";function E(r,e="jsx"){return`${r}/page.${e==="jsx"?"tsx":"html"}`}t(E,"pagePath");function b(r){return`${r}/page.js`}t(b,"pageModulePath");function s(r){return`${r}/page.json`}t(s,"pageManifestPath");function a(r){return`${r}/review.json`}t(a,"reviewPath");function p(r){return`${r}/response.json`}t(p,"responsePath");function S(r){return`${r}/progress.json`}t(S,"progressPath");function l(r){return`${r}/claim.json`}t(l,"claimPath");function f(r){return`${r}/reply-route.json`}t(f,"replyRoutePath");function R(r){return`${r}/action.json`}t(R,"actionBindingPath");function T(r){const e=f(r);if(!n(e))return null;let o;try{o=JSON.parse(m(e,"utf8"))}catch{throw new Error(`invalid ticket reply route: ${e}`)}const i=o?.bridge_node_id;if(typeof i!="string"||i==="")throw new Error(`invalid ticket reply route: ${e}`);return{bridge_node_id:i}}t(T,"readTicketReplyRoute");function _(r,e){u(f(r),{bridge_node_id:e})}t(_,"bindTicketReplyRoute");function N(r){return!n(s(r))&&!n(a(r))?"missing":n(p(r))?"resolved":n(l(r))?"claimed":"pending"}t(N,"interactionState");function J(r){return n(p(r))}t(J,"isResolved");function M(r){return n(l(r))}t(M,"isClaimed");function O(r){const e=g(r);if(!n(s(e))&&!n(a(e)))throw new Error("ticket directory has no page or review");return e}t(O,"requireTicket");function F(r,e){const o=`${r}.${process.pid}.${Math.random().toString(16).slice(2)}.tmp`;h($(r),{recursive:!0,mode:448}),y(o,`${JSON.stringify(e,null,2)}
+`,{mode:384});try{return x(o,r),!0}catch(i){if(i.code==="EEXIST")return!1;throw i}finally{c(o)}}t(F,"publishJsonExclusive");function I(r){try{c(S(r))}catch(e){if(e.code!=="ENOENT")throw e}}t(I,"clearProgress");export{R as actionBindingPath,u as atomicWriteJson,w as atomicWriteText,_ as bindTicketReplyRoute,l as claimPath,I as clearProgress,N as interactionState,M as isClaimed,J as isResolved,s as pageManifestPath,b as pageModulePath,E as pagePath,S as progressPath,F as publishJsonExclusive,T as readTicketReplyRoute,f as replyRoutePath,O as requireTicket,p as responsePath,a as reviewPath};

package/dist/core/human/feedback-companion.d.ts

@@ -0,0 +1,19 @@
+/** Hex sha256 of the ticket's page document, recorded at first comment so the
+ * settle-time completion can say whether the page changed during feedback. */
+export declare function pageDocumentSha256(dir: string): string;
+/** A companion node nothing on the ticket points at must not stay resident:
+ * the comment that would have bound it was refused, failed to commit, or lost
+ * the first-comment race to a concurrently recorded companion. */
+export declare function discardFeedbackCompanion(nodeId: string): void;
+/**
+ * Fork the sending node's current state into the ticket-bound companion and
+ * wait for its durable boundary bind. Throws on any failure — the caller
+ * refuses the comment so no feedback is accepted without a visible
+ * conversation able to receive it.
+ */
+export declare function realizeFeedbackCompanion(args: {
+    ticketId: string;
+    dir: string;
+    senderNodeId: string;
+    title: string;
+}): Promise<string>;

package/dist/core/human/feedback-companion.js

@@ -0,0 +1 @@
+var f=Object.defineProperty;var i=(e,o)=>f(e,"name",{value:o,configurable:!0});import{createHash as l}from"node:crypto";import{readFileSync as s}from"node:fs";import{getNode as u}from"../canvas/index.js";import{awaitCompanionBind as w,captureOrigin as h}from"../review/companion.js";import{COMPANION_BIND_DEADLINE_MS as t}from"../review/types.js";import{buildLaunchSpec as _}from"../runtime/launch.js";import{transition as N}from"../runtime/lifecycle.js";import{headlessBrokerHost as k}from"../runtime/host.js";import{spawnNode as b}from"../runtime/nodes.js";import{reviveNode as I}from"../runtime/revive.js";import{materializeSessionBranch as S}from"../runtime/session-branch.js";import{forkNodeLedger as x}from"../runtime/ledger.js";import{pagePath as a}from"./convention.js";import{selectedPageDir as c}from"./tickets.js";function H(e){return l("sha256").update(s(a(c(e),"jsx"))).digest("hex")}i(H,"pageDocumentSha256");function y(e){try{N(e,"cancel",{reason:"retired"}),k.teardown(e)}catch{}}i(y,"discardFeedbackCompanion");async function q(e){const o=u(e.senderNodeId);if(o===null)throw new Error(`page sender was not found: ${e.senderNodeId}`);const d=await h(e.senderNodeId),n=S(d),{launch:m}=_(o.kind,o.mode,{lifecycle:"resident",hasManager:!1,model:d.modelSpec,modelExact:!0,cwd:o.cwd,profileId:o.profile_id??null}),r=await b({kind:o.kind,mode:o.mode,lifecycle:"resident",cwd:o.cwd,profile_id:o.profile_id??null,parent:e.senderNodeId,creator:e.senderNodeId,subscribe:!1,forkFrom:n,forkSourceFile:n,modelOverride:d.modelSpec,reviewBinding:{kind:"page_feedback",review_id:e.ticketId,origin_node_id:e.senderNodeId,branch_file:n,target_file:a(c(e.dir),"jsx")},name:`Feedback \xB7 ${e.title}`,launch:m});try{if(x(r.node_id,e.senderNodeId),await I(r.node_id,{resume:!1,capacity:"refuse"}),!await w(r.node_id,t))throw new Error(`feedback companion did not bind within ${t}ms`)}catch(p){throw y(r.node_id),p}return r.node_id}i(q,"realizeFeedbackCompanion");export{y as discardFeedbackCompanion,H as pageDocumentSha256,q as realizeFeedbackCompanion};