@crouton-kit/crouter 0.3.70 → 0.3.79

package/dist/core/command-plugins/discovery.js

@@ -0,0 +1,565 @@
+// Command-plugin discovery + validation.
+//
+// An installed, enabled plugin may declare `commands?: string` in its
+// `plugin.json` — a plugin-root-relative path to one declarative command
+// manifest (`commands.json`). This module reads and validates those manifests
+// WITHOUT executing any plugin code, turning each into either an accepted
+// contribution (a validated top-level branch node) or one or more typed
+// discovery issues. crtr owns parse/help/render/errors; the plugin owns one
+// executable that the adapter direct-spawns per leaf invocation.
+//
+// Everything here is invocation-local and side-effect-free: no cache, no
+// persisted state, no spawning. `discoverCommandContributions` is called only
+// on the fallthrough (non-core-fast-path) command path (see `build-root.ts`);
+// `validateEffectiveCommandPlugins` is the entry point Phase 2 lifecycle
+// surfaces (`pkg plugin show`, `sys doctor`) consume to report issues — it
+// carries cross-plugin collision issues that the per-plugin
+// `validatePluginCommands` structurally cannot see.
+import { realpathSync, readFileSync, statSync } from 'node:fs';
+import { resolve, sep } from 'node:path';
+import { listInstalledPlugins, listInstalledPluginsInRoot } from '../resolver.js';
+import { projectScopeRoots } from '../scope.js';
+const TIERS = new Set(['normal', 'common', 'important']);
+const FLAG_TYPES = new Set(['string', 'int', 'bool', 'path', 'enum']);
+const KEBAB = /^[a-z][a-z0-9]*(-[a-z0-9]+)*$/;
+const MANIFEST_KEYS = new Set(['schemaVersion', 'executable', 'mounts']);
+const MOUNT_KEYS = new Set(['parent', 'node']);
+const BRANCH_KEYS = new Set([
+    'kind', 'name', 'description', 'whenToUse', 'tier', 'rootEntry', 'summary', 'model', 'children',
+]);
+const LEAF_KEYS = new Set([
+    'kind', 'name', 'description', 'whenToUse', 'tier', 'summary', 'params', 'output', 'outputKind', 'effects',
+]);
+const ROOT_ENTRY_KEYS = new Set(['concept', 'description', 'whenToUse']);
+// Allowed keys are per-kind: a key valid on a flag (e.g. `default`, `choices`)
+// is rejected on a stdin param, and `repeatable`/`hidden` are not external API
+// at all (repeatable is unimplemented; external plugins cannot declare hidden
+// commands) — so they are unknown keys everywhere. This keeps the strict
+// reject-unknown posture from silently dropping a declared-but-ignored key.
+const PARAM_KEYS_BY_KIND = {
+    positional: new Set(['kind', 'name', 'type', 'required', 'constraint']),
+    flag: new Set(['kind', 'name', 'type', 'choices', 'required', 'constraint', 'default']),
+    stdin: new Set(['kind', 'name', 'required', 'constraint']),
+    'context-file': new Set(['kind', 'name', 'required', 'constraint', 'shape']),
+};
+const OUTPUT_KEYS = new Set(['name', 'type', 'required', 'constraint']);
+// ---------------------------------------------------------------------------
+// Effective plugin resolution (M3 — reuse, no new resolver)
+// ---------------------------------------------------------------------------
+/** The effective, deduped set of enabled plugins that declare a command
+ *  manifest, in scope-precedence order. Enumerated with existing machinery
+ *  only: `projectScopeRoots()` (profile-widened, nearest-first) via
+ *  `listInstalledPluginsInRoot('project', root)`, then user scope. Dedup is by
+ *  plugin NAME across ALL copies (highest precedence wins) BEFORE the enabled
+ *  filter — so a disabled higher-precedence copy suppresses lower-precedence
+ *  copies of the same name. */
+export function effectiveCommandPlugins(startDir = process.cwd(), profileId) {
+    const seen = new Set();
+    const deduped = [];
+    const consider = (p) => {
+        if (seen.has(p.name))
+            return;
+        seen.add(p.name);
+        deduped.push(p);
+    };
+    for (const root of projectScopeRoots(startDir, profileId)) {
+        for (const p of listInstalledPluginsInRoot('project', root))
+            consider(p);
+    }
+    for (const p of listInstalledPlugins('user'))
+        consider(p);
+    return deduped.filter((p) => p.enabled && typeof p.manifest.commands === 'string' && p.manifest.commands.length > 0);
+}
+// ---------------------------------------------------------------------------
+// Discovery snapshot (tree composer entry point)
+// ---------------------------------------------------------------------------
+/** Validate every effective command plugin and compose an invocation-local
+ *  registry snapshot. `reservedNames` are the core top-level subtree names —
+ *  a contribution claiming one is silently skipped from the tree and recorded
+ *  as a `command_collision` issue (core always wins). A plugin-vs-plugin
+ *  top-level name collision drops all claimants with an issue. Accepted
+ *  contributions are sorted by name for deterministic help/order. */
+export function discoverCommandContributions(reservedNames, startDir = process.cwd(), profileId) {
+    const validations = validateEffectiveCommandPlugins(reservedNames, startDir, profileId);
+    const contributions = validations.flatMap((v) => v.contributions);
+    contributions.sort((a, b) => a.node.name.localeCompare(b.node.name));
+    return { contributions, issues: validations.flatMap((v) => v.issues) };
+}
+/** Validate every effective command plugin, including the cross-plugin
+ *  top-level name collision pass: a name claimed by more than one plugin is
+ *  dropped from EVERY claimant's contributions and a `command_collision`
+ *  issue is recorded on EACH claimant's validation, so per-plugin surfaces
+ *  (`sys doctor`, `pkg plugin show`) see it too. This is the entry point for
+ *  any surface that reports on mounted commands — the per-plugin
+ *  `validatePluginCommands` cannot see other plugins' claims. */
+export function validateEffectiveCommandPlugins(reservedNames, startDir = process.cwd(), profileId) {
+    const validations = effectiveCommandPlugins(startDir, profileId).map((p) => validatePluginCommands(p, reservedNames));
+    // Plugin-vs-plugin top-level name collision: drop all claimants + flag each.
+    const claimants = new Map();
+    for (const v of validations) {
+        for (const c of v.contributions) {
+            const list = claimants.get(c.node.name);
+            if (list !== undefined)
+                list.push(v);
+            else
+                claimants.set(c.node.name, [v]);
+        }
+    }
+    for (const [name, vs] of claimants) {
+        if (vs.length === 1)
+            continue;
+        const names = vs.map((x) => x.plugin.name).join(', ');
+        for (const v of vs) {
+            v.contributions = v.contributions.filter((c) => c.node.name !== name);
+            v.issues.push({
+                code: 'command_collision',
+                plugin: v.plugin.name,
+                path: name,
+                message: `top-level command "${name}" is claimed by multiple plugins: ${names}`,
+                received: names,
+                expected: 'exactly one plugin per top-level command name',
+                next: `Disable or remove all but one of: ${names}.`,
+            });
+        }
+    }
+    return validations;
+}
+// ---------------------------------------------------------------------------
+// Per-plugin validation (Phase 2 lifecycle entry point)
+// ---------------------------------------------------------------------------
+/** Validate one plugin's command manifest without executing its binary.
+ *  `reservedNames` are the core top-level names used for the core-collision
+ *  check; pass an empty set to skip it. Never throws. */
+export function validatePluginCommands(plugin, reservedNames = new Set()) {
+    const issues = [];
+    const contributions = [];
+    const rel = plugin.manifest.commands ?? '';
+    const manifestPath = resolve(plugin.root, rel);
+    const issue = (code, message, received, expected, next, path) => {
+        issues.push({ code, plugin: plugin.name, ...(path !== undefined ? { path } : {}), message, received, expected, next });
+    };
+    // Load + parse the manifest under path-safety confinement.
+    const safe = safePath(plugin.root, rel);
+    if (safe === null) {
+        issue('command_path_unsafe', `commands pointer escapes the plugin root or is not a regular file`, rel, 'a relative path to a regular file inside the plugin root', 'Fix the `commands` field in plugin.json.');
+        return { plugin, manifestPath, contributions, issues };
+    }
+    let raw;
+    try {
+        raw = readFileSync(safe, 'utf8');
+    }
+    catch {
+        issue('command_manifest_unreadable', `commands.json is missing or unreadable`, safe, 'a readable JSON file', 'Reinstall or update the plugin.');
+        return { plugin, manifestPath, contributions, issues };
+    }
+    let parsed;
+    try {
+        parsed = JSON.parse(raw);
+    }
+    catch {
+        issue('command_manifest_invalid', `commands.json is not valid JSON`, safe, 'a JSON object', 'Regenerate commands.json from the plugin\'s command definitions.');
+        return { plugin, manifestPath, contributions, issues };
+    }
+    if (!isObject(parsed)) {
+        issue('command_manifest_invalid', `commands.json must be a JSON object`, typeName(parsed), 'a JSON object', 'Regenerate commands.json.');
+        return { plugin, manifestPath, contributions, issues };
+    }
+    // Top-level shape: exact schemaVersion, no unknown keys.
+    const unknown = Object.keys(parsed).filter((k) => !MANIFEST_KEYS.has(k));
+    if (unknown.length > 0) {
+        issue('command_manifest_invalid', `commands.json has unknown top-level keys`, unknown.join(', '), 'only: schemaVersion, executable, mounts', 'Remove the unknown keys.');
+        return { plugin, manifestPath, contributions, issues };
+    }
+    if (parsed['schemaVersion'] !== 1) {
+        issue('command_schema_version', `unsupported command schemaVersion`, String(parsed['schemaVersion']), 'exactly the integer 1', 'Update the plugin to a version compatible with this crtr.');
+        return { plugin, manifestPath, contributions, issues };
+    }
+    // Executable path safety + exec bit.
+    const execRel = parsed['executable'];
+    if (typeof execRel !== 'string' || execRel.length === 0) {
+        issue('command_manifest_invalid', `executable must be a non-empty string`, typeName(execRel), 'a relative path string', 'Set executable to the plugin-relative path of the command binary.', 'executable');
+        return { plugin, manifestPath, contributions, issues };
+    }
+    const execSafe = safePath(plugin.root, execRel);
+    if (execSafe === null) {
+        issue('command_path_unsafe', `executable escapes the plugin root or is not a regular file`, execRel, 'a relative path to a regular file inside the plugin root', 'Fix the executable path in commands.json.', 'executable');
+        return { plugin, manifestPath, contributions, issues };
+    }
+    if (!hasExecBit(execSafe)) {
+        issue('command_not_executable', `executable lacks the POSIX exec bit`, execRel, 'a file with an executable permission bit', 'chmod +x the plugin\'s command binary, then update the plugin.', 'executable');
+        return { plugin, manifestPath, contributions, issues };
+    }
+    // Mounts.
+    const mounts = parsed['mounts'];
+    if (!Array.isArray(mounts)) {
+        issue('command_manifest_invalid', `mounts must be an array`, typeName(mounts), 'an array of mounts', 'Declare at least one mount.', 'mounts');
+        return { plugin, manifestPath, executable: execSafe, contributions, issues };
+    }
+    if (mounts.length === 0) {
+        issue('command_manifest_invalid', `manifest declares no mounts (inert)`, '[]', 'at least one top-level mount', 'Declare a mount, or drop the `commands` field.', 'mounts');
+    }
+    const topNames = new Set();
+    mounts.forEach((mount, i) => {
+        const path = `mounts[${i}]`;
+        if (!isObject(mount)) {
+            issue('command_node_invalid', `mount must be an object`, typeName(mount), 'a { parent, node } object', 'Fix the mount.', path);
+            return;
+        }
+        const mUnknown = Object.keys(mount).filter((k) => !MOUNT_KEYS.has(k));
+        if (mUnknown.length > 0) {
+            issue('command_node_invalid', `mount has unknown keys`, mUnknown.join(', '), 'only: parent, node', 'Remove the unknown keys.', path);
+            return;
+        }
+        // v1: top-level mounts only — parent must be [].
+        if (!Array.isArray(mount['parent']) || mount['parent'].length !== 0) {
+            issue('command_parent_invalid', `mount parent must be [] (top-level only in v1)`, JSON.stringify(mount['parent']), 'an empty array []', 'Mount the node at top level; nested mounts are not supported in v1.', `${path}.parent`);
+            return;
+        }
+        const node = validateNode(mount['node'], `${path}.node`, true, issue);
+        if (node === null)
+            return;
+        // node is a top-level branch here (validateNode enforced kind + rootEntry).
+        if (topNames.has(node.name)) {
+            issue('command_node_invalid', `this plugin declares two top-level commands named "${node.name}"`, node.name, 'a unique top-level command name per plugin', 'Rename one of the duplicate top-level mounts.', `${path}.node.name`);
+            return;
+        }
+        topNames.add(node.name);
+        if (reservedNames.has(node.name)) {
+            issue('command_collision', `top-level command "${node.name}" collides with a core command`, node.name, 'a name not used by a core crtr command', 'Rename the plugin\'s top-level command.', `${path}.node.name`);
+            return;
+        }
+        contributions.push({ plugin, executable: execSafe, node: node });
+    });
+    return { plugin, manifestPath, executable: execSafe, contributions, issues };
+}
+/** Validate one declarative node. Returns the typed node on success, else null
+ *  (recording issues). `topLevel` requires a branch with a rootEntry. */
+function validateNode(raw, path, topLevel, issue) {
+    if (!isObject(raw)) {
+        issue('command_node_invalid', `node must be an object`, typeName(raw), 'a branch or leaf node object', 'Fix the node.', path);
+        return null;
+    }
+    const kind = raw['kind'];
+    if (kind === 'branch')
+        return validateBranch(raw, path, topLevel, issue);
+    if (kind === 'leaf') {
+        if (topLevel) {
+            issue('command_node_invalid', `top-level node must be a branch`, 'leaf', 'a branch node with a rootEntry', 'Wrap the command in a top-level branch (noun) with a rootEntry.', `${path}.kind`);
+            return null;
+        }
+        return validateLeaf(raw, path, issue);
+    }
+    issue('command_node_invalid', `node kind must be "branch" or "leaf"`, String(kind), 'branch | leaf', 'Set kind to branch or leaf.', `${path}.kind`);
+    return null;
+}
+function validateBranch(raw, path, topLevel, issue) {
+    if (!checkKeys(raw, BRANCH_KEYS, path, issue))
+        return null;
+    if (!checkCommon(raw, path, issue))
+        return null;
+    // rootEntry: required at top level, forbidden nested.
+    const hasRoot = raw['rootEntry'] !== undefined;
+    if (topLevel && !hasRoot) {
+        issue('command_node_invalid', `top-level branch requires a rootEntry`, '(missing)', 'a rootEntry { concept, description, whenToUse }', 'Add a rootEntry to the top-level branch.', `${path}.rootEntry`);
+        return null;
+    }
+    if (!topLevel && hasRoot) {
+        issue('command_node_invalid', `nested branch must not declare a rootEntry`, 'rootEntry', 'no rootEntry (only top-level branches carry one)', 'Remove rootEntry from the nested branch.', `${path}.rootEntry`);
+        return null;
+    }
+    let rootEntry;
+    if (hasRoot) {
+        const re = validateRootEntry(raw['rootEntry'], `${path}.rootEntry`, issue);
+        if (re === null)
+            return null;
+        rootEntry = re;
+    }
+    if (typeof raw['summary'] !== 'string' || raw['summary'].length === 0) {
+        issue('command_node_invalid', `branch summary must be a non-empty string`, typeName(raw['summary']), 'a one-line summary string', 'Add a summary.', `${path}.summary`);
+        return null;
+    }
+    if (raw['model'] !== undefined && typeof raw['model'] !== 'string') {
+        issue('command_node_invalid', `branch model must be a string`, typeName(raw['model']), 'a string or omitted', 'Fix or remove model.', `${path}.model`);
+        return null;
+    }
+    const children = raw['children'];
+    if (!Array.isArray(children) || children.length === 0) {
+        issue('command_node_invalid', `branch children must be a non-empty array`, typeName(children), 'a non-empty array of branch/leaf nodes', 'Add at least one child.', `${path}.children`);
+        return null;
+    }
+    const validated = [];
+    const childNames = new Set();
+    for (let i = 0; i < children.length; i++) {
+        const c = validateNode(children[i], `${path}.children[${i}]`, false, issue);
+        if (c === null)
+            return null;
+        if (childNames.has(c.name)) {
+            issue('command_node_invalid', `duplicate child name`, c.name, 'unique child names within a branch', 'Rename the duplicate child.', `${path}.children[${i}].name`);
+            return null;
+        }
+        childNames.add(c.name);
+        validated.push(c);
+    }
+    return {
+        kind: 'branch',
+        name: raw['name'],
+        description: raw['description'],
+        whenToUse: raw['whenToUse'],
+        ...(raw['tier'] !== undefined ? { tier: raw['tier'] } : {}),
+        ...(rootEntry !== undefined ? { rootEntry } : {}),
+        summary: raw['summary'],
+        ...(raw['model'] !== undefined ? { model: raw['model'] } : {}),
+        children: validated,
+    };
+}
+function validateLeaf(raw, path, issue) {
+    if (!checkKeys(raw, LEAF_KEYS, path, issue))
+        return null;
+    if (!checkCommon(raw, path, issue))
+        return null;
+    if (typeof raw['summary'] !== 'string' || raw['summary'].length === 0) {
+        issue('command_node_invalid', `leaf summary must be a non-empty string`, typeName(raw['summary']), 'a one-line summary string', 'Add a summary.', `${path}.summary`);
+        return null;
+    }
+    if (raw['outputKind'] !== 'object') {
+        issue('command_node_invalid', `leaf outputKind must be "object" in v1`, String(raw['outputKind']), 'exactly "object"', 'Set outputKind to "object".', `${path}.outputKind`);
+        return null;
+    }
+    const params = validateParams(raw['params'], `${path}.params`, issue);
+    if (params === null)
+        return null;
+    const output = validateOutput(raw['output'], `${path}.output`, issue);
+    if (output === null)
+        return null;
+    const effects = raw['effects'];
+    if (!Array.isArray(effects) || effects.length === 0 || !effects.every((e) => typeof e === 'string')) {
+        issue('command_node_invalid', `leaf effects must be a non-empty string array`, typeName(effects), 'a non-empty array of strings (["None. Read-only."] for read-only leaves)', 'Declare every persistent effect.', `${path}.effects`);
+        return null;
+    }
+    return {
+        kind: 'leaf',
+        name: raw['name'],
+        description: raw['description'],
+        whenToUse: raw['whenToUse'],
+        ...(raw['tier'] !== undefined ? { tier: raw['tier'] } : {}),
+        summary: raw['summary'],
+        params,
+        output,
+        outputKind: 'object',
+        effects: effects,
+    };
+}
+/** Validate name/description/whenToUse/tier shared by branches and leaves. */
+function checkCommon(raw, path, issue) {
+    const name = raw['name'];
+    if (typeof name !== 'string' || !KEBAB.test(name)) {
+        issue('command_node_invalid', `node name must be a lowercase kebab-case token`, String(name), 'a kebab-case token like "app" or "list-all"', 'Rename the node.', `${path}.name`);
+        return false;
+    }
+    if (typeof raw['description'] !== 'string' || raw['description'].length === 0) {
+        issue('command_node_invalid', `node description must be a non-empty string`, typeName(raw['description']), 'a short parent-listing description', 'Add a description.', `${path}.description`);
+        return false;
+    }
+    if (typeof raw['whenToUse'] !== 'string' || raw['whenToUse'].length === 0) {
+        issue('command_node_invalid', `node whenToUse must be a non-empty string`, typeName(raw['whenToUse']), 'a parent selection rubric', 'Add a whenToUse rubric.', `${path}.whenToUse`);
+        return false;
+    }
+    if (raw['tier'] !== undefined && !TIERS.has(String(raw['tier']))) {
+        issue('command_node_invalid', `node tier must be normal|common|important`, String(raw['tier']), 'normal | common | important', 'Fix or omit tier (external plugins cannot declare hidden commands).', `${path}.tier`);
+        return false;
+    }
+    return true;
+}
+function validateRootEntry(raw, path, issue) {
+    if (!isObject(raw)) {
+        issue('command_node_invalid', `rootEntry must be an object`, typeName(raw), 'a { concept, description, whenToUse } object', 'Fix rootEntry.', path);
+        return null;
+    }
+    if (!checkKeys(raw, ROOT_ENTRY_KEYS, path, issue))
+        return null;
+    for (const k of ['concept', 'description', 'whenToUse']) {
+        if (typeof raw[k] !== 'string' || raw[k].length === 0) {
+            issue('command_node_invalid', `rootEntry.${k} must be a non-empty string`, typeName(raw[k]), 'a non-empty string', `Add rootEntry.${k}.`, `${path}.${k}`);
+            return null;
+        }
+    }
+    return {
+        concept: raw['concept'],
+        description: raw['description'],
+        whenToUse: raw['whenToUse'],
+    };
+}
+function validateParams(raw, path, issue) {
+    if (raw === undefined)
+        return [];
+    if (!Array.isArray(raw)) {
+        issue('command_node_invalid', `params must be an array`, typeName(raw), 'an array of params (or omitted)', 'Fix params.', path);
+        return null;
+    }
+    const out = [];
+    const names = new Set();
+    let positionals = 0;
+    for (let i = 0; i < raw.length; i++) {
+        const p = raw[i];
+        const pp = `${path}[${i}]`;
+        if (!isObject(p)) {
+            issue('command_node_invalid', `param must be an object`, typeName(p), 'a param object', 'Fix the param.', pp);
+            return null;
+        }
+        const kind = p['kind'];
+        if (typeof kind !== 'string' || !(kind in PARAM_KEYS_BY_KIND)) {
+            issue('command_node_invalid', `param kind must be positional|flag|stdin|context-file`, String(kind), 'positional | flag | stdin | context-file', 'Fix the param kind.', `${pp}.kind`);
+            return null;
+        }
+        if (!checkKeys(p, PARAM_KEYS_BY_KIND[kind], pp, issue))
+            return null;
+        const name = p['name'];
+        if (typeof name !== 'string' || !KEBAB.test(name)) {
+            issue('command_node_invalid', `param name must be a kebab-case token`, String(name), 'a kebab-case token', 'Rename the param.', `${pp}.name`);
+            return null;
+        }
+        if (names.has(name)) {
+            issue('command_node_invalid', `duplicate param name`, name, 'unique param names', 'Rename the duplicate param.', `${pp}.name`);
+            return null;
+        }
+        names.add(name);
+        if (typeof p['required'] !== 'boolean') {
+            issue('command_node_invalid', `param required must be a boolean`, typeName(p['required']), 'true | false', 'Set required.', `${pp}.required`);
+            return null;
+        }
+        if (typeof p['constraint'] !== 'string') {
+            issue('command_node_invalid', `param constraint must be a string`, typeName(p['constraint']), 'an inline constraint string', 'Add a constraint.', `${pp}.constraint`);
+            return null;
+        }
+        if (kind === 'positional') {
+            positionals++;
+            if (positionals > 1) {
+                issue('command_node_invalid', `a leaf may declare at most one positional`, 'multiple positionals', 'at most one positional param', 'Convert extra positionals to flags.', pp);
+                return null;
+            }
+            out.push({ kind: 'positional', name, ...(p['type'] !== undefined ? { type: p['type'] } : {}), required: p['required'], constraint: p['constraint'] });
+        }
+        else if (kind === 'stdin') {
+            out.push({ kind: 'stdin', name, required: p['required'], constraint: p['constraint'] });
+        }
+        else if (kind === 'context-file') {
+            out.push({ kind: 'context-file', name, required: p['required'], constraint: p['constraint'], ...(typeof p['shape'] === 'string' ? { shape: p['shape'] } : {}) });
+        }
+        else if (kind === 'flag') {
+            const type = p['type'];
+            if (typeof type !== 'string' || !FLAG_TYPES.has(type)) {
+                issue('command_node_invalid', `flag type must be string|int|bool|path|enum`, String(type), 'string | int | bool | path | enum', 'Fix the flag type.', `${pp}.type`);
+                return null;
+            }
+            let choices;
+            if (type === 'enum') {
+                const c = p['choices'];
+                if (!Array.isArray(c) || c.length === 0 || !c.every((x) => typeof x === 'string')) {
+                    issue('command_node_invalid', `enum flag requires a non-empty string choices array`, typeName(c), 'a non-empty array of strings', 'Declare choices for the enum flag.', `${pp}.choices`);
+                    return null;
+                }
+                choices = c;
+            }
+            else if (p['choices'] !== undefined) {
+                issue('command_node_invalid', `choices is only valid on an enum flag`, 'choices', 'no choices unless type is enum', 'Remove choices.', `${pp}.choices`);
+                return null;
+            }
+            out.push({
+                kind: 'flag', name, type: type,
+                ...(choices !== undefined ? { choices } : {}),
+                required: p['required'], constraint: p['constraint'],
+                ...(p['default'] !== undefined ? { default: p['default'] } : {}),
+            });
+        }
+    }
+    return out;
+}
+function validateOutput(raw, path, issue) {
+    if (!Array.isArray(raw)) {
+        issue('command_node_invalid', `output must be an array`, typeName(raw), 'an array of output fields', 'Declare the leaf output fields.', path);
+        return null;
+    }
+    const out = [];
+    for (let i = 0; i < raw.length; i++) {
+        const f = raw[i];
+        const fp = `${path}[${i}]`;
+        if (!isObject(f)) {
+            issue('command_node_invalid', `output field must be an object`, typeName(f), 'a { name, type, required, constraint } object', 'Fix the output field.', fp);
+            return null;
+        }
+        if (!checkKeys(f, OUTPUT_KEYS, fp, issue))
+            return null;
+        if (typeof f['name'] !== 'string' || f['name'].length === 0) {
+            issue('command_node_invalid', `output field name must be a non-empty string`, typeName(f['name']), 'a field name', 'Add a name.', `${fp}.name`);
+            return null;
+        }
+        if (typeof f['type'] !== 'string' || f['type'].length === 0) {
+            issue('command_node_invalid', `output field type must be a non-empty string`, typeName(f['type']), 'a type name', 'Add a type.', `${fp}.type`);
+            return null;
+        }
+        if (typeof f['required'] !== 'boolean') {
+            issue('command_node_invalid', `output field required must be a boolean`, typeName(f['required']), 'true | false', 'Set required.', `${fp}.required`);
+            return null;
+        }
+        if (typeof f['constraint'] !== 'string') {
+            issue('command_node_invalid', `output field constraint must be a string`, typeName(f['constraint']), 'a constraint string', 'Add a constraint.', `${fp}.constraint`);
+            return null;
+        }
+        out.push({ name: f['name'], type: f['type'], required: f['required'], constraint: f['constraint'] });
+    }
+    return out;
+}
+// ---------------------------------------------------------------------------
+// Small helpers
+// ---------------------------------------------------------------------------
+function isObject(v) {
+    return typeof v === 'object' && v !== null && !Array.isArray(v);
+}
+function typeName(v) {
+    if (v === null)
+        return 'null';
+    if (Array.isArray(v))
+        return 'array';
+    return typeof v;
+}
+function checkKeys(raw, allowed, path, issue) {
+    const unknown = Object.keys(raw).filter((k) => !allowed.has(k));
+    if (unknown.length > 0) {
+        issue('command_node_invalid', `unknown keys`, unknown.join(', '), `only: ${[...allowed].join(', ')}`, 'Remove the unknown keys.', path);
+        return false;
+    }
+    return true;
+}
+/** Resolve `rel` under `root`, confining it to the realpath'd root and
+ *  requiring a regular file. Returns the resolved absolute path or null. */
+function safePath(root, rel) {
+    if (typeof rel !== 'string' || rel.length === 0)
+        return null;
+    let rootReal;
+    let real;
+    try {
+        rootReal = realpathSync(root);
+        real = realpathSync(resolve(root, rel));
+    }
+    catch {
+        return null;
+    }
+    if (real !== rootReal && !real.startsWith(rootReal + sep))
+        return null;
+    try {
+        if (!statSync(real).isFile())
+            return null;
+    }
+    catch {
+        return null;
+    }
+    return real;
+}
+function hasExecBit(file) {
+    try {
+        return (statSync(file).mode & 0o111) !== 0;
+    }
+    catch {
+        return false;
+    }
+}

package/dist/core/config.d.ts

@@ -3,9 +3,27 @@ export declare function configPath(scope: Scope): string | null;
 export declare function statePath(scope: Scope): string | null;
 export declare function readConfig(scope: Scope): ScopeConfig;
 export declare function readState(scope: Scope): ScopeState;
+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;
+/** Persist a RAW PARTIAL config to a scope's config.json exactly as given.
+ *  Unlike `writeConfig`, this makes no promise that every field is present --
+ *  callers pass the sparse partial that should live on disk, so an untouched
+ *  key stays absent (and `readConfig`/`mergeConfig` re-derive it live from
+ *  whichever build is running). This is the single central primitive every
+ *  mutation path funnels through so no writer ever freezes a fully
+ *  materialized `modelLadders` (concrete model ids that go stale across
+ *  builds -- the live-Hearth freeze bug) onto disk. */
+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;
+/** 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 readRawScopeConfig(scope: Scope): Partial<ScopeConfig> | null;
 export interface MergedLaunchConfig {
     kinds: Record<string, KindConfig>;
     modelLadders: ModelLaddersConfig;
@@ -65,5 +83,35 @@ export declare function subKindsAvailableTo(kind: string): {
     kind: string;
     whenToUse: string;
 }[];
+/** Apply `mutate` to a scope's MERGED config (so callers can read + write any
+ *  field), then persist only a RAW PARTIAL: every top-level key the mutation
+ *  left untouched keeps its exact on-disk raw value (absent stays absent, a
+ *  sparse override stays sparse), and only keys the mutation actually changed
+ *  are written. `modelLadders` gets sub-field-granular sparse handling via
+ *  `sparseModelLaddersToPersist`. Result: a fresh bootstrap or any unrelated
+ *  `sys config set` no longer freezes a full concrete `modelLadders` to disk,
+ *  and a direct ladder-rung set still persists only the touched rung -- all
+ *  through one lock-protected atomic update path. */
 export declare function updateConfig(scope: Scope, mutate: (cfg: ScopeConfig) => void): ScopeConfig;
+/** Persist a model as the DEFAULT for a kind — the `/model`-picker "defaults
+ *  going forward" write. Writes a SPARSE `kinds.<kind>` patch (just the one
+ *  model field, merged by `normalizeKindPatch`/`mergeKinds` over whatever the
+ *  lower scopes define — never a frozen full kind entry) into the PROFILE's
+ *  config.json when the node runs under a profile, else the user scope's.
+ *  Mode-aware: an orchestrator's pick lands on `orchestratorModel` (base
+ *  workers of the same kind keep their own default), a base node's on `model`.
+ *  Callers pass a model string in any form `normalizeModel` accepts; portable
+ *  ladder tokens (`ultra`, `anthropic/strong`) are preferred by callers since
+ *  they never go stale across builds. */
+export declare function persistDefaultKindModel(opts: {
+    kind: string;
+    model: string;
+    orchestrator?: boolean;
+    profileId?: string | null;
+}): {
+    scope: 'profile' | 'user';
+    path: string;
+    field: 'model' | 'orchestratorModel';
+};
 export declare function updateState(scope: Scope, mutate: (s: ScopeState) => void): ScopeState;
+export {};