@skanl/brambo-cli 0.1.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 SKANL
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,208 @@
+# @skanl/brambo-cli
+
+Minimal `brambo` command-line surface, and nothing more than a binding: it parses
+argv, calls [`@skanl/brambo-session`](../session/README.md), prints the typed envelope as
+structured JSON and maps it to an exit code. The composition it used to own —
+workspace under `<cwd>/.brambo/workspaces/<uuid>`, adapter, cancellation, cleanup —
+lives in that package, so a third party can do everything this CLI does without
+installing it. It reads no files itself; `eslint.config.js` forbids this package
+from importing `node:fs` at all, because a capability that needs a filesystem
+read is a capability that belongs in `@skanl/brambo-session` or `@skanl/brambo-environment`.
+
+## Install
+
+```sh
+npm i -g @skanl/brambo-cli
+```
+
+The binary is `brambo`. Every command below is written the way it works after
+that install; inside this repository's own checkout the same commands run as
+`pnpm brambo …`, which is a development convenience and not what a consumer types.
+
+## Usage
+
+```sh
+brambo run "list files in this workspace"
+brambo run --executor codex "list files in this workspace"
+```
+
+Output: the `ResultEnvelope` as pretty-printed JSON on stdout.
+
+## Choosing an executor
+
+Brambo ships three adapters — `claude-code`, `codex` and `opencode` — and resolves
+which one runs through layered configuration, widest to narrowest:
+
+| Layer | Source |
+| ----- | ------ |
+| `defaults` | brambo's built-in default, `claude-code` |
+| `global` | `~/.brambo/config.json` |
+| `project` | `<project>/.brambo/config.json` |
+| `invocation` | `--executor <id>` (or `--executor=<id>`) |
+
+The document is JSON. `executor` is the key this table resolves; the same file
+carries the other selections brambo reads — `method` (see `brambo swap method`) and
+the `workspace` subtree that `@skanl/brambo-workspace-local` and
+`@skanl/brambo-workspace-git-worktree` document:
+
+```json
+{ "executor": "codex" }
+```
+
+**Every real invocation now writes one line to stderr**, naming the selection and
+the layer that decided it — `executor: codex (selected by the 'project' layer)`.
+A run whose output cannot tell you which agent produced it is not a swap you can
+trust. This is a behaviour change for a script that treats any stderr output as
+failure; branch on the exit code instead.
+
+A configuration document that is MISSING is simply an absent layer. One that
+exists and cannot be used — unreadable, a dangling symlink, invalid JSON, not an
+object, or an `executor` that is not a string — is a coded error and exits 2. It
+is never a quiet fall back to the default, because running a different agent than
+the one you configured is the failure this feature exists to remove. `--executor`
+overrides a configuration brambo can READ; it does not rescue one it cannot.
+
+## Putting something in the registry
+
+Everything `brambo init` projects comes out of the registry, and until story M4.D
+there was no way to put anything in it from the binary — the store shipped, the
+surface did not.
+
+```sh
+brambo add skill commit-lint --entry-path ./skills/commit-lint/SKILL.md
+brambo add mcp-server fs --command npx --arg -y --arg @modelcontextprotocol/server-filesystem
+brambo list
+brambo remove skill commit-lint
+```
+
+The scope comes from the GRAMMAR, never from a flag: `brambo <verb>` is the
+machine scope and `brambo project <verb> … [directory]` is a project's, exactly
+like `init`, `doctor` and `remediate`. There is deliberately no `--scope agent` —
+the agent scope is an in-memory map that dies with the process, so a flag for it
+would accept the flag, exit 0 and persist nothing.
+
+Which field flags a type accepts is the registry CONTRACT's answer, not this
+command's: `brambo add mcp-server t --entry-path ./x` is refused with
+`BRAMBO_REGISTRY_INVALID_ENTRY`, because an `mcp-server` carries a `command` and
+`args`. The CLI holds no per-type table, so it cannot drift from the one the
+contract already has.
+
+Story M4.E RETIRED the `tool` type: no executor has a non-MCP location for an
+identity plus an executable command, and an `mcp-server` entry already carries
+exactly what a `tool` entry carried. Story M4.F retired `profile` through the
+same door, on the PRD's own glossary: a Profile is a named bundle of registry
+SELECTIONS carried by Bundles, so it is a container over `skill` and
+`mcp-server` rather than a peer of them, and it returns designed in Epic 5.
+`brambo add tool …` and `brambo add profile …` are usage errors, but a registry
+written by an older build is still read, still listed, and still emptied
+through the product — `brambo remove` accepts a retired type, and `brambo doctor`
+prints the exact spelling for each entry it finds.
+
+`add` registers and projects nothing; it names the command that does. Coupling
+the two would make registration fail for projection reasons.
+
+That next step is DERIVED from the same planner `brambo init` runs, never written
+beside the command, and it can say that nothing takes the entry at all:
+
+```
+$ brambo project add skill deadend --entry-path ./s.md
+registered: project - skill - deadend
+NOTHING TAKES IT HERE: no detected executor has a project-scope location for a
+skill entry, so `brambo project init` would project it nowhere
+the machine scope takes it (codex): register it with `brambo add` and project it
+with `brambo init`
+```
+
+That is a real dead end and it used to be silent: no executor has a
+project-scope skills root brambo has verified, machine-scope projection cannot
+see a project-scope entry, and `add` still pointed at `brambo project init`, which
+exits 0 and delivers nothing. The registration still succeeds — the entry is
+yours and `brambo list` shows it — but the command you are pointed at is the one
+that would actually deliver it, or none, and never a command that would not.
+
+`remove` on an entry that was not there says so and exits 1. An empty `list`
+exits 0 — an empty list is a result, not a failure.
+
+## Leaving a state `brambo doctor` reported
+
+`brambo doctor` reports drift and refuses to resolve it, which is correct and used
+to be terminal: the only exit was hand-editing `~/.brambo/projection-ledger.json`,
+the file every safety guarantee in that subsystem is stored in.
+
+```sh
+brambo remediate adopt --executor claude-code --entry context7          # describes
+brambo remediate adopt --executor claude-code --entry context7 --apply  # performs
+```
+
+One finding at a time, named by the user, and only a finding the same run just
+reported — zero matches and more than one match are both refusals, and the
+refusal lists what could have been named. Without `--apply` the command only
+describes, computed by the code that would perform it. Nothing is ever
+remediated automatically or in bulk.
+
+| Verb | What it changes | What it lets a LATER run do |
+| ---- | --------------- | --------------------------- |
+| `adopt` | brambo's ledger only | brambo OWNS the location: the next `brambo init` replaces what is there, and on a skills root can remove it. Every path that becomes deletable is named in the description first |
+| `release` | brambo's ledger only | nothing — the claim goes, the file is not even opened, and no later run touches it |
+| `repair` | brambo's own ledger document, dropping exactly the records it cannot read | nothing to a vendor file, ever |
+| `discard` | one vendor file, removing only brambo's own prior output (correction-01 C6) | nothing further |
+
+Three of the four write nothing but brambo's own ledger — but `adopt` is an
+ownership TRANSFER, and owning a location is what makes it replaceable and, on a
+skills root, removable. Read the description: it says which of the two the next
+`brambo init` will do and which paths it covers. A `remediate` that brambo refuses
+exits 1 with `BRAMBO_PROJECTION_REMEDIATION_REFUSED` and changes nothing.
+
+`brambo doctor` names the verb for every state that has one, so the report and the
+exit are one string.
+
+## How much quota is left
+
+```sh
+brambo status
+```
+
+One row per executor, reporting what that executor published about its own usage
+the last time brambo ran it — the windows the vendor NAMES, with the vendor's own
+utilisation and reset values and the instant the reading was taken. Brambo
+averages nothing, converts nothing, and states no "time remaining" the vendor did
+not state.
+
+`brambo status` **invokes no executor and writes nothing**. A report that spent
+the quota it reports on would be unusable on exactly the day you most want it, so
+the run that already paid for a reading is the one that records it, and `status`
+reads the record. That is also why every row is honest about what it does not
+know: an executor that publishes no usage surface says so
+(`BRAMBO_USAGE_NO_SURFACE`), and one brambo has not run yet says so and names the
+command that would produce a reading (`BRAMBO_USAGE_NOT_OBSERVED`). Neither is
+ever shown as `0%` — a zero for something brambo never measured reads as a
+measurement that was taken.
+
+Today only `claude-code` publishes such a surface, in its own event stream. It is
+a typed field the vendor emits deliberately under a documented flag, not text
+scraped off a terminal.
+
+## Exit codes
+
+| Code | Meaning |
+| ---- | ------- |
+| 0 | run completed with a status `ok` envelope |
+| 1 | run returned `failed` or `cancelled` (envelope still printed) |
+| 2 | usage error, invalid request, or environment failure (message on stderr) |
+
+For `status` there are two: 0 whenever a report could be produced — an
+all-absence report is still a report — and 2 only when none could be. There is no
+1, because a utilisation is not a verdict brambo gets to fail on.
+
+For `doctor` the three narrow: 0 clean, 1 at least one finding that is a problem,
+2 no diagnosis could be produced. For `remediate`: 0 described or performed, 1
+brambo refused, 2 usage or environment failure. For `remove`: 0 removed, 1 the
+entry was not registered at that scope (typed absence, never a silent 0), 2 usage
+or a coded registry failure.
+
+An executor name brambo has no adapter for (`BRAMBO_EXECUTOR_NOT_FOUND`) and an
+unusable configuration document (`BRAMBO_CONFIGURATION_UNUSABLE`) are both 2, and
+carry distinct codes because their fixes differ: correct the name versus repair
+the file.
+
+No TUI, no streaming — progress surfaces arrive in later stories.

package/dist/bin/brambo.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/dist/bin/brambo.js

@@ -0,0 +1,9 @@
+#!/usr/bin/env node
+import { runBrambo } from '../src/run.js';
+// `brambo run ... | head` must not crash: a closed stdout pipe surfaces as an
+// async EPIPE error on the stream, which we treat as a graceful exit.
+process.stdout?.on('error', (error) => {
+    if (error.code === 'EPIPE')
+        process.exit(0);
+});
+process.exitCode = await runBrambo(process.argv.slice(2));

package/dist/src/index.d.ts

@@ -0,0 +1,2 @@
+export { runBrambo } from './run.ts';
+export type { RunCommandOptions } from './run.ts';

package/dist/src/index.js

@@ -0,0 +1 @@
+export { runBrambo } from './run.js';

package/dist/src/registry-commands.d.ts

@@ -0,0 +1,94 @@
+import type { OmittedEntry } from '@skanl/brambo-environment';
+export type RegistryVerb = 'add' | 'remove' | 'list';
+/** The verbs `run.ts` dispatches into this file, under both grammars. */
+export declare const REGISTRY_VERBS: readonly RegistryVerb[];
+export declare function isRegistryVerb(token: string | undefined): token is RegistryVerb;
+export interface RegistryCommandContext {
+    readonly out: (line: string) => void;
+    readonly err: (line: string) => void;
+    /** The synopsis printed after a usage error; `run.ts` owns the text. */
+    readonly defaultUsage: string;
+    /** Defaults to the OS home directory, like every other command's. */
+    readonly homeDir: string | undefined;
+    /** The project directory when no positional one is given. */
+    readonly cwd: string | undefined;
+}
+/**
+ * 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 declare function verbAt(scope: 'machine' | 'project', verb: string): string;
+export declare function runRegistryCommand(verb: RegistryVerb, tokens: readonly string[], scope: 'machine' | 'project', context: RegistryCommandContext): Promise<number>;
+/**
+ * `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 declare function runExportCommand(tokens: readonly string[], context: RegistryCommandContext): Promise<number>;
+/** What an import put in place, before the projection half runs. */
+export interface ImportInstallation {
+    readonly path: string;
+    readonly homeDir: string;
+    readonly imported: number;
+    /** Entries whose `type:id` was already registered here and has been taken over. */
+    readonly replaced: readonly {
+        type: string;
+        id: string;
+    }[];
+    /**
+     * What the bundle could not carry, forwarded verbatim: FR-22's manual work.
+     *
+     * `OmittedEntry` itself rather than a structural copy of its shape. The copy
+     * spelled `{type, id, field}`, which is exactly the shape the `id` arm must
+     * NOT have — so a hand-written mirror of a type is how a second slot for the
+     * credential gets re-opened one package downstream.
+     */
+    readonly pending: readonly OmittedEntry[];
+}
+/**
+ * `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 declare function runImportCommand(tokens: readonly string[], context: RegistryCommandContext): Promise<ImportInstallation | number>;
+/**
+ * `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 declare function runIngestCommand(tokens: readonly string[], context: RegistryCommandContext): Promise<number>;