@skanl/brambo-cli 0.1.1

package/dist/src/registry-commands.js

@@ -0,0 +1,612 @@
+import { homedir } from 'node:os';
+import { REGISTRY_ENTRY_TYPES, REMOVABLE_ENTRY_TYPES, createBundle, deliveryFor, expandRegistryEntryPaths, ingestMachine, isRetiredEntryType, readBundle, scopeDirectory, storeFor, writeBundle, } from '@skanl/brambo-environment';
+/** The verbs `run.ts` dispatches into this file, under both grammars. */
+export const REGISTRY_VERBS = ['add', 'remove', 'list'];
+export function isRegistryVerb(token) {
+    return REGISTRY_VERBS.includes(token);
+}
+/**
+ * The field flags, mapped ONE-TO-ONE onto the envelope field they carry.
+ *
+ * No entry type appears in this table and none may: the frozen Ask-First clause
+ * of this story forbids the CLI holding a per-type table of which flag belongs
+ * to which type, because that is a second copy of `REGISTRY_PATH_FIELDS`. A flag
+ * that does not suit the type is rejected by the CONTRACT, one layer down.
+ */
+const FIELD_FLAGS = {
+    '--command': 'command',
+    '--entry-path': 'entryPath',
+};
+/** Repeatable, and order-preserving: `args` is a command line, not a set. */
+const ARG_FLAG = '--arg';
+/** The only option `brambo ingest` has; every other one is a usage error. */
+const DRY_RUN_FLAG = '--dry-run';
+/**
+ * Argv for all three verbs: the field flags, and the positionals each verb then
+ * reads for itself. Shared, so `remove` cannot drift into accepting an option
+ * `add` rejects.
+ */
+function parseTokens(tokens) {
+    const positionals = [];
+    const args = [];
+    let command;
+    let entryPath;
+    let terminated = false;
+    const assign = (field, value) => {
+        if (field === 'command')
+            command = value;
+        else
+            entryPath = value;
+    };
+    for (let index = 0; index < tokens.length; index += 1) {
+        const token = tokens[index];
+        if (token === undefined)
+            continue;
+        // `--` ends the options, POSIX-style. Without it an id that begins with a
+        // dash could be registered — `ingestProviders` accepts one, and nothing in
+        // the envelope forbids it — and then never removed, because every spelling
+        // of `brambo remove mcp-server --fs` is a usage error. `brambo doctor` points
+        // straight at that command, so the entry had a dispatchable instruction that
+        // could not be run for the entry it was about.
+        if (!terminated && token === '--') {
+            terminated = true;
+            continue;
+        }
+        if (terminated) {
+            positionals.push(token);
+            continue;
+        }
+        const named = Object.keys(FIELD_FLAGS).find((flag) => token === flag || token.startsWith(`${flag}=`));
+        const flag = named ?? (token === ARG_FLAG || token.startsWith(`${ARG_FLAG}=`) ? ARG_FLAG : undefined);
+        if (flag !== undefined) {
+            // The SAME guard for both spellings: `--command=-x` reaching the entry
+            // while `--command -x` is refused would be two answers to one question,
+            // which is the shape `brambo run --executor` was already fixed for.
+            //
+            // `--arg` is the ONE exception, and it is not a relaxation of the rule but
+            // the rule applied to a different thing: an mcp-server's arguments are a
+            // command line, where `-y` is an ordinary value — `npx -y @mcp/fs` is the
+            // documented invocation of half the servers that exist. Refusing it would
+            // make the flag unable to express the case it was added for. `--help` can
+            // never be eaten by it, because help is answered before this parse runs.
+            const inline = token.startsWith(`${flag}=`);
+            const value = inline ? token.slice(flag.length + 1) : tokens[index + 1];
+            if (value === undefined || value.length === 0 || (value.startsWith('-') && flag !== ARG_FLAG)) {
+                return { usageError: `option '${flag}' requires a value` };
+            }
+            if (!inline)
+                index += 1;
+            if (flag === ARG_FLAG)
+                args.push(value);
+            else
+                assign(FIELD_FLAGS[flag], value);
+            continue;
+        }
+        if (token.startsWith('-'))
+            return { usageError: `unrecognized option '${token}'` };
+        positionals.push(token);
+    }
+    return {
+        positionals,
+        fields: {
+            ...(command === undefined ? {} : { command }),
+            ...(entryPath === undefined ? {} : { entryPath }),
+            ...(args.length === 0 ? {} : { args }),
+        },
+    };
+}
+function knownTypes() {
+    return REGISTRY_ENTRY_TYPES.join(', ');
+}
+/**
+ * The vocabulary each verb accepts, and the asymmetry is the point: `remove`
+ * takes a RETIRED type as well, because an entry written by an older build has
+ * to have an exit through the product, and `add` does not, because nothing may
+ * create one again. Both lists come from `@skanl/brambo-contracts` — there is still no
+ * table of entry types in this file.
+ */
+function acceptedTypes(verb) {
+    return verb === 'remove' ? REMOVABLE_ENTRY_TYPES : REGISTRY_ENTRY_TYPES;
+}
+/**
+ * The entry type, as an argv question. A missing or misspelled type is a usage
+ * error about the command line — the user has not named an entry yet — while
+ * everything about the entry ITSELF is the contract's to answer.
+ */
+/**
+ * The verb a user at THIS scope can actually run.
+ *
+ * `brambo project add` with no type answered `brambo add needs an entry type`. The
+ * verb was right and the grammar was not: at project scope `brambo add` is a
+ * different command against a different registry, so the sentence named
+ * something that would act on the wrong one. `scope` was already a parameter at
+ * every one of these sites and was simply not read.
+ *
+ * Two spellings rather than one interpolation, so the printed-command invariant
+ * sees a real verb in each — the same shape `doctor.ts` uses for its exits.
+ */
+export function verbAt(scope, verb) {
+    return scope === 'machine' ? `brambo ${verb}` : `brambo project ${verb}`;
+}
+function readType(verb, token, scope) {
+    const accepted = acceptedTypes(verb);
+    if (token === undefined) {
+        return { usageError: `${verbAt(scope, verb)} needs an entry type: ${knownTypes()}` };
+    }
+    const found = accepted.find((candidate) => candidate === token);
+    if (found === undefined) {
+        // A retired word reaching `add` gets the sentence that is USEFUL rather than
+        // the generic one: the user is either upgrading from a build that had it, or
+        // reading documentation that did, and the entry they already have is
+        // removable by exactly the spelling that was just refused here.
+        //
+        // Under the GRAMMAR the user actually typed. The machine sentence reused at
+        // project scope asserted the entry is listed by `brambo list`, which does not
+        // read a project registry, and named `brambo remove`, which exits 1 for a
+        // project-scope entry -- a refusal that hands out a command that fails.
+        return {
+            usageError: isRetiredEntryType(token)
+                ? scope === 'machine'
+                    ? `'${token}' is a RETIRED entry type; brambo has ${knownTypes()}. An existing '${token}' entry is still listed by \`brambo list\` and removed by \`brambo remove ${token} <id>\``
+                    : `'${token}' is a RETIRED entry type; brambo has ${knownTypes()}. An existing '${token}' entry is still listed by \`brambo project list\` and removed by \`brambo project remove ${token} <id>\``
+                : `unknown entry type '${token}'; brambo has ${knownTypes()}`,
+        };
+    }
+    return found;
+}
+async function bind(scope, directory, context) {
+    // The same trust boundary `brambo init` applies, and for the same reason: these
+    // paths decide where brambo creates `.brambo`, and `brambo project add x y ~/typo`
+    // must not build the missing tree. Brambo BINDS a directory, never creates one.
+    // `homedir()` here and in the capability are the same call: a second spelling
+    // of "the home directory" is how `brambo add` and `brambo init` come to disagree
+    // about which registry they are talking about.
+    const home = await scopeDirectory('the home directory', context.homeDir ?? homedir());
+    const root = scope === 'machine'
+        ? home
+        : await scopeDirectory('the project directory', directory ?? context.cwd ?? process.cwd());
+    const store = storeFor(scope, home, root);
+    const registryScope = scope === 'machine' ? 'global' : 'project';
+    return {
+        scope,
+        registryScope,
+        projectCommand: scope === 'machine' ? 'brambo init' : 'brambo project init',
+        registryPath: store.storePath(registryScope),
+        homeDir: home,
+        projectDir: root,
+        store,
+    };
+}
+/** One entry as the line a human reads: its scope, its type and its id. */
+function describeEntry(scope, entry) {
+    const fields = [
+        entry.command === undefined ? undefined : `command ${entry.command}`,
+        entry.entryPath === undefined ? undefined : `entry-path ${entry.entryPath}`,
+        entry.args === undefined ? undefined : `args ${entry.args.join(' ')}`,
+    ].filter((part) => part !== undefined);
+    return `${scope} · ${entry.type} · ${entry.id}${fields.length === 0 ? '' : ` (${fields.join(' · ')})`}`;
+}
+export async function runRegistryCommand(verb, tokens, scope, context) {
+    const { out, err } = context;
+    const parsed = parseTokens(tokens);
+    if ('usageError' in parsed) {
+        err(parsed.usageError);
+        err(context.defaultUsage);
+        return 2;
+    }
+    // `add` and `remove` name an entry, `list` names none; the project grammar
+    // then takes one optional directory after that, exactly like
+    // `brambo project init [directory]` and `brambo project remediate <verb> [directory]`.
+    const named = verb === 'list' ? 0 : 2;
+    const maxPositionals = named + (scope === 'project' ? 1 : 0);
+    if (parsed.positionals.length > maxPositionals) {
+        err(`unexpected argument '${parsed.positionals[maxPositionals]}'`);
+        err(context.defaultUsage);
+        return 2;
+    }
+    if (verb === 'list') {
+        if (Object.keys(parsed.fields).length > 0) {
+            err("'list' takes no field options; it shows every entry there is");
+            err(context.defaultUsage);
+            return 2;
+        }
+        return await runList(parsed.positionals[0], scope, context);
+    }
+    const type = readType(verb, parsed.positionals[0], scope);
+    if (typeof type !== 'string') {
+        err(type.usageError);
+        err(context.defaultUsage);
+        return 2;
+    }
+    const id = parsed.positionals[1];
+    if (id === undefined) {
+        err(`${verbAt(scope, verb)} needs the id of the ${type} entry`);
+        err(context.defaultUsage);
+        return 2;
+    }
+    if (verb === 'remove' && Object.keys(parsed.fields).length > 0) {
+        err("'remove' takes no field options; an entry is removed by its type and id");
+        err(context.defaultUsage);
+        return 2;
+    }
+    const bound = await bind(scope, parsed.positionals[2], context);
+    try {
+        return verb === 'add'
+            ? await performAdd({ type, id, ...parsed.fields }, bound, out, err)
+            : await performRemove(type, id, bound, out, err);
+    }
+    finally {
+        await bound.store.dispose();
+    }
+}
+/**
+ * `add` REGISTERS and does not project — it reports the command that does.
+ * Coupling the two would make registration fail for projection reasons, on a
+ * machine where the failure has nothing to do with the entry just registered.
+ *
+ * The next step it reports is DERIVED, by `deliveryFor`, from the same planner
+ * `brambo init` runs. It used to be a sentence written here —
+ * "`brambo project init` puts it into every detected executor" — and for a skill
+ * that sentence was false: nothing at that scope takes one, machine-scope
+ * projection cannot see a project-scope entry, and the entry was inert forever
+ * behind a command that exits 0. This binding therefore holds NO idea of which
+ * entry type has a location at which scope; it prints what the planner found.
+ */
+async function performAdd(entry, bound, out, err) {
+    // Straight to the store: it validates through `validateRegistryEntry` and
+    // throws a coded `BramboError` for a bad type, an empty id, an unprojectable id
+    // and a field that does not belong on this type. Nothing is checked here first.
+    await bound.store.register(entry, bound.registryScope);
+    // AFTER the write, never before: the entry is registered either way, and a
+    // planner that cannot answer must not be able to fail the registration.
+    const delivery = await deliveryFor(entry, bound.scope, bound.homeDir, bound.projectDir);
+    out(JSON.stringify({ scope: bound.registryScope, registryPath: bound.registryPath, entry, delivery }, null, 2));
+    err(`registered: ${describeEntry(bound.registryScope, entry)}`);
+    err(`stored in '${bound.registryPath}'`);
+    for (const line of deliveryLines(entry, delivery, bound.scope))
+        err(line);
+    return 0;
+}
+/**
+ * The derived next step, as the lines a human reads. Every sentence here is a
+ * rendering of {@link EntryDelivery} — which executors the planner found for
+ * this entry at this scope, the targets' own refusals where it found none, and
+ * the other scope when that one would take it.
+ */
+function deliveryLines(entry, delivery, scope) {
+    const lines = [];
+    if (delivery.undetermined !== undefined) {
+        // No claim about delivery is made, because none was established. The
+        // grammar fact stays true and is all that is said.
+        lines.push(`the entry is registered; brambo could not work out what would take it (${delivery.undetermined})`);
+        lines.push(`\`${delivery.command}\` is the command that projects this scope`);
+        return lines;
+    }
+    if (delivery.executorIds.length > 0) {
+        lines.push(`nothing was projected: \`${delivery.command}\` puts it into ${delivery.executorIds.join(', ')}`);
+        return lines;
+    }
+    // A GRAMMAR FAULT IS NOT AN ENVIRONMENT FACT, AND THE OLD BLOCK SAID IT WAS.
+    //
+    // `command` is the only executable field an mcp-server has, and
+    // `collectMcpEntries` skips a command-less one unconditionally — not even an
+    // `extensions` payload rescues it. So such an entry is inert on every
+    // executor, at every scope, on every machine, forever. The block printed three
+    // sentences about SCOPE for it ("HERE", "at the machine scope", "no other
+    // scope takes it either"), which reads as a local condition another scope
+    // might not have. None of that is true of it.
+    //
+    // And the repair is ONE command, driven: `brambo add` on an existing id updates
+    // it in place and exits 0, so no `brambo remove` is needed. Naming it here is
+    // the difference between a diagnosis and an exit.
+    if (entry.type === 'mcp-server' && entry.command === undefined) {
+        lines.push(`NOTHING TAKES IT, ANYWHERE: an mcp-server with no command renders into nothing — on every executor and at every scope, not just this one`);
+        lines.push(
+        // THE SHARPEST OF THIS CLASS. Printed at project scope, the machine
+        // spelling of add-with-a-command does not update this entry — it creates a
+        // SECOND one, in the MACHINE registry, and the sentence promising "in
+        // place" is what sends the user there. (Spelled out, that sentence wrapped
+        // across two lines and the unclosed-command guard refused it. Describe.)
+        `the entry is registered and stays listed by \`${verbAt(scope, 'list')}\`; give it a command with \`${verbAt(scope, 'add')} mcp-server ${entry.id} --command <c>\`, which updates this entry in place`);
+        return lines;
+    }
+    // The headline says only what was OBSERVED — that no target took it. It used
+    // to explain WHY ("no detected executor has a machine-scope location for a
+    // skill entry"), which conflated "no target exists for this surface" with
+    // "a target existed and refused THIS entry", and printed the first sentence
+    // seconds after codex had used exactly such a location.
+    lines.push(`NOTHING TAKES IT HERE: no detected executor would take this ${entry.type} entry at the ${delivery.scope} scope, so \`${delivery.command}\` would project it nowhere`);
+    for (const reason of delivery.reasons)
+        lines.push(`  refused: ${reason}`);
+    if (delivery.reasons.length === 0) {
+        // Said rather than left blank: a target that skips an entry without a reason
+        // has given brambo nothing to pass on, and inventing one here is the failure
+        // the headline above was just corrected for.
+        lines.push(`  no target said why; \`${verbAt(scope, 'doctor')}\` reports what each one would do`);
+    }
+    const elsewhere = delivery.elsewhere;
+    if (elsewhere === undefined) {
+        lines.push(`no other scope takes it either; it stays in the registry, listed by \`${verbAt(scope, 'list')}\`, and removable with \`${verbAt(scope, 'remove')}\``);
+        return lines;
+    }
+    // The scope that WOULD deliver it, named as the two commands that get there.
+    lines.push(elsewhere.scope === 'machine'
+        ? `the machine scope takes it (${elsewhere.executorIds.join(', ')}): register it with \`brambo add\` and project it with \`${elsewhere.command}\``
+        : `the project scope takes it (${elsewhere.executorIds.join(', ')}): register it with \`brambo project add\` and project it with \`${elsewhere.command}\``);
+    return lines;
+}
+/**
+ * `remove` on an entry that is not there is TYPED ABSENCE (AD-5): it says so and
+ * exits non-zero. A silent 0 would tell a script the entry is gone when the id
+ * was simply misspelled, which is the same class of lie as an empty diagnosis.
+ *
+ * The existence check reads the ONE scope being written, never the merged view:
+ * an entry shadowing from another scope would otherwise report a removal that
+ * did not happen — and hide a stale entry in this scope forever.
+ */
+async function performRemove(type, id, bound, out, err) {
+    const present = await bound.store.get(type, id, bound.registryScope);
+    if (present === undefined) {
+        out(JSON.stringify({ scope: bound.registryScope, registryPath: bound.registryPath, removed: null, type, id }, null, 2));
+        err(`nothing was removed: no ${type} entry '${id}' is registered at the ${bound.registryScope} scope in '${bound.registryPath}'`);
+        return 1;
+    }
+    await bound.store.remove(type, id, bound.registryScope);
+    out(JSON.stringify({ scope: bound.registryScope, registryPath: bound.registryPath, removed: present }, null, 2));
+    err(`removed: ${describeEntry(bound.registryScope, present)}`);
+    err(`stored in '${bound.registryPath}'`);
+    // NOT "takes it out of every executor brambo wrote it into" — that was false,
+    // not merely vacuous: over a location the user has edited, `brambo init`
+    // answers "brambo will not remove a tree it no longer recognises" and the
+    // content stays. What is true is the rule brambo actually applies.
+    err(`nothing was projected: \`${bound.projectCommand}\` removes it from every location brambo still owns, and reports the ones it no longer recognises rather than deleting them`);
+    return 0;
+}
+/**
+ * Every entry, WITH the scope it came from — which is why each scope is read on
+ * its own rather than through the merged view every projection uses: the merge
+ * keeps one row per `type:id`, so the scope that produced it is exactly the fact
+ * it drops.
+ *
+ * An empty registry exits 0. An empty list is a result, not a failure; the
+ * command did look, and it says what it found.
+ */
+async function runList(directory, scope, context) {
+    const { out, err } = context;
+    const bound = await bind(scope, directory, context);
+    try {
+        // The machine grammar has one scope and can see no other; the project
+        // grammar sees the project's entries over the machine's, in that order.
+        const scopes = scope === 'machine' ? ['global'] : ['global', 'project'];
+        const rows = [];
+        for (const registryScope of scopes) {
+            for (const entry of await bound.store.list(registryScope))
+                rows.push({ scope: registryScope, entry });
+        }
+        out(JSON.stringify({
+            scope: bound.registryScope,
+            registryPath: bound.registryPath,
+            entries: rows.map((row) => ({ scope: row.scope, ...row.entry })),
+        }, null, 2));
+        if (rows.length === 0) {
+            err(`the registry is empty; \`${verbAt(scope, 'add')} <type> <id>\` puts an entry in it`);
+            return 0;
+        }
+        for (const row of rows)
+            err(describeEntry(row.scope, row.entry));
+        return 0;
+    }
+    finally {
+        await bound.store.dispose();
+    }
+}
+/**
+ * `brambo export <path>` — the machine's Registry as a portable artifact.
+ *
+ * It lives beside `add`/`remove`/`list` rather than in its own module because
+ * it needs `bind`, and `bind` is the trust boundary those three already share:
+ * one spelling of "the home directory" and a bound directory brambo never
+ * creates. A second binding here is how two verbs come to disagree about which
+ * registry they are talking about.
+ *
+ * It is NOT a RegistryVerb. Those three also carry a project-scoped spelling,
+ * and a project-scoped export would name a directory the destination machine
+ * does not have — so the global scope is the only one that can travel, and
+ * there is no second grammar to offer.
+ */
+export async function runExportCommand(tokens, context) {
+    const { out, err } = context;
+    const [path, ...rest] = tokens;
+    if (path === undefined || path.length === 0 || path.startsWith('-')) {
+        // The destination is REQUIRED. The binary passes no cwd, so a default would
+        // resolve one way under a harness that supplies one and another way for
+        // every real user — the defect that made `brambo project swap` exit 2 for
+        // everyone while its whole suite was green.
+        err('usage: brambo export <path>');
+        err(context.defaultUsage);
+        return 2;
+    }
+    if (rest.length > 0) {
+        err(`unexpected argument '${rest[0]}'`);
+        err(context.defaultUsage);
+        return 2;
+    }
+    const bound = await bind('machine', undefined, context);
+    try {
+        // `bound.homeDir` and not a second `homedir()` call: the bundle's paths have
+        // to be relative to the SAME home the store was bound to, or an export run
+        // with an injected home writes paths pointing at the real one.
+        const bundle = createBundle(await bound.store.list('global'), bound.homeDir);
+        await writeBundle(path, bundle);
+        out(JSON.stringify({
+            path,
+            version: bundle.version,
+            scope: bundle.scope,
+            exported: bundle.entries.length,
+            // Named, never counted alone: an entry that did not travel is a task
+            // waiting on the other machine, and a bare number is not one.
+            //
+            // Forwarded VERBATIM, and that is what makes stdout clean without a
+            // redaction step here: the record's `id` arm has no id to print, so
+            // there is nothing at this site to remember to strip.
+            omitted: bundle.omitted,
+        }, null, 2));
+        return 0;
+    }
+    finally {
+        await bound.store.dispose();
+    }
+}
+/**
+ * `brambo import <path>` — the install half. The caller re-projects.
+ *
+ * Split there on purpose: re-projection is `initMachine`, whose result already
+ * has one reporting implementation in `run.ts`, and this file may not grow a
+ * second one. What belongs here is the part that needs `bind` — the same trust
+ * boundary add/remove/list/export share.
+ */
+export async function runImportCommand(tokens, context) {
+    const { err } = context;
+    const [path, ...rest] = tokens;
+    if (path === undefined || path.length === 0 || path.startsWith('-')) {
+        err('usage: brambo import <path>');
+        err(context.defaultUsage);
+        return 2;
+    }
+    if (rest.length > 0) {
+        err(`unexpected argument '${rest[0]}'`);
+        err(context.defaultUsage);
+        return 2;
+    }
+    // Read and validate BEFORE binding anything: a bundle brambo cannot read must
+    // not leave a `.brambo` directory behind on a machine the user was only
+    // trying an artifact on.
+    const bundle = await readBundle(path);
+    const bound = await bind('machine', undefined, context);
+    const replaced = [];
+    try {
+        for (const entry of bundle.entries) {
+            // Asked BEFORE registering, because `register` replaces by `type:id` and
+            // says nothing. A user moving devices who had already run `brambo add`
+            // deserves to be told which of their entries the bundle took over — the
+            // same rule as the omission record: brambo never overwrites in silence.
+            if ((await bound.store.get(entry.type, entry.id, 'global')) !== undefined) {
+                replaced.push({ type: entry.type, id: entry.id });
+            }
+            // EXPANDED against this machine's home before registering, and this is not
+            // symmetry for its own sake. `register` normalizes what it is given, and a
+            // bundle is ALREADY normalized — so handing it over verbatim runs the
+            // normalizer over `~/skills/x.ts`, whose leading `~` is the reserved
+            // marker, and the escape rule turns it into `~~/skills/x.ts`: a path to a
+            // file literally named `~/skills/x.ts`. Measured by driving the binary; a
+            // machine imported that way had every path field quietly wrong.
+            //
+            // The store's surface takes REAL paths — it is what `brambo add` passes and
+            // what `list()` returns — so import converts back into that vocabulary and
+            // lets the store normalize once, exactly as it does for any other write.
+            await bound.store.register(expandRegistryEntryPaths(entry, bound.homeDir), 'global');
+        }
+        return {
+            path,
+            homeDir: bound.homeDir,
+            imported: bundle.entries.length,
+            replaced,
+            pending: bundle.omitted.map((omitted) => ({ ...omitted })),
+        };
+    }
+    finally {
+        // Released before the caller re-projects: `initMachine` binds its own store
+        // and would contend with this one for the same lock.
+        await bound.store.dispose();
+    }
+}
+/**
+ * `brambo ingest [--dry-run]` — the machine's own skills AND MCP servers, into
+ * the registry.
+ *
+ * The binding's whole job, and the reason it is this short: argv in, one
+ * capability call, the outcome rendered, exit 0. Which skills roots and which
+ * executor configs are read, what the ownership ledger excludes, and what counts
+ * as a skill or a server are `ingestMachine`'s answers — a second opinion here
+ * would be a rule that drifts from the one the capability enforces, and the CLI
+ * may not touch the filesystem at all.
+ *
+ * A run that wrote nothing because there was nothing to write exits 0. That is
+ * the same answer `brambo list` gives for an empty registry: it is a result, not
+ * a failure, and a script must be able to tell it apart from a run that broke.
+ */
+export async function runIngestCommand(tokens, context) {
+    const { out, err } = context;
+    const flag = tokens.find((token) => token.startsWith('-'));
+    if (flag !== undefined && flag !== DRY_RUN_FLAG) {
+        err(`unrecognized option '${flag}'`);
+        err(context.defaultUsage);
+        return 2;
+    }
+    const positional = tokens.find((token) => !token.startsWith('-'));
+    if (positional !== undefined) {
+        // Machine scope only: `ingestMachine` reads the skills roots and the
+        // executor configs brambo has verified for this machine, and there is no
+        // directory to name.
+        err(`unexpected argument '${positional}'`);
+        err(context.defaultUsage);
+        return 2;
+    }
+    const report = await ingestMachine({
+        homeDir: context.homeDir,
+        dryRun: tokens.includes(DRY_RUN_FLAG),
+    });
+    out(JSON.stringify({
+        scope: 'global',
+        registryPath: report.registryPath,
+        dryRun: report.dryRun,
+        roots: report.roots,
+        // Both halves, side by side. The mcp-server half under its own key
+        // rather than merged into the skills fields: a user reading `skipped`
+        // has to be able to tell a directory that is not a skill from a server
+        // brambo could not read, and one flat list answers neither question.
+        configPaths: report.mcpServers.configPaths,
+        registered: report.outcome.registered,
+        unchanged: report.outcome.unchanged,
+        ownedByBrambo: report.ownedByBrambo,
+        skipped: report.skipped,
+        mcpServers: {
+            ownedByBrambo: report.mcpServers.ownedByBrambo,
+            skipped: report.mcpServers.skipped,
+            dropped: report.mcpServers.dropped,
+        },
+        warnings: report.outcome.warnings,
+    }, null, 2));
+    // Each fact on its own line, because a user who ran a command wants the work
+    // left for them without parsing JSON for it.
+    for (const skip of report.skipped)
+        err(`skipped: ${skip.detail}`);
+    for (const skip of report.mcpServers.skipped) {
+        // A config brambo could not open is not a candidate it skipped: the servers
+        // in it were never seen at all, and calling that "skipped" would understate
+        // it. Every other kind is one entry brambo looked at and declined.
+        err(skip.kind === 'unreadable-config' ? `not read: ${skip.detail}` : `skipped: ${skip.detail}`);
+    }
+    // What did NOT travel, named with the file it stayed in. A key brambo cannot
+    // carry is still in the vendor's document doing its job; saying nothing would
+    // let a user believe the registry holds the whole server.
+    for (const drop of report.mcpServers.dropped) {
+        err(`'${drop.entryId}' was ingested for its command and arguments only; '${drop.keys.join("', '")}' stayed in '${drop.filePath}' because a registry mcp-server entry has nowhere to put them`);
+    }
+    for (const warning of report.outcome.warnings)
+        err(warning.detail);
+    if (report.ownedByBrambo.length > 0) {
+        err(`${report.ownedByBrambo.length} director(ies) in those roots were written by brambo itself and were left alone`);
+    }
+    if (report.mcpServers.ownedByBrambo.length > 0) {
+        err(`${report.mcpServers.ownedByBrambo.length} server(s) in those configs were written by brambo itself and were left alone`);
+    }
+    const written = report.outcome.registered.length;
+    err(report.dryRun
+        ? `${written} entr(ies) would be ingested into '${report.registryPath}'; nothing was written`
+        : `${written} entr(ies) ingested into '${report.registryPath}'`);
+    if (report.outcome.unchanged.length > 0) {
+        err(`${report.outcome.unchanged.length} entr(ies) were already registered and unchanged`);
+    }
+    return 0;
+}

package/dist/src/run.d.ts

@@ -0,0 +1,26 @@
+import { type InitMachineOptions } from '@skanl/brambo-environment';
+import { type LogRecord, type SessionOptions } from '@skanl/brambo-session';
+/**
+ * The seams are PICKED from the capability packages rather than redeclared: this
+ * package forwards them and owns none of them, so naming their types here would
+ * be the first step back towards composing sessions in the CLI (see the
+ * thin-binding pin in `test/run.test.ts`). What the CLI owns is where the output
+ * goes.
+ */
+export interface RunCommandOptions extends Pick<SessionOptions, 'cwd' | 'adapterOptions' | 'createAdapter' | 'createProvider' | 'onInterrupt'>, Pick<InitMachineOptions, 'homeDir'> {
+    readonly stdout?: (line: string) => void;
+    readonly stderr?: (line: string) => void;
+}
+export declare const USAGE: string;
+export declare function runBrambo(argv: readonly string[], options?: RunCommandOptions): Promise<number>;
+/**
+ * One record, one line, for a human watching a run happen. Fields in the order
+ * the kernel writes them, each present only when the record carries it.
+ *
+ * It formats and decides nothing — the whole of cordis's `ConsoleExporter` is
+ * `console.log(this.render(message))` over a renderer just like this one. `at`
+ * is left out on purpose: the record carries a wall clock for whoever PERSISTS
+ * the stream, but ordering is `seq`, and a timestamp on a line scrolling past
+ * live is noise that carries no order the number does not already carry.
+ */
+export declare function renderLogRecord(record: LogRecord): string;