@platless/axom-cli 0.1.0

package/README.md

@@ -0,0 +1,64 @@
+# @platless/axom-cli
+
+One npm package, one bin: `axom`. An authenticated MCP client for Axomwork (`struct`/`record`/`execute`/`guide`), plus the personal Workstation daemon — registration, encrypted tunnels, self-update, and OS service lifecycle — merged into the same package.
+
+## Install
+
+Install the build your Axomwork server publishes, so the CLI and the server always agree on the wire
+format:
+
+```sh
+npm install -g http://<your-axom-server>/download/client/axom-cli-<version>.tgz
+```
+
+The exact filename is in the manifest the server publishes:
+
+```sh
+curl -s http://<your-axom-server>/download/client/manifest.json
+```
+
+A plain `-g` install on purpose: it puts `axom` on your `PATH` the way npm puts every other global
+binary there. Do **not** add `--prefix` — the CLI's own self-update runs the same `npm install
+--global`, and a private prefix leaves the binary somewhere no shell looks.
+
+Verify before going further — this is the step that catches a broken install:
+
+```sh
+axom --version
+```
+
+## Quickstart
+
+```sh
+axom auth --server http://localhost:8080
+axom whoami
+
+axom struct list app
+axom struct get model demo/Article
+
+axom record query demo/Article '{"filters":[{"op":"eq","field":"status","value":"active"}],"page":{"number":1,"size":20}}'
+axom record create demo/Article '{"title":"Hello"}'
+
+axom execute demo/Article/publish '{"id":"rec-1"}'
+axom execute healthCheck '{}'
+```
+
+## Skills
+
+`axom skills add [--claude] [--project]` installs the bundled `axom`/`axom-definition`/`axom-platform` skills. By default it writes them to `.agents/skills/` in the current directory — the convention Codex, Cursor, OpenCode, Pi and others already read on their own. With `--claude` it installs the full plugin through Claude Code's plugin marketplace instead. `axom skills remove` reverses either path.
+
+## Workstation
+
+`axom workstation start` registers this machine (reusing the `axom auth` login) and installs/starts the daemon as an OS service; `stop`/`restart`/`status` control or query it; `install`/`uninstall` manage just the service definition (launchd/systemd) for manual repair.
+
+## Updating
+
+`axom update [--version x.y.z]` upgrades `axom` itself to the release the connected server currently publishes. It only installs the new package and prints a hint — it does not restart the workstation daemon (that would kill every active agent session on the machine), so run `axom workstation restart` afterward to apply it.
+
+## Config
+
+Non-secret CLI auth state is stored in `~/.axom/config.json` with mode `0600`. The file keeps one `defaultServer` and a `servers` map whose authenticated entries contain only `{ "authenticated": true }`; that value is a marker, not a credential. The refresh token is stored in the operating system's credential store (isolated behind the credential broker on macOS), while the access token and its expiry stay only in the credential process's in-memory cache. Config entries containing the obsolete `clientId`, `accessToken`, `refreshToken`, or `expiresAt` fields are rejected and must be removed before running `axom auth` again. Use `--server <url>` to override the default server for any command.
+
+## Learn more
+
+This README is a front page, not the manual. For the full command reference (arguments, exit codes, examples) and architecture notes, see `docs/modules/cli.md` and `guide/en/agent-integration/axom-cli/` in the Axomwork monorepo this package is built from.

package/dist/args.js

@@ -0,0 +1,29 @@
+import { UsageError } from './config.js';
+export function splitPath(input, segments, usage) {
+    const parts = input.split('/');
+    if (parts.length !== segments || parts.some((part) => part.length === 0)) {
+        throw new UsageError(`Expected ${usage}, got "${input}"`);
+    }
+    return parts;
+}
+export function splitPathFlexible(input, usage) {
+    const parts = input.split('/');
+    if (parts.length < 1 || parts.length > 3 || parts.some((part) => part.length === 0)) {
+        throw new UsageError(`Expected ${usage}, got "${input}"`);
+    }
+    return parts;
+}
+export function parseJsonArg(input, what, example) {
+    if (input === undefined)
+        return {};
+    try {
+        const parsed = JSON.parse(input);
+        if (!parsed || typeof parsed !== 'object' || Array.isArray(parsed)) {
+            throw new Error('Expected a JSON object');
+        }
+        return parsed;
+    }
+    catch {
+        throw new UsageError(`Invalid JSON for ${what}. Example: ${example}`);
+    }
+}

package/dist/cli.js

@@ -0,0 +1,76 @@
+#!/usr/bin/env node
+import { Command } from 'commander';
+import { realpathSync } from 'node:fs';
+import { fileURLToPath, pathToFileURL } from 'node:url';
+import { authAction, logoutAction } from './commands/auth.js';
+import { registerExecuteCommand } from './commands/execute.js';
+import { registerGuideCommands } from './commands/guide.js';
+import { registerRecordCommands } from './commands/record.js';
+import { registerSkillsCommands } from './commands/skills.js';
+import { registerStructCommands } from './commands/struct.js';
+import { registerUpdateCommand } from './commands/update.js';
+import { registerWorkstationCommands } from './commands/workstation.js';
+import { whoamiAction } from './commands/whoami.js';
+import { runCredentialBroker } from './credentials.js';
+import { runCommand } from './output.js';
+import { install, restart, start, status, stop, uninstall } from './workstation/daemonctl.js';
+import { runDaemon } from './workstation/daemon.js';
+import { registerWorkstation } from './workstation/register.js';
+import { detectSupervision } from './workstation/supervision.js';
+import { CLIENT_VERSION } from './workstation/version.js';
+export function buildProgram() {
+    const program = new Command().name('axom').version(CLIENT_VERSION).option('--server <url>', 'Axomwork server URL');
+    const serverOption = () => program.opts().server;
+    program
+        .command('auth')
+        .description('Authorize axom-cli with an Axomwork server')
+        .option('--server <url>', 'Axomwork server URL')
+        .action((options) => runCommand(() => authAction({ server: options.server ?? serverOption() })));
+    program
+        .command('whoami')
+        .description('Print the authenticated Axomwork user')
+        .action(() => runCommand(() => whoamiAction({ server: serverOption() })));
+    program
+        .command('logout')
+        .description('Revoke and remove axom-cli credentials for an Axomwork server')
+        .option('--server <url>', 'Axomwork server URL')
+        .action((options) => runCommand(() => logoutAction({ server: options.server ?? serverOption() })));
+    program
+        .command('__credential-broker', { hidden: true })
+        .action(() => runCredentialBroker());
+    registerStructCommands(program);
+    registerRecordCommands(program);
+    registerExecuteCommand(program);
+    registerGuideCommands(program);
+    registerSkillsCommands(program);
+    registerUpdateCommand(program);
+    registerWorkstationCommands(program, {
+        start, stop, restart, install, uninstall, runDaemon, registerWorkstation,
+        status: async () => {
+            const current = await status();
+            return current.running
+                ? `running connected to ${current.server ?? 'unknown server'} as ${current.workstationId ?? 'unknown workstation'}`
+                : 'stopped';
+        },
+        log: console.log,
+        authenticate: (server) => authAction({ server }),
+        detectSupervision,
+        isInteractive: () => Boolean(process.stdin.isTTY),
+    });
+    return program;
+}
+export function isMainModule(argv1) {
+    if (!argv1)
+        return false;
+    try {
+        // A `.bin` entry is usually a symlink; compare the resolved target.
+        return realpathSync(argv1) === fileURLToPath(import.meta.url);
+    }
+    catch {
+        // argv[1] does not exist on disk (or is not resolvable) — fall back to comparing URLs.
+        return import.meta.url === pathToFileURL(argv1).href;
+    }
+}
+if (isMainModule(process.argv[1])) {
+    await buildProgram().parseAsync();
+}

package/dist/commands/auth.js

@@ -0,0 +1,52 @@
+import { hostname } from 'node:os';
+import { loadConfig, resolveServer, saveConfig } from '../config.js';
+import { callAxomTool } from '../mcp.js';
+import { authorizeDevice } from '../workstation/oauth/deviceAuthorization.js';
+import { revokeAndClearTokens, saveTokens } from '../credentials.js';
+export const DEFAULT_SERVER_URL = 'http://localhost:8080';
+export async function authAction(options, deps = {}) {
+    const config = await loadConfig();
+    const server = resolveServer(config, options.server ?? config.defaultServer ?? DEFAULT_SERVER_URL);
+    const host = hostname();
+    const { accessToken, refreshToken, expiresInSeconds } = await authorizeDevice(server, `Axomwork CLI (${host})`, host, deps);
+    const updated = await loadConfig();
+    try {
+        await saveTokens(server, { accessToken, refreshToken, expiresAt: new Date(Date.now() + expiresInSeconds * 1000).toISOString() });
+    }
+    catch (error) {
+        await revokeRefreshToken(server, refreshToken);
+        throw error;
+    }
+    updated.servers[server] = { authenticated: true };
+    if (!updated.defaultServer) {
+        updated.defaultServer = server;
+    }
+    await saveConfig(updated);
+    const outcome = await callAxomTool(server, 'axom__system__whoami', {});
+    if (outcome.isError) {
+        throw new Error(outcome.text);
+    }
+    console.log(`Logged in as ${outcome.text}`);
+}
+export async function logoutAction(options) {
+    const config = await loadConfig();
+    const server = resolveServer(config, options.server ?? config.defaultServer ?? DEFAULT_SERVER_URL);
+    await revokeAndClearTokens(server);
+    delete config.servers[server];
+    if (config.defaultServer === server) {
+        config.defaultServer = Object.keys(config.servers)[0];
+    }
+    await saveConfig(config);
+    console.log(`Logged out from ${server}`);
+}
+async function revokeRefreshToken(server, refreshToken) {
+    await fetch(`${server}/oauth/revoke`, {
+        method: 'POST',
+        headers: { 'content-type': 'application/x-www-form-urlencoded' },
+        body: new URLSearchParams({
+            token: refreshToken,
+            token_type_hint: 'refresh_token',
+            client_id: 'axom-cli',
+        }),
+    }).catch(() => undefined);
+}

package/dist/commands/execute.js

@@ -0,0 +1,40 @@
+import { parseJsonArg, splitPathFlexible } from '../args.js';
+import { loadConfig, resolveServer } from '../config.js';
+import { callAxomTool } from '../mcp.js';
+import { printOutcome, runCommand } from '../output.js';
+const executeUsage = '<app>/<model>/<operation> | [<app>/]<serviceName>';
+const executeExample = '{"id":"rec-1"}';
+export function registerExecuteCommand(program) {
+    const serverOption = () => program.opts().server;
+    program
+        .command('execute')
+        .description('Execute an Axomwork operation or service')
+        .argument('<path>', executeUsage)
+        .argument('[json]')
+        .action((path, json) => runCommand(() => executeAction({ path, json, server: serverOption() })));
+}
+export async function executeAction(options) {
+    const server = resolveServer(await loadConfig(), options.server);
+    const parts = splitPathFlexible(options.path, executeUsage);
+    const input = parseJsonArg(options.json, 'execute input', executeExample);
+    if (parts.length === 3) {
+        const [applicationName, modelName, operationName] = parts;
+        printOutcome(
+        // 同步是 axom__*__execute 的固有语义；awaitResult 参数已随 InvocationMode 重构移除，
+        // 继续传会被工具的封闭 inputSchema 直接拒掉。
+        await callAxomTool(server, 'axom__operation__execute', {
+            applicationName,
+            modelName,
+            operationName,
+            input,
+        }));
+        return;
+    }
+    if (parts.length === 2) {
+        const [applicationName, serviceName] = parts;
+        printOutcome(await callAxomTool(server, 'axom__service__execute', { applicationName, serviceName, input }));
+        return;
+    }
+    const [serviceName] = parts;
+    printOutcome(await callAxomTool(server, 'axom__service__execute', { serviceName, input }));
+}

package/dist/commands/guide.js

@@ -0,0 +1,38 @@
+import { loadConfig, resolveServer } from '../config.js';
+import { callAxomTool } from '../mcp.js';
+import { printOutcome, runCommand } from '../output.js';
+export function registerGuideCommands(program) {
+    const guide = program.command('guide').description('Read and search the Axomwork Guide');
+    const serverOption = () => program.opts().server;
+    guide
+        .command('load')
+        .description('Load a guide page, or the table of contents when no path is given')
+        .argument('[path]', 'guide page path, e.g. script-language/sdk/records')
+        .option('--locale <locale>', 'guide locale (en|zh)')
+        .action((path, options) => runCommand(() => guideLoadAction({ path, locale: options.locale, server: serverOption() })));
+    guide
+        .command('search')
+        .description('Search the guide with keywords or a question')
+        .argument('<query>')
+        .option('--locale <locale>', 'guide locale (en|zh)')
+        .option('--limit <n>', 'maximum hits')
+        .action((query, options) => runCommand(() => guideSearchAction({ query, locale: options.locale, limit: options.limit, server: serverOption() })));
+}
+export async function guideLoadAction(options) {
+    const server = resolveServer(await loadConfig(), options.server);
+    const args = {};
+    if (options.path !== undefined)
+        args.path = options.path;
+    if (options.locale !== undefined)
+        args.locale = options.locale;
+    printOutcome(await callAxomTool(server, 'axom__guide__load', args));
+}
+export async function guideSearchAction(options) {
+    const server = resolveServer(await loadConfig(), options.server);
+    const args = { query: options.query };
+    if (options.locale !== undefined)
+        args.locale = options.locale;
+    if (options.limit !== undefined)
+        args.limit = Number(options.limit);
+    printOutcome(await callAxomTool(server, 'axom__guide__search', args));
+}

package/dist/commands/record.js

@@ -0,0 +1,99 @@
+import { parseJsonArg, splitPath } from '../args.js';
+import { UsageError, loadConfig, resolveServer } from '../config.js';
+import { callAxomTool } from '../mcp.js';
+import { printOutcome, runCommand } from '../output.js';
+const recordExample = '{"title":"Hello"}';
+const queryExample = '{"filters":[{"op":"eq","field":"status","value":"active"}],"page":{"number":1,"size":20}}';
+const queryKeys = ['filters', 'sorts', 'page'];
+export function registerRecordCommands(program) {
+    const record = program.command('record').description('Read and mutate Axomwork records');
+    const serverOption = () => program.opts().server;
+    record
+        .command('get')
+        .argument('<path>', '<app>/<model>')
+        .argument('<recordId>')
+        .action((path, id) => runCommand(() => recordGetAction({ path, id, server: serverOption() })));
+    record
+        .command('create')
+        .argument('<path>', '<app>/<model>')
+        .argument('<json>')
+        .action((path, json) => runCommand(() => recordCreateAction({ path, json, server: serverOption() })));
+    record
+        .command('update')
+        .argument('<path>', '<app>/<model>')
+        .argument('<recordId>')
+        .argument('<json>')
+        .action((path, id, json) => runCommand(() => recordUpdateAction({ path, id, json, server: serverOption() })));
+    record
+        .command('upsert')
+        .argument('<application>')
+        .argument('<model>')
+        .requiredOption('--identity-field <field>', 'Field used to match an existing record')
+        .requiredOption('--record <json>', 'JSON record payload')
+        .action((applicationName, modelName, options) => runCommand(() => recordUpsertAction({ ...options, applicationName, modelName, server: serverOption() })));
+    record
+        .command('delete')
+        .argument('<path>', '<app>/<model>')
+        .argument('<recordId>')
+        .action((path, id) => runCommand(() => recordDeleteAction({ path, id, server: serverOption() })));
+    record
+        .command('query')
+        .argument('<path>', '<app>/<model>')
+        .argument('[criteriaJson]')
+        .action((path, json) => runCommand(() => recordQueryAction({ path, json, server: serverOption() })));
+}
+export async function recordGetAction(options) {
+    const server = await resolveActionServer(options.server);
+    const [applicationName, modelName] = splitPath(options.path, 2, '<app>/<model>');
+    printOutcome(await callAxomTool(server, 'axom__record__get', { applicationName, modelName, id: options.id }));
+}
+export async function recordCreateAction(options) {
+    const server = await resolveActionServer(options.server);
+    const [applicationName, modelName] = splitPath(options.path, 2, '<app>/<model>');
+    const record = parseJsonArg(options.json, 'record', recordExample);
+    printOutcome(await callAxomTool(server, 'axom__record__create', { applicationName, modelName, record }));
+}
+export async function recordUpdateAction(options) {
+    const server = await resolveActionServer(options.server);
+    const [applicationName, modelName] = splitPath(options.path, 2, '<app>/<model>');
+    const changes = parseJsonArg(options.json, 'record update changes', recordExample);
+    printOutcome(await callAxomTool(server, 'axom__record__update', { applicationName, modelName, id: options.id, changes }));
+}
+export async function recordUpsertAction(options) {
+    const server = await resolveActionServer(options.server);
+    const record = parseJsonArg(options.record, 'record', recordExample);
+    printOutcome(await callAxomTool(server, 'axom__record__upsert', {
+        applicationName: options.applicationName,
+        modelName: options.modelName,
+        identityField: options.identityField,
+        record,
+    }));
+}
+export async function recordDeleteAction(options) {
+    const server = await resolveActionServer(options.server);
+    const [applicationName, modelName] = splitPath(options.path, 2, '<app>/<model>');
+    printOutcome(await callAxomTool(server, 'axom__record__delete', { applicationName, modelName, id: options.id }));
+}
+export async function recordQueryAction(options) {
+    const server = await resolveActionServer(options.server);
+    const [applicationName, modelName] = splitPath(options.path, 2, '<app>/<model>');
+    const criteria = parseJsonArg(options.json, 'record query criteria', queryExample);
+    const invalidKeys = Object.keys(criteria).filter((key) => !queryKeys.includes(key));
+    if (invalidKeys.length > 0) {
+        throw new UsageError(`Invalid record query criteria keys: ${invalidKeys.join(', ')}. Valid keys: filters, sorts, page. Example: ${queryExample}`);
+    }
+    const args = { applicationName, modelName };
+    const queryCriteria = {};
+    for (const key of ['filters', 'sorts']) {
+        if (key in criteria)
+            queryCriteria[key] = criteria[key];
+    }
+    if (Object.keys(queryCriteria).length > 0)
+        args.criteria = queryCriteria;
+    if ('page' in criteria)
+        args.page = criteria.page;
+    printOutcome(await callAxomTool(server, 'axom__record__query', args));
+}
+async function resolveActionServer(server) {
+    return resolveServer(await loadConfig(), server);
+}

package/dist/commands/skills.js

@@ -0,0 +1,69 @@
+import { UsageError, loadConfig, resolveServer } from '../config.js';
+import { materializeAgentsSkills, removeAgentsSkills } from '../install/agentsDir.js';
+import { installAgent, skillsSourceDir, uninstallAgent } from '../install/installer.js';
+import { runCommand } from '../output.js';
+/**
+ * `axom skills add|remove`: materializes the bundled skills into `.agents/skills/` under the
+ * current directory — the convention Codex, Cursor, OpenCode, Pi and others already read, no
+ * per-agent code needed. `--claude` is the one exception, since Claude Code reads skills through
+ * its own plugin/marketplace mechanism instead; that path delegates to the existing
+ * `installAgent`/`uninstallAgent('claude', ...)`.
+ *
+ * `--project` only means something on the `--claude` path (Claude's user-wide-vs-project
+ * registration switch). The default `.agents/skills` path always writes under the current
+ * working directory, so `--project` there is meaningless and is rejected rather than ignored.
+ */
+export function registerSkillsCommands(program) {
+    const serverOption = () => program.opts().server;
+    const skills = program.command('skills').description('Materialize Axomwork skills for AI coding agents');
+    skills
+        .command('add')
+        .description('Add Axomwork skills to .agents/skills in the current directory (or --claude for Claude Code)')
+        .option('--claude', 'install the Claude Code plugin instead of writing .agents/skills')
+        .option('--project', 'Claude Code only: register for the current project instead of user-wide')
+        .action((options) => runCommand(async () => {
+        if (options.claude) {
+            const server = resolveServer(await loadConfig(), serverOption());
+            const report = await installAgent('claude', {
+                serverUrl: server,
+                scope: options.project ? 'project' : 'user',
+            });
+            console.log(`target: ${report.target}`);
+            for (const file of report.installedFiles)
+                console.log(`installed: ${file}`);
+            console.log(report.mcpRegistration);
+            return;
+        }
+        rejectProjectWithoutClaude(options);
+        const { files } = await materializeAgentsSkills(skillsSourceDir(), process.cwd());
+        for (const file of files)
+            console.log(`installed: ${file}`);
+    }));
+    skills
+        .command('remove')
+        .description('Remove Axomwork skills from .agents/skills in the current directory (or --claude for Claude Code)')
+        .option('--claude', 'remove the Claude Code plugin instead of .agents/skills')
+        .option('--project', 'Claude Code only: matches the scope used with `add --project`')
+        .action((options) => runCommand(async () => {
+        if (options.claude) {
+            const report = await uninstallAgent('claude', {
+                serverUrl: '',
+                scope: options.project ? 'project' : 'user',
+            });
+            console.log(`target: ${report.target}`);
+            for (const file of report.removed)
+                console.log(`removed: ${file}`);
+            console.log(report.notes);
+            return;
+        }
+        rejectProjectWithoutClaude(options);
+        const { removed } = await removeAgentsSkills(process.cwd());
+        for (const file of removed)
+            console.log(`removed: ${file}`);
+    }));
+}
+function rejectProjectWithoutClaude(options) {
+    if (options.project) {
+        throw new UsageError('--project is only meaningful with --claude; the default .agents/skills path always writes to the current directory.');
+    }
+}

package/dist/commands/struct.js

@@ -0,0 +1,50 @@
+import { splitPath } from '../args.js';
+import { UsageError, loadConfig, resolveServer } from '../config.js';
+import { callAxomTool } from '../mcp.js';
+import { printOutcome, runCommand } from '../output.js';
+export function registerStructCommands(program) {
+    const struct = program.command('struct').description('Inspect Axomwork app and model structure');
+    const serverOption = () => program.opts().server;
+    struct
+        .command('list')
+        .argument('<kind>', 'app|model')
+        .argument('[target]', 'app name for model listing')
+        .action((kind, target) => runCommand(() => structListAction({ kind, target, server: serverOption() })));
+    struct
+        .command('get')
+        .argument('<kind>', 'app|model')
+        .argument('<target>', 'app name or app/model path')
+        .action((kind, target) => runCommand(() => structGetAction({ kind, target, server: serverOption() })));
+}
+export async function structListAction(options) {
+    const server = await resolveActionServer(options.server);
+    const kind = requireStructKind(options.kind);
+    if (kind === 'app') {
+        if (options.target !== undefined) {
+            throw new UsageError('Expected axom struct list app with no target.');
+        }
+        printOutcome(await callAxomTool(server, 'axom__struct__list_applications', {}));
+        return;
+    }
+    const [applicationName] = splitPath(options.target ?? '', 1, '<applicationName>');
+    printOutcome(await callAxomTool(server, 'axom__struct__list_models', { applicationName }));
+}
+export async function structGetAction(options) {
+    const server = await resolveActionServer(options.server);
+    const kind = requireStructKind(options.kind);
+    if (kind === 'app') {
+        const [applicationName] = splitPath(options.target ?? '', 1, '<applicationName>');
+        printOutcome(await callAxomTool(server, 'axom__struct__get_application', { applicationName }));
+        return;
+    }
+    const [applicationName, modelName] = splitPath(options.target ?? '', 2, '<applicationName>/<modelName>');
+    printOutcome(await callAxomTool(server, 'axom__struct__get_model', { applicationName, modelName }));
+}
+async function resolveActionServer(server) {
+    return resolveServer(await loadConfig(), server);
+}
+function requireStructKind(kind) {
+    if (kind === 'app' || kind === 'model')
+        return kind;
+    throw new UsageError(`Unknown struct kind "${kind}". Valid values: app|model`);
+}

package/dist/commands/update.js

@@ -0,0 +1,88 @@
+import { randomUUID } from 'node:crypto';
+import { UsageError, loadConfig, resolveServer } from '../config.js';
+import { runCommand } from '../output.js';
+import { clientDir } from '../workstation/config.js';
+import { CLI_PATH } from '../workstation/daemonctl.js';
+import { createUpdateCoordinator } from '../workstation/update/runUpdate.js';
+function isManifest(value) {
+    return typeof value === 'object' && value !== null
+        && typeof value.version === 'string'
+        && typeof value.url === 'string'
+        && typeof value.size === 'number'
+        && typeof value.sha512 === 'string';
+}
+/** Fetches the release the server currently publishes for this exact deployment. */
+async function fetchManifest(server, fetchImpl) {
+    const url = new URL('/download/client/manifest.json', server).toString();
+    const response = await fetchImpl(url);
+    if (!response.ok) {
+        throw new Error(`Fetching the release manifest failed with HTTP ${response.status}`);
+    }
+    const parsed = await response.json();
+    if (!isManifest(parsed)) {
+        throw new Error('Release manifest is malformed');
+    }
+    return parsed;
+}
+function defaultCoordinator(dir, server) {
+    return createUpdateCoordinator({
+        dir, server,
+        // `CLI_PATH` is resolved once, from daemonctl.js's own compiled location — not re-derived here
+        // from this module's own URL. See CLI_PATH's doc in daemonctl.ts for why that would be the
+        // wrong thing to do even though, at update.js's current depth under dist/, it would happen to
+        // produce the right answer.
+        cliPath: CLI_PATH,
+        // A one-shot CLI invocation with no supervisor and, on a CLI-only machine, no daemon to
+        // restart into: it must not provision the OS service or arm the rollback watchdog. See
+        // UpdateCoordinatorDeps.serviceLifecycle in runUpdate.ts for why.
+        serviceLifecycle: 'none',
+    });
+}
+/**
+ * `axom update [--version x.y.z]`: pulls the release manifest the configured server currently
+ * publishes and runs it through the exact same `UpdateCoordinator` a server-triggered update uses
+ * (see runUpdate.ts) — there is no second update implementation for the manual path.
+ */
+export async function updateAction(options, deps = {}) {
+    const config = await loadConfig();
+    const server = resolveServer(config, options.server ?? config.defaultServer);
+    const fetchImpl = deps.fetch ?? globalThis.fetch;
+    const manifest = await fetchManifest(server, fetchImpl);
+    if (options.version && options.version !== manifest.version) {
+        throw new UsageError(`Requested version ${options.version} does not match the server's published release ${manifest.version}.`);
+    }
+    const release = {
+        version: manifest.version, url: manifest.url, size: manifest.size, sha512: manifest.sha512,
+    };
+    const dir = deps.dir ?? clientDir();
+    const coordinator = deps.createCoordinator ? deps.createCoordinator({ dir, server }) : defaultCoordinator(dir, server);
+    const command = { commandId: `manual-${randomUUID()}`, release, force: false };
+    const status = await coordinator.handle(command);
+    const log = deps.log ?? console.log;
+    // 'RESTARTING' and 'BUSY' are not handled as separate cases: neither is reachable from
+    // `defaultCoordinator`. 'RESTARTING' is the phase of an update that hands off by exiting, and
+    // `serviceLifecycle: 'none'` above is exactly the lifecycle that has nothing to hand off to —
+    // the coordinator ends such an update at 'SUCCEEDED' instead (see the `restart`-less branch in
+    // UpdateCoordinator.execute), which is why the successful case below is that phase and why this
+    // command, not the coordinator, is what tells the operator a restart is still owed. 'BUSY' would
+    // require `TaskRegistry.canUpdate()` to return false, but the manual path always hands the
+    // coordinator a fresh, empty, in-process `TaskRegistry` (there is nothing else in this process
+    // that could be running a task), so it is always true. Keeping dedicated cases for phases the
+    // real assembly can never produce is exactly the untestable-branch shape this command was
+    // flagged for; if a future caller makes either reachable, restore its case then.
+    switch (status.phase) {
+        case 'SUCCEEDED':
+            log(`Installed ${release.version}. Run \`axom workstation restart\` to apply it.`);
+            return;
+        default:
+            throw new Error(status.error ?? `Update did not complete (phase: ${status.phase}).`);
+    }
+}
+export function registerUpdateCommand(program) {
+    const serverOption = () => program.opts().server;
+    program
+        .command('update')
+        .description('Update axom-cli to the release the configured server currently publishes')
+        .option('--version <version>', 'Fail unless the server-published release matches this exact version')
+        .action((options) => runCommand(() => updateAction({ server: serverOption(), version: options.version })));
+}

package/dist/commands/whoami.js

@@ -0,0 +1,8 @@
+import { loadConfig, resolveServer } from '../config.js';
+import { callAxomTool } from '../mcp.js';
+import { printOutcome } from '../output.js';
+export async function whoamiAction(options) {
+    const config = await loadConfig();
+    const server = resolveServer(config, options.server);
+    printOutcome(await callAxomTool(server, 'axom__system__whoami', {}));
+}