@widgetic/cli 0.0.0-stage → 0.1.1

package/LICENSE

@@ -0,0 +1,122 @@
+Widgetic Integration License
+Version 1.0
+
+Copyright (c) Widgetic. All rights reserved.
+
+This license covers the software package that it came with, in source and
+compiled form, together with its documentation (the "Software"). By
+installing, copying or using the Software you accept this license. If you do
+not accept it, do not install or use the Software.
+
+In this license, "Widgetic" is the company that publishes the Software, "you"
+is the person or organization that uses it, and "Your Application" is an
+application, website, product or service that you build or operate, for
+yourself or for a client. "Widgetic Services" are the services that Widgetic
+operates: the Widgetic API, widgets, compositions, embeds, editors, file
+browser, chat and AI creator, and the other services that can be reached from
+widgetic.com or its API hosts.
+
+1. What you may do
+
+Widgetic grants you a worldwide, non-exclusive, non-transferable and
+non-sublicensable license to use the Software, unmodified, for one purpose: to
+integrate the Widgetic Services into Your Application. Within that purpose you
+may:
+
+(a) install the Software and run it in Your Application, in development,
+testing and production;
+
+(b) use it to call the Widgetic API, to show Widgetic widgets and
+compositions, and to open Widgetic's editors, file browser, chat and AI
+creator inside Your Application;
+
+(c) bundle, minify and tree-shake the Software with the build tools of Your
+Application, deliver the result to the people who use Your Application as a
+part of it, and let them run it there;
+
+(d) keep the copies of the Software that (a), (b) and (c) need, including
+copies in your version control, your build systems and your backups.
+
+2. What you may not do
+
+You may not, and may not allow anyone else to:
+
+(a) use the Software for any purpose other than the one in section 1;
+
+(b) use the Software to build, run or improve a service that offers what the
+Widgetic Services offer, or to connect Your Application to anything other than
+the Widgetic Services (a proxy of yours that forwards calls to the Widgetic
+Services is fine);
+
+(c) copy, modify, translate, adapt or make derivative works of the Software,
+except as section 1(c) allows;
+
+(d) publish, sell, rent, lease, sublicense or distribute the Software on its
+own, or inside a library, SDK, template or product that others could use for
+anything other than integrating the Widgetic Services, including by
+publishing it, or a copy of it, to a package registry or a public CDN;
+
+(e) reverse engineer, decompile or disassemble the Software, or try to get at
+its source code, except as far as the law lets you despite this restriction;
+
+(f) remove or change a copyright, license or attribution notice in the
+Software;
+
+(g) bypass, disable or interfere with the authentication, rate limits, quotas,
+credits, plan limits or other protections of the Widgetic Services, or help
+anyone else to;
+
+(h) use the name, logo or trademarks of Widgetic, except to say truthfully
+that Your Application integrates Widgetic.
+
+3. The Widgetic Services are separate
+
+This license is for the Software only. It does not give you the right to use
+the Widgetic Services. That right comes from your account or agreement with
+Widgetic and from Widgetic's Terms of Service (https://widgetic.com/terms),
+which this license does not change.
+
+4. Ownership
+
+The Software is licensed to you, not sold. Widgetic and its licensors keep all
+rights in it. Any right that this license does not give you in plain words is
+reserved to Widgetic.
+
+5. Third-party software
+
+The Software may include or depend on software from others. That software is
+under its own license, which applies to it instead of this one, and nothing in
+this license limits your rights under it.
+
+6. How long it lasts
+
+This license lasts while you follow it and while you are entitled to use the
+Widgetic Services. It ends on its own if you break it or that entitlement
+ends. When it ends, you stop using the Software and delete your copies of it,
+except copies that the law requires you to keep. Sections 4, 8 and 9 still
+apply after it has ended.
+
+7. Versions
+
+This license applies to the version of the Software that it came with and to
+later versions that carry it. A version that Widgetic published under another
+license stays under that license, for the copies of it that you already have.
+
+8. No warranty
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR
+PURPOSE AND NON-INFRINGEMENT.
+
+9. Limit of liability
+
+TO THE EXTENT THE LAW ALLOWS, WIDGETIC IS NOT LIABLE FOR ANY INDIRECT,
+INCIDENTAL, SPECIAL, CONSEQUENTIAL OR PUNITIVE DAMAGES, OR FOR LOST PROFITS,
+REVENUE, DATA OR GOODWILL, THAT ARISE FROM THE SOFTWARE OR FROM THIS LICENSE,
+EVEN IF IT HAS BEEN TOLD THAT THEY ARE POSSIBLE. NOTHING IN THIS LICENSE
+LIMITS A LIABILITY THAT THE LAW DOES NOT ALLOW TO BE LIMITED.
+
+10. Questions
+
+If you need to do something that this license does not allow, ask first:
+support@widgetic.com.

package/README.md

@@ -1,3 +1,185 @@
-# Temporary Holding Version
+# @widgetic/cli
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+The Widgetic command line. One binary, two namespaces:
+
+- `widgetic api <group> <command>`: every operation of the public REST API.
+- `widgetic mcp <command>`: every AI build tool of the Widgetic MCP server.
+
+Every command is generated from the backend's own contracts, not written by hand, and every command takes `--json` (machine-readable output) and `--dry-run` (print the exact request, send nothing).
+
+## Quick start
+
+Needs Node 22.12 or later.
+
+```bash
+npm install -g @widgetic/cli
+
+widgetic auth login                    # asks for an API key without showing it, checks it, saves it
+widgetic doctor                        # the install, the key, the REST API and the MCP server
+widgetic api widgets get-widgets       # a REST call
+widgetic mcp create-widget --title "Launch countdown" --brief "A countdown to 14 March 2027" --wait
+```
+
+`widgetic --help`, `widgetic api --help`, `widgetic api <group> --help` and `widgetic <command> --help` list what is there. The whole reference, one page per group, is generated into [`docs/commands`](docs/commands/index.mdx).
+
+## The commands
+
+| Command                                                                  | What it does                                                                                                                            |
+| ------------------------------------------------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------- |
+| `widgetic api <group> <command>`                                         | One REST operation. The group is the tag of the OpenAPI description, the command is its operation (`get-widgets`, `create-widget`).     |
+| `widgetic mcp <command>`                                                 | One MCP tool (`create_widget` is `widgetic mcp create-widget`).                                                                         |
+| `widgetic api call <operationId>`, `widgetic mcp call <tool>`            | Run a command by the name its contract gives it. It also reaches the public embed operations, which `--help` does not list.             |
+| `widgetic schema api <group> <command>`, `widgetic schema mcp <command>` | The whole description of one command and the JSON Schema its input is checked against: the cheap way for an agent to learn one command. |
+| `widgetic auth login`, `logout`, `status`                                | Save, forget and check the API key.                                                                                                     |
+| `widgetic doctor`                                                        | Check the CLI, the key and both servers, and say what is wrong (exit 1 when a check fails; `--json` prints every check).                |
+| `widgetic update`                                                        | Look on npm for a newer version of the CLI, show it beside the installed one, and install it after a yes (see [Updates](#updates)).     |
+| `widgetic completion bash\|zsh\|fish`                                    | The script that completes commands and flags with the Tab key.                                                                          |
+
+### Every command takes
+
+| Flag                  | What it does                                                                                                                                                                 |
+| --------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `--json`              | The result, and only the result, as one line of JSON on stdout. An error is one line on stderr: `{"error":{"code","message","status","requestId"}}`. It never asks anything. |
+| `--dry-run`           | Print the exact request (the API key is left out) and send nothing. It needs no key.                                                                                         |
+| `--yes`               | Go ahead without asking. Only a command that deletes or changes something asks (on a terminal), and without a terminal it needs `--yes`.                                     |
+| `--profile <name>`    | The saved key to use (default: `WIDGETIC_PROFILE`, else `default`).                                                                                                          |
+| `--timeout <seconds>` | Give up on a call after this long (default 60).                                                                                                                              |
+| `--data` / `--input`  | The whole request document as JSON, `@file.json`, or `-` for standard input. The flags of the command override its keys.                                                     |
+
+What goes on stdout with `--json`: for a REST command the response body as the server sent it; for an MCP tool its `structuredContent`.
+
+### Build tools
+
+The tools that build a widget (`create-widget`, `replicate-widget`, `revise-widget`) answer at once and the build goes on in the background. `--wait` keeps asking `get_widget` until the build has finished (up to 15 minutes) and prints the finished widget; a build that fails or is cancelled ends with exit code 5 and the widget in the error. A tool that takes `publish` sends `publish: false` unless you pass `--publish`, so what the CLI builds stays a draft.
+
+### Retries
+
+A call is tried at most three times. A `429` is always waited out (a `Retry-After` of up to 30 seconds is honoured; a longer one is reported with exit code 6). A dropped connection, a timeout, a `502`, `503` or `504` is tried again only when repeating cannot do anything twice: the call reads, or it carries an idempotency key. The CLI makes the key of a call that creates something, and sends the same one on every try.
+
+## What it can reach
+
+The CLI is generated from the **public** contracts and from nothing else. `@widgetic/api-contracts` carries the public OpenAPI description (the file the partners' SDKs, `@widgetic/api-sdk-ts` and its siblings, are generated from, and the published API reference) and the MCP tool contract. It is not generated from the private description that Widgetic's own apps use (`@widgetic/api-sdk`, which also lists the administrator and internal operations), so none of those is a command. A mistake in the gateway cannot add one: the package is only built from a description in which every operation is marked `x-visibility: public` and has a level that an API key passes, and the build stops at the first operation that is not.
+
+| Level of the operation (`x-access-level`) | Who calls it                                                            | In the CLI                                                                       |
+| ----------------------------------------- | ----------------------------------------------------------------------- | -------------------------------------------------------------------------------- |
+| `user`                                    | Any API key: your widgets, your account                                 | Listed. Its help names no special key.                                           |
+| `partner`                                 | A partner key (`wgt_prt_…`): managed users, credits, storage, analytics | Listed. Its help says `Needs a partner API key (wgt_prt_…).`                     |
+| `public`                                  | Browsers, with no key: the runtime of an embed                          | Left out of `--help`; `widgetic api call <operationId>` runs it. No key is sent. |
+
+The CLI does not decide who may do what. The API does, on every call, from the key: a key without the scope or the level gets a 403 (exit code 3), the same answer as from the SDK or from `curl`. The CLI only makes what the key may already do easy to find and to call.
+
+## The key
+
+A command that needs a key uses, in this order:
+
+1. `WIDGETIC_API_KEY` in the environment: used as it is, never written anywhere. Use it in CI and in agents.
+2. The key of the profile that `widgetic auth login` saved in `credentials.json` (mode 0600, in a folder of mode 0700).
+
+`widgetic auth login` reads the key from a hidden prompt, or from standard input with `--with-key` (`echo "$WIDGETIC_API_KEY" | widgetic auth login --with-key`); a key is never taken from an argument, because an argument is in the shell history. It checks the key with the server before it saves it. The help of a command says when it needs a partner key (`wgt_prt_…`) or none at all.
+
+The key is sent to the API's own address and to nowhere else: a redirect to another origin does not carry it along ([`test/key-stays-home.test.ts`](test/key-stays-home.test.ts) holds that with the real `fetch`).
+
+### Secrets in a command
+
+A value the contract marks as a secret (the key of an adapter, the secret half of a storage key, a database connection string: `format: password` or `writeOnly`) is never typed as the text of a flag, because what is typed stays in the shell's history and in the list of processes. Its flag takes `@path` (a file) or `-` (a hidden prompt on a terminal, standard input otherwise):
+
+```bash
+widgetic api partners set-partner-adapter-connection --partner-id <id> --adapter-id <adapter> --credential-key <name> --credential @./key.txt
+pass show provider/key | widgetic api partners set-partner-adapter-connection --partner-id <id> --adapter-id <adapter> --credential-key <name> --credential -
+```
+
+A secret typed as the text of the flag is refused (exit code 2), nothing is sent, and the error does not repeat it. `--dry-run` prints `[redacted]` in its place, whether it came from a flag or from the document of `--data`. Which values are secrets is the contract's word, not a list in the CLI ([`src/secrets.ts`](src/secrets.ts)): the generator stops at a secret it has no safe way to take (one in a URL, a header, a form field or an MCP tool argument).
+
+### Environment variables
+
+| Variable                                         | What it is                                                                                                                                   |
+| ------------------------------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------- |
+| `WIDGETIC_API_KEY`                               | The API key. The one secret.                                                                                                                 |
+| `WIDGETIC_PROFILE`                               | The profile of the saved key when `--profile` is not given.                                                                                  |
+| `WIDGETIC_API_URL`                               | The REST address, to call another environment (https; http only for localhost). Default: the server of the OpenAPI description.              |
+| `WIDGETIC_MCP_URL`                               | The MCP address. Default: `https://mcp.widgetic.com/`.                                                                                       |
+| `WIDGETIC_CONFIG_DIR`                            | The folder of the CLI's own files. Default: `~/.config/widgetic` (`$XDG_CONFIG_HOME/widgetic`, `%APPDATA%\widgetic` on Windows).             |
+| `WIDGETIC_DEBUG=1`                               | Print a stack with an unexpected error, and say why the CLI did not look for a newer version.                                                |
+| `NO_UPDATE_NOTIFIER`, `WIDGETIC_NO_UPDATE_CHECK` | Set to anything but `0`, `false`, `no` or `off`: never look for a newer version or ask about one (`CI` does the same).                       |
+| `npm_config_registry`                            | The registry that the look for a newer version asks (default `https://registry.npmjs.org`); npm's own variable, https or http for localhost. |
+
+## Exit codes
+
+| Code | Meaning                                                                                |
+| ---- | -------------------------------------------------------------------------------------- |
+| 0    | ok                                                                                     |
+| 1    | anything else (a bug, an unexpected 5xx, a build that did not finish in time)          |
+| 2    | usage or validation: the command line or a JSON document is wrong; nothing sent        |
+| 3    | authentication or plan: no key, 401, 402, 403                                          |
+| 4    | not found (404, 410)                                                                   |
+| 5    | rejected by the server (400, 409, 422, other 4xx; an MCP tool result with error)       |
+| 6    | rate limited or unavailable (429, 502, 503, 504, timeout, no network)                  |
+| 7    | this CLI is too old (426): `widgetic update`, or `npm install -g @widgetic/cli@latest` |
+
+## Updates
+
+After a command, at a terminal, the CLI says when a newer version is on npm, shows both versions and asks:
+
+```text
+A new version of the Widgetic CLI is available: 0.1.0 → 0.2.0
+Update now? (runs `npm install -g @widgetic/cli@0.2.0`) [y/N]
+```
+
+- **It never gets in the way.** The look for the newest version is one small request to `https://registry.npmjs.org/@widgetic%2fcli/latest` (no key and nothing from your account: npm sees your address and the user agent `@widgetic/cli/<version> (update check)`). It starts with the command and runs beside it, with a 2 second limit, and its answer is kept for 24 hours (1 hour after a failure) under `updateCheck` in `state.json`. The question comes after the command has printed its result, on stderr, and nothing that happens in it changes the command's exit code.
+- **It asks a person, and only a person.** Not with `--json` or `--yes`; not when standard input, output or errors is not a terminal; not in CI (`CI`); not with `NO_UPDATE_NOTIFIER` or `WIDGETIC_NO_UPDATE_CHECK` set; not for `--help`, `--version`, `help`, `completion` (the shell calls it on every Tab) or `update`; and not for a source checkout or a copy that `npx` fetched to run once. `WIDGETIC_DEBUG=1` says which of these applied.
+- **The default is no.** Enter, Ctrl-C and 20 seconds of silence are all "no". A "no" is remembered for 7 days for that version, and a newer version asks at once. A server that refuses the CLI as too old (exit code 7) always gets the question.
+- **It installs what it showed.** On yes it runs the global install command of the package manager that installed this copy (`npm install -g`, `pnpm add -g`, `yarn global add` or `bun add -g`), pinned to the version it showed, and then reads the installed copy again to check that it changed. A copy it cannot place (inside a project's `node_modules`, a custom prefix) is not touched: the CLI prints the new version and the command to run.
+
+`widgetic update` does the same whenever you ask. It asks npm itself instead of using what was kept; `--check` only reports, `--yes` installs without asking, and `--json` prints `{package, current, latest, updateAvailable, updated, installedWith, command}` and never asks (add `--yes` to install). The code is in [`src/update`](src/update) and [`src/commands/update.ts`](src/commands/update.ts); the question lives in `runProcess` ([`src/main.ts`](src/main.ts)), so the commands themselves, and their tests, never ask it.
+
+## Where the commands come from
+
+The gateway (`Services/api-gateway-service`) builds a package, [`@widgetic/api-contracts`](https://www.npmjs.com/package/@widgetic/api-contracts): the public OpenAPI description and the MCP tool contract, version-stamped with the gateway's own version. This repository keeps **no copy** of either.
+
+- `npm run generate` reads the installed `@widgetic/api-contracts` and writes `generated/` (git-ignored): the REST command manifest, the MCP command manifest and a small record of the contracts' versions.
+- `npm run build` generates, then compiles `src/` to `dist/`. The package ships `dist/` and `generated/`.
+- At run time the CLI builds its commands from `generated/`. A new endpoint or a new MCP tool is a new command the day the contracts package is bumped and the CLI is released; nobody writes it.
+
+### Keeping the CLI and the MCP in step
+
+There is nothing to keep in step by hand: the commands are a function of the contracts, and four guards fail when they are not.
+
+- **Tests.** `test/command-snapshot.test.ts` holds the command tree (names, flags, groups) to a checked-in snapshot, so a new endpoint, a renamed tool or a changed flag shows up as a diff somebody reads; `test/command-reference.test.ts` does the same for the generated reference in `docs/commands`; the generator tests fail on an operation or a tool that has no command, or two with one name.
+- **The release gate** (`npm run check:release`, run by the publish script before the version is raised, and by the `publish` job of `.gitlab-ci.yml`). It fails unless the contracts the commands were generated from are a release, are the newest `latest` of `@widgetic/api-contracts` on npm, and the tool names and the tool contract version are the ones production's MCP `tools/list` answers. It asks production with the key of `WIDGETIC_API_KEY` or of `widgetic auth login`; a read-only key is enough. Nothing is published and no version is raised when it fails.
+- **At run time.** When an MCP command opens a session and the server's tool contract is not the one the CLI was built for, the CLI says so once in 24 hours on stderr (never with `--json`), and `widgetic doctor` always shows the two versions.
+- **The server can refuse an old CLI.** Every request carries `X-SDK-Version: @widgetic/cli/<version>` (MCP: the client's `clientInfo`). The gateway counts the versions it sees and can answer `426` to one that is too old: exit code 7.
+
+## Development
+
+Needs Node 22.18 or later (the scripts run TypeScript directly with Node's type stripping; the published package is plain JavaScript and needs Node 22.12).
+
+```bash
+npm install
+npm run check          # typecheck, tests, prettier
+npm run build          # dist/ (and generated/)
+npm run docs           # write docs/commands from the installed contracts
+npm run snapshot       # write the command snapshot from the installed contracts
+npm run check:release  # the release gate (needs the network and a key)
+```
+
+Tests run the real program in-process against a fake environment (`test/helpers/fake-environment.ts`): a fetch that answers from a function and records what it was asked, streams that collect the output, no terminal, no real network, and a package manager that is a function (nothing is ever installed by a test). A fake MCP server (`test/helpers/fake-mcp-server.ts`) answers the MCP tests. The question on the terminal is the one thing the fake replaces whole, so `test/terminal.test.ts` runs the real one on streams of its own.
+
+### A new version of the contracts
+
+```bash
+npm update @widgetic/api-contracts     # the gateway's release put a new version on npm
+npm run generate && npm run snapshot && npm run docs
+npm run check                          # the diff of the snapshot and of docs/commands is the change
+```
+
+Commit the lock file, the snapshot and `docs/commands` together. To try a change of the gateway's description before it is published, build the contracts there (`npm run build-api-contracts`) and put them here with `npm run contracts:local -- <folder or tarball>`; it changes nothing but `node_modules`.
+
+### Release
+
+`npm run publish-to-npm` (the script of `Frontend/dev-tools`) merges what is on `origin`, runs `npm run check` and `npm run check:release`, raises the patch version, builds, publishes with `npm publish --ignore-scripts --access public`, commits the version, tags `v<version>` and pushes. A release is the owner's decision: nothing publishes by itself, and the `publish` job of the pipeline is manual.
+
+Before a release, copy `docs/commands/*.mdx` into the docs site (`Frontend/docs-site/docs/cli/commands/`) and list the pages in its `docs.json`.
+
+## Licence
+
+Widgetic Integration License: see `LICENSE`.

package/bin/widgetic.js

@@ -0,0 +1,5 @@
+#!/usr/bin/env node
+// The `widgetic` command. All of it is in dist/ (built from src/); this file only starts it.
+import { main } from '../dist/main.js';
+
+await main();

package/dist/cli.js

@@ -0,0 +1,106 @@
+import { Command, CommanderError } from 'commander';
+import { registerAuthCommands } from "./commands/auth.js";
+import { registerApiCall, registerMcpCall } from "./commands/call.js";
+import { registerCompletionCommands } from "./commands/completion.js";
+import { registerDoctorCommand } from "./commands/doctor.js";
+import { registerSchemaCommand } from "./commands/schema.js";
+import { registerUpdateCommand } from "./commands/update.js";
+import { CliError, EXIT_CODES, usageError } from "./errors.js";
+import { loadMcpManifest, loadRestManifest } from "./manifest/load.js";
+import { registerMcpCommands } from "./mcp/register.js";
+import { asCliError, printError } from "./output.js";
+import { registerRestCommands } from "./rest/register.js";
+import { cliVersion } from "./version.js";
+/**
+ * The program: the root `widgetic` command and what hangs from it. `run` parses an argument list against an
+ * Environment and returns the exit code; nothing here calls `process.exit`, so a test runs the real program in-process.
+ */
+/**
+ * Commander codes that mean "nothing went wrong, the text was printed": --help, --version, and the help of a command
+ * that was run without its subcommand (`widgetic api` lists what is under `api`, it is not a failure).
+ */
+const CLEAN_COMMANDER_CODES = new Set(['commander.helpDisplayed', 'commander.version', 'commander.help']);
+export function createRootCommand(environment) {
+    const root = new Command('widgetic');
+    root
+        .description('The Widgetic command line: the public REST API and the AI build tools, in one binary.')
+        .version(cliVersion(), '-V, --version', 'print the version of this CLI')
+        // A subcommand has its own options (a tool may have a `--version` of its own), so the root's are read only
+        // before the subcommand: `widgetic mcp publish-widget --version 3` is the tool's flag, never the CLI's.
+        .enablePositionalOptions()
+        .allowExcessArguments(false)
+        .showSuggestionAfterError(true)
+        .exitOverride()
+        .configureOutput({
+        writeOut: (text) => environment.stdout.write(text),
+        // Commander writes to this stream only to show the help of a command that was run without its subcommand
+        // (`widgetic api`). That is a question ("what can I do here?"), and its answer belongs on stdout.
+        writeErr: (text) => environment.stdout.write(text),
+        // Commander's own error line is not printed: `run` prints every error itself, the same way, so that
+        // `--json` gets JSON for a flag that is missing as well as for a server that refused.
+        outputError: () => { }
+    });
+    return root;
+}
+/**
+ * The namespace the arguments are about (`api` or `mcp`), when they are about one: the first word, or the one after
+ * `help`. Only that namespace's commands are built, so `widgetic mcp …` never reads the 500 KB REST manifest.
+ */
+export function namespaceOf(argv) {
+    const words = argv.filter((word) => !word.startsWith('-'));
+    const first = words[0] === 'help' ? words[1] : words[0];
+    return first === 'api' || first === 'mcp' ? first : undefined;
+}
+/**
+ * The whole program for `argv`. The namespaces are listed in the help of `widgetic` itself, and their commands are
+ * added only for the one the arguments name; the commands that are not generated (`auth`, `doctor`, `update`,
+ * `schema`, `completion`) are always there.
+ */
+export function buildProgram(environment, argv = []) {
+    const root = createRootCommand(environment);
+    const api = root
+        .command('api')
+        .description('Call the public REST API: one command for every operation of its OpenAPI description.');
+    const mcp = root
+        .command('mcp')
+        .description('Run the AI build tools of the Widgetic MCP server: one command for every tool.');
+    const namespace = namespaceOf(argv);
+    if (namespace === 'api') {
+        const manifest = loadRestManifest();
+        registerRestCommands(api, manifest, environment);
+        registerApiCall(api, manifest);
+    }
+    if (namespace === 'mcp') {
+        const manifest = loadMcpManifest();
+        registerMcpCommands(mcp, manifest, environment);
+        registerMcpCall(mcp, manifest, { environment, manifest });
+    }
+    registerAuthCommands(root, environment);
+    registerDoctorCommand(root, environment);
+    registerUpdateCommand(root, environment);
+    registerSchemaCommand(root, environment);
+    registerCompletionCommands(root, environment, (words) => buildProgram(environment, words));
+    return root;
+}
+/** What a Commander error becomes: `null` when it only means "the help or the version was printed". */
+function fromCommanderError(error) {
+    if (CLEAN_COMMANDER_CODES.has(error.code))
+        return null;
+    const message = error.message.replace(/^error:\s*/i, '');
+    return usageError(message, 'Run the command with --help to see what it takes.');
+}
+export async function run(argv, environment) {
+    const json = argv.includes('--json');
+    try {
+        const program = buildProgram(environment, argv);
+        await program.parseAsync([...argv], { from: 'user' });
+        return EXIT_CODES.ok;
+    }
+    catch (error) {
+        const failure = error instanceof CommanderError ? fromCommanderError(error) : asCliError(error, environment);
+        if (failure === null)
+            return EXIT_CODES.ok;
+        printError(environment, failure, json);
+        return failure.exitCode;
+    }
+}