@north-light/api 0.3.579 → 0.3.587

package/dist/commands/canvas/edges.js

@@ -0,0 +1,41 @@
+import { defineLeaf } from '../../core/command.js';
+import { cliClient, rethrowAsCliError } from '../api-client.js';
+import { REF_CONSTRAINT } from './read.js';
+const EDGE_TYPES = ['acted-on', 'links-to', 'watches'];
+export const edgesLeaf = defineLeaf({
+    name: 'edges',
+    description: 'list the edges of an object: acted-on, links-to, watches',
+    whenToUse: 'you need what a document links to or what links to it, who acted on an object, or who watches it. Records nothing.',
+    help: {
+        name: 'canvas edges',
+        summary: 'list an object\u2019s acted-on, links-to and watches edges; records nothing',
+        params: [
+            { kind: 'positional', name: 'ref', required: true, constraint: REF_CONSTRAINT },
+            { kind: 'flag', name: 'type', type: 'enum', choices: EDGE_TYPES, required: false, constraint: 'Only edges of this type. acted-on: an actor changed or wrote the object. links-to: a body names the object as `[[name]]`. watches: a watcher of the object.' },
+            { kind: 'flag', name: 'direction', type: 'enum', choices: ['out', 'in'], required: false, constraint: 'out: edges from this object; in: edges to it. Omit for both.' },
+        ],
+        output: [
+            { name: 'items', type: 'string[]', required: true, constraint: 'One row per edge you can read both ends of: type, source and destination as id and `[[name]]`, and for links-to the name as the body wrote it.' },
+        ],
+        outputKind: 'object',
+        effects: ['None. Listing edges records no watch.'],
+    },
+    run: async (input) => {
+        const query = {
+            ...(input['type'] ? { type: input['type'] } : {}),
+            ...(input['direction'] ? { direction: input['direction'] } : {}),
+        };
+        try {
+            return { ...(await cliClient().objects.edges(input['ref'], query)) };
+        }
+        catch (err) {
+            rethrowAsCliError(err);
+        }
+    },
+    render: (result) => {
+        const { items } = result;
+        if (items.length === 0)
+            return 'No edges.';
+        return items.map((e) => `- ${e.type}: ${e.src.id} [[${e.src.name}]] → ${e.dst.id} [[${e.dst.name}]]${e.written_as ? ` (written as [[${e.written_as}]])` : ''}`).join('\n');
+    },
+});

package/dist/commands/canvas/list.d.ts

@@ -0,0 +1,4 @@
+import type { LeafDef } from '../../core/command.js';
+import type { ObjectListItemDTO } from '../../api/dto/objects.js';
+export declare function listItemRow(item: ObjectListItemDTO): string;
+export declare const listLeaf: LeafDef;

package/dist/commands/canvas/list.js

@@ -0,0 +1,79 @@
+import { defineLeaf } from '../../core/command.js';
+import { PRIVACY_LEVELS_DTO } from '../../api/dto/objects.js';
+import { cliClient, rethrowAsCliError } from '../api-client.js';
+import { objectRow } from './read.js';
+export function listItemRow(item) {
+    const row = item.machine ? `${objectRow(item)} machine=${item.machine.name}` : objectRow(item);
+    if (item.type !== 'document')
+        return row;
+    const extra = [`privacy=${item.privacy}`, item.rules !== undefined ? `rules=${item.rules}` : ''].filter(Boolean).join(' ');
+    return `${row}\n  ${extra}${item.summary ? ` — ${item.summary}` : ''}`;
+}
+export const listLeaf = defineLeaf({
+    name: 'list',
+    description: 'list objects by type, kind, owner, privacy or name prefix',
+    whenToUse: 'browsing what exists without reading it — the documents an owner holds, a node\u2019s reports, every job of a node. Records nothing, so listing does not make you a watcher.',
+    help: {
+        name: 'canvas list',
+        summary: 'list the objects you can read, filtered; records nothing',
+        params: [
+            { kind: 'flag', name: 'type', type: 'string', required: false, constraint: 'Only objects of this kind: document, node, job, person, app, repo or profile. The daemon rejects a name no kind declares and lists the kinds.' },
+            { kind: 'flag', name: 'kind', type: 'string', required: false, constraint: 'Only objects of this kind: for documents knowledge, preference or report; for nodes the node kind.' },
+            { kind: 'flag', name: 'owner', type: 'string', required: false, constraint: 'Only objects this owner owns directly: a node id, a handle, or any name `crtr canvas read` accepts.' },
+            { kind: 'flag', name: 'privacy', type: 'enum', choices: [...PRIVACY_LEVELS_DTO], required: false, constraint: 'Only objects at this privacy level.' },
+            { kind: 'flag', name: 'name', type: 'string', required: false, constraint: 'Only objects whose name starts with this prefix.' },
+            { kind: 'flag', name: 'deleted', type: 'bool', required: false, constraint: 'When present, lists deleted objects instead of live ones.' },
+            { kind: 'flag', name: 'shared', type: 'bool', required: false, constraint: 'When present, lists only objects you reach through a share from another person, not through your own objects.' },
+            { kind: 'flag', name: 'machine', type: 'string', required: false, constraint: 'List exactly one machine of your account (`runtime:<id>` or its bare id), paging through its own cursor. Without it a joined runtime lists its own objects plus the first page of every other machine, each row labelled `machine=<name>`.' },
+            { kind: 'flag', name: 'limit', type: 'int', required: false, default: 50, constraint: 'Page size, 1 to 100.' },
+            { kind: 'flag', name: 'cursor', type: 'string', required: false, constraint: 'The `next_cursor` of the previous page.' },
+        ],
+        output: [
+            { name: 'items', type: 'string[]', required: true, constraint: 'One row per object: id, `[[name]]`, type/kind, owner handle and preview. A document row adds its privacy, its rule count and its summary.' },
+            { name: 'machines', type: 'object[]', required: false, constraint: 'On a joined runtime: one entry per machine, `{machine_id, name, state: ok|unreachable|too_old, more}`. `more` means that machine has further rows: page it with `--machine`.' },
+            { name: 'next_cursor', type: 'string', required: false, constraint: 'Pass as `--cursor` for the next page of THIS machine (or of `--machine`); absent on the last page.' },
+        ],
+        outputKind: 'object',
+        effects: ['None. Listing records no watch.'],
+    },
+    run: async (input) => {
+        const query = {
+            ...(input['type'] ? { type: input['type'] } : {}),
+            ...(input['kind'] ? { kind: input['kind'] } : {}),
+            ...(input['owner'] ? { owner: input['owner'] } : {}),
+            ...(input['privacy'] ? { privacy: input['privacy'] } : {}),
+            ...(input['name'] ? { name: input['name'] } : {}),
+            ...(input['deleted'] === true ? { deleted: true } : {}),
+            ...(input['shared'] === true ? { shared: true } : {}),
+            ...(input['machine'] ? { machine: input['machine'] } : {}),
+            limit: input['limit'] ?? 50,
+            ...(input['cursor'] ? { cursor: input['cursor'] } : {}),
+        };
+        try {
+            return { ...(await cliClient().objects.list(query)) };
+        }
+        catch (err) {
+            rethrowAsCliError(err);
+        }
+    },
+    render: (result) => {
+        const { items, next_cursor, machines } = result;
+        // A single-machine answer (`--machine`) pages that machine: the next page names it too.
+        const only = machines?.length === 1 ? machines[0].machine_id : null;
+        const lines = items.length === 0 ? ['No objects match.'] : items.map(listItemRow);
+        const gaps = (machines ?? []).filter((m) => m.state !== 'ok');
+        const more = (machines ?? []).filter((m) => m.state === 'ok' && m.more && m.machine_id !== machines[0].machine_id && only === null);
+        if (gaps.length > 0 || more.length > 0)
+            lines.push('');
+        for (const m of gaps) {
+            lines.push(m.state === 'too_old'
+                ? `Not listed: ${m.name} (${m.machine_id}) runs a crtr too old to take part; update it with \`crtr sys update\` there.`
+                : `Not listed: ${m.name} (${m.machine_id}) is unreachable, so its objects are missing from this list.`);
+        }
+        for (const m of more)
+            lines.push(`${m.name} has more: \`crtr canvas list --machine ${m.machine_id} …\`.`);
+        if (next_cursor)
+            lines.push('', `More: \`crtr canvas list …${only === null ? '' : ` --machine ${only}`} --cursor ${next_cursor}\`.`);
+        return lines.join('\n');
+    },
+});

package/dist/commands/canvas/read.d.ts

@@ -0,0 +1,14 @@
+import type { LeafDef } from '../../core/command.js';
+import type { ObjectReadDTO } from '../../api/dto/objects.js';
+export declare const REF_CONSTRAINT = "A name (the `[[ ]]` brackets are optional) or a raw object id. A name is `<owner-handle>/<path>`; a node or other owner is also named by its id or handle.";
+export { attr, objectRow } from '../../core/graph/kinds/render.js';
+export declare function renderRead(result: ObjectReadDTO): string;
+export declare function documentReadParts(result: ObjectReadDTO): {
+    body: string;
+    metadata: string;
+    context: string;
+} | null;
+/** Never mirror bodies into viewer metadata; a head's body belongs in the tool result. */
+export declare function previewRead(result: ObjectReadDTO): Record<string, unknown>;
+export declare function renderReadOutput(result: ObjectReadDTO): string;
+export declare const readLeaf: LeafDef;

package/dist/commands/canvas/read.js

@@ -0,0 +1,95 @@
+import { defineLeaf } from '../../core/command.js';
+import { attr, header, section } from '../../core/graph/kinds/render.js';
+import { PREVIEW_RESULT_PATH_ENV } from '../../core/preview-result-path.js';
+import { isJsonOutput } from '../../core/io.js';
+import { cliClient, rethrowAsCliError } from '../api-client.js';
+export const REF_CONSTRAINT = 'A name (the `[[ ]]` brackets are optional) or a raw object id. A name is `<owner-handle>/<path>`; a node or other owner is also named by its id or handle.';
+export { attr, objectRow } from '../../core/graph/kinds/render.js';
+export function renderRead(result) {
+    if (result.state === 'remote') {
+        return `No object named ${result.remote} on this runtime. It may be on another runtime, or the name may be misspelled.`;
+    }
+    if (result.state === 'unknown') {
+        return `No machine of yours answers for ${result.ref} (unreachable: ${result.unreachable.join(', ') || 'none named'}). It may be on one of them; try again when they are back.`;
+    }
+    if (result.state === 'deleted') {
+        const o = result.deleted;
+        return [`${header('deleted', o, attr('deleted_at', o.deleted_at))}`, `Last preview: ${o.preview}`, '</deleted>'].join('\n');
+    }
+    return `${result.text}\n</object>`;
+}
+export function documentReadParts(result) {
+    if (result.state !== 'object' || result.type !== 'document')
+        return null;
+    const d = result.data;
+    const o = result.object;
+    const lines = [header('object', o, attr('privacy', o.privacy) + attr('revision', d.revision)), `Preview: ${o.preview}`];
+    if (d.summary)
+        lines.push(`Summary: ${d.summary}`);
+    if (d.fields !== undefined)
+        lines.push(`<fields>\n${JSON.stringify(d.fields, null, 2)}\n</fields>`);
+    if (d.needs_merge) {
+        d.heads.forEach((h, i) => lines.push(`<head${attr('rev', h.rev_id)}${attr('number', h.number)}${attr('author', h.author_id)}>\n${d.bodies[i] ?? ''}\n</head>`));
+        lines.push(`This document has ${d.heads.length} heads. Your next \`crtr doc edit\` writes the merged body and joins them into one revision.`);
+    }
+    if (d.listing?.length) {
+        const under = d.listing.some((l) => l.owner?.id === o.owner?.id && l.name.startsWith(`${o.name}/`));
+        const linked = d.listing.some((l) => l.owner?.id !== o.owner?.id || !l.name.startsWith(`${o.name}/`));
+        lines.push('', ...section(under && linked ? `Names under ${o.name}/ and documents it links to`
+            : under ? `Names under ${o.name}/` : 'Documents it links to', d.listing));
+    }
+    lines.push('</object>');
+    return { body: d.needs_merge ? '' : d.bodies[0] ?? '', metadata: lines.join('\n'), context: d.attachments ?? '' };
+}
+/** Never mirror bodies into viewer metadata; a head's body belongs in the tool result. */
+export function previewRead(result) {
+    const parts = documentReadParts(result);
+    if (parts === null || result.state !== 'object' || isJsonOutput())
+        return result;
+    return { state: 'object', type: 'document', object: result.object, readMetadata: parts.metadata, readContext: parts.context };
+}
+export function renderReadOutput(result) {
+    const parts = documentReadParts(result);
+    if (parts === null)
+        return renderRead(result);
+    if (process.env[PREVIEW_RESULT_PATH_ENV] === undefined && process.stdout.isTTY)
+        return renderRead(result);
+    // For a merge there is no single body: stdout is empty, each attributed head
+    // (and its text) goes through metadata, so a partial replacement remains disallowed.
+    const metadata = `${parts.metadata}\n${parts.context ? `${parts.context}\n` : ''}`;
+    if (!process.env[PREVIEW_RESULT_PATH_ENV])
+        process.stderr.write(metadata);
+    return parts.body;
+}
+export const readLeaf = defineLeaf({
+    name: 'read',
+    description: 'read one object — a document, node, job or owner — by name or id',
+    whenToUse: 'you need the content or state of an object you can name: a document\u2019s body, a node\u2019s status and what it owns, a job\u2019s result. Reading makes you a watcher of the object. Find the name first with `crtr canvas search` or `crtr canvas list` when you do not know it.',
+    help: {
+        name: 'canvas read',
+        summary: 'read one object by name or id and become a watcher of it',
+        params: [
+            { kind: 'positional', name: 'ref', required: true, constraint: REF_CONSTRAINT },
+            { kind: 'flag', name: 'fields', type: 'bool', required: false, constraint: 'When present, a document read also returns its delivery rules, why-it-exists, unlisted, lint-ignore and plugin extension fields.' },
+        ],
+        output: [
+            { name: 'object', type: 'string', required: true, constraint: 'A document prints only its exact body to stdout (including when piped or redirected). Its attributed `<object>` header, preview, summary, revision, listing, linked previews, and `<auto-loaded-context>` arrive AFTER command output in a node’s tool result. Several heads print no stdout body; each head with its text appears in metadata, and the next `crtr doc edit` merges them. Outside a node, metadata goes to stderr when stdout is not a TTY; a TTY shows the full rendering as before. `--json` is unchanged. Non-document objects retain their full rendered stdout.' },
+            { name: 'deleted', type: 'string', required: false, constraint: '`<deleted …>` with the last preview when the object was deleted.' },
+            { name: 'remote', type: 'string', required: false, constraint: 'A line saying no object has that name on this runtime: it may be on another runtime, or the name may be misspelled.' },
+        ],
+        outputKind: 'object',
+        effects: ['A live read records a watch on the object for you (every event subject) and publishes a read event to its other watchers. A deleted or remote answer records nothing.'],
+    },
+    run: async (input) => {
+        try {
+            return { ...(await cliClient().objects.read(input['ref'], input['fields'] === true ? { fields: true } : undefined)) };
+        }
+        catch (err) {
+            rethrowAsCliError(err);
+        }
+    },
+    render: (result) => renderReadOutput(result),
+    preview: (result) => previewRead(result),
+    stdoutExact: (result) => documentReadParts(result) !== null
+        && !(process.env[PREVIEW_RESULT_PATH_ENV] === undefined && process.stdout.isTTY),
+});

package/dist/commands/canvas/search.d.ts

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

package/dist/commands/canvas/search.js

@@ -0,0 +1,49 @@
+import { defineLeaf } from '../../core/command.js';
+import { cliClient, rethrowAsCliError } from '../api-client.js';
+import { listItemRow } from './list.js';
+export const searchLeaf = defineLeaf({
+    name: 'search',
+    description: 'search objects by name, preview or body text',
+    whenToUse: 'finding an object when you do not know its name — a document on a topic, a report that mentions something, the exact line a regex matches. Records nothing; read a hit with `crtr canvas read`.',
+    help: {
+        name: 'canvas search',
+        summary: 'find the objects you can read by text; records nothing',
+        params: [
+            { kind: 'positional', name: 'text', required: true, constraint: 'Words matched against names, previews and summaries (and document bodies with --body).' },
+            { kind: 'flag', name: 'body', type: 'bool', required: false, constraint: 'When present, also matches document bodies.' },
+            { kind: 'flag', name: 'grep', type: 'string', required: false, constraint: 'An ECMAScript regex matched against document body lines; each hit lists its matching lines with line numbers.' },
+            { kind: 'flag', name: 'type', type: 'string', required: false, constraint: 'Only objects of this kind: document, node, job, person, app, repo or profile. The daemon rejects a name no kind declares and lists the kinds.' },
+            { kind: 'flag', name: 'kind', type: 'string', required: false, constraint: 'Only objects of this kind.' },
+            { kind: 'flag', name: 'owner', type: 'string', required: false, constraint: 'Only objects this owner owns directly: a node id, a handle, or any name `crtr canvas read` accepts.' },
+            { kind: 'flag', name: 'limit', type: 'int', required: false, constraint: 'Most hits returned, 1 to 100.' },
+        ],
+        output: [
+            { name: 'items', type: 'string[]', required: true, constraint: 'One row per hit, as `crtr canvas list` shows it, followed by the matching body lines when --grep is set.' },
+        ],
+        outputKind: 'object',
+        effects: ['None. Searching records no watch.'],
+    },
+    run: async (input) => {
+        const request = {
+            text: input['text'],
+            ...(input['body'] === true ? { body: true } : {}),
+            ...(input['grep'] ? { grep: input['grep'] } : {}),
+            ...(input['type'] ? { type: input['type'] } : {}),
+            ...(input['kind'] ? { kind: input['kind'] } : {}),
+            ...(input['owner'] ? { owner: input['owner'] } : {}),
+            ...(input['limit'] ? { limit: input['limit'] } : {}),
+        };
+        try {
+            return { ...(await cliClient().objects.search(request)) };
+        }
+        catch (err) {
+            rethrowAsCliError(err);
+        }
+    },
+    render: (result) => {
+        const { items } = result;
+        if (items.length === 0)
+            return 'No objects match.';
+        return items.map((hit) => [listItemRow(hit.object), ...(hit.matches ?? []).map((m) => `    ${m.line}: ${m.text}`)].join('\n')).join('\n');
+    },
+});

package/dist/commands/canvas/share.d.ts

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

package/dist/commands/canvas/share.js

@@ -0,0 +1,80 @@
+import { defineLeaf } from '../../core/command.js';
+import { usage } from '../../core/errors.js';
+import { SHARE_VERBS } from '../../api/dto/permissions.js';
+import { routes } from '../../api/routes.js';
+import { cliClient, rethrowAsCliError } from '../api-client.js';
+import { REF_CONSTRAINT } from './read.js';
+/** `everyone` is the wildcard subject `user:*`; every other subject is written as the fact names it. */
+function subjectOf(raw) {
+    if (raw === 'everyone')
+        return 'user:*';
+    if (!/^(user|team):[^\s:*]+$/.test(raw)) {
+        throw usage(`\`${raw}\` is not a subject`, { field: 'subject', received: raw, next: 'Use `user:<id>`, `team:<id>` or `everyone`.' });
+    }
+    return raw;
+}
+export const shareLeaf = defineLeaf({
+    name: 'share',
+    description: 'share an object you own with a person, a team or everyone, take the share back, or list who it is shared with',
+    whenToUse: 'another person (or a directory team, or everyone) should read, edit, message or use something you own — a document, a node, an environment. Only the owner and the owner’s agents can share; someone a thing was shared with cannot pass it on.',
+    help: {
+        name: 'canvas share',
+        summary: 'give a person, team or everyone one permission on an object; `--revoke` removes it; with only the object, lists its shares',
+        params: [
+            { kind: 'positional', name: 'object', required: true, constraint: REF_CONSTRAINT },
+            { kind: 'positional', name: 'verb', required: false, constraint: 'Omit with the subject to list the object’s shares. `read` (any object), `edit` (documents), `message` (nodes and profiles: attach, drive, interrupt and read in full; the owner pays for the turns), `use` (environments).' },
+            { kind: 'positional', name: 'subject', required: false, constraint: '`user:<id>`, `team:<id>` (a directory team) or `everyone`. `everyone` takes only `read` and needs an install that has joined the directory.' },
+            { kind: 'flag', name: 'revoke', type: 'bool', required: false, constraint: 'Remove the share instead of adding it. Takes effect on the next check: a connected viewer is closed and watchers stop receiving events.' },
+        ],
+        output: [
+            { name: 'result', type: 'string', required: true, constraint: 'What was shared or revoked, or that it already held; or one line per share (verb, subject, who wrote it, when) for the list.' },
+        ],
+        outputKind: 'object',
+        effects: ['With a verb and subject, writes or deletes one permission fact on the object; it applies to everything the object owns, and the object publishes `relation.written` or `relation.deleted`.'],
+    },
+    run: async (input) => {
+        const ref = input['object'];
+        const verb = input['verb'];
+        const rawSubject = input['subject'];
+        if (verb === undefined || rawSubject === undefined) {
+            if (verb !== undefined || input['revoke'] === true)
+                throw usage('`share` needs a verb and a subject', { field: 'subject', next: 'Give `<object> <verb> <subject>`, or only `<object>` to list its shares.' });
+            try {
+                return { list: true, ...(await cliClient().request('GET', routes.objectShares(ref))) };
+            }
+            catch (err) {
+                rethrowAsCliError(err);
+            }
+        }
+        if (!SHARE_VERBS.includes(verb)) {
+            throw usage(`\`${verb}\` is not a share verb`, { field: 'verb', received: verb, next: `Use one of ${SHARE_VERBS.join(', ')}.` });
+        }
+        const subject = subjectOf(rawSubject);
+        try {
+            const client = cliClient();
+            if (input['revoke'] === true) {
+                const query = new URLSearchParams({ verb, subject });
+                return { revoked: true, ...(await client.request('DELETE', `${routes.objectShares(ref)}?${query}`)) };
+            }
+            const body = { verb: verb, subject };
+            return { revoked: false, ...(await client.request('POST', routes.objectShares(ref), body)) };
+        }
+        catch (err) {
+            rethrowAsCliError(err);
+        }
+    },
+    render: (result) => {
+        if (result.list === true) {
+            const l = result;
+            if (l.items.length === 0)
+                return `[[${l.name}]] is shared with no one.`;
+            return [`[[${l.name}]] is shared with:`, ...l.items.map((i) => `- ${i.subject === 'user:*' ? 'everyone' : i.subject} can ${i.verb} (written by ${i.written_by}, ${i.created_at})`)].join('\n');
+        }
+        const r = result;
+        const who = r.subject === 'user:*' ? 'everyone' : r.subject;
+        const verb = Object.entries({ reader: 'read', editor: 'edit', messenger: 'message', user_of: 'use' }).find(([rel]) => rel === r.relation)?.[1] ?? r.relation;
+        if (r.revoked)
+            return r.changed ? `Revoked ${verb} on [[${r.name}]] from ${who}.` : `${who} held no ${verb} share on [[${r.name}]].`;
+        return r.changed ? `Shared [[${r.name}]]: ${who} can ${verb} it.` : `${who} could already ${verb} [[${r.name}]].`;
+    },
+});

package/dist/commands/canvas/unwatch.d.ts

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

package/dist/commands/canvas/unwatch.js

@@ -0,0 +1,42 @@
+import { defineLeaf } from '../../core/command.js';
+import { routes } from '../../api/routes.js';
+import { publishToken } from '../custom-object/shared.js';
+import { cliClient, rethrowAsCliError } from '../api-client.js';
+import { REF_CONSTRAINT } from './read.js';
+import { PATTERN_CONSTRAINT } from './watch.js';
+export const unwatchLeaf = defineLeaf({
+    name: 'unwatch',
+    description: 'stop watching an object as yourself or a custom object',
+    whenToUse: 'you or your custom object no longer need an object’s events — a document you read once, a node whose work no longer concerns you.',
+    help: {
+        name: 'canvas unwatch',
+        summary: 'remove your or a custom object’s watch, optionally for one pattern only',
+        params: [
+            { kind: 'positional', name: 'ref', required: true, constraint: REF_CONSTRAINT },
+            { kind: 'flag', name: 'pattern', type: 'string', required: false, constraint: `Remove only this pattern. ${PATTERN_CONSTRAINT} Omit to remove every pattern.` },
+            { kind: 'flag', name: 'as', type: 'string', required: false, constraint: 'Custom-object ref whose watch to remove instead of your node’s. Use an authorized principal or its publish token via CRTR_PUBLISH_TOKEN.' },
+        ],
+        output: [
+            { name: 'unwatched', type: 'string', required: true, constraint: 'The object and how many watch patterns were removed.' },
+        ],
+        outputKind: 'object',
+        effects: ['Removes the watcher’s patterns on the object; its events stop reaching that receiver. Watches that keep a spawned node in your tree are removed the same way.'],
+    },
+    run: async (input) => {
+        try {
+            const query = {
+                ...(input['pattern'] ? { pattern: input['pattern'] } : {}),
+                ...(input['as'] ? { watcher: input['as'] } : {}),
+            };
+            const params = new URLSearchParams(query);
+            return { ...(await cliClient().request('DELETE', `${routes.objectWatch(input['ref'])}?${params}`, undefined, input['as'] ? publishToken(input) : undefined)) };
+        }
+        catch (err) {
+            rethrowAsCliError(err);
+        }
+    },
+    render: (result) => {
+        const { object, removed } = result;
+        return `<unwatched id="${object.id}" name="${object.name}" removed="${removed}">`;
+    },
+});

package/dist/commands/canvas/watch.d.ts

@@ -0,0 +1,3 @@
+import type { LeafDef } from '../../core/command.js';
+export declare const PATTERN_CONSTRAINT = "An event subject pattern: dot-separated segments, where `*` matches exactly one segment and `>` matches one or more trailing segments. `>` alone matches every event.";
+export declare const watchLeaf: LeafDef;

package/dist/commands/canvas/watch.js

@@ -0,0 +1,63 @@
+import { defineLeaf } from '../../core/command.js';
+import { usage } from '../../core/errors.js';
+import { cliClient, rethrowAsCliError } from '../api-client.js';
+import { routes } from '../../api/routes.js';
+import { publishToken } from '../custom-object/shared.js';
+import { REF_CONSTRAINT } from './read.js';
+export const PATTERN_CONSTRAINT = 'An event subject pattern: dot-separated segments, where `*` matches exactly one segment and `>` matches one or more trailing segments. `>` alone matches every event.';
+function parseJsonObject(flag, raw) {
+    if (raw === undefined)
+        return undefined;
+    let value;
+    try {
+        value = JSON.parse(raw);
+    }
+    catch {
+        value = undefined;
+    }
+    if (value === null || typeof value !== 'object' || Array.isArray(value)) {
+        throw usage(`--${flag} must be a JSON object`, { field: flag, received: raw, next: `Run \`crtr canvas watch -h\` for the --${flag} shape.` });
+    }
+    return value;
+}
+export const watchLeaf = defineLeaf({
+    name: 'watch',
+    description: 'watch an object as yourself or as a custom object',
+    whenToUse: 'you or a registered custom object should receive an object’s future events — a document edit, a node report — without reading it now. Reading already makes you a watcher; use this for patterns or a listening configuration.',
+    help: {
+        name: 'canvas watch',
+        summary: 'make yourself or a custom object a watcher, optionally for chosen events only',
+        params: [
+            { kind: 'positional', name: 'ref', required: true, constraint: REF_CONSTRAINT },
+            { kind: 'flag', name: 'pattern', type: 'string', required: false, repeatable: true, constraint: `${PATTERN_CONSTRAINT} Default \`>\`.` },
+            { kind: 'flag', name: 'listen', type: 'string', required: false, constraint: 'JSON object mapping an event level (1–10) to how it reaches you: `{"<level>":"interrupt|steer|after-turn|next-turn"}`. Omitted levels use the watcher’s listening default (your node or --as object).' },
+            { kind: 'flag', name: 'filter', type: 'string', required: false, constraint: 'JSON object of event fields an event must match to be delivered.' },
+            { kind: 'flag', name: 'as', type: 'string', required: false, constraint: 'Custom-object ref to watch as instead of your node. Its receiver gets events under its owner’s read rights; use an authorized principal or its publish token via CRTR_PUBLISH_TOKEN.' },
+        ],
+        output: [
+            { name: 'watching', type: 'string', required: true, constraint: 'The object and the patterns you now watch it for.' },
+        ],
+        outputKind: 'object',
+        effects: ['Records a watch; matching events reach your node or the --as object’s receiver, and the watched object’s other watchers see a watched event.'],
+    },
+    run: async (input) => {
+        const listen = parseJsonObject('listen', input['listen']);
+        const filter = parseJsonObject('filter', input['filter']);
+        const request = {
+            ...(Array.isArray(input['pattern']) ? { patterns: input['pattern'] } : {}),
+            ...(listen ? { config: listen } : {}),
+            ...(filter ? { filter } : {}),
+            ...(input['as'] ? { watcher: input['as'] } : {}),
+        };
+        try {
+            return { ...(await cliClient().request('POST', routes.objectWatch(input['ref']), request, input['as'] ? publishToken(input) : undefined)) };
+        }
+        catch (err) {
+            rethrowAsCliError(err);
+        }
+    },
+    render: (result) => {
+        const { object, patterns } = result;
+        return `<watching id="${object.id}" name="${object.name}" patterns="${patterns.join(' ')}">`;
+    },
+});

package/dist/commands/canvas-analytics/chart.d.ts

@@ -0,0 +1,52 @@
+/** Horizontal bar at eighth-cell resolution, `value` scaled against `max` over
+ *  `cells` columns, padded to exactly `cells`. A non-zero value shows at least
+ *  one eighth, so it never reads as zero. */
+export declare function hbar(value: number, max: number, cells: number): string;
+/** The fills a stacked bar uses, in order. The last one is for "other". */
+export declare const STACK_FILLS: readonly ["█", "▓", "▒", "░"];
+export declare const OTHER_FILL = "\u259A";
+/** One fill per part: the first four parts take `STACK_FILLS`, any later part
+ *  takes `OTHER_FILL`. Callers put "other" last. */
+export declare function stackFill(index: number): string;
+/** A bar of exactly `cells` whole cells split by share of the parts' total.
+ *  Each non-zero part gets at least one cell while cells allow, so a part that
+ *  exists never disappears from the bar. `fills[i]` defaults to `stackFill(i)`. */
+export declare function stackedBar(parts: readonly number[], cells: number, fills?: readonly string[]): string;
+/** The legend for a stacked bar: "█ opus  ▓ sonnet  ▒ codex  ░ gemini  ▚ other". */
+export declare function stackLegend(labels: readonly string[], fills?: readonly string[]): string;
+/** A column chart `rows` high, top row first. Each value is one column of
+ *  `columnWidth` cells, columns separated by `gap` spaces, scaled to the
+ *  largest value at eighth-cell resolution. A non-zero value shows at least ▁. */
+export declare function columnChart(values: readonly number[], rows: number, columnWidth?: number, gap?: number): string[];
+/** A log-scale axis from `minMs` to `maxMs` over `cells` columns. */
+export interface LogAxis {
+    minMs: number;
+    maxMs: number;
+    cells: number;
+}
+/** The column (0 … cells−1) for `ms` on a log axis; values outside the axis
+ *  sit at its end. */
+export declare function logPosition(ms: number, axis: LogAxis): number;
+/** A percentile line on a log axis: `─` from p10 to p90 and `●` at the
+ *  median, padded to exactly `axis.cells`. One sample (p10 = p90) is one `●`. */
+export declare function percentileLine(stats: {
+    p10_ms: number;
+    median_ms: number;
+    p90_ms: number;
+}, axis: LogAxis): string;
+/** Tick labels placed at their log positions over `axis.cells` columns, each
+ *  label starting at its tick; a label that would overlap the previous one is
+ *  dropped. */
+export declare function logAxisLabels(ticks: ReadonlyArray<{
+    ms: number;
+    label: string;
+}>, axis: LogAxis): string;
+/** A ranked list folded to its first `keep` rows plus the rest as one sum, for
+ *  "<n> more …" rows. The rest is undefined when nothing is folded. */
+export declare function foldRanked<T>(rows: readonly T[], keep: number, value: (row: T) => number): {
+    top: T[];
+    rest: {
+        count: number;
+        sum: number;
+    } | undefined;
+};