@north-light/api 0.3.579 → 0.3.587

package/dist/commands/doc/replace-blocks.js

@@ -0,0 +1,40 @@
+import { usage } from '../../core/errors.js';
+/** Parse line-delimited, literal SEARCH/REPLACE blocks. Delimiters are whole lines;
+ * the newline immediately before a delimiter belongs to syntax, not the text. */
+export function parseReplaceBlocks(source) {
+    const lines = source.split('\n');
+    const blocks = [];
+    let at = 0;
+    const fail = (message) => { throw usage(`block ${blocks.length + 1}: ${message}`, { field: 'blocks', next: 'Use whole-line <<<<<<< SEARCH, =======, >>>>>>> REPLACE markers.' }); };
+    while (at < lines.length) {
+        if (lines[at] === '' && at === lines.length - 1 && blocks.length > 0)
+            break;
+        if (lines[at] !== '<<<<<<< SEARCH')
+            fail(`expected <<<<<<< SEARCH, got ${JSON.stringify(lines[at])}`);
+        at++;
+        const search = [];
+        while (at < lines.length && lines[at] !== '=======') {
+            if (lines[at] === '>>>>>>> REPLACE' || lines[at] === '<<<<<<< SEARCH')
+                fail('missing ======= separator');
+            search.push(lines[at++]);
+        }
+        if (at === lines.length)
+            fail('missing ======= separator');
+        if (search.length === 0 || (search.length === 1 && search[0] === ''))
+            fail('empty SEARCH is not allowed');
+        at++;
+        const replacement = [];
+        while (at < lines.length && lines[at] !== '>>>>>>> REPLACE') {
+            if (lines[at] === '<<<<<<< SEARCH' || lines[at] === '=======')
+                fail('missing >>>>>>> REPLACE terminator');
+            replacement.push(lines[at++]);
+        }
+        if (at === lines.length)
+            fail('missing >>>>>>> REPLACE terminator');
+        at++;
+        blocks.push({ old: search.join('\n'), new: replacement.join('\n') });
+    }
+    if (blocks.length === 0)
+        fail('expected at least one block');
+    return blocks;
+}

package/dist/commands/doc/shared.d.ts

@@ -0,0 +1,25 @@
+import type { FlagParam } from '../../core/help.js';
+import type { DocOwnerFlag } from '../../api/dto/docs.js';
+export declare const REF_CONSTRAINT = "A document name (with or without [[ ]]) or a raw object id.";
+export declare const OWNER_VALUES = "node | user | profile | profile:<name> | app | repo | repo:<handle>";
+export declare function ownerParam(constraint: string): FlagParam;
+export declare function ruleParam(constraint: string): FlagParam;
+export declare const FIELD_FLAGS: {
+    preview: (constraint: string) => FlagParam;
+    kind: FlagParam;
+    summary: FlagParam;
+    privacy: (constraint: string) => FlagParam;
+    whyItExists: FlagParam;
+    unlisted: (constraint: string) => FlagParam;
+    lintIgnore: FlagParam;
+    extension: FlagParam;
+};
+/** Parse every field flag shared by write and edit; reports every bad value in one error. */
+export declare function fieldsFromInput(input: Record<string, unknown>): Record<string, unknown>;
+export declare function ownerFromInput(input: Record<string, unknown>): {
+    owner?: DocOwnerFlag;
+};
+/** Rethrow an API failure with the next step its code implies for `ref`. */
+export declare function rethrowDocError(err: unknown, ref: string): never;
+/** The link lines under a write or edit result. */
+export declare function renderLinkReport(r: Record<string, unknown>): string;

package/dist/commands/doc/shared.js

@@ -0,0 +1,160 @@
+// Shared flags, parsing and error hints for the `crtr doc` leaves.
+import { usage } from '../../core/errors.js';
+import { ApiError } from '../../api/errors.js';
+import { rethrowAsCliError } from '../api-client.js';
+import { RULE_ON, RULE_DELIVER, DOC_KINDS } from '../../api/dto/docs.js';
+import { PRIVACY_LEVELS_DTO } from '../../api/dto/objects.js';
+export const REF_CONSTRAINT = 'A document name (with or without [[ ]]) or a raw object id.';
+export const OWNER_VALUES = 'node | user | profile | profile:<name> | app | repo | repo:<handle>';
+export function ownerParam(constraint) {
+    return {
+        kind: 'flag',
+        name: 'owner',
+        type: 'string',
+        required: false,
+        constraint,
+        focusedHelp: {
+            whenToUse: 'Omit it for a document only this node and the nodes it points at need: the writing node owns it and it is deleted with the node, unless a kept document links to it. Give another owner when the document must outlive this node or reach other nodes by itself. ' +
+                'A document worth another owner carries reusable current truth: a non-obvious procedure, a gotcha, a lasting preference, a convention across repos. Task notes, conversation summaries and facts the repo already records stay with the node or are not written. ' +
+                'Before writing one, search for a document that already covers it (`crtr canvas search`) and revise that one with `crtr doc edit` instead of adding a near copy. When one document grows long, keep the most important content in it and move separate subjects into documents named under it (`topic/part`), each pointed at with a `[[link]]`. ' +
+                'Choose the narrowest owner that still reaches the next agent who needs it.',
+            value: `One of ${OWNER_VALUES}. ` +
+                '`node` — the writing node; only this node loads it by rule, other nodes read it when pointed at it; deleted with the node. ' +
+                '`profile` — the node\'s profile, or `profile:<name>`; loads for nodes running in that profile; stays on this runtime. ' +
+                '`app` — the app that runs the node; kept until deleted; readable by that app\'s nodes. ' +
+                '`repo` — the repo the node works in (from its working directory), or `repo:<handle>` for another repo whose checkout the node\'s file permissions let it write (such as a project of its profile); every clone and worktree of the repo shares it, and it syncs to collaborators over the repo\'s `refs/crtr/docs`. A repo owns only public documents: a private document that should load in one repo is owned by `user` and carries a rule with `if: {"repo": "<handle>"}`. ' +
+                '`user` — you, the person; loads for every node by its rules; readable by apps by privacy level. ' +
+                'Default: the writing node; a person\'s own run (not a node) defaults to `user`. ' +
+                'The owner becomes the start of the document\'s full name (`<owner-handle>/<name>`); `crtr doc move --owner` changes it later and keeps the id and every link.',
+            effects: [
+                'Decides who may read and change the document, where it syncs, and what deleting takes it with.',
+            ],
+        },
+    };
+}
+const PREDICATE_TEXT = '`if` is a condition on the receiving node. Fields: `kind`, `mode`, `lifecycle`, `cwd`, `repo` (the handle of a repo the node is eligible for: those enclosing its cwd and those of its profile\'s projects; use `cwd` for where it works), `profile`, `depth`. A field map is ANDed across fields; dotted fields resolve nested values. A scalar matches by equality (a list value matches when any element is equal); a list matcher matches by membership or overlap; an object matcher takes `eq`, `ne`, `in`, `nin`, `exists`, `contains`, `containsAll`, `containsAny`, `matches`, `imatches`, `gt`, `gte`, `lt`, `lte`. `all`, `any` and `not` combine conditions; field matchers beside them are ANDed in. An empty condition always matches; an unknown operator never matches. `match_frontmatter` uses the same language against the read file\'s YAML frontmatter.';
+export function ruleParam(constraint) {
+    return {
+        kind: 'flag',
+        name: 'rule',
+        type: 'string',
+        required: false,
+        repeatable: true,
+        constraint,
+        focusedHelp: {
+            whenToUse: 'Omit it for most documents: a document with no rule is read when a node is pointed at it (`[[name]]`), finds it with `crtr canvas search`, or sees it in a listing. Add a rule only when the document must load on its own because of what a node is doing; every rule costs context in every node it fires on. ' +
+                'Prefer the narrowest trigger: a `file-read` rule with a real glob over `boot` for knowledge about specific code; `boot` for knowledge about a person or process with no file boundary. When the whole document is one sentence, deliver `content` — a preview line would be longer than the document.',
+            value: 'One JSON object per occurrence: `{"on": …, "match"?: [globs], "match_frontmatter"?: {…}, "if"?: {…}, "deliver": …}`. ' +
+                `\`on\` is the node's activity: ${RULE_ON.join(' | ')}. ` +
+                '`boot` — every session start of the node. `workspace-open` — the node\'s first message when it works in the document\'s repo. `file-read` — the node reads the content of a file whose absolute path or basename matches a `match` glob, or whose frontmatter matches `match_frontmatter`; through the Read tool, or a bash segment of `cat`, `sed` (not `-i`), `head`, `tail` (not `-f`), `nl` or `awk` on a literal path (resolved after the command\'s own `cd`s; `rg`, `grep`, `find`, `ls`, `wc`, `stat` are searches, not reads, and never fire it). `document-read` — another document whose name matches is delivered at content, including an explicit read. `command` — a shell segment of a bash command matches (segments split on `&&`, `||`, `;`, `|` and newlines outside quotes, leading `VAR=value` dropped; `*` spans whole whitespace-separated tokens, `?` one character, quoted text is opaque). `pre-command` — as `command`, but runs before the command: when the node has not read the document, the command does not run and the document is returned instead; the node re-issues the command. `slash-command` — the document is a `/<name>` slash command whose body is the injected prompt. ' +
+                '`match` is required on `file-read` (unless `match_frontmatter` is given), `document-read`, `command` and `pre-command`, and not allowed on `boot`, `workspace-open` and `slash-command`. ' +
+                PREDICATE_TEXT + ' ' +
+                `\`deliver\` is ${RULE_DELIVER.join(' | ')}: the bare name, the preview line, or the whole body. ` +
+                'The flag set replaces the document\'s whole rule list; on `crtr doc edit`, `--unset rules` removes every rule.',
+            effects: [
+                'When several rules deliver one document to a node, the highest delivery wins: content over preview over name; content already in the node\'s context is not delivered again.',
+                'A document delivered at content is a read: it records the node as a watcher, so the node is pushed later edits.',
+                'The profile\'s delivery limit per owner caps what `boot` and `workspace-open` rules deliver for that owner.',
+                'A rule that delivers at `preview` requires the preview in the shape "When <situation in the reader\'s work>, read this because <what the reader gains>"; `crtr doc lint` checks it. There the line alone decides whether a node that did not ask for the document opens it.',
+            ],
+        },
+    };
+}
+export const FIELD_FLAGS = {
+    preview: (constraint) => ({ kind: 'flag', name: 'preview', type: 'string', required: false, constraint }),
+    kind: { kind: 'flag', name: 'kind', type: 'enum', choices: [...DOC_KINDS], required: false, constraint: 'knowledge is consulted for facts or procedures; preference directs behavior. Default knowledge.' },
+    summary: { kind: 'flag', name: 'summary', type: 'string', required: false, constraint: 'A very short version of the content, shown in `crtr canvas list`.' },
+    privacy: (constraint) => ({ kind: 'flag', name: 'privacy', type: 'enum', choices: [...PRIVACY_LEVELS_DTO], required: false, constraint }),
+    whyItExists: { kind: 'flag', name: 'why-it-exists', type: 'string', required: false, constraint: 'The observed failure this document exists to prevent; shown only with `crtr canvas read --fields`.' },
+    unlisted: (constraint) => ({ kind: 'flag', name: 'unlisted', type: 'bool', required: false, constraint }),
+    lintIgnore: { kind: 'flag', name: 'lint-ignore', type: 'string', required: false, repeatable: true, constraint: 'A `crtr doc lint` rule name to skip for this document.' },
+    extension: { kind: 'flag', name: 'extension', type: 'string', required: false, repeatable: true, constraint: 'One declared plugin field as `<plugin>.<field>=<json value>`.' },
+};
+function list(value) {
+    if (value === undefined)
+        return [];
+    return Array.isArray(value) ? value.map(String) : [String(value)];
+}
+/** Parse every field flag shared by write and edit; reports every bad value in one error. */
+export function fieldsFromInput(input) {
+    const errors = [];
+    const out = {};
+    for (const [flag, key] of [['preview', 'preview'], ['kind', 'kind'], ['summary', 'summary'], ['privacy', 'privacy'], ['whyItExists', 'why_it_exists']]) {
+        if (typeof input[flag] === 'string')
+            out[key] = input[flag];
+    }
+    if (typeof out['preview'] === 'string' && /[\r\n]/.test(out['preview']))
+        errors.push('--preview must be one line');
+    if (input['unlisted'] === true)
+        out['unlisted'] = true;
+    const ignore = list(input['lintIgnore']);
+    if (ignore.length > 0)
+        out['lint_ignore'] = ignore;
+    const rules = list(input['rule']);
+    if (rules.length > 0) {
+        const parsed = [];
+        rules.forEach((raw, i) => {
+            try {
+                const value = JSON.parse(raw);
+                if (typeof value !== 'object' || value === null || Array.isArray(value))
+                    errors.push(`--rule #${i + 1} must be a JSON object`);
+                else
+                    parsed.push(value);
+            }
+            catch {
+                errors.push(`--rule #${i + 1} is not valid JSON: ${raw}`);
+            }
+        });
+        out['rules'] = parsed;
+    }
+    const extensions = {};
+    for (const raw of list(input['extension'])) {
+        const m = /^([^.=]+)\.([^=]+)=(.*)$/s.exec(raw);
+        if (!m) {
+            errors.push(`--extension ${raw} is not <plugin>.<field>=<json value>`);
+            continue;
+        }
+        try {
+            (extensions[m[1]] ??= {})[m[2]] = JSON.parse(m[3]);
+        }
+        catch {
+            errors.push(`--extension ${raw}: the value after = is not valid JSON`);
+        }
+    }
+    if (Object.keys(extensions).length > 0)
+        out['extensions'] = extensions;
+    if (errors.length > 0)
+        throw usage(errors.join('; '), { next: 'Fix every value above and rerun; `--rule -h` gives the rule grammar.' });
+    return out;
+}
+export function ownerFromInput(input) {
+    const owner = input['owner'];
+    if (owner === undefined)
+        return {};
+    const value = String(owner);
+    if (!/^(node|user|profile|app|repo)$|^(profile|repo):.+$/.test(value)) {
+        throw usage(`invalid --owner ${value}`, { field: 'owner', next: `Pass one of ${OWNER_VALUES}.` });
+    }
+    return { owner: value };
+}
+/** Rethrow an API failure with the next step its code implies for `ref`. */
+export function rethrowDocError(err, ref) {
+    if (err instanceof ApiError) {
+        if (err.code === 'read_first')
+            rethrowAsCliError(err, `Read it first with \`crtr canvas read ${ref}\`, then rerun the edit.`);
+        if (err.code === 'stale_revision')
+            rethrowAsCliError(err, `Someone edited it after your read. Read it again with \`crtr canvas read ${ref}\`, make your change on the current text, and rerun the edit.`);
+    }
+    rethrowAsCliError(err);
+}
+/** The link lines under a write or edit result. */
+export function renderLinkReport(r) {
+    const lines = [];
+    const unresolved = r['unresolved_links'];
+    const remote = r['remote_links'];
+    if (unresolved?.length)
+        lines.push(`Unresolved links (no document by these names yet): ${unresolved.map((l) => `[[${l}]]`).join(', ')}`);
+    if (remote?.length)
+        lines.push(`Not on this runtime: ${remote.map((l) => `[[${l}]]`).join(', ')} — each may be on another runtime, or the name may be misspelled.`);
+    return lines.map((l) => `\n${l}`).join('');
+}

package/dist/commands/doc/write.d.ts

@@ -0,0 +1,2 @@
+import type { LeafDef } from '../../core/command.js';
+export declare const writeLeaf: LeafDef;

package/dist/commands/doc/write.js

@@ -0,0 +1,52 @@
+import { defineLeaf } from '../../core/command.js';
+import { cliClient, rethrowAsCliError } from '../api-client.js';
+import { FIELD_FLAGS, fieldsFromInput, ownerFromInput, ownerParam, renderLinkReport, ruleParam } from './shared.js';
+export const writeLeaf = defineLeaf({
+    name: 'write',
+    description: 'write a new document from a stdin body',
+    whenToUse: 'a spec, plan, map, finding, knowledge or preference should exist as a document other nodes can read; creation only — revise an existing one with `crtr doc edit`',
+    help: {
+        name: 'doc write',
+        summary: 'write a new document from a stdin body',
+        guide: 'Most documents need only a name, a preview and a body: the writing node owns it, it has no delivery rules, and other nodes read it when pointed at it as `[[<name printed below>]]`, and each `[[link]]` in its body attaches that document\'s preview wherever this one is delivered in full. ' +
+            'Give --owner or --rule only when the document must outlive this node or load on its own; each has focused help. Read, list and search documents with `crtr canvas read|list|search`.',
+        params: [
+            { kind: 'positional', name: 'name', required: true, constraint: 'Name under its owner: segments of letters, digits, `_` and `-`, joined by `/`. Must be free under that owner.' },
+            { kind: 'stdin', name: 'body', required: true, constraint: 'Document body (markdown), piped on stdin and saved byte for byte. Pipe it straight in with a quoted heredoc (`<<\'EOF\'`); an unquoted one lets the shell expand `$` and backticks in the text before it is saved.' },
+            { ...FIELD_FLAGS.preview('One line shown wherever the document is listed or delivered without its body, telling a reader whether to open it.'), required: true },
+            FIELD_FLAGS.kind,
+            FIELD_FLAGS.summary,
+            FIELD_FLAGS.privacy('`public` (default) or `private`: a private document is kept from apps without a private-read scope; the owner and anyone it is shared with still read it. A repo-owned document must be public.'),
+            ownerParam('Whose document it is; default the writing node.'),
+            ruleParam('A delivery rule that loads the document into nodes by their activity.'),
+            FIELD_FLAGS.whyItExists,
+            FIELD_FLAGS.unlisted('Keep it out of listings; reads, links and rules still work.'),
+            FIELD_FLAGS.lintIgnore,
+            FIELD_FLAGS.extension,
+        ],
+        output: [
+            { name: 'name', type: 'string', required: true, constraint: 'Full name, `<owner-handle>/<name>`; point at it as `[[name]]`.' },
+            { name: 'id', type: 'string', required: true, constraint: 'Object id.' },
+            { name: 'unresolved_links', type: 'string[]', required: false, constraint: '`[[links]]` in the body that name no document yet; absent when every link resolves.' },
+            { name: 'remote_links', type: 'string[]', required: false, constraint: '`[[links]]` whose first segment is no owner on this runtime: on another runtime, or misspelled.' },
+        ],
+        outputKind: 'object',
+        effects: ['Creates the document at revision 1 and makes the writer a watcher, so it is pushed later edits.'],
+    },
+    run: async (input) => {
+        const request = {
+            name: input['name'],
+            body: input['body'],
+            ...fieldsFromInput(input),
+            ...ownerFromInput(input),
+            cwd: process.cwd(),
+        };
+        try {
+            return { ...(await cliClient().docs.write(request)) };
+        }
+        catch (err) {
+            rethrowAsCliError(err);
+        }
+    },
+    render: (r) => `<written name="${String(r['name'])}" id="${String(r['id'])}">${renderLinkReport(r)}`,
+});

package/dist/commands/doc.d.ts

@@ -0,0 +1,2 @@
+import type { BranchDef } from '../core/command.js';
+export declare function registerDoc(): BranchDef;

package/dist/commands/doc.js

@@ -0,0 +1,27 @@
+// `crtr doc` — write, edit, move, delete and lint documents. Reading, listing
+// and searching documents are `crtr canvas read|list|search`.
+import { defineBranch } from '../core/command.js';
+import { writeLeaf } from './doc/write.js';
+import { editLeaf } from './doc/edit.js';
+import { moveLeaf } from './doc/move.js';
+import { historyLeaf } from './doc/history.js';
+import { deleteLeaf } from './doc/delete.js';
+import { lintLeaf } from './doc/lint.js';
+import { readLeaf } from './doc/read.js';
+import { listLeaf } from './doc/list.js';
+export function registerDoc() {
+    return defineBranch({
+        name: 'doc',
+        rootEntry: {
+            concept: 'a document — markdown written for readers: knowledge, preferences, specs, plans, maps',
+            desc: 'write, edit, move, delete and lint documents',
+            useWhen: 'writing or revising a document; read, list and search documents with `crtr canvas`',
+        },
+        help: {
+            name: 'doc',
+            summary: 'write, edit, move, delete and lint documents',
+            model: 'Reading, listing and searching documents are `crtr canvas read`, `crtr canvas list --type document` and `crtr canvas search`. A document is pointed at as `[[name]]`.',
+        },
+        children: [writeLeaf, editLeaf, moveLeaf, historyLeaf, deleteLeaf, lintLeaf, readLeaf, listLeaf],
+    });
+}

package/dist/commands/human/components.d.ts

@@ -0,0 +1,4 @@
+import { type BranchDef } from '../../core/command.js';
+/** The product components the runtime registers, read through the daemon. */
+export declare function productComponents(): Promise<import("../../api/index.js").PageComponentDTO[]>;
+export declare const humanComponents: BranchDef;

package/dist/commands/human/components.js

@@ -0,0 +1,78 @@
+import { defineBranch, defineLeaf } from '../../core/command.js';
+import { stateBlock } from '../../core/help.js';
+import { InputError } from '../../core/io.js';
+import { componentNames, renderComponentCatalog, renderComponentContract } from '../../core/human/component-docs.js';
+import { cliClient } from '../api-client.js';
+/** The product components the runtime registers, read through the daemon. */
+export async function productComponents() {
+    return (await cliClient().listPageComponents()).components;
+}
+async function componentNameState() {
+    const names = componentNames(await productComponents());
+    return stateBlock('components', { count: names.length }, names.join(', '));
+}
+const humanComponentsList = defineLeaf({
+    name: 'list',
+    description: 'list page components for selection',
+    whenToUse: 'choosing which components to put in an authored page module.',
+    help: {
+        name: 'human components list',
+        summary: 'list page components for selection',
+        inputNote: 'No input parameters.',
+        output: [
+            { name: 'catalog', type: 'markdown', required: true, constraint: 'One concise selection entry per registry and product-registered component, grouped structural/response/display; no props or response schemas. A product component is written with the PascalCase tag derived from its registered kind.' },
+            { name: 'follow_up', type: 'string', required: true, constraint: 'Points to `crtr human components show <component>` for one selected component contract.' },
+        ],
+        outputKind: 'object',
+        effects: ['None. Read-only.'],
+    },
+    run: async () => ({
+        catalog: renderComponentCatalog(await productComponents()),
+        follow_up: 'Use `crtr human components show <component>` for one component contract.',
+    }),
+    render: (result) => `${String(result['catalog'])}\n\n${String(result['follow_up'])}`,
+});
+const humanComponentsShow = defineLeaf({
+    name: 'show',
+    description: 'show one page component contract',
+    whenToUse: 'authoring one selected page component and needing its exact props, response contract, and shape in a page module.',
+    help: {
+        name: 'human components show',
+        summary: 'show one page component contract',
+        params: [
+            { kind: 'positional', name: 'component', type: 'string', required: true, constraint: 'Component name from the live <components> catalog below. Case-sensitive: registry components are PascalCase.' },
+        ],
+        output: [
+            { name: 'component', type: 'string', required: true, constraint: 'The selected component name.' },
+            { name: 'contract', type: 'markdown', required: true, constraint: 'Hand-written props, response contract, and authoring example for that component. A shadcn family (Card, CardHeader, …) shares one contract covering every member.' },
+        ],
+        outputKind: 'object',
+        effects: ['None. Read-only.'],
+    },
+    helpState: { leaf: componentNameState },
+    run: async (input) => {
+        const component = input['component'];
+        const contract = renderComponentContract(component, await productComponents());
+        if (contract === undefined) {
+            throw new InputError({
+                error: 'unknown_component',
+                message: `unknown page component "${component}"`,
+                field: 'component',
+                next: 'Run `crtr human components show -h` and choose a component from its live catalog.',
+            });
+        }
+        return { component, contract };
+    },
+    render: (result) => String(result['contract']),
+});
+export const humanComponents = defineBranch({
+    name: 'components',
+    description: 'discover page components and their contracts',
+    whenToUse: 'authoring a page module and choosing components, or needing one component’s exact props and response contract.',
+    help: {
+        name: 'human components',
+        summary: 'discover page components and their contracts',
+        model: 'These are the components already in scope in a page module — no import, ever. List is the selection catalog; show owns the full props, response contract, and authoring shape for one selected component.',
+    },
+    children: [humanComponentsList, humanComponentsShow],
+});

package/dist/commands/human/feedback.d.ts

@@ -0,0 +1,2 @@
+import type { BranchDef } from '../../core/command.js';
+export declare const humanFeedbackBranch: BranchDef;

package/dist/commands/human/feedback.js

@@ -0,0 +1,112 @@
+// `crtr human feedback` — the feedback companion's surface for a page ticket's
+// feedback comments. list shows every item with its id and status; resolve is
+// the companion's terminal report that an open item has been dealt with.
+// Creating comments is the person's channel (the page surface); no agent
+// authors, edits, or deletes them.
+import { envNodeId } from '../../shared/env.js';
+import { ApiError } from '../../api/index.js';
+import { defineBranch, defineLeaf } from '../../core/command.js';
+import { InputError } from '../../core/io.js';
+import { cliClient, rethrowAsCliError } from '../api-client.js';
+/** Feedback tickets are addressed by request identity; crtrd returns their inbox identity. */
+async function requirePageTicketId(raw) {
+    const requestId = raw;
+    try {
+        const request = await cliClient().getHumanRequest(requestId);
+        if (request.kind !== 'page')
+            throw new InputError({ error: 'not_found', message: `no page ticket: ${requestId}`, field: 'ticket_id', next: 'Pass the ticket id from your bearings, or a page ticket_id from `crtr human list`.' });
+        return { requestId, inboxTicketId: request.inbox_ticket_id };
+    }
+    catch (error) {
+        if (error instanceof InputError)
+            throw error;
+        rethrowAsCliError(error, 'Pass the ticket id from your bearings, or a page ticket_id from `crtr human list`.');
+    }
+}
+const humanFeedbackList = defineLeaf({
+    name: 'list',
+    description: "list a page ticket's feedback comments",
+    whenToUse: 'you are the feedback companion for a page ticket and need each comment\'s id and open/resolved status.',
+    help: {
+        name: 'human feedback list',
+        summary: "every feedback comment on one page ticket, with ids and open/resolved status",
+        params: [
+            { kind: 'positional', name: 'ticket_id', type: 'string', required: true, constraint: 'The page ticket id from your bearings (also the page_id from human send).' },
+        ],
+        output: [
+            { name: 'ticket_id', type: 'string', required: true, constraint: 'The page ticket id.' },
+            { name: 'open_count', type: 'integer', required: true, constraint: 'How many comments remain open. Zero once feedback exists means all of it has been dealt with.' },
+            { name: 'comments', type: 'object[]', required: true, constraint: 'Each: {id, quote, context?, note, status, created_at, resolved_at?}; status is open or resolved. Oldest first.' },
+        ],
+        outputKind: 'object',
+        effects: ['None. Read-only.'],
+    },
+    run: async (input) => {
+        const ticket = await requirePageTicketId(input['ticket_id']);
+        try {
+            const page = await cliClient().getHumanInboxPage(ticket.inboxTicketId);
+            return { ticket_id: ticket.requestId, open_count: page.feedback.open_count, comments: page.feedback.comments };
+        }
+        catch (e) {
+            rethrowAsCliError(e);
+        }
+    },
+});
+const humanFeedbackResolve = defineLeaf({
+    name: 'resolve',
+    description: 'mark one dealt-with feedback comment resolved',
+    whenToUse: 'you are the feedback companion and have dealt with an open comment — by revising the page or answering it in conversation.',
+    help: {
+        name: 'human feedback resolve',
+        summary: 'mark one open feedback comment resolved — terminal, and only after the feedback has actually been dealt with',
+        guide: 'Resolution is your report that the work is done, not a triage state: revise the page or answer the comment in conversation first, then resolve. It appends no chat turn — briefly report the result in the conversation yourself. A resolved comment never reopens; a renewed concern arrives as a new comment.',
+        params: [
+            { kind: 'positional', name: 'comment_id', type: 'string', required: true, constraint: 'A comment id from `crtr human feedback list`. The ticket is your own: it comes from the companion binding of the calling node.' },
+        ],
+        output: [
+            { name: 'resolved', type: 'boolean', required: true, constraint: 'True when this call resolved the comment; false when it was already resolved.' },
+            { name: 'ticket_id', type: 'string', required: true, constraint: 'The page ticket id.' },
+            { name: 'comment_id', type: 'string', required: true, constraint: 'The comment id.' },
+            { name: 'open_count', type: 'integer', required: false, constraint: 'Comments still open after this resolution. Present when resolved is true.' },
+            { name: 'reason', type: 'string', required: false, constraint: 'comment_already_resolved when resolved is false.' },
+        ],
+        outputKind: 'object',
+        effects: ["Marks the comment resolved in your own ticket's feedback record — the ticket comes from the calling companion's binding. Only the ticket's bound companion may resolve — any other node refuses with not_companion. A terminal ticket refuses with ticket_terminal — settlement already closed this collaboration."],
+    },
+    run: async (input) => {
+        const commentId = input['comment_id'];
+        const callerNodeId = envNodeId();
+        if (callerNodeId === undefined || callerNodeId === '') {
+            throw new InputError({ error: 'no_node', message: 'resolve runs inside the ticket\u2019s feedback companion (CRTR_NODE_ID unset)', next: 'Run this from the companion conversation bound to the ticket.' });
+        }
+        const binding = (await cliClient().getNode(callerNodeId)).review_binding;
+        if (binding === undefined || binding === null || binding.kind !== 'page_feedback') {
+            throw new InputError({ error: 'not_companion', message: 'this node is not a page-feedback companion — only the ticket\u2019s bound companion resolves its comments', next: 'Resolve from the companion conversation bound to the ticket.' });
+        }
+        const ticket = await requirePageTicketId(binding.review_id);
+        try {
+            const result = await cliClient().resolvePageFeedbackComment(ticket.inboxTicketId, commentId, callerNodeId);
+            return { resolved: true, ticket_id: ticket.requestId, comment_id: commentId, open_count: result.feedback.open_count };
+        }
+        catch (e) {
+            if (e instanceof ApiError && e.status === 409 && e.code === 'comment_already_resolved') {
+                return { resolved: false, ticket_id: ticket.requestId, comment_id: commentId, reason: 'comment_already_resolved' };
+            }
+            rethrowAsCliError(e);
+        }
+    },
+    render: (r) => r['resolved'] === true
+        ? `Resolved feedback comment ${r['comment_id']} — ${r['open_count']} still open on ${r['ticket_id']}.`
+        : `Nothing to resolve for ${r['comment_id']} — ${r['reason']}.`,
+});
+export const humanFeedbackBranch = defineBranch({
+    name: 'feedback',
+    description: "operate on a page ticket's feedback comments",
+    whenToUse: "you are a feedback companion working a page ticket's feedback comments.",
+    help: {
+        name: 'human feedback',
+        summary: "a page ticket's feedback comments — the person creates them on the page; the bound companion lists and resolves them",
+        model: 'Each comment is immutable once sent and open until resolved. resolve is terminal and companion-only, taken after the feedback has been dealt with by revising the page or answering in conversation.',
+    },
+    children: [humanFeedbackList, humanFeedbackResolve],
+});

package/dist/commands/human/prompts.d.ts

@@ -0,0 +1,21 @@
+import { type PageSource } from '../../core/human/page-schema.js';
+/** Provenance for crouter tickets. Ticket *identity* comes from the bridge node
+ * directory, never ticket data; `nodeId` carries the originating node so a
+ * consumer can relate a ticket back to whatever that node belongs to, and
+ * `sessionName` is a presentation label only, while `profileName` lets product
+ * consumers resolve the applet or worker identity behind the ticket. Review
+ * tickets stamp the same provenance (`core/review/realize.ts`), so pages match
+ * them. `nodeId` is stamped even when the daemon is unreachable — losing the
+ * labels is survivable, losing machine attribution is not.
+ *
+ * The same read answers who is sending: `lifecycle` decides whether the sender
+ * has a transcript a human is plausibly reading, which is what makes skipping
+ * the inbox safe. It is null for a bare shell (no node at all) and when the
+ * daemon cannot answer — neither is a terminal sender, so neither restricts
+ * delivery. */
+export declare function sender(): Promise<{
+    source: PageSource;
+    lifecycle: 'terminal' | 'resident' | null;
+}>;
+export declare function humanSend(pageSurface?: boolean): import("../../core/command.js").LeafDef;
+export declare const humanShow: import("../../core/command.js").LeafDef;