@north-light/api 0.3.580 → 0.3.588

package/dist/commands/sys/config.js

@@ -0,0 +1,353 @@
+import { defineBranch, defineLeaf } from '../../core/command.js';
+import { InvalidRawSettingsError, readConfig, readRawSettingsForTarget, replaceRawSettingsForTarget, updateConfig, persistModelLadders, configPath as coreConfigPath } from '../../core/config.js';
+import { usage, notFound } from '../../core/errors.js';
+import { requireScopeRoot } from '../../core/scope.js';
+import { resolveScope } from './shared.js';
+import { resolveProfileOperand } from '../../core/profiles/manifest.js';
+import { SettingsRevisionConflictError } from '../../core/scoped-state/person-store.js';
+import { InputError } from '../../core/io.js';
+import { SCOPE_CONFIG_KEYS, USER_SETTINGS, findUserSetting } from '../../core/user-settings.js';
+// Config helpers (ported from commands/config.ts)
+const CONFIG_TOP_LEVEL_HELP = SCOPE_CONFIG_KEYS.join(', ');
+const SCALAR_SETTING_HELP = USER_SETTINGS.map((setting) => `${setting.key} (${setting.valueConstraint})`).join(', ');
+const MODEL_PROVIDERS = new Set(['anthropic', 'openai']);
+const MODEL_STRENGTHS = new Set(['ultra', 'strong', 'medium', 'light']);
+function isModelProvider(value) {
+    return MODEL_PROVIDERS.has(value);
+}
+function isModelStrength(value) {
+    return MODEL_STRENGTHS.has(value);
+}
+function getNestedValue(obj, key) {
+    const parts = key.split('.');
+    let current = obj;
+    for (const part of parts) {
+        if (current === null || typeof current !== 'object')
+            return undefined;
+        current = current[part];
+    }
+    return current;
+}
+function parseConfigValue(raw) {
+    if (raw === 'true')
+        return true;
+    if (raw === 'false')
+        return false;
+    if (/^-?\d+$/.test(raw))
+        return parseInt(raw, 10);
+    return raw;
+}
+function assertUserScopeBrokerThresholds(key, scope) {
+    if (key.split('.', 1)[0] === 'brokerThresholds' && scope !== 'user') {
+        throw usage('brokerThresholds are available only in user scope');
+    }
+}
+function assertUserScopeLifecycle(key, scope) {
+    if (key.split('.', 1)[0] === 'lifecycle' && scope !== 'user') {
+        throw usage('lifecycle settings are available only in user scope');
+    }
+}
+function assertWorkingGerundsScope(key, scope) {
+    if (key === 'working_gerunds' && scope !== 'user') {
+        throw usage('working_gerunds is available only in user scope');
+    }
+}
+function assertWhipMessagesScope(key, scope) {
+    if (key === 'whip_messages' && scope !== 'user') {
+        throw usage('whip_messages are available only in user scope');
+    }
+}
+function assertUserSettingScope(key, scope) {
+    if (findUserSetting(key) !== undefined && scope !== 'user') {
+        throw usage(`${key} is available only in user scope`);
+    }
+}
+/** Validate a `modelLadders.*` key/value into an explicit sparse patch, or
+ *  return null when the key is not a ladder key. Ladder sets do NOT go through
+ *  `setNestedValue`/`updateConfig`: that path persists only what differs from
+ *  the compiled defaults, so choosing today's default value would record
+ *  nothing (see `persistModelLadders`). */
+function modelLadderPatch(key, rawValue) {
+    const parts = key.split('.');
+    if (parts[0] !== 'modelLadders')
+        return null;
+    if (parts.length === 2 && parts[1] === 'defaultProvider') {
+        if (!isModelProvider(rawValue)) {
+            throw usage(`modelLadders.defaultProvider must be anthropic or openai`);
+        }
+        return { defaultProvider: rawValue };
+    }
+    if (parts.length === 3) {
+        const provider = parts[1];
+        const strength = parts[2];
+        if (!isModelProvider(provider)) {
+            throw usage(`modelLadders provider must be anthropic or openai`);
+        }
+        if (!isModelStrength(strength)) {
+            throw usage(`modelLadders strength must be ultra, strong, medium, or light`);
+        }
+        if (rawValue.trim() === '') {
+            throw usage(`modelLadders.${provider}.${strength} cannot be empty`);
+        }
+        return { [provider]: { [strength]: rawValue } };
+    }
+    throw usage(`unsupported key path for set: ${key}`);
+}
+function rawSettingsTarget(input) {
+    const scope = input['scope'];
+    if (scope === 'project') {
+        throw usage('project settings remain a JSON file; use `crtr sys config set` or `crtr sys config path --scope project`.');
+    }
+    const profile = input['profile'];
+    if (scope === 'user') {
+        if (profile !== undefined)
+            throw usage('--profile is available only with --scope profile.');
+        return { scope: 'user' };
+    }
+    if (profile === undefined)
+        throw usage('--profile is required with --scope profile.');
+    return { scope: 'profile', profileId: resolveProfileOperand(profile).profileId };
+}
+function parseRawSettings(raw) {
+    let value;
+    try {
+        value = JSON.parse(raw);
+    }
+    catch {
+        throw new InputError({ error: 'invalid_request', message: 'stdin must be valid JSON', field: 'stdin', next: 'Pipe one complete JSON object on stdin.' });
+    }
+    if (value === null || typeof value !== 'object' || Array.isArray(value)) {
+        throw new InputError({ error: 'invalid_request', message: 'stdin must be a JSON object', field: 'stdin', next: 'Pipe one complete JSON object on stdin.' });
+    }
+    return value;
+}
+function setNestedValue(cfg, key, rawValue, value) {
+    const parts = key.split('.');
+    const topKey = parts[0];
+    if (key === 'working_gerunds' || key === 'whip_messages') {
+        let parsed;
+        try {
+            parsed = JSON.parse(rawValue);
+        }
+        catch {
+            throw usage(`${key} must be a JSON array of non-empty strings`);
+        }
+        if (!Array.isArray(parsed) || parsed.length === 0 || !parsed.every((entry) => typeof entry === 'string' && entry.trim() !== '')) {
+            throw usage(`${key} must be a non-empty JSON array of non-empty strings`);
+        }
+        cfg[key] = parsed.map((entry) => entry.trim());
+        return;
+    }
+    if (topKey === 'keybindings') {
+        throw usage('keybindings are edited only through `crtr sys settings`');
+    }
+    if (topKey === 'modelLadders') {
+        throw usage('modelLadders keys are written through persistModelLadders, not this path');
+    }
+    const setting = findUserSetting(key);
+    if (setting !== undefined) {
+        const error = setting.setFromString(cfg, rawValue);
+        if (error !== null)
+            throw usage(error);
+        return;
+    }
+    if (topKey === 'brokerThresholds') {
+        if (parts.length !== 2 || (parts[1] !== 'warning' && parts[1] !== 'automaticReviveCap')) {
+            throw usage(`brokerThresholds key must be warning or automaticReviveCap`);
+        }
+        if (typeof value !== 'number' || !Number.isFinite(value) || value < 1) {
+            throw usage(`brokerThresholds.${parts[1]} must be an integer >= 1`);
+        }
+        const threshold = Math.floor(value);
+        if (parts[1] === 'warning' && threshold > cfg.brokerThresholds.automaticReviveCap) {
+            throw usage('brokerThresholds.warning must be <= brokerThresholds.automaticReviveCap');
+        }
+        if (parts[1] === 'automaticReviveCap' && threshold < cfg.brokerThresholds.warning) {
+            throw usage('brokerThresholds.automaticReviveCap must be >= brokerThresholds.warning');
+        }
+        cfg.brokerThresholds[parts[1]] = threshold;
+        return;
+    }
+    if (topKey === 'lifecycle') {
+        if (parts.length !== 2 || parts[1] !== 'unattendedParkMs') {
+            throw usage(`lifecycle key must be unattendedParkMs`);
+        }
+        if (typeof value !== 'number' || !Number.isFinite(value) || value < 1) {
+            throw usage(`lifecycle.unattendedParkMs must be an integer >= 1`);
+        }
+        cfg.lifecycle.unattendedParkMs = Math.floor(value);
+        return;
+    }
+    throw usage(`unsupported key path for set: ${key}`);
+}
+// Leaf definitions
+const configGet = defineLeaf({
+    name: 'get',
+    description: 'read a config value by key',
+    whenToUse: 'you want to inspect one config value — including the whole user keybindings object — optionally from a specific scope. Use sys settings to edit keybindings and sys config set for supported scalar settings.',
+    help: {
+        name: 'sys config get',
+        summary: 'read a config value by dotted key',
+        params: [
+            { kind: 'positional', name: 'key', type: 'string', required: true, constraint: `Dotted key path. Top-level keys: ${CONFIG_TOP_LEVEL_HELP}. brokerThresholds and lifecycle are user-only; keybindings is readable only as the whole user-scope object and editable only through sys settings.` },
+            { kind: 'flag', name: 'scope', type: 'enum', choices: ['user', 'project'], required: false, constraint: 'Scope to read from. Default: user.' },
+        ],
+        output: [
+            { name: 'key', type: 'string', required: true, constraint: 'Echo of input key.' },
+            { name: 'value', type: 'unknown', required: true, constraint: 'The resolved value. Type depends on the key.' },
+            { name: 'scope', type: 'string', required: true, constraint: 'Scope the value was read from.' },
+        ],
+        outputKind: 'object',
+        effects: ['None. Read-only.'],
+    },
+    run: async (input) => {
+        const key = input['key'];
+        const scope = resolveScope(input['scope']);
+        assertUserScopeBrokerThresholds(key, scope);
+        assertUserScopeLifecycle(key, scope);
+        if (key.startsWith('keybindings.') || (key === 'keybindings' && scope !== 'user')) {
+            throw notFound('keybindings are available only as the whole user-scope object');
+        }
+        const cfg = readConfig(scope);
+        const value = getNestedValue(cfg, key);
+        if (value === undefined) {
+            throw notFound(`config key not found: ${key}`);
+        }
+        return { key, value: value, scope };
+    },
+});
+const configSet = defineLeaf({
+    name: 'set',
+    description: 'write a config value by key',
+    whenToUse: 'you want to change a supported crtr setting in user or project scope. Use sys settings instead for keybindings, and sys config get to inspect values.',
+    help: {
+        name: 'sys config set',
+        summary: 'write a config value by dotted key',
+        params: [
+            { kind: 'positional', name: 'key', type: 'string', required: true, constraint: `Dotted key path. User-scope scalar settings: ${SCALAR_SETTING_HELP}. Also supported: working_gerunds and whip_messages (non-empty JSON string arrays), brokerThresholds.warning and brokerThresholds.automaticReviveCap (user scope; integer >= 1), lifecycle.unattendedParkMs (user scope; integer ms >= 1), modelLadders.defaultProvider, and modelLadders.<anthropic|openai>.<ultra|strong|medium|light>. Keybindings are edited only through sys settings. For arbitrary raw user or profile documents, use sys config get-raw and set-raw.` },
+            { kind: 'flag', name: 'value', type: 'string', required: true, constraint: 'value VALUE — string, required. working_gerunds and whip_messages accept JSON arrays; other values are stored as-is if quoted and coerced to number or boolean when unambiguous.' },
+            { kind: 'flag', name: 'scope', type: 'enum', choices: ['user', 'project'], required: false, constraint: 'Scope to write to. Default: user. Project scope is supported only for modelLadders.' },
+        ],
+        output: [
+            { name: 'value', type: 'unknown', required: true, constraint: 'Resolved value as written after parsing and setting-specific coercion.' },
+            { name: 'scope', type: 'string', required: true, constraint: 'Scope the value was written to.' },
+        ],
+        outputKind: 'object',
+        effects: ['Writes the updated value through the target scope’s configuration storage.'],
+    },
+    run: async (input) => {
+        const key = input['key'];
+        const rawValue = input['value'];
+        const scope = resolveScope(input['scope']);
+        assertUserScopeBrokerThresholds(key, scope);
+        assertUserScopeLifecycle(key, scope);
+        assertWorkingGerundsScope(key, scope);
+        assertWhipMessagesScope(key, scope);
+        assertUserSettingScope(key, scope);
+        // Flags are stringly-typed; coerce to number or boolean when unambiguous
+        const parsed = parseConfigValue(rawValue);
+        // Ladder rungs record explicit intent (even when the value equals today's
+        // compiled default); everything else mutates + persists through the central
+        // raw-partial path, which never freezes a materialized `modelLadders`.
+        const ladder = modelLadderPatch(key, rawValue);
+        const cfg = ladder !== null
+            ? (await persistModelLadders(requireScopeRoot(scope), ladder), readConfig(scope))
+            : await updateConfig(scope, (c) => setNestedValue(c, key, rawValue, parsed));
+        // Read back the resolved value that was written
+        const written = getNestedValue(cfg, key);
+        return { value: written, scope };
+    },
+});
+const configGetRaw = defineLeaf({
+    name: 'get-raw',
+    description: 'read one raw SQL-backed settings document and revision',
+    whenToUse: 'you need the exact stored user or profile settings document before replacing it with set-raw.',
+    help: {
+        name: 'sys config get-raw',
+        summary: 'read one raw user or profile settings document',
+        params: [
+            { kind: 'flag', name: 'scope', type: 'enum', choices: ['user', 'profile', 'project'], required: true, constraint: 'SQL-backed target: user or profile. project is rejected because its settings remain a JSON file.' },
+            { kind: 'flag', name: 'profile', type: 'string', required: false, constraint: 'Profile id or name to target. Required with --scope profile; rejected with --scope user or project.' },
+        ],
+        output: [
+            { name: 'revision', type: 'string', required: true, constraint: 'Opaque revision token for set-raw. absent means the settings row does not exist.' },
+            { name: 'settings', type: 'object | null', required: true, constraint: 'Exact stored settings document, or null when no row exists.' },
+        ],
+        outputKind: 'object',
+        effects: ['None. Read-only.'],
+    },
+    run: async (input) => readRawSettingsForTarget(rawSettingsTarget(input)),
+});
+const configSetRaw = defineLeaf({
+    name: 'set-raw',
+    description: 'replace one raw SQL-backed settings document at a revision',
+    whenToUse: 'you have a complete user or profile settings document from get-raw and must replace it without losing a concurrent change.',
+    help: {
+        name: 'sys config set-raw',
+        summary: 'atomically replace one raw user or profile settings document',
+        params: [
+            { kind: 'flag', name: 'scope', type: 'enum', choices: ['user', 'profile', 'project'], required: true, constraint: 'SQL-backed target: user or profile. project is rejected because its settings remain a JSON file.' },
+            { kind: 'flag', name: 'profile', type: 'string', required: false, constraint: 'Profile id or name to target. Required with --scope profile; rejected with --scope user or project.' },
+            { kind: 'flag', name: 'if-revision', type: 'string', required: true, constraint: 'Revision returned by get-raw. Required; use absent only when get-raw reported no settings row.' },
+            { kind: 'stdin', name: 'settings', required: true, allowPositional: false, constraint: 'One complete JSON object. It replaces the document exactly; values are not normalized or merged.' },
+        ],
+        output: [
+            { name: 'revision', type: 'string', required: true, constraint: 'Revision token of the stored document after this operation.' },
+            { name: 'changed', type: 'boolean', required: true, constraint: 'Whether the stored document changed.' },
+        ],
+        outputKind: 'object',
+        effects: ['Atomically replaces the SQL-backed settings document only when --if-revision matches its current revision.'],
+    },
+    run: async (input) => {
+        const target = rawSettingsTarget(input);
+        const settings = parseRawSettings(input['settings']);
+        try {
+            return replaceRawSettingsForTarget(target, settings, input['ifRevision']);
+        }
+        catch (error) {
+            if (error instanceof SettingsRevisionConflictError) {
+                throw new InputError({ error: 'settings_revision_conflict', message: 'settings changed since the supplied revision', field: 'if_revision', next: 'Run `crtr sys config get-raw` again, reapply the intended transformation, and retry with its revision.' });
+            }
+            if (error instanceof InvalidRawSettingsError) {
+                throw new InputError({ error: 'invalid_settings', message: error.message, field: 'stdin', next: 'Correct the document so crouter can merge it into resolved settings, then retry with a fresh revision.' });
+            }
+            throw error;
+        }
+    },
+});
+const configPath = defineLeaf({
+    name: 'path',
+    description: 'print the project config.json path',
+    whenToUse: 'you need the project config.json path for inspection or backup. User and profile settings use get-raw and set-raw instead.',
+    help: {
+        name: 'sys config path',
+        summary: 'print the project config.json path',
+        params: [
+            { kind: 'flag', name: 'scope', type: 'enum', choices: ['project', 'user', 'profile'], required: false, constraint: 'Project is the only path-backed settings scope. user and profile are rejected because they use SQL-backed get-raw and set-raw. Default: project.' },
+        ],
+        output: [
+            { name: 'paths', type: 'object[]', required: true, constraint: 'One {scope: "project", path} entry when the current project has a config file; otherwise empty.' },
+        ],
+        outputKind: 'object',
+        effects: ['None. Read-only.'],
+    },
+    run: async (input) => {
+        const scope = input['scope'];
+        if (scope === 'user' || scope === 'profile') {
+            throw usage(`${scope} settings are SQL-backed; use \`crtr sys config get-raw --scope ${scope}\` instead.`);
+        }
+        const path = coreConfigPath('project');
+        return { paths: path === null ? [] : [{ scope: 'project', path }] };
+    },
+});
+export const configBranch = defineBranch({
+    name: 'config',
+    description: 'read and write configuration',
+    whenToUse: 'inspecting crtr settings, changing supported scalar values, replacing complete raw user or profile settings documents, or locating a project config.json. Keybinding changes belong in sys settings.',
+    help: {
+        name: 'sys config',
+        summary: 'read and write crtr configuration, including model ladders and raw SQL-backed user/profile settings',
+        model: 'get and set resolve individual settings. get-raw and set-raw read and replace complete user or profile documents with a revision precondition. path applies only to project config.json.',
+    },
+    children: [configGet, configSet, configGetRaw, configSetRaw, configPath],
+});

package/dist/commands/sys/connect.d.ts

@@ -0,0 +1 @@
+export declare const sysConnectLeaf: import("../../core/command.js").LeafDef;

package/dist/commands/sys/connect.js

@@ -0,0 +1,185 @@
+import { randomBytes } from 'node:crypto';
+import path from 'node:path';
+import { defineLeaf } from '../../core/command.js';
+import { readConfig, updateConfig } from '../../core/config.js';
+import { emit, InputError, isJsonOutput } from '../../core/io.js';
+import { renderResult } from '../../core/render.js';
+import { addScopedApiToken, getApiToken, setApiToken } from '../../core/secrets.js';
+import { ENFORCED } from '@north-light/identity';
+import { envCrtrdTcp, envCrtrdToken, envNodeId } from '../../shared/env.js';
+import { shellQuote } from '../../shared/shell-quote.js';
+import { cliClient } from '../api-client.js';
+const DEFAULT_TCP = '127.0.0.1:8787';
+const LISTENER_WAIT_MS = 30_000;
+const LISTENER_POLL_MS = 100;
+function token() {
+    return randomBytes(32).toString('hex');
+}
+/** Parse `--scopes` into a non-empty validated list, or undefined when the
+ *  flag was omitted (the owner token). */
+function parseScopes(raw) {
+    if (raw === undefined)
+        return undefined;
+    const scopes = String(raw).split(',').map((scope) => scope.trim()).filter((scope) => scope !== '');
+    if (scopes.length === 0) {
+        throw new InputError({
+            error: 'empty_scopes',
+            message: '--scopes names no scope',
+            received: raw,
+            field: 'scopes',
+            next: `Pass a comma-separated list from ${[...ENFORCED].join(', ')}; omit the flag for the owner token.`,
+        });
+    }
+    for (const scope of scopes)
+        if (!ENFORCED.has(scope))
+            throw new InputError({ error: 'invalid_scope', message: `invalid scope: ${scope}`, field: 'scopes', received: scope, next: `Use one of ${[...ENFORCED].join(', ')}.` });
+    return scopes;
+}
+function printCredentials(result) {
+    if (isJsonOutput())
+        emit(result);
+    else
+        process.stdout.write(renderResult(result, sysConnectLeaf.help) + '\n');
+}
+function fixedTcpPort(tcp) {
+    const separator = tcp.lastIndexOf(':');
+    if (separator === -1 || Number(tcp.slice(separator + 1)) !== 0)
+        return tcp;
+    return `${tcp.slice(0, separator + 1)}8787`;
+}
+async function awaitTcpListener() {
+    const client = cliClient();
+    const deadline = Date.now() + LISTENER_WAIT_MS;
+    let lastError;
+    while (Date.now() < deadline) {
+        try {
+            const status = await client.status();
+            if (status.listeners.tcp !== null)
+                return status;
+        }
+        catch (error) {
+            lastError = error;
+        }
+        await new Promise((resolve) => setTimeout(resolve, LISTENER_POLL_MS));
+    }
+    throw new InputError({
+        error: 'listener_unavailable',
+        message: `the successor did not expose a TCP listener within ${LISTENER_WAIT_MS}ms${lastError instanceof Error ? `: ${lastError.message}` : ''}`,
+        next: 'Run `crtr sys daemon status` to inspect the daemon, then retry `crtr sys connect`.',
+    });
+}
+async function ensureProviderCredential(client, selectors) {
+    const readiness = await client.getModelAuthReadiness(selectors);
+    if (readiness.credential === 'ready')
+        return;
+    process.stderr.write(`Logging in to ${readiness.provider} for ${readiness.model}.\n`);
+    const { loginProvider, openProviderLoginRuntime, terminalAuthInteraction } = await import('./provider-login.js');
+    await loginProvider(await openProviderLoginRuntime(), readiness.provider, terminalAuthInteraction());
+    const confirmed = await client.getModelAuthReadiness(selectors);
+    if (confirmed.credential !== 'ready') {
+        throw new InputError({
+            error: 'provider_login_incomplete',
+            message: `provider ${confirmed.provider} credential is ${confirmed.credential} after login`,
+            next: `Run \`${connectCommand(selectors)}\` again and complete the provider login.`,
+        });
+    }
+}
+function connectCommand(selectors) {
+    return [
+        'crtr sys connect',
+        selectors.profile === undefined ? undefined : `--profile ${shellQuote(selectors.profile)}`,
+        selectors.cwd === undefined ? undefined : `--cwd ${shellQuote(selectors.cwd)}`,
+        selectors.kind === undefined ? undefined : `--kind ${shellQuote(selectors.kind)}`,
+        selectors.model === undefined ? undefined : `--model ${shellQuote(selectors.model)}`,
+    ].filter((part) => part !== undefined).join(' ');
+}
+export const sysConnectLeaf = defineLeaf({
+    name: 'connect',
+    description: 'enable browser access to this daemon',
+    whenToUse: 'an application needs a browser-reachable daemon URL and bearer token; this enables the local TCP listener and reports the credentials to paste into that application. Add --app and --scopes to mint an app token instead of the owner token.',
+    help: {
+        name: 'sys connect',
+        summary: 'enable authenticated browser access and log in to the selected model provider when needed; a handover reports browser credentials before it begins',
+        params: [
+            { kind: 'flag', name: 'app', type: 'string', required: false, constraint: 'App id for the new scoped token (without the app: prefix). Required with --scopes; omit both for the owner token.' },
+            { kind: 'flag', name: 'scopes', type: 'string', required: false, constraint: `Comma-separated list from ${[...ENFORCED].join(', ')}. Requires --app; mints a NEW app bearer with this resolved scope set. Omit both flags for the owner token.` },
+            { kind: 'flag', name: 'profile', type: 'string', required: false, constraint: 'Profile setting selecting the provider a root launch with these settings would use.' },
+            { kind: 'flag', name: 'cwd', type: 'string', required: false, constraint: 'Directory setting selecting the provider a root launch with these settings would use. Default: this directory.' },
+            { kind: 'flag', name: 'kind', type: 'string', required: false, constraint: 'Node kind setting selecting the provider a root launch with these settings would use.' },
+            { kind: 'flag', name: 'model', type: 'string', required: false, constraint: 'Model setting selecting the provider a root launch with these settings would use.' },
+        ],
+        output: [
+            { name: 'base_url', type: 'string', required: true, constraint: 'The HTTP URL configured for the TCP listener.' },
+            { name: 'token', type: 'string', required: true, constraint: 'The bearer token accepted by that listener: the owner token, or with --scopes the newly minted scoped token. Paste it only into the application that needs daemon access.' },
+        ],
+        outputKind: 'object',
+        effects: [
+            'Stores a missing listener address in user settings and a missing owner bearer token in the 0600 user secrets store.',
+            'With --scopes, appends a new scoped token to that secrets store; there is no revoke verb yet, so removing one means editing the store by hand.',
+            'When the listener is not already up with both settings present, or a scoped token was minted (the daemon reads tokens only at boot), asks the daemon to hand over to a successor.',
+            'After the listener is available, resolves the provider selected by these params (default: this directory) and runs its existing OAuth login flow when that provider has no usable credential.',
+        ],
+    },
+    run: async (input) => {
+        const selectors = {
+            profile: input['profile'],
+            cwd: path.resolve(input['cwd'] ?? process.cwd()),
+            kind: input['kind'],
+            model: input['model'],
+        };
+        const scopes = parseScopes(input['scopes']);
+        const app = input['app'];
+        if ((scopes === undefined) !== (app === undefined) || (app !== undefined && !/^[a-zA-Z0-9][a-zA-Z0-9._-]*$/.test(String(app)))) {
+            throw new InputError({ error: 'invalid_app', message: '--app must name an app id and is required exactly when --scopes is set', field: 'app', received: app, next: 'Pass --app with an app id and --scopes together, or omit both for the owner token.' });
+        }
+        const callerNodeId = envNodeId();
+        const config = readConfig('user');
+        const storedTcp = config.api.tcp;
+        const storedToken = getApiToken('user');
+        const client = cliClient();
+        const status = await client.status();
+        if (storedTcp === '')
+            await updateConfig('user', (next) => { next.api.tcp = DEFAULT_TCP; });
+        else if (Number(storedTcp.slice(storedTcp.lastIndexOf(':') + 1)) === 0) {
+            await updateConfig('user', (next) => { next.api.tcp = fixedTcpPort(storedTcp); });
+        }
+        const tcp = envCrtrdTcp() ?? readConfig('user').api.tcp;
+        if (Number(tcp.slice(tcp.lastIndexOf(':') + 1)) === 0) {
+            throw new InputError({
+                error: 'dynamic_tcp_port',
+                message: 'CRTRD_TCP must use a fixed port for `crtr sys connect`',
+                next: 'Set CRTRD_TCP to a host and fixed port, then run `crtr sys connect` again.',
+            });
+        }
+        if (scopes === undefined && storedTcp !== '' && storedToken !== undefined && status.listeners.tcp !== null) {
+            await ensureProviderCredential(client, selectors);
+            return {
+                base_url: `http://${status.listeners.tcp}`,
+                token: envCrtrdToken() ?? storedToken,
+            };
+        }
+        if (storedToken === undefined)
+            setApiToken(token(), 'user');
+        const ownerToken = envCrtrdToken() ?? getApiToken('user');
+        if (ownerToken === undefined) {
+            throw new Error('TCP listener cannot start without a bearer token');
+        }
+        let issued = ownerToken;
+        if (scopes !== undefined) {
+            issued = token();
+            addScopedApiToken({ token: issued, grantee: `app:${String(app)}`, scopes, created: new Date().toISOString() }, 'user');
+        }
+        // Handover can replace the caller's broker before it receives a returned result.
+        printCredentials({ base_url: `http://${tcp}`, token: issued });
+        await client.restartDaemon();
+        await awaitTcpListener();
+        await ensureProviderCredential(client, selectors);
+        if (callerNodeId !== undefined) {
+            await client.sendMessage(callerNodeId, {
+                body: 'Browser access is ready.',
+                tier: 'urgent',
+                from: callerNodeId,
+            });
+        }
+    },
+});

package/dist/commands/sys/context/admin/actions.d.ts

@@ -0,0 +1,23 @@
+import { type AdminDoc, type AdminRecord, type AdminRule } from './model.js';
+export interface ActionOutcome {
+    ok: boolean;
+    message: string;
+    /** The name the document answers to after the action — the new name after a
+     *  move. Absent when the action changed no document. */
+    name?: string;
+}
+/** The notice a write shows instead of writing, or null when the document is
+ *  writable here. A shipped document belongs to its package and is replaced,
+ *  not edited. */
+export declare function readOnlyReason(record: AdminRecord): string | null;
+/** Replace the document's whole rule list. An empty list clears it. */
+export declare function writeRules(record: AdminRecord, rules: AdminRule[], success: string): Promise<ActionOutcome>;
+export declare function toggleUnlisted(record: AdminRecord): Promise<ActionOutcome>;
+export declare function writePreview(record: AdminRecord, line: string): Promise<ActionOutcome>;
+/** The document's current body, read the way `crtr canvas read` reads it —
+ *  which also records the read the following edit is based on. */
+export declare function readBody(doc: AdminDoc): Promise<string>;
+/** Replace the whole body. */
+export declare function writeBody(record: AdminRecord, body: string): Promise<ActionOutcome>;
+/** Rename a document under its own owner. */
+export declare function moveDoc(record: AdminRecord, to: string): Promise<ActionOutcome>;

package/dist/commands/sys/context/admin/actions.js

@@ -0,0 +1,89 @@
+// Every write `crtr sys context admin` can make. Document changes go through
+// the same `/v1/docs` routes `crtr doc edit` and `crtr doc move` use, always
+// with rationale `editor`, and address the document by its object id so a
+// same-named document elsewhere in the view is never the one rewritten.
+import { ApiError } from '../../../../api/index.js';
+import { cliClient } from '../../../api-client.js';
+import { ruleToDTO } from './model.js';
+const RATIONALE = 'editor';
+/** The notice a write shows instead of writing, or null when the document is
+ *  writable here. A shipped document belongs to its package and is replaced,
+ *  not edited. */
+export function readOnlyReason(record) {
+    const doc = record.doc;
+    if (doc.shipped) {
+        return `${doc.displayName} ships with the plugin \u201c${doc.ownerHandle}\u201d and is read-only here \u2014 override it with \`crtr doc write ${doc.name} --owner user\`.`;
+    }
+    return null;
+}
+function failure(error) {
+    if (error instanceof ApiError)
+        return { ok: false, message: error.message };
+    return { ok: false, message: error instanceof Error ? error.message : String(error) };
+}
+async function runEdit(record, request, success) {
+    const refusal = readOnlyReason(record);
+    if (refusal !== null)
+        return { ok: false, message: refusal };
+    try {
+        await cliClient().docs.edit(record.doc.object.id, { rationale: RATIONALE, ...request });
+        return { ok: true, message: success, name: record.doc.displayName };
+    }
+    catch (error) {
+        return failure(error);
+    }
+}
+/** Replace the document's whole rule list. An empty list clears it. */
+export function writeRules(record, rules, success) {
+    return runEdit(record, rules.length === 0 ? { unset: ['rules'] } : { rules: rules.map(ruleToDTO) }, success);
+}
+export function toggleUnlisted(record) {
+    const name = record.doc.displayName;
+    return record.doc.unlisted
+        ? runEdit(record, { unset: ['unlisted'] }, `${name} is listed again.`)
+        : runEdit(record, { unlisted: true }, `${name} is now unlisted.`);
+}
+export function writePreview(record, line) {
+    const trimmed = line.trim();
+    if (trimmed === '') {
+        return Promise.resolve({ ok: false, message: 'A preview cannot be empty \u2014 it is what a reader decides to open the document on.' });
+    }
+    return runEdit(record, { preview: trimmed }, `Rewrote the preview of ${record.doc.displayName}.`);
+}
+/** The document's current body, read the way `crtr canvas read` reads it —
+ *  which also records the read the following edit is based on. */
+export async function readBody(doc) {
+    const read = await cliClient().objects.read(doc.object.id);
+    if (read.state !== 'object' || read.type !== 'document')
+        throw new Error(`${doc.displayName} is no longer a readable document.`);
+    const data = read.data;
+    if (data.needs_merge)
+        throw new Error(`${doc.displayName} has diverged heads; merge them with \`crtr doc edit\` first.`);
+    return data.bodies[0] ?? '';
+}
+/** Replace the whole body. */
+export function writeBody(record, body) {
+    if (body.trim() === '') {
+        return Promise.resolve({
+            ok: false,
+            message: `An empty body is not an edit \u2014 remove ${record.doc.displayName} with \`crtr doc delete\` instead.`,
+        });
+    }
+    return runEdit(record, { body }, `Rewrote the body of ${record.doc.displayName}.`);
+}
+/** Rename a document under its own owner. */
+export async function moveDoc(record, to) {
+    const trimmed = to.trim();
+    if (trimmed === '')
+        return { ok: false, message: 'Type the new name.' };
+    const refusal = readOnlyReason(record);
+    if (refusal !== null)
+        return { ok: false, message: refusal };
+    try {
+        const moved = await cliClient().docs.move(record.doc.object.id, { new_name: trimmed });
+        return { ok: true, message: `${record.doc.displayName} now answers to ${moved.name}.`, name: moved.name };
+    }
+    catch (error) {
+        return failure(error);
+    }
+}