@north-light/cli 0.0.0 → 0.3.414

package/dist/core/command-plugins/transport/http-plan.d.ts

@@ -0,0 +1,68 @@
+import type { InputParam, Field } from '../../help.js';
+import type { RestMapping, ManifestTimeouts } from '../../../api/command-manifest/schema.js';
+import type { LeafRunContext } from '../../command.js';
+export interface HttpInvokerSpec {
+    /** The effective registration: local name, manifest endpoint, optional auth env var. */
+    registration: {
+        name: string;
+        endpoint: string;
+        authEnv?: string;
+    };
+    /** Manifest-level REST base override (§4.2); falls back to the endpoint origin. */
+    baseUrl?: string;
+    /** Manifest-level timeout overrides (§6.6); each clock has a crtr default. */
+    timeouts?: ManifestTimeouts;
+    /** Declared leaf params (authored kebab names), used to resolve descriptors + presence. */
+    params: InputParam[];
+    /** The validated REST mapping for this leaf. */
+    rest: RestMapping;
+    /** Declared output fields — validated against a unary 2xx body before render. */
+    output: Field[];
+    /** Full canonical command path, e.g. ['device', 'reboot'] — for error labels only. */
+    commandPath: string[];
+}
+/** The caller controls credentials and correlation, never a manifest parameter. */
+export interface RequestPlanOptions {
+    authorization: string | null;
+    requestId: string;
+    extraHeaders: Record<string, string>;
+    fileMode: 'read-local' | 'pass-through';
+}
+/** A fully-built request plan — everything needed to open the socket, computed
+ *  before any network I/O so pre-network failures (auth/file/header) surface
+ *  through the ordinary structured error path without a socket ever opening. */
+export interface RequestPlan {
+    url: URL;
+    method: string;
+    /** Case-insensitively deduplicated headers in §6.1 application order. */
+    headers: Record<string, string>;
+    /** JSON request body, or undefined when the assembled body has no keys. */
+    body?: string;
+}
+export declare function buildRequestPlan(spec: HttpInvokerSpec, input: Record<string, unknown>, context: LeafRunContext | undefined, options: RequestPlanOptions): RequestPlan;
+/** Map a unary 2xx body to the validated result object, or throw
+ *  cli_protocol_error (GENERAL) for bad JSON / a non-object / an output mismatch. */
+export declare function mapUnary2xx(spec: HttpInvokerSpec, body: string): Record<string, unknown>;
+/** Extract a non-2xx error. A conforming nested `{ error: { code, message,
+ *  field?, next? } }` with an acceptable snake_case, non-reserved code becomes a
+ *  CrtrError carrying that code; a reserved/ill-formed code demotes to
+ *  cli_protocol_error; a missing/malformed/nonconforming envelope becomes
+ *  cli_http_error. The HTTP status supplies the exit code in every case, and
+ *  rides its own `http_status` slot — never `received`, which names the CALLER's
+ *  offending value and would otherwise make the backend look like it was
+ *  complaining about the number 400. A backend that supplies its own `received`
+ *  keeps it. This is error-envelope extraction, not success-envelope
+ *  unwrapping. Always throws. */
+export declare function throwNon2xx(spec: HttpInvokerSpec, status: number, body: string): never;
+/** Parsed provider/backend error body, without any CLI exit policy. */
+export interface HttpErrorEnvelope {
+    code: string;
+    message: string;
+    field?: string;
+    received?: unknown;
+    next?: string;
+    manifestStale: boolean;
+    /** Provider approval payload, preserved for the daemon to validate. */
+    question?: unknown;
+}
+export declare function parseHttpError(body: string): HttpErrorEnvelope | null;

package/dist/core/command-plugins/transport/http-plan.js

@@ -0,0 +1 @@
+var N=Object.defineProperty;var f=(e,t)=>N(e,"name",{value:t,configurable:!0});import{readFileSync as k,statSync as R}from"node:fs";import{resolve as j}from"node:path";import{validateDeclaredResult as C}from"../../../api/command-manifest/result.js";import{CrtrError as g}from"../../errors.js";import{envelopeClaimsStale as z,staleErrorDetails as U}from"../../manifest-stale.js";import{ExitCode as m}from"../../../types.js";import{isRecord as x}from"../../../shared/predicates.js";const q=/^[a-z][a-z0-9]*(_[a-z0-9]+)*$/,P=new Set(["internal","unknown_path","command_collision","cli_protocol_error"]),T=new Set(["authorization","crtr-request-id","crtr-run-id","crtr-approval","crtr-upload-id","crtr-upload-link","accept","content-type"]);function X(e,t,n,r){const i=new Map;for(const o of e.params)i.set(o.name,o);const l=Object.entries(e.rest.params),u=e.baseUrl??new URL(e.registration.endpoint).origin;let p=e.rest.path;for(const[o,a]of l){if(a.in!=="path")continue;const s=t[w(o)];p=p.split(`{${o}}`).join(G(s))}const b=new URL(p,u);for(const[o,a]of l){if(a.in!=="query")continue;const s=w(o);$(i.get(o),s,t,n)&&b.searchParams.append(a.as??o,String(t[s]))}const y=L(e,l,i,t,n,r.fileMode),h=Object.keys(y).length>0?JSON.stringify(y):void 0,c={},d=f((o,a)=>{const s=Object.keys(c).find(S=>S.toLowerCase()===o.toLowerCase());s!==void 0&&delete c[s],c[o]=a},"setHeader");d("Accept","application/json"),d("Crtr-Request-Id",r.requestId),r.authorization!==null&&d("Authorization",r.authorization);for(const[o,a]of l){if(a.in!=="header")continue;const s=w(o);if(!$(i.get(o),s,t,n))continue;const S=a.as;if(r.fileMode==="pass-through"&&T.has(S.toLowerCase()))throw new g("invalid_type",`${v(e)}: header "${S}" is reserved for the runtime`,m.USAGE,{field:o,next:"Remove the runtime-owned header mapping from the manifest."});const _=String(t[s]);if(/[\r\n]/.test(_))throw new g("invalid_type",`${v(e)}: header "${S}" value must not contain a newline`,m.USAGE,{field:o,received:"(newline in header value)",next:"Remove newline characters from the value."});d(S,_)}h!==void 0&&d("Content-Type","application/json");for(const[o,a]of Object.entries(r.extraHeaders)){if(r.fileMode==="pass-through"&&/[\r\n]/.test(a))throw new g("invalid_type",`${v(e)}: header "${o}" value must not contain a newline`,m.USAGE);d(o,a)}if(r.fileMode==="pass-through"){if(d("Accept","application/json"),h!==void 0)d("Content-Type","application/json");else{const o=Object.keys(c).find(a=>a.toLowerCase()==="content-type");o!==void 0&&delete c[o]}if(d("Crtr-Request-Id",r.requestId),r.authorization!==null)d("Authorization",r.authorization);else{const o=Object.keys(c).find(a=>a.toLowerCase()==="authorization");o!==void 0&&delete c[o]}}return{url:b,method:e.rest.method,headers:c,...h!==void 0?{body:h}:{}}}f(X,"buildRequestPlan");function L(e,t,n,r,i,l){const u=new Map;for(const[y,h]of t){if(h.in!=="body")continue;const c=h.as??y,d=u.get(c);d!==void 0?d.push(y):u.set(c,[y])}const p={};for(const[y,h]of u){const c=h.map(s=>({name:s,param:n.get(s)})),d=c.find(s=>s.param.kind!=="stdin"),o=c.find(s=>s.param.kind==="stdin");let a;d!==void 0&&$(d.param,w(d.name),r,i)?a={param:d.param,value:r[w(d.name)]}:o!==void 0&&$(o.param,w(o.name),r,i)&&(a={param:o.param,value:r[w(o.name)]}),a!==void 0&&(p[y]=A(e,a.param,a.value,l))}const b={...e.rest.body};return e.rest.bodyRoot!==void 0?b[e.rest.bodyRoot]=p:Object.assign(b,p),b}f(L,"assembleBody");function A(e,t,n,r){if(r==="pass-through"||t.kind==="context-file")return n;if((t.kind==="positional"||t.kind==="flag")&&t.type==="path"){if(Array.isArray(n))return n.map(p=>A(e,t,p,r));const i=String(n),l=j(process.cwd(),i);let u;try{u=R(l)}catch{throw O(e,t.name,i,"no file exists at that path","an existing local file path")}if(!u.isFile())throw O(e,t.name,i,"the path is not a regular file","a regular local file (not a directory, socket, or device)");try{return t.encoding==="base64"?k(l).toString("base64"):k(l,"utf8")}catch{throw O(e,t.name,i,"the file could not be read","a readable local file path")}}return n}f(A,"materializeBodyValue");function O(e,t,n,r,i){return new g("invalid_type",`${v(e)}: cannot read file for "${t}" \u2014 ${r}: ${n}`,m.USAGE,{field:t,received:n,next:`Pass ${i}, relative to the current directory or absolute.`})}f(O,"fileError");function $(e,t,n,r){return r!==void 0?r.providedParams.has(t):Object.prototype.hasOwnProperty.call(n,t)&&n[t]!==void 0}f($,"isPresent");function G(e){const t=String(e);return t==="."||t===".."?t.replace(/\./g,"%2E"):encodeURIComponent(t)}f(G,"encodePathSegmentValue");function w(e){return e.replace(/-([a-z])/g,(t,n)=>n.toUpperCase())}f(w,"paramKey");function Y(e,t){let n;try{n=JSON.parse(t)}catch{throw E(e,"response body was not valid JSON","a JSON object matching the declared output")}if(!x(n))throw E(e,`response body was not a JSON object (got ${J(n)})`,"a JSON object matching the declared output");const r=C(e.output,n);if(r!==null){const l=e.output.find(u=>u.name===r.field)?.type??"unknown";throw r.receivedType!==void 0?E(e,`output field "${r.field}" has the wrong type`,`${r.field}: ${l}`):E(e,`response is missing required output field "${r.field}"`,`a "${r.field}" field of type ${l}`)}return n}f(Y,"mapUnary2xx");function Z(e,t,n){const r=D(t),i=I(n);if(i!==null){const l=q.test(i.code)&&!P.has(i.code);throw new g(l?i.code:"cli_protocol_error",i.message,r,{...i.received!==void 0?{received:i.received}:{},...i.field!==void 0?{field:i.field}:{},...i.manifestStale?U(e.registration.name):{},http_status:t,next:i.next??"Inspect the backend response, then retry if appropriate."})}throw new g("cli_http_error",`${v(e)}: request failed with HTTP ${t}`,r,{http_status:t,next:"Inspect the backend response, then retry if appropriate."})}f(Z,"throwNon2xx");function I(e){let t;try{t=JSON.parse(e)}catch{return null}if(!x(t)||!x(t.error))return null;const n=t.error;return typeof n.code!="string"||typeof n.message!="string"?null:{code:n.code,message:n.message,...typeof n.field=="string"?{field:n.field}:{},...n.received!==void 0?{received:n.received}:{},...typeof n.next=="string"?{next:n.next}:{},manifestStale:z(n),...n.question!==void 0?{question:n.question}:{}}}f(I,"parseHttpError");function D(e){return e===400||e===401||e===403||e===422?m.USAGE:e===404?m.NOT_FOUND:e===409?m.AMBIGUOUS:m.GENERAL}f(D,"deriveExit");function E(e,t,n){return new g("cli_protocol_error",`${v(e)}: ${t}. Expected ${n}.`,m.GENERAL,{received:t,next:`Run \`crtr pkg plugin update ${e.registration.name}\` or inspect the backend response.`})}f(E,"protocolError");function v(e){return`HTTP-transport plugin "${e.registration.name}" command \`${e.commandPath.join(" ")}\``}f(v,"label");function J(e){return e===null?"null":Array.isArray(e)?"array":typeof e}f(J,"typeName");export{X as buildRequestPlan,Y as mapUnary2xx,I as parseHttpError,Z as throwNon2xx};

package/dist/core/command.d.ts

@@ -0,0 +1,210 @@
+import type { RootHelp, RootEntry, BranchHelp, LeafHelp, EffectiveLeafHelp, AsyncHelpState, InputParam, SubTier } from './help.js';
+import { CrtrError } from './errors.js';
+/** Runtime context passed to a leaf's run function. Includes metadata about
+ *  which parameters were explicitly provided vs. defaulted. Used by configured
+ *  CLIs to distinguish intentionally-empty stdin from absent stdin. */
+export interface LeafRunContext {
+    /** Set of declared parameter names that were explicitly provided by the
+     *  caller. For optional parameters, presence in this set means the value was
+     *  supplied, even if it is falsy (empty string, 0, false, etc.). Parameters
+     *  absent from this set were either defaulted or not provided. For stdin
+     *  specifically, presence means it was piped/redirected (non-TTY), supplied
+     *  as a positional argument, or explicitly passed; absence means TTY with no
+     *  pipe (truly absent). */
+    readonly providedParams: ReadonlySet<string>;
+    /** Absolute source paths for JSON values supplied through `--context-file`,
+     *  keyed by their camel-cased parameter name. The parsed JSON remains the
+     *  leaf input; this metadata preserves its source directory for values that
+     *  reference adjacent files. */
+    readonly contextFilePaths: ReadonlyMap<string, string>;
+}
+/** Opt-in flag that surfaces a node as an editor slash command (a pi prompt
+ *  template / Claude Code command). When set, the bootstrap auto-writes a
+ *  markdown template named `<name>.md` to the host's command dirs on each crtr
+ *  run, so `/name` becomes available. The body is thin — it points the agent at
+ *  the live `crtr` workflow so the CLI stays the source of truth. */
+export interface SlashSpec {
+    /** Command name → `/<name>` and the template filename. */
+    name: string;
+    /** Frontmatter description shown in the autocomplete dropdown. */
+    description: string;
+    /** Optional autocomplete hint, e.g. `<url>` or `[topic]`. */
+    argumentHint?: string;
+    /** Markdown body (no frontmatter). Bootstrap wraps it with frontmatter + a
+     *  version marker. Use `$ARGUMENTS` for the invocation's free text. */
+    body: string;
+}
+export interface LeafDef {
+    kind: 'leaf';
+    name: string;
+    /** Short description for this node's <subcommand> row in its parent's -h. */
+    description?: string;
+    /** Selection rubric for the parent's listing — plainly states when to reach
+     *  for this command (expansive with examples for judgment-heavy ones, concise
+     *  for single-purpose). Rendered verbatim, no prefix. */
+    whenToUse?: string;
+    /** Visibility tier in ancestor listings (see SubTier). Default 'normal';
+     *  'hidden' keeps an internal leaf out of every listing. */
+    tier?: SubTier;
+    help: LeafHelp;
+    /** Invocation-local immutable help view. Present only on hook-eligible core
+     *  leaves; static discovery may change Effects but never executes hooks. */
+    effectiveHelp?: (focusedFlag?: string) => Promise<EffectiveLeafHelp>;
+    /** Opt this conditionally-void leaf out of core command hooks. */
+    hookEligible?: false;
+    /** Plugin that contributed this leaf to an extensible core branch. */
+    plugin?: string;
+    /** Opt into editor slash-command exposure (see SlashSpec). */
+    slash?: SlashSpec;
+    run: (input: Record<string, unknown>, context?: LeafRunContext) => Promise<Record<string, unknown> | void>;
+    /** Optional bespoke renderer: turn the result into instruction-shaped
+     *  XML+markdown the agent acts on. Omit to fall back to the schema-driven
+     *  generic renderer. Ignored when `--json` is set. */
+    render?: (result: Record<string, unknown>) => string;
+    /** Bounded side-channel record, separate from the unchanged --json response. */
+    preview?: (result: Record<string, unknown>) => Record<string, unknown>;
+    /** Suppress the dispatcher's trailing newline for byte-exact stdout. */
+    stdoutExact?: (result: Record<string, unknown>) => boolean;
+}
+export interface BranchDef {
+    kind: 'branch';
+    name: string;
+    /** Short description for this node's <subcommand> row in its parent's -h.
+     *  Unused on a top-level subtree (its root representation is its rootEntry). */
+    description?: string;
+    /** Selection rubric for the parent's listing — plainly states when to reach
+     *  for this command (expansive with examples for judgment-heavy ones, concise
+     *  for single-purpose). Rendered verbatim, no prefix. */
+    whenToUse?: string;
+    /** Visibility tier in ancestor listings (see SubTier). Default 'normal'. */
+    tier?: SubTier;
+    help: BranchHelp;
+    /** Optional caller-specific branch listing, resolved only when this branch's help renders. */
+    effectiveHelp?: () => Promise<BranchHelp>;
+    /** How this subtree represents itself one level up. Present on top-level
+     *  subtrees (assembled into root -h by defineRoot); omitted on nested
+     *  branches, whose parent representation is the branch's own children list. */
+    rootEntry?: RootEntry;
+    /** Allows command plugins to contribute direct children below this core branch. */
+    extensible?: true;
+    /** Plugin that contributed this branch to an extensible core branch. */
+    plugin?: string;
+    /** Opt into editor slash-command exposure (see SlashSpec). */
+    slash?: SlashSpec;
+    /** Opt this branch out of the tree model entirely: every token after this
+     *  branch's name is forwarded VERBATIM (raw argv, not the `--json`-filtered
+     *  tokens) to an external binary via spawn, with stdio inherited and the
+     *  child's exit code propagated. Plugin-owned paths have already resolved to
+     *  absolute executable paths; bare program names resolve through PATH. A deliberate, documented exception for
+     *  wrapping an external CLI whose own schema crtr cannot and must not
+     *  duplicate (the official marketplace's `capture` plugin mounts `crtr
+     *  capture` this way) — not a general escape hatch. A
+     *  passthrough branch should declare no children. */
+    passthrough?: {
+        bin: string;
+        installHint: string;
+    };
+    /** A granted provider without a usable bundle rejects every leaf path. */
+    unavailable?: string;
+    children: (LeafDef | BranchDef)[];
+}
+export interface RootDef {
+    kind: 'root';
+    help: RootHelp;
+    subtrees: BranchDef[];
+}
+export declare function defineLeaf(opts: {
+    name: string;
+    description?: string;
+    whenToUse?: string;
+    tier?: SubTier;
+    help: LeafHelp;
+    effectiveHelp?: (focusedFlag?: string) => Promise<EffectiveLeafHelp>;
+    /** State the help reads asynchronously; becomes the leaf's effectiveHelp. */
+    helpState?: AsyncHelpState;
+    plugin?: string;
+    slash?: SlashSpec;
+    /** Opt this conditionally-void leaf out of core command hooks. */
+    hookEligible?: false;
+    run: (input: Record<string, unknown>, context?: LeafRunContext) => Promise<Record<string, unknown> | void>;
+    render?: (result: Record<string, unknown>) => string;
+    preview?: (result: Record<string, unknown>) => Record<string, unknown>;
+    stdoutExact?: (result: Record<string, unknown>) => boolean;
+}): LeafDef;
+export declare function defineBranch(opts: {
+    name: string;
+    description?: string;
+    whenToUse?: string;
+    tier?: SubTier;
+    help: BranchHelp;
+    effectiveHelp?: () => Promise<BranchHelp>;
+    rootEntry?: RootEntry;
+    extensible?: true;
+    plugin?: string;
+    slash?: SlashSpec;
+    passthrough?: {
+        bin: string;
+        installHint: string;
+    };
+    children: (LeafDef | BranchDef)[];
+}): BranchDef;
+/** Walk the whole tree and collect every node's SlashSpec (depth-first). Used
+ *  by the bootstrap to discover which commands opted into slash exposure. */
+export declare function collectSlashSpecs(root: RootDef): SlashSpec[];
+/** Assemble root -h from the subtrees themselves. Root owns only the tagline
+ *  and globals; every subtree's concept line, selection rubric, and dynamic
+ *  block come from its own RootEntry. A subtree without a rootEntry does not
+ *  appear in root -h — declaring the parent-level representation is how a
+ *  subtree opts into being listed. */
+export declare function defineRoot(opts: {
+    tagline: string;
+    globals: {
+        name: string;
+        desc: string;
+    }[];
+    subtrees: BranchDef[];
+}): RootDef;
+type AnyNode = RootDef | BranchDef | LeafDef;
+/** Walk argv tokens to the deepest matched node.
+ *  Returns { node, path, remaining } where path is the sequence of matched node
+ *  names from root (excluding root itself) and remaining are unconsumed tokens.
+ *  -h / --help tokens are NOT consumed here — the caller checks for them. */
+export declare function walk(root: RootDef, tokens: string[]): {
+    node: AnyNode;
+    path: string[];
+    remaining: string[];
+};
+export declare function renderNode(node: AnyNode): string;
+/** Build a structured unknown-path error. Names valid children of the deepest
+ *  matched node and names the entry command per the spec. The entry command is
+ *  the full path to the matched node (not just its local name), so the recovery
+ *  hint is a command that actually exists. No fuzzy matching. */
+export declare function unknownPathError(node: AnyNode, path: string[], bad: string): CrtrError;
+/** Options for parseArgv. */
+export interface ParseArgvOptions {
+    /** Optional collector for tracking which parameters were explicitly provided.
+     *  Called once with a ReadonlySet of parameter names that were supplied by
+     *  the caller (distinct from defaulted or missing values). */
+    onProvidedParams?: (provided: ReadonlySet<string>) => void;
+    /** Optional collector for absolute source paths of JSON values supplied via
+     *  `--context-file`, keyed by their camel-cased parameter name. */
+    onContextFilePaths?: (paths: ReadonlyMap<string, string>) => void;
+    /** The walked command path (e.g. `['push','final']`), supplied by the
+     *  dispatcher. Used only to name the exact leaf in a schema-class error's
+     *  `Next:` line, which mandates reading that leaf's `-h`. */
+    leafPath?: readonly string[];
+}
+/** Parse remaining argv tokens against the leaf's InputParam schema.
+ *  Returns a plain object whose keys are camelCase parameter names.
+ *  Optionally tracks which parameters were explicitly provided via a callback. */
+export declare function parseArgv(params: InputParam[], tokens: string[], options?: ParseArgvOptions): Promise<Record<string, unknown>>;
+/**
+ * Tokens handled before dispatch and stripped from what the leaf schema parses
+ * (root `-h` renders them as the Globals footer). They belong to no command, so
+ * anything reasoning about which command an argv names — the plugin
+ * revalidation gate, for one — has to ignore them too. One declaration, so a
+ * new global cannot be added here and missed there.
+ */
+export declare const GLOBAL_TOKENS: ReadonlySet<string>;
+export declare function runCli(root: RootDef, argv: string[]): Promise<void>;
+export {};

package/dist/core/command.js

@@ -0,0 +1,10 @@
+var z=Object.defineProperty;var f=(e,i)=>z(e,"name",{value:i,configurable:!0});import{renderRoot as q,renderBranch as F,renderLeafArgv as O,withAsyncHelpState as J,collapseWideChildren as G,rootPromotedChildren as B}from"./help.js";import{beginPreview as K,publishPreviewResult as L,readStdinRaw as I,peekStdinRaw as D,emit as Y,handle as Q,setJsonOutput as X,isJsonOutput as Z}from"./io.js";import{renderResult as ee}from"./render.js";import{CrtrError as R}from"./errors.js";import{isManifestStaleError as ne}from"./manifest-stale.js";import{operationIdContext as te}from"./events/operation-id.js";import{ExitCode as C}from"../types.js";import{envNodeId as ie}from"../shared/env.js";import{readFileSync as re}from"node:fs";import{spawnSync as ae}from"node:child_process";import{constants as oe}from"node:os";import{isatty as se}from"node:tty";import{resolve as le}from"node:path";function V(e){if(e===null||typeof e!="object"||Object.isFrozen(e))return e;for(const i of Object.values(e))V(i);return Object.freeze(e)}f(V,"freezeCommandMetadata");function Te(e){const i=V(e.help),{helpState:r}=e;if(r!==void 0&&e.effectiveHelp!==void 0)throw new Error(`leaf ${e.name} declares both helpState and effectiveHelp`);return Object.freeze({kind:"leaf",name:e.name,description:e.description,whenToUse:e.whenToUse,tier:e.tier,help:i,effectiveHelp:e.effectiveHelp??(r===void 0?void 0:n=>J(i,r,n)),slash:e.slash===void 0?void 0:V(e.slash),hookEligible:e.hookEligible,plugin:e.plugin,run:e.run,render:e.render,preview:e.preview,stdoutExact:e.stdoutExact})}f(Te,"defineLeaf");function de(e){return e.kind!=="branch"?0:(e.help.listing??[]).filter(i=>i.tier!=="hidden").length}f(de,"visibleSubCount");function Oe(e){if(e.passthrough!==void 0&&e.children.length>0)throw new Error(`defineBranch("${e.name}"): a passthrough branch must declare no children (found ${e.children.length})`);return e.help.listing=e.children.map(i=>{const r=de(i);return{name:i.name,description:i.description??"",whenToUse:i.whenToUse??"",tier:i.tier??"normal",kind:i.kind,...i.plugin!==void 0?{plugin:i.plugin}:{},...r>0?{subCount:r}:{}}}),{kind:"branch",name:e.name,description:e.description,whenToUse:e.whenToUse,tier:e.tier,help:e.help,effectiveHelp:e.effectiveHelp,rootEntry:e.rootEntry,extensible:e.extensible,plugin:e.plugin,slash:e.slash,passthrough:e.passthrough,children:e.children}}f(Oe,"defineBranch");function Ve(e){const i=[],r=f(n=>{if(n.slash!==void 0&&i.push(n.slash),n.kind==="branch")for(const a of n.children)r(a)},"visit");for(const n of e.subtrees)r(n);return i}f(Ve,"collectSlashSpecs");function We(e){const i=e.subtrees.filter(n=>n.rootEntry!==void 0).map(n=>{const a=(n.help.listing??[]).filter(s=>s.tier!=="hidden"),d=B(a).map(s=>({path:`${n.name} ${s.name}`,desc:s.tier==="important"?s.description:void 0}));return{name:n.name,concept:n.rootEntry.concept,desc:n.rootEntry.desc,useWhen:n.rootEntry.useWhen,dynamicState:n.rootEntry.dynamicState,subcommands:d.length>0?d:void 0,otherSubcommandCount:a.length-d.length}});return{kind:"root",help:{tagline:e.tagline,commands:i,globals:e.globals},subtrees:e.subtrees}}f(We,"defineRoot");function fe(e){if(e.kind==="root")return e.subtrees.filter(i=>i.tier!=="hidden").map(i=>i.name);if(e.kind==="branch"){const{listed:i,unlisted:r}=G(e.children.filter(n=>n.tier!=="hidden"));return[...i.map(n=>n.name),...r>0?[`(and ${r} more)`]:[]]}return[]}f(fe,"childNames");function ue(e,i){let r=e;const n=[];let a=0;for(;a<i.length;){const d=i[a];if(d==="-h"||d==="--help")break;if(r.kind==="root"){const s=r.subtrees.find(o=>o.name===d);if(s===void 0)break;r=s,n.push(s.name),a++}else if(r.kind==="branch"){const s=r.children.find(o=>o.name===d);if(s===void 0)break;r=s,n.push(s.name),a++}else break}return{node:r,path:n,remaining:i.slice(a)}}f(ue,"walk");function ce(e){return e.kind==="root"?q(e.help):e.kind==="branch"?F(e.help):O(e.help)}f(ce,"renderNode");async function M(e,i,r){if(r!==void 0&&e.kind==="leaf")return O(e.effectiveHelp!==void 0?await e.effectiveHelp(r):e.help,r);const n=e.kind==="leaf"&&e.effectiveHelp!==void 0?O(await e.effectiveHelp()):e.kind==="branch"&&e.effectiveHelp!==void 0?F(await e.effectiveHelp()):ce(e);if(i.length===0)return n;const{hasEffectiveCommandPlugins:a}=await import("./command-plugins/presence.js");if(!a())return n;const[{collectHelpAddenda:d},{SUBTREE_NAMES:s,coreCommandPathsCovering:o,extensibleCoreBranches:x}]=await Promise.all([import("./command-plugins/help-addenda.js"),import("../build-root.js")]),w=await d(i.join(" "),{reservedCoreNames:new Set(s),coreCommandPaths:o,extensibleCoreBranches:x});return n+w.map($=>`
+
+<plugin-help plugin="${$.plugin}">
+${$.text}
+</plugin-help>`).join("")}f(M,"renderNodeWithAddenda");function he(e){return e.some(i=>i==="-h"||i==="--help")}f(he,"helpRequested");function pe(e,i){if(e.kind!=="leaf"||i.length!==2)return;const[r,n]=i;if(n!=="-h"&&n!=="--help"||!r.startsWith("--")||r.includes("="))return;const a=r.slice(2);return(e.help.params??[]).find(s=>s.kind==="flag"&&s.name===a)?.focusedHelp!==void 0?a:void 0}f(pe,"focusedHelpFlag");function me(e,i){let r=0;for(let n=0;n<e.length;n++){if(r===i.length)return e.slice(n);e[n]!=="--json"&&e[n]===i[r]&&r++}return[]}f(me,"rawArgsAfterPath");function ge(e,i){const r=ae(e.bin,i,{stdio:"inherit"});if(r.error!==void 0){const n=r.error;throw new R("binary_missing",`${e.bin} could not be run (${n.code??n.message})`,C.USAGE,{received:e.bin,next:e.installHint})}if(r.status!==null&&process.exit(r.status),r.signal!==null){const n=oe.signals[r.signal];n!==void 0&&process.exit(128+n)}process.exit(1)}f(ge,"runPassthrough");function we(e,i,r){const n=fe(e),a=n.length>0?n.join(", "):"(none)",d=i.length>0?`crtr ${i.join(" ")} -h`:"crtr -h",s=n.some(o=>o.startsWith("(and "));return new R("unknown_path",`unknown subcommand: ${r}`,C.USAGE,{received:r,next:s?`Valid children include: ${a}. Run \`${d}\` for how to find the rest.`:`Valid children: ${a}. Run \`${d}\` for the full list.`})}f(we,"unknownPathError");function m(e,i,r,n,a){return new R(e,i,C.USAGE,{received:r,field:n,next:a!==void 0?a:"Run the command with -h to see the parameter schema."})}f(m,"parseArgvError");function v(e){return e.replace(/-([a-z])/g,(i,r)=>r.toUpperCase())}f(v,"flagNameToKey");async function be(e,i,r){const n={},a=new Set,d=new Map,s=e.filter(t=>t.kind==="positional"),o=e.find(t=>t.kind==="stdin"),x=e.find(t=>t.kind==="context-file"),w=e.filter(t=>t.kind==="flag"),$=new Map(w.map(t=>[t.name,t])),y=w.some(t=>t.sensitive===!0);for(const t of w)t.type==="bool"?n[v(t.name)]=t.default!==void 0?t.default:!1:t.default!==void 0&&(n[v(t.name)]=t.default);const g=[];let u=0,k=!1,A=!1,b=0;for(;b<i.length;){const t=i[b];if(t==="--"&&!A){A=!0,b++;continue}if(!A&&t.startsWith("--")){const h=t.indexOf("=");let l,S;if(h!==-1?(l=t.slice(2,h),S=t.slice(h+1)):l=t.slice(2),l==="context-file"){if(x===void 0)throw m("unknown_flag","unknown flag: --context-file","--context-file",void 0,"This leaf does not accept --context-file.");const p=S!==void 0?S:i[++b];if(p===void 0)throw m("missing_parameter","--context-file requires a PATH argument","--context-file","context-file");let N;try{N=re(p,"utf8")}catch{throw m("invalid_type",`--context-file: cannot read file: ${p}`,p,"context-file","Provide a readable file path.")}let W;try{W=JSON.parse(N)}catch{throw m("invalid_type",`--context-file: file is not valid JSON: ${p}`,p,"context-file","Ensure the file contains a valid JSON object.")}const T=v(x.name);n[T]=W,d.set(T,le(p)),a.add(T),b++;continue}const E=$.get(l);if(E===void 0)throw m("unknown_flag",`unknown flag: --${l}`,`--${l}`,void 0,"Use --<flag-name> for declared flags only. Run -h for the schema.");const j=v(l);if(a.add(j),E.type==="bool"){if(S!==void 0)throw m("invalid_type",`boolean flag --${l} takes no value`,`--${l}=${S}`,l,`Use --${l} (presence = true) with no value.`);n[j]=!0,b++;continue}const P=S!==void 0?S:i[++b];if(P===void 0||S===void 0&&P.startsWith("--")){const p=E.focusedHelp!==void 0&&(r?.leafPath?.length??0)>0?`Run \`crtr ${r.leafPath.join(" ")} --${l} -h\` and read the focused value contract before retrying.`:void 0;throw m("missing_parameter",`--${l} requires a value`,`--${l}`,l,p)}let H;if(E.type==="int"){const p=Number(P);if(!Number.isInteger(p))throw m("invalid_type",`--${l} must be an integer`,P,l,`Provide an integer value for --${l}.`);H=p}else if(E.type==="enum"){const p=E.choices;if(p!==void 0&&!p.includes(P))throw m("invalid_type",`--${l} must be one of: ${p.join(", ")}`,P,l,`Retry with one of: ${p.join(", ")}.`);H=P}else H=P;if(E.repeatable===!0){const p=n[j],N=Array.isArray(p)?p:[];N.push(H),n[j]=N}else n[j]=H;b++;continue}const c=s[u];if(c!==void 0){const h=v(c.name);if(c.repeatable===!0){const l=n[h]??[];l.push(t),n[h]=l}else n[h]=t,u++;g.push(t),k=!0,a.add(h),b++;continue}if(g.length>0){if(o!==void 0&&s.length===0){g.push(t),k=!0,b++;continue}throw o!==void 0?m("bad_invocation",`unexpected extra positional argument (value withheld: this leaf reads "${o.name}" from stdin, never argv)`,void 0,void 0,"Pipe it on stdin instead of passing it as a positional argument."):m("bad_invocation",y?"unexpected extra positional argument (value withheld: this leaf takes a secret)":`unexpected extra positional argument: ${t}`,y?void 0:i.join(" "),void 0,"Use declared flags or positional parameters. Run -h for the schema.")}if(s.length===0&&(o===void 0||o.allowPositional===!1))throw m("bad_invocation",y?"this leaf takes no positional arguments (value withheld: this leaf takes a secret)":`this leaf takes no positional arguments: ${t}`,y?void 0:t,void 0,"Use --flag for parameters. Run -h for the schema.");g.push(t),k=!0,b++}let U=!1;if(o!==void 0){if(g.length>1&&s.length===0){const t=o.positionalStdinConflict?.(n);throw t!==void 0?m("bad_invocation",t.message,void 0,t.field,t.next):m("bad_invocation",`unexpected extra positional argument (value withheld: this leaf reads "${o.name}" from stdin, never argv)`,void 0,void 0,"Pipe it on stdin instead of passing it as a positional argument.")}if(g.length>0&&s.length===0&&o.allowPositional!==!1){const t=g[0];if(t==="-"){const c=await I();(c.trim()!==""||!o.required)&&(n[v(o.name)]=c),U=!0}else{if((await D()).trim()!==""){const h=o.positionalStdinConflict?.(n);throw m("bad_invocation",h?.message??`both a positional argument ("${t}") and piped stdin were provided for ${o.name}`,t,h?.field??o.name,h?.next??"Pass exactly one: either the positional argument or piped stdin, not both.")}n[v(o.name)]=t,U=!0}}else{const t=se(0),c=await I();(c.trim()!==""||!o.required)&&(n[v(o.name)]=c),U=!t||k}}U&&o!==void 0&&a.add(v(o.name));for(const t of e){if(t.kind!=="flag"&&t.kind!=="positional"||t.defaultFromEnv===void 0)continue;const c=v(t.name);if(a.has(c))continue;const h=process.env[t.defaultFromEnv];h===void 0||h===""||(n[c]=t.kind==="positional"&&t.repeatable===!0?[h]:h,a.add(c))}const _=[];for(const t of e){const c=v(t.name),h=t.kind==="flag"&&t.type==="bool"&&!a.has(c);if(t.required&&(h||n[c]===void 0||n[c]===null)){const l=t.kind==="positional"?`positional ${t.name.toUpperCase()}`:t.kind==="flag"?`--${t.name}`:t.kind==="context-file"?"--context-file":"stdin";_.push({display:l,name:t.name})}}if(_.length>0){const t=_.map(l=>l.display).join(", "),c=r?.leafPath,h=c!==void 0&&c.length>0?`\`crtr ${c.join(" ")} -h\``:"this command with -h";throw m("missing_parameter",_.length===1?`required parameter is missing: ${t}`:`required parameters are missing: ${t}`,void 0,_.map(l=>l.name).join(", "),`Run ${h} and read the full schema before re-issuing \u2014 do not guess parameters one at a time.`)}return r?.onProvidedParams!==void 0&&r.onProvidedParams(a),r?.onContextFilePaths!==void 0&&r.onContextFilePaths(d),n}f(be,"parseArgv");const ve=new Set(["--json","--no-autostart"]);async function qe(e,i){const r=i.slice(2);r.includes("--json")&&X(!0);const n=r.filter(o=>!ve.has(o));if(n.length===0||n.length===1&&(n[0]==="-h"||n[0]==="--help")){const o=ie()?{...e.help,commands:await Promise.all(e.help.commands.map(async x=>{const w=e.subtrees.find(u=>u.name===x.name);if(w?.effectiveHelp===void 0)return x;const y=((await w.effectiveHelp()).listing??[]).filter(u=>u.tier!=="hidden"),g=B(y).map(u=>({path:`${w.name} ${u.name}`,desc:u.tier==="important"?u.description:void 0}));return{...x,subcommands:g.length?g:void 0,otherSubcommandCount:y.length-g.length}}))}:e.help;process.stdout.write(q(o)+`
+`),process.exitCode=C.SUCCESS;return}if(n.length===1&&(n[0]==="--version"||n[0]==="-v")){const{readPackageVersion:o}=await import("../commands/sys/shared.js");process.stdout.write(o()+`
+`),process.exitCode=C.SUCCESS;return}let{node:a,path:d,remaining:s}=ue(e,n);try{if(a.kind==="branch"&&a.passthrough!==void 0&&ge(a.passthrough,me(r,d)),a.kind==="branch"&&a.unavailable!==void 0&&s.length>0&&s[0]!=="-h"&&s[0]!=="--help")throw new R("provider_unavailable",a.unavailable,C.NETWORK,{next:"The daemon retries bundle installation on grant sync; retry after the provider becomes available."});if((a.kind==="root"||a.kind==="branch")&&s.length>0&&s[0]!=="-h"&&s[0]!=="--help")throw we(a,d,s[0]);if(he(s)){process.stdout.write(await M(a,d,pe(a,s))+`
+`),process.exitCode=C.SUCCESS;return}if(a.kind==="root"||a.kind==="branch"){process.stdout.write(await M(a,d)+`
+`),process.exitCode=C.SUCCESS;return}const o=a;K(d.join(" "));const x=o.help.params!==void 0?o.help.params:[];let w=new Set,$=new Map;const y=await be(x,s,{leafPath:d,onProvidedParams:f(k=>{w=k},"onProvidedParams"),onContextFilePaths:f(k=>{$=k},"onContextFilePaths")}),g={providedParams:w,contextFilePaths:$},u=await te.fresh(()=>o.run(y,g));if(L(u==null?u:o.preview?.(u)??u),u!=null)if(Z())Y(u);else{const k=o.render!==void 0?o.render(u):ee(u,o.help);process.stdout.write(k+(o.stdoutExact?.(u)?"":`
+`))}}catch(o){if(ne(o))throw o;Q(o)}}f(qe,"runCli");export{ve as GLOBAL_TOKENS,Ve as collectSlashSpecs,Oe as defineBranch,Te as defineLeaf,We as defineRoot,be as parseArgv,ce as renderNode,qe as runCli,we as unknownPathError,ue as walk};

package/dist/core/config.d.ts

@@ -0,0 +1,233 @@
+import type { PageComponentRegistration, Scope, ScopeConfig, ScopeState, HumanActionConfig, KindConfig, ModelLaddersConfig, ModelProvider, ModelStrength, ModelRouteConfig, ModelRoutingConfig, ProviderOptionsConfig } from '../types.js';
+import { type BindingId } from './keybindings/catalog.js';
+import type { RotationConfig } from './subscription-state.js';
+export declare function configPath(scope: Scope): string | null;
+export declare function statePath(scope: Scope): string | null;
+export interface BrokerConfigSnapshot {
+    user: ResolvedScopeConfig;
+    launch: MergedLaunchConfig;
+    rotation: RotationConfig;
+}
+export declare function installBrokerConfigSnapshot(snapshot: BrokerConfigSnapshot): void;
+export declare function brokerConfigSnapshot(): BrokerConfigSnapshot | undefined;
+export declare function readConfig(scope: Scope): ResolvedScopeConfig;
+export declare function readConfigAtRoot(root: string): ResolvedScopeConfig;
+export declare function readState(scope: Scope): ScopeState;
+export type RawSettingsTarget = {
+    scope: 'user';
+} | {
+    scope: 'profile';
+    profileId: string;
+};
+export declare class InvalidRawSettingsError extends Error {
+    constructor(cause: unknown);
+}
+export declare function readRawSettingsForTarget(target: RawSettingsTarget): {
+    settings: Record<string, unknown> | null;
+    revision: string;
+};
+export declare function replaceRawSettingsForTarget(target: RawSettingsTarget, next: Record<string, unknown>, ifRevision: string): {
+    revision: string;
+    changed: boolean;
+};
+type RawConfig = Record<string, unknown>;
+export declare function updateRawConfigAtomically(scope: Scope, mutate: (latest: RawConfig) => RawConfig): RawConfig;
+export declare function writeConfig(scope: Scope, config: ScopeConfig): void;
+export declare function writeRawConfig(scope: Scope, config: Partial<ScopeConfig>): void;
+export declare function writeState(scope: Scope, state: ScopeState): void;
+export declare function ensureScopeInitialized(scope: Scope, root: string): void;
+/** Normalize the user-owned list of attach actions allowed to bridge through an
+ * occupied tmux root binding. Unknown and non-attach ids have no effect. */
+export declare function normalizeTmuxPassthrough(raw: unknown): BindingId[];
+type LegacyModelRouteConfig = Omit<ModelRouteConfig, 'models'> & {
+    models: Partial<Record<ModelStrength, string>>;
+};
+/** Read configuration exposes legacy sparse routes separately during the
+ * one-release cutover; launch code only treats `modelRoutes` as complete. */
+export type ResolvedScopeConfig = ScopeConfig & {
+    legacyModelRoutes?: Record<string, LegacyModelRouteConfig>;
+};
+/** One malformed `bin` declaration. The read path retains these as doctor
+ *  findings rather than letting malformed config break a node launch. */
+export interface BinDeclarationIssue {
+    name: string;
+    message: string;
+}
+/** Validate raw `bin` declaration shape without touching the filesystem.
+ *  Install uses these findings as a hard gate for plugin manifests; scope
+ *  resolution reports them through `crtr sys doctor` and continues. */
+export declare function binDeclarationIssues(raw: unknown): BinDeclarationIssue[];
+/** Normalize one raw `bin` block (a scope `config.json`'s or a plugin
+ *  manifest's) to name → root-relative path. Invalid entries never become
+ *  commands; `binDeclarationIssues` keeps them visible to Doctor. */
+export declare function normalizeBin(raw: unknown): Record<string, string>;
+export interface HumanActionDeclarationIssue {
+    name: string;
+    reason: string;
+    block?: true;
+}
+/** Validate `humanActions` declaration shape without touching the filesystem.
+ * Filesystem checks happen only when resolving an action or running Doctor. */
+export declare function humanActionDeclarationIssues(raw: unknown): HumanActionDeclarationIssue[];
+/** Normalize valid action declarations for scope-local config inspection.
+ * Invalid entries remain available through raw reads so resolution and Doctor
+ * can report them rather than silently treating them as absent. */
+export declare function normalizeHumanActions(raw: unknown): Record<string, HumanActionConfig>;
+/** STRICT install-time validation for a plugin-declared `bin` block. Target
+ *  filesystem state is checked later by Doctor because it can change after
+ *  install. */
+export declare function invalidPluginBinReasons(raw: unknown): string[];
+/** Normalize a plugin manifest's advisory executable requirements. Invalid
+ *  declarations stay out of the read path; source installs reject them through
+ *  `invalidPluginRequiresReasons`. */
+export declare function normalizeRequires(raw: unknown): Record<string, string>;
+/** STRICT install-time validation for a plugin's advisory `requires` block.
+ *  A missing executable is advisory; only malformed declarations fail install. */
+export declare function invalidPluginRequiresReasons(raw: unknown): string[];
+/** The ACTIVE page-component catalog every authoring, validation, daemon,
+ *  inbox, and TUI consumer resolves: the user scope's own `page_components`
+ *  entries plus the contributions of every ENABLED plugin installed under that
+ *  same root, plugin name-sorted for determinism (directory listing order is
+ *  filesystem-dependent). Installing, updating, or removing a plugin therefore
+ *  adds, changes, or retires its components with no config edit.
+ *
+ *  User scope only, deliberately: this catalog is read from the daemon, the
+ *  CLI, and the inbox TUI, whose ambient cwds differ, and a page slot whose
+ *  validity depended on which directory a process happened to start in would
+ *  validate in one surface and fail in another. `page_components` has always
+ *  been a user-scope block (`readConfig('user')`); its plugin channel keeps
+ *  that boundary.
+ *
+ *  Throws on a duplicate kind or derived JSX tag across sources, and on a
+ *  plugin whose block is malformed — matching the existing catalog validation
+ *  style, where a bad `page_components` block already fails config read rather
+ *  than silently dropping a component the product expects to be authorable.
+ *  Install-time validation (`invalidPageComponentsReasons`) is what keeps a
+ *  malformed block from ever reaching this path. */
+export declare function resolvePageComponents(): PageComponentRegistration[];
+/** STRICT install-time validation for a plugin-declared `kinds` block —
+ *  the loud counterpart to `mergeKinds`'s silent read-time dropping. Read
+ *  paths must never throw on bad config, but an INSTALL delivering a bad
+ *  block must fail the install, not ship a kind that silently never
+ *  registers. Returns one human-readable reason per defect; empty = valid.
+ *  Used by the archive-bundle validator (`command-plugins/bundle.ts`) on
+ *  `bundle.json`'s optional `kinds` member. */
+export declare function invalidPluginKindsReasons(raw: unknown): string[];
+/** Raw (un-defaulted) partial config for one scope, or null if the scope has
+ *  no root or no config.json. Used by `readMergedLaunchConfig` to layer
+ *  scopes onto each other WITHOUT each scope's own default-fill masking a
+ *  lower-precedence scope's real customization (see that function's comment
+ *  for why `readConfig(scope)`, which already defaults-fills, is unusable
+ *  for cross-scope layering). */
+export declare function readRawConfigAtRoot(root: string): Partial<ScopeConfig> | null;
+export declare function readRawScopeConfig(scope: Scope): Partial<ScopeConfig> | null;
+export interface MergedLaunchConfig {
+    kinds: Record<string, KindConfig>;
+    modelLadders: ModelLaddersConfig;
+    /** Per-provider behavior options keyed by runtime provider id, merged
+     *  per provider across scopes (project stack > profile > user). */
+    providerOptions: Record<string, ProviderOptionsConfig>;
+    /** Complete declared routes. Every route here has all four strengths. */
+    modelRoutes?: Record<string, ModelRouteConfig>;
+    /** Read-only compatibility view for sparse routes written before complete
+     * routes were required. New route persistence never produces this shape. */
+    legacyModelRoutes?: Record<string, LegacyModelRouteConfig>;
+    modelRouting?: ModelRoutingConfig;
+    /** The merged `spawnEnv.allow` set (project stack > profile > user >
+     *  builtin, additive) — read by `buildOperationalEnvBase`
+     *  (`core/runtime/spawn-env.ts`) as source C of the broker spawn-env
+     *  boundary. */
+    spawnEnv: {
+        allow: string[];
+    };
+}
+/** Merge launch knobs (`kinds`, `modelLadders`) across scopes in
+ *  project stack > profile > user > builtin precedence — the same precedence
+ *  order used for memory resolution. For `kinds` only, each plugin-bearing
+ *  scope (user, each project root) additionally layers its enabled plugins'
+ *  manifest `kinds` blocks directly BELOW that scope's own raw config — see
+ *  `layerPluginKinds`. A kind or ladder cell declared at a
+ *  more-specific scope shadows the same key from a less-specific scope; the
+ *  project STACK (`findProjectScopeRoots` — every ancestor `.crouter/`,
+ *  widened by a selected profile's `projects`) layers nearest-root-strongest;
+ *  a key no scope declares falls through to the builtin default registry
+ *  (`defaultScopeConfig().kinds` / `.modelLadders`).
+ *
+ *  Layers RAW (un-defaulted) partial config per scope, not `readConfig(scope)`
+ *  — `readConfig` already fills in every default kind for a scope that
+ *  customizes even one, so naively overlaying two already-defaulted
+ *  `ScopeConfig.kinds` objects would let an untouched project-scope kind
+ *  (silently defaulted) clobber a real user-scope customization of that same
+ *  kind. Layering the raw partials avoids that.
+ *
+ *  Callers (launch, kind registry) go through this function rather than
+ *  `readConfig` directly, so `ScopeConfig.kinds`/`modelLadders`/tools/
+ *  extensions/`availableTo` all honor the same profile + multi-project
+ *  precedence.
+ *
+ *  `targetCwd`/`targetProfileId` default to this PROCESS's own ambient cwd
+ *  and `CRTR_PROFILE_ID` — correct for a caller resolving config for itself
+ *  (front-door commands, kind listing). A caller resolving config on behalf
+ *  of a DIFFERENT node (the broker spawn-env boundary or cron executor — both
+ *  run inside the daemon, whose ambient cwd/profile is the daemon's own, not
+ *  the target node's) MUST pass the target's own cwd/profile explicitly, or
+ *  `spawnEnv.allow` resolves from the wrong scope entirely (the C-1
+ *  follow-up fix this parameterization exists for). */
+export declare function readMergedLaunchConfig(targetCwd?: string, targetProfileId?: string | null): MergedLaunchConfig;
+/** The effective `KindConfig` for one full kind string (top-level, e.g.
+ *  `developer`, or sub-kind, e.g. `audit/security`), across
+ *  project > user > builtin precedence. Returns `undefined` for a kind no
+ *  scope registers — existence is deliberately NOT validated here (kind
+ *  existence/launch-menu enumeration is a caller concern); this only
+ *  resolves the config for a kind the caller already knows about. */
+export declare function resolveKindConfig(kind: string): KindConfig | undefined;
+/** The sub-kinds available to spawn FROM a given top-level kind — every
+ *  registered sub-kind (full path contains `/`) whose `availableTo` (default:
+ *  its own top-level ancestor, e.g. `audit/security` defaults to
+ *  `['audit']`) includes `kind` or `'*'`. The single source both `sys
+ *  prompt-review --list`'s `subPersonas` metadata and the live sub-persona
+ *  spawn-menu splice (`core/substrate/delivery/render-boot.ts`) read, so the two can never
+ *  drift apart. Sorted by full kind name for stable rendering. */
+export declare function subKindsAvailableTo(kind: string): {
+    kind: string;
+    whenToUse: string;
+}[];
+/** Persist an EXPLICIT sparse `modelLadders` intent at one config root: the
+ *  patch's rungs (and `defaultProvider`) are merged over whatever sparse ladder
+ *  is already on disk, and every untouched rung stays absent so it keeps
+ *  re-deriving from the running build's registry.
+ *
+ *  Ladder edits must come through here rather than `updateConfig`, because that
+ *  path infers what to persist by diffing the mutated config against the merged
+ *  baseline: setting a rung to the value that happens to be today's compiled
+ *  default produces an empty diff and silently persists nothing, so the choice
+ *  evaporates as soon as the default moves. Explicit intent is recorded as
+ *  written. Mirrors `persistDefaultKindModel`. */
+export declare function persistModelLadders(root: string, patch: {
+    defaultProvider?: ModelProvider;
+    anthropic?: Partial<Record<ModelStrength, string>>;
+    openai?: Partial<Record<ModelStrength, string>>;
+}): void;
+/** Persist one complete route at one exact config root. The route is the only
+ * raw route entry touched; unrelated routes and local ladder defaults remain
+ * absent. Pass `undefined` to remove this scope's entry, which resumes lower
+ * scope inheritance rather than introducing a tombstone. */
+export declare function persistModelRoute(root: string, routeId: string, route: ModelRouteConfig | undefined): void;
+/** Mutate one exact config root. Setup uses this for profile and explicit
+ * project targets that cannot be represented by the user/project Scope enum. */
+export declare function updateConfigAtRoot(root: string, mutate: (cfg: ScopeConfig) => void): ScopeConfig;
+export declare function updateConfig(scope: Scope, mutate: (cfg: ScopeConfig) => void): ScopeConfig;
+/** Persist one sparse kind-model field at an exact config root. The sparse
+ * patch keeps every unrelated kind and launch knob inherited from lower
+ * scopes instead of freezing a materialized registry snapshot. */
+export declare function persistDefaultKindModel(opts: {
+    root: string;
+    kind: string;
+    model: string;
+    orchestrator?: boolean;
+}): {
+    path: string;
+    field: 'model' | 'orchestratorModel';
+};
+export declare function updateState(scope: Scope, mutate: (s: ScopeState) => void): ScopeState;
+export {};