@prestack/thread 0.0.1

package/dist/operations/generators/capability.js

@@ -0,0 +1,603 @@
+var __rewriteRelativeImportExtension = (this && this.__rewriteRelativeImportExtension) || function (path, preserveJsx) {
+    if (typeof path === "string" && /^\.\.?\//.test(path)) {
+        return path.replace(/\.(tsx)$|((?:\.d)?)((?:\.[^./]+?)?)\.([cm]?)ts$/i, function (m, tsx, d, ext, cm) {
+            return tsx ? preserveJsx ? ".jsx" : ".js" : d && (!ext || !cm) ? m : (d + ext + "." + cm.toLowerCase() + "js");
+        });
+    }
+    return path;
+};
+import { existsSync, mkdirSync, readdirSync, readFileSync, writeFileSync } from 'node:fs';
+import { dirname, resolve } from 'node:path';
+import { argv, stdout } from 'node:process';
+import { pathToFileURL } from 'node:url';
+import { marked, wordsIn } from "../../core/asking.js";
+import { ROOT, TREE, descend } from "../../core/descend.js";
+import { exit, invoked } from "../../core/invoked.js";
+import { named as packageOf } from "../../core/scope.js";
+import { PREFIXES } from "../../core/thread.js";
+import { servesBrowser } from "../../integrations/target.js";
+import { CAPABILITIES_AT, CLIENT_AT, DECLARED_SEAMS_AT, MCP_AT, OPENAPI_AT, DISPATCHING_AT, SEAMS_AT, routeAt, SURFACES, switched, } from "../capabilities.js";
+import { ENVIRONMENT } from "../../core/actor.js";
+import { PERMITS_AT } from "../access.js";
+import { SAID as HANDED, supplies } from "../seams.js";
+import { beside, operations, quoted, runtime, types } from "./seed.js";
+const compare = (a, b) => (a < b ? -1 : a > b ? 1 : 0);
+function stable(value) {
+    if (Array.isArray(value))
+        return value.map(stable);
+    if (typeof value === 'object' && value !== null) {
+        const found = {};
+        for (const key of Object.keys(value).sort(compare)) {
+            found[key] = stable(value[key]);
+        }
+        return found;
+    }
+    return value === undefined ? null : value;
+}
+const printed = (value) => `${JSON.stringify(stable(value), null, 2)}\n`;
+function verbOf(id) {
+    if (id.startsWith(PREFIXES.view))
+        return 'GET';
+    if (id.startsWith(PREFIXES.workflow) || id.startsWith(PREFIXES.agent))
+        return 'POST';
+    return undefined;
+}
+async function schemaOf(at) {
+    const from = resolve(ROOT, at);
+    if (!existsSync(from))
+        return `${at} is not there, so nothing states what this operation takes`;
+    const held = (await import(__rewriteRelativeImportExtension(pathToFileURL(from).href)));
+    const input = held.input;
+    if (input === undefined)
+        return `${at} exports no \`input\`, so nothing states what this operation takes`;
+    const zod = (await import('zod'));
+    if (zod.toJSONSchema === undefined) {
+        return 'this app\'s zod states no `toJSONSchema`, so an input schema cannot be written from it';
+    }
+    try {
+        return zod.toJSONSchema(input);
+    }
+    catch (thrown) {
+        return `${at} states an input that cannot be written as a schema: ${thrown instanceof Error ? thrown.message : String(thrown)}`;
+    }
+}
+async function sheet(file, list) {
+    const at = resolve(ROOT, `_threads/${file}`);
+    if (!existsSync(at))
+        return [];
+    try {
+        const held = (await import(__rewriteRelativeImportExtension(pathToFileURL(at).href)));
+        return held[list] ?? [];
+    }
+    catch {
+        return [];
+    }
+}
+function browsing(requires, targets, secrets) {
+    for (const word of requires) {
+        const target = targets.find((one) => one.id === word);
+        if (target === undefined)
+            continue;
+        if (servesBrowser(target, secrets) !== true)
+            return false;
+    }
+    return true;
+}
+function locally(requires) {
+    for (const word of requires) {
+        if (!supplies(word))
+            return false;
+        if (word === 'sm_vault')
+            return false;
+    }
+    return true;
+}
+export async function derive() {
+    const pass = descend();
+    const known = types(pass);
+    const refusals = [];
+    const found = [];
+    const targets = await sheet('targets.ts', 'TARGETS');
+    const secrets = await sheet('secrets.ts', 'SECRETS');
+    const at = resolve(ROOT, CAPABILITIES_AT);
+    const already = switched(existsSync(at) ? readFileSync(at, 'utf8') : undefined);
+    for (const [id, one] of [...operations(pass, known)].sort((a, b) => compare(a[0], b[0]))) {
+        const stated = pass.stated.get(id);
+        const describes = stated?.describes;
+        if (describes === undefined) {
+            refusals.push(`\`${id}\` states no \`describes\`, and a caller told nothing about an operation cannot choose it`);
+            continue;
+        }
+        const method = verbOf(id);
+        if (method === undefined) {
+            refusals.push(`\`${id}\` wears none of the prefixes an operation may wear (${Object.values(PREFIXES).join(', ')}), so there is no verb to give it`);
+            continue;
+        }
+        const takes = one.takes[0]?.at;
+        if (takes === undefined) {
+            refusals.push(`\`${id}\` names nothing it takes, so nothing states its input`);
+            continue;
+        }
+        const schema = await schemaOf(takes);
+        if (typeof schema === 'string') {
+            refusals.push(`\`${id}\`: ${schema}`);
+            continue;
+        }
+        const live = already.get(id) ?? [...SURFACES];
+        found.push({
+            operation: id,
+            describes,
+            requires: [...one.requires].sort(compare),
+            nodes: one.nodes.map((each) => each.id ?? '').filter((each) => each !== ''),
+            input: schema,
+            live: [...live].sort(compare),
+            browsable: browsing(one.requires, targets, secrets),
+            local: browsing(one.requires, targets, secrets) && locally(one.requires),
+            mcp: { name: id, description: describes, inputSchema: schema },
+            cli: { invocation: `${id} --input '<json>'`, describes },
+            api: { method, path: `/operations/${id}` },
+        });
+    }
+    return { found, refusals };
+}
+function named() {
+    try {
+        const held = JSON.parse(readFileSync(resolve(ROOT, 'package.json'), 'utf8'));
+        return {
+            title: typeof held.name === 'string' ? held.name : 'this app',
+            version: typeof held.version === 'string' ? held.version : '0.0.0',
+        };
+    }
+    catch {
+        return { title: 'this app', version: '0.0.0' };
+    }
+}
+function openapi(found) {
+    const paths = {};
+    for (const one of found) {
+        if (!one.live.includes('api'))
+            continue;
+        const method = one.api.method.toLowerCase();
+        const responses = {
+            '200': {
+                description: 'the operation ran',
+                content: { 'application/json': { schema: { type: 'object', properties: { ok: { const: true }, value: {} }, required: ['ok'] } } },
+            },
+            '400': {
+                description: 'dispatch refused it — the code says which gate',
+                content: {
+                    'application/json': {
+                        schema: {
+                            type: 'object',
+                            properties: {
+                                ok: { const: false },
+                                code: { enum: ['denied', 'invalid', 'rate_limited', 'feature_denied', 'quota_exceeded', 'error'] },
+                                error: { type: 'string' },
+                                because: { type: 'string' },
+                            },
+                            required: ['ok', 'code', 'error'],
+                        },
+                    },
+                },
+            },
+        };
+        paths[one.api.path] = {
+            [method]: {
+                operationId: one.operation,
+                summary: one.describes,
+                ...(one.api.method === 'GET'
+                    ? { parameters: [{ name: 'input', in: 'query', required: true, content: { 'application/json': { schema: one.input } } }] }
+                    : { requestBody: { required: true, content: { 'application/json': { schema: one.input } } } }),
+                responses,
+            },
+        };
+    }
+    const who = named();
+    return {
+        openapi: '3.1.0',
+        info: { title: who.title, version: who.version, description: 'Every operation this app declares that is live on its API surface.' },
+        paths,
+    };
+}
+const mcp = (found) => ({
+    tools: found.filter((one) => one.live.includes('mcp')).map((one) => one.mcp),
+});
+const compiled = (operation) => existsSync(resolve(ROOT, `operations/${operation}.ts`));
+function client(found) {
+    const rows = found
+        .filter(held)
+        .map((one) => [
+        '  {',
+        `    operation: ${JSON.stringify(one.operation)},`,
+        `    describes: ${JSON.stringify(one.describes)},`,
+        `    method: ${JSON.stringify(one.api.method)},`,
+        `    path: ${JSON.stringify(one.api.path)},`,
+        '  },',
+    ].join('\n'));
+    const near = found.filter((one) => one.local && compiled(one.operation));
+    const bound = near.flatMap((one) => [
+        `export async function ${one.operation}Locally(input: unknown, actor: Actor, seams: Seams): Promise<Result<unknown>> {`,
+        `  const held = await dispatch(${one.operation}, input, actor, seams)`,
+        '  return held',
+        '}',
+        '',
+    ]);
+    return [
+        ...(near.length === 0
+            ? []
+            : [
+                `import type { Actor } from '${runtime(CLIENT_AT, '../../core/actor.ts')}'`,
+                `import type { Result } from '${runtime(CLIENT_AT, '../result.ts')}'`,
+                `import type { Seams } from '${runtime(CLIENT_AT, '../seams.ts')}'`,
+                '',
+                "import { dispatch } from './_dispatch.ts'",
+                ...near.map((one) => `import { operation as ${one.operation} } from './${one.operation}.ts'`),
+                '',
+            ]),
+        'export interface Reachable {',
+        '  readonly operation: string',
+        '  readonly describes: string',
+        "  readonly method: 'GET' | 'POST'",
+        '  readonly path: string',
+        '}',
+        '',
+        `export const CLIENT: readonly Reachable[] = [${rows.length === 0 ? '' : `\n${rows.join('\n')}\n`}]`,
+        '',
+        'export const reachable = (operation: string): Reachable | undefined =>',
+        '  CLIENT.find((one) => one.operation === operation)',
+        '',
+        ...bound,
+        '',
+    ].join('\n');
+}
+function route(one) {
+    const at = routeAt(one.operation);
+    return [
+        "import { existsSync } from 'node:fs'",
+        "import { join } from 'node:path'",
+        '',
+        "import { dispatch } from '../../../operations/_dispatch.ts'",
+        `import { actor } from '${beside(at, DECLARED_SEAMS_AT)}'`,
+        `import { SEAMS } from '${beside(at, SEAMS_AT)}'`,
+        `import { operation } from '../../../operations/${one.operation}.ts'`,
+        '',
+        'const STATUS: Record<string, number> = {',
+        '  denied: 403,',
+        '  invalid: 400,',
+        '  rate_limited: 429,',
+        '  feature_denied: 403,',
+        '  quota_exceeded: 429,',
+        '  error: 500,',
+        '}',
+        '',
+        "const PASSED = existsSync(join(process.cwd(), '.thread', 'gate.json'))",
+        '',
+        `export async function ${one.api.method}(request: Request): Promise<Response> {`,
+        '  if (!PASSED) {',
+        '    return Response.json(',
+        "      { ok: false, code: 'error', error: 'failed', because: 'this tree has no passing gate, so nothing in it may answer a request. Run `thread gate` — a gate that has never run is not a gate that passed' },",
+        '      { status: 500 },',
+        '    )',
+        '  }',
+        ...(one.api.method === 'GET'
+            ? ['  const input = Object.fromEntries(new URL(request.url).searchParams)']
+            : ['  const input = await request.json().catch(() => undefined)']),
+        '  const held = await dispatch(operation, input, await actor(request), SEAMS)',
+        '  return Response.json(held, { status: held.ok ? 200 : (STATUS[held.code] ?? 500) })',
+        '}',
+        '',
+    ].join('\n');
+}
+const SEAM = /export\s+const\s+store\s*:/;
+const STORES_AT = 'src/stores';
+function kept() {
+    const at = resolve(ROOT, STORES_AT);
+    if (!existsSync(at))
+        return [];
+    return readdirSync(at)
+        .filter((one) => one.endsWith('.ts'))
+        .filter((one) => {
+        try {
+            return SEAM.test(readFileSync(resolve(at, one), 'utf8'));
+        }
+        catch {
+            return false;
+        }
+    })
+        .sort()
+        .map((one) => `${STORES_AT}/${one}`);
+}
+const ENTITIES_AT = `${TREE}entities.ts`;
+const OPERATIONS_AT = `${TREE}operations.ts`;
+const VAULT_AT = `src/vault.${'ts'}`;
+function settled(keeping, stores, ruled, vaulted) {
+    const named = stores.map((one, at) => ({ from: beside(DECLARED_SEAMS_AT, one), as: `s${String(at)}` }));
+    const only = named[0];
+    return [
+        `import { ANONYMOUS, type Actor, type Environment } from '${runtime(DECLARED_SEAMS_AT, '../../core/actor.ts')}'`,
+        `import { httpSeam } from '${runtime(DECLARED_SEAMS_AT, '../http.ts')}'`,
+        `import { arrived, fresh, inMemorySeams } from '${runtime(DECLARED_SEAMS_AT, '../memory.ts')}'`,
+        `import type { Seams } from '${runtime(DECLARED_SEAMS_AT, '../seams.ts')}'`,
+        ...(keeping ? [`import { ENTITIES } from '${beside(DECLARED_SEAMS_AT, ENTITIES_AT)}'`] : []),
+        ...(ruled ? [`import { permits } from '${beside(DECLARED_SEAMS_AT, PERMITS_AT)}'`] : []),
+        ...(vaulted ? [`import { vault as opening } from '${beside(DECLARED_SEAMS_AT, VAULT_AT)}'`] : []),
+        ...(stores.length === 1 && only !== undefined ? [`import { store as kept } from '${only.from}'`] : []),
+        ...(stores.length > 1 ? named.map((one) => `import { keeps as ${one.as}Keeps, store as ${one.as} } from '${one.from}'`) : []),
+        '',
+        ...(keeping
+            ? [
+                'const KEPT = new Map(ENTITIES.map((one) => [one.id, new Set(one.holds.map((each) => each.id))]))',
+                '',
+                'const ADDRESSED = new Map(',
+                '  ENTITIES.flatMap((one) => {',
+                "    const held = (one.must ?? []).flatMap((each) => ('unique' in each ? each.unique : []))[0]",
+                '    return held === undefined ? [] : [[one.id, held] as const]',
+                '  }),',
+                ')',
+                '',
+                'const made = inMemorySeams({ entities: KEPT, keys: ADDRESSED }).seams',
+            ]
+            : ['const made = inMemorySeams().seams']),
+        '',
+        ...(stores.length > 1
+            ? [
+                "const WHERE = new Map<string, Seams['store']>([",
+                ...named.map((one) => `  ...${one.as}Keeps.map((entity) => [entity, ${one.as}] as const),`),
+                '])',
+                '',
+                'function at(entity: string) {',
+                '  const found = WHERE.get(entity)',
+                "  if (found === undefined) throw new Error(entity + ' is not kept in any target this app declares')",
+                '  return found',
+                '}',
+                '',
+                "const store: Seams['store'] = {",
+                '  insert: (actor, entity, row) => at(entity).insert(actor, entity, row),',
+                '  get: (actor, entity, key, fields) => at(entity).get(actor, entity, key, fields),',
+                '  list: (actor, entity, opts) => at(entity).list(actor, entity, opts),',
+                '  update: (actor, entity, key, patch, expectedVersion) => at(entity).update(actor, entity, key, patch, expectedVersion),',
+                '  remove: (actor, entity, key) => at(entity).remove(actor, entity, key),',
+                '}',
+                '',
+            ]
+            : []),
+        'const shared = globalThis as { __threadSeams?: Seams }',
+        '',
+        'export const DECLARED: Seams = (shared.__threadSeams ??= {',
+        '  ...made,',
+        ...(stores.length === 1 ? ['  store: kept,'] : []),
+        ...(stores.length > 1 ? ['  store,'] : []),
+        '  clock: { now: arrived },',
+        '  random: { next: Math.random, uuid: fresh },',
+        '  http: httpSeam(),',
+        ...(ruled ? ['  permits: { check: (actor, action, resource) => Promise.resolve(permits(actor, action, resource)) },'] : []),
+        ...(vaulted ? ['  vault: { resolve: opening },'] : []),
+        '})',
+        '',
+        'function environment(request: Request): Environment {',
+        ...ENVIRONMENT.map(([fact, header]) => `  const ${fact} = request.headers.get(${quoted(header)})`),
+        '  return {',
+        ...ENVIRONMENT.map(([fact]) => `    ...(${fact} === null ? {} : { ${fact} }),`),
+        '  }',
+        '}',
+        '',
+        ...(keeping
+            ? [
+                'const worn = (held: unknown): readonly string[] =>',
+                "  Array.isArray(held) ? held.filter((one) => typeof one === 'string') : typeof held === 'string' ? [held] : []",
+                '',
+                'function addressed(request: Request, from: string): string | null {',
+                "  if (from.startsWith('cookie:')) {",
+                "    const jar = request.headers.get('cookie') ?? ''",
+                "    const want = `${from.slice('cookie:'.length).trim()}=`",
+                "    const found = jar.split(';').map((one) => one.trim()).find((one) => one.startsWith(want))",
+                '    return found === undefined ? null : decodeURIComponent(found.slice(want.length))',
+                '  }',
+                '  const held = request.headers.get(from)',
+                '  if (held === null) return null',
+                "  const bare = held.startsWith('Bearer ') ? held.slice('Bearer '.length) : held",
+                "  return bare.trim() === '' ? null : bare.trim()",
+                '}',
+                '',
+                'export async function actor(request: Request): Promise<Actor> {',
+                '  const anyone: Actor = { ...ANONYMOUS, ...environment(request) }',
+                '  const who = ENTITIES.find((one) => one.actor !== undefined)',
+                '  if (who?.actor === undefined) return anyone',
+                '',
+                "  const address = (who.must ?? []).flatMap((one) => ('unique' in one ? one.unique : []))[0]",
+                '  if (address === undefined) return anyone',
+                '',
+                '  const held = addressed(request, who.actor.from)',
+                '  if (held === null) return anyone',
+                '',
+                '  const token = who.actor.verifies',
+                '',
+                '  const row =',
+                '    token === undefined',
+                '      ? await DECLARED.store.get(anyone, who.id, held, [',
+                '          address,',
+                '          who.actor.roles,',
+                '          ...(who.actor.entitlements === undefined ? [] : [who.actor.entitlements]),',
+                '        ])',
+                '      : ((await DECLARED.store.list(anyone, who.id, { where: { [token]: held }, limit: 1 }))[0] ?? null)',
+                '  if (row === null) return anyone',
+                '',
+                '  return {',
+                '    ...anyone,',
+                '    id: String(row[address] ?? held),',
+                '    roles: worn(row[who.actor.roles]),',
+                '    entitlements: who.actor.entitlements === undefined ? [] : worn(row[who.actor.entitlements]),',
+                '  }',
+                '}',
+                '',
+            ]
+            : [
+                'export const actor = (request: Request): Promise<Actor> => Promise.resolve({ ...ANONYMOUS, ...environment(request) })',
+                '',
+            ]),
+    ].join('\n');
+}
+const seeded = () => [
+    `import { DECLARED } from '${beside(SEAMS_AT, DECLARED_SEAMS_AT)}'`,
+    `import type { Seams } from '${runtime(SEAMS_AT, '../seams.ts')}'`,
+    '',
+    'export const SEAMS: Seams = {',
+    '  ...DECLARED,',
+    '}',
+    '',
+].join('\n');
+const width = Math.max(...Object.keys(HANDED).map((one) => one.length));
+const handing = (stores, keeping, vaulted) => [
+    `capabilities: seeded ${SEAMS_AT} — what this app hands its operations, and yours from here.`,
+    `  It hands on everything ${DECLARED_SEAMS_AT} settles from your declarations: rows go to ` +
+        (stores.length === 0 ? 'memory until a target keeps entities' : stores.join(', ')) +
+        `, who is asking is ${keeping ? 'read off the entity that names the caller' : 'nobody until an entity names the caller'}, ` +
+        `calls leave through http${vaulted ? ' with credentials opened by the vault' : ''}.`,
+    '  Replace a seam, or add one, by naming it in SEAMS. Every seam an operation can be handed:',
+    ...Object.entries(HANDED).map(([one, says]) => `    ${one.padEnd(width)}  ${says}`),
+    '',
+].join('\n');
+const served = (one) => one.live.includes('api') && compiled(one.operation);
+const held = (one) => one.browsable && one.live.includes('api');
+function dispatching(found) {
+    const reachable = found.filter(served);
+    return [
+        '/* GENERATED by thread — do not edit. It is derived from what this app declares. */',
+        '',
+        `declare module '${packageOf('ui')}/checked' {`,
+        ...(reachable.length === 0
+            ? ['  interface Dispatching {}']
+            : ['  interface Dispatching {', ...reachable.map((one) => `    readonly ${one.operation}: true`), '  }']),
+        '}',
+        '',
+        'interface Reaches {',
+        '  readonly operation: string',
+        "  readonly method: 'GET' | 'POST'",
+        '  readonly path: string',
+        '}',
+        '',
+        `const REACHES: readonly Reaches[] = [${reachable.length === 0
+            ? ''
+            : `\n${reachable
+                .map((one) => `  { operation: ${JSON.stringify(one.operation)}, method: ${JSON.stringify(one.api?.method)}, path: ${JSON.stringify(one.api?.path)} },`)
+                .join('\n')}\n`}]`,
+        '',
+        'export async function dispatchTo(operation: string, input?: Readonly<Record<string, unknown>>): Promise<unknown> {',
+        '  const one = REACHES.find((each) => each.operation === operation)',
+        '  if (one === undefined) {',
+        '    throw new Error(',
+        "      `thread: nothing declares an operation called ${operation}, so there is nowhere to send this. ` +",
+        "        `This app reaches: ${REACHES.map((each) => each.operation).join(', ') || '(nothing)'}`,",
+        '    )',
+        '  }',
+        '  const sent = await fetch(one.path, {',
+        '    method: one.method,',
+        "    headers: { 'content-type': 'application/json' },",
+        "    ...(one.method === 'GET' ? {} : { body: JSON.stringify(input ?? {}) }),",
+        '  })',
+        '  return await sent.json()',
+        '}',
+        '',
+    ].join('\n');
+}
+const installed = () => existsSync(resolve(ROOT, '_threads', 'ui.ts'));
+const files = (found) => [
+    { at: CAPABILITIES_AT, text: printed(found) },
+    { at: OPENAPI_AT, text: printed(openapi(found)) },
+    { at: MCP_AT, text: printed(mcp(found)) },
+    { at: CLIENT_AT, text: client(found) },
+    ...(installed() ? [{ at: DISPATCHING_AT, text: dispatching(found) }] : []),
+    ...found.filter(served).map((one) => ({ at: routeAt(one.operation), text: route(one) })),
+];
+if (invoked(import.meta.url)) {
+    const { found, refusals } = await derive();
+    for (const one of refusals)
+        console.error(`capabilities: ${one}`);
+    const mark = (one) => marked([one.operation, one.describes, one.requires.join(','), one.nodes.join(','), one.live.join(',')]);
+    const words = wordsIn(['read']);
+    const verb = words[0];
+    if (verb === 'read') {
+        const which = words[1];
+        const one = found.find((each) => mark(each) === which);
+        if (one === undefined) {
+            console.error(`capabilities: \`${which ?? '(nothing)'}\` is not a mark this tree issued. Run \`thread capabilities\` to see them — each is printed in brackets beside the capability it belongs to.`);
+            exit(1);
+        }
+        stdout.write(`${one.operation} — ${one.describes}\n`);
+        stdout.write(`requires ${one.requires.length === 0 ? 'nothing' : one.requires.join(', ')}\n`);
+        stdout.write(`nodes: ${one.nodes.length === 0 ? '(none)' : one.nodes.join(', ')}\n`);
+        stdout.write(`live: ${SURFACES.map((each) => `${one.live.includes(each) ? '[on] ' : '[off]'} ${each}`).join('   ')}\n`);
+        stdout.write(`${one.browsable ? 'may be called from a page' : 'server only — it reaches a target that needs a server secret'}\n`);
+        stdout.write(`${one.local ? 'runs where it is called, with nothing sent' : 'reaches a target over the network'}\n`);
+        stdout.write(`api: ${one.api.method} ${one.api.path}\n`);
+        stdout.write(`cli: ${one.cli.invocation}\n`);
+        stdout.write(`mcp: ${one.mcp.name} — ${one.mcp.description}\n`);
+        stdout.write('input:\n');
+        for (const line of printed(one.input).trimEnd().split('\n'))
+            stdout.write(`  ${line}\n`);
+        exit(0);
+    }
+    const checking = argv.includes('--check');
+    let adrift = 0;
+    const keeping = existsSync(resolve(ROOT, ENTITIES_AT));
+    if (existsSync(resolve(ROOT, OPERATIONS_AT))) {
+        const stores = kept();
+        const vaulted = existsSync(resolve(ROOT, VAULT_AT));
+        const text = settled(keeping, stores, existsSync(resolve(ROOT, PERMITS_AT)), vaulted);
+        const at = resolve(ROOT, DECLARED_SEAMS_AT);
+        if ((existsSync(at) ? readFileSync(at, 'utf8') : '') !== text) {
+            if (checking) {
+                adrift += 1;
+                console.error(`capabilities: ${DECLARED_SEAMS_AT} is not what the declarations settle. Run \`thread capabilities\` and commit the result.`);
+            }
+            else {
+                mkdirSync(dirname(at), { recursive: true });
+                writeFileSync(at, text, 'utf8');
+                console.log(`capabilities: wrote ${DECLARED_SEAMS_AT} — the seams your targets, entities, grants and secrets settle.`);
+            }
+        }
+        const seed = resolve(ROOT, SEAMS_AT);
+        if (!existsSync(seed)) {
+            if (checking) {
+                adrift += 1;
+                console.error(`capabilities: ${SEAMS_AT} is not there, and it is what hands every operation its seams. Run \`thread capabilities\` — it seeds the file once, and from then on it is yours.`);
+            }
+            else {
+                mkdirSync(dirname(seed), { recursive: true });
+                writeFileSync(seed, seeded(), 'utf8');
+                stdout.write(handing(stores, keeping, vaulted));
+            }
+        }
+    }
+    if (found.length === 0 && refusals.length === 0) {
+        console.log('capabilities: this app declares no operation, so nothing is reachable through one yet.');
+        exit(adrift > 0 ? 1 : 0);
+    }
+    const written = files(found);
+    if (checking) {
+        const drifted = written.filter((one) => {
+            const path = resolve(ROOT, one.at);
+            return (existsSync(path) ? readFileSync(path, 'utf8') : '') !== one.text;
+        });
+        for (const one of drifted) {
+            console.error(`capabilities: ${one.at} is not what the operations derive. Run \`thread capabilities\` and commit the result.`);
+        }
+        const off = found.filter((one) => one.live.length < SURFACES.length);
+        console.log(`capabilities: ${String(found.length)} operation(s) reachable, ${String(off.length)} with a surface switched off, ` +
+            `${String(drifted.length + adrift)} finding(s).`);
+        exit(drifted.length + adrift > 0 || refusals.length > 0 ? 1 : 0);
+    }
+    if (refusals.length > 0) {
+        console.error(`capabilities: ${String(refusals.length)} refusal(s) above, so nothing was written`);
+        exit(1);
+    }
+    for (const one of written) {
+        const path = resolve(ROOT, one.at);
+        mkdirSync(dirname(path), { recursive: true });
+        writeFileSync(path, one.text);
+    }
+    const shipped = found.filter(held).length;
+    stdout.write(`capabilities: wrote ${written.map((one) => one.at).join(', ')} — ${String(found.length)} operation(s), ` +
+        `${String(shipped)} of them in the client bundle.\n`);
+    exit(0);
+}

package/dist/operations/generators/compile.d.ts

@@ -0,0 +1,2 @@
+export declare function parts(text: string): readonly string[];
+export declare function compile(say?: boolean): Promise<number>;