@substrio/cli 0.0.0-stage → 0.1.0

package/src/commands/skills.mjs

@@ -0,0 +1,177 @@
+/**
+ * Substrio CLI: `substrio skills list | show NAME | install [NAME...] [--for
+ * claude|cursor|codex|agents-md|all] [--dir DIR]`.
+ *
+ * Reads the server's agent skills (documentation.skill.list/get: the same
+ * skills served at `substrio://skills/<name>` over MCP and `GET
+ * /v1/_docs/skills`) and, for install, writes them where each client reads
+ * its own skills/rules from.
+ */
+
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
+import { dirname, join } from 'node:path';
+
+import { CliError, ErrorCode, emit, fail } from '../cli.mjs';
+import { FlagKind, parseFlags } from '../local/args.mjs';
+import { invokeOperation } from './op.mjs';
+
+const C = { reset: '\x1b[0m', bold: '\x1b[1m', dim: '\x1b[2m', green: '\x1b[92m' };
+
+const USAGE = 'substrio skills list | show NAME | install [NAME...] [--for claude|cursor|codex|agents-md|all] [--dir DIR]';
+
+/** Where `skills install` can write a skill (pure data). */
+export const SkillTarget = Object.freeze({
+    CLAUDE: 'claude', CURSOR: 'cursor', CODEX: 'codex', AGENTS_MD: 'agents-md', ALL: 'all',
+});
+const INSTALL_TARGETS = [SkillTarget.CLAUDE, SkillTarget.CURSOR, SkillTarget.CODEX, SkillTarget.AGENTS_MD];
+
+export const AGENTS_MD_BEGIN = '<!-- substrio:skills:begin -->';
+export const AGENTS_MD_END = '<!-- substrio:skills:end -->';
+
+function showSkillList({ skills = [] }) {
+    if (!skills.length) { console.log(`${C.dim}No skills.${C.reset}`); return; }
+    for (const s of skills) console.log(`${C.bold}${s.name}${C.reset}${C.dim} - ${s.title}${C.reset}\n  ${s.description}`);
+}
+
+/** A skill's frontmatter ({name, description, ...}) and body, after the closing `---` (pure). Throws when there is none. */
+export function splitFrontmatter(markdown) {
+    const m = /^---\n([\s\S]*?)\n---\n?([\s\S]*)$/.exec(markdown);
+    if (!m) throw new CliError('Skill markdown has no --- frontmatter', { code: ErrorCode.UNKNOWN });
+    const frontmatter = {};
+    for (const line of m[1].split('\n')) {
+        const i = line.indexOf(':');
+        if (i < 0) continue;
+        frontmatter[line.slice(0, i).trim()] = line.slice(i + 1).trim();
+    }
+    return { frontmatter, body: m[2] };
+}
+
+/** The .cursor/rules/substrio-<name>.mdc text for one skill (pure): its own description, alwaysApply false, then the body. */
+export function cursorRuleOf(description, body) {
+    return `---\ndescription: ${description}\nalwaysApply: false\n---\n${body}`;
+}
+
+/** One skill's AGENTS.md section (pure), without the markers (agentsMdBlockOf wraps the joined sections once). */
+export function agentsMdSectionOf(name, markdown) {
+    return `## Skill: ${name}\n\n${markdown.trim()}\n`;
+}
+
+/** The whole marked block `agentsMdOf` writes, every skill's section joined (pure). */
+function agentsMdBlockOf(skills) {
+    return `${AGENTS_MD_BEGIN}\n${skills.map((s) => agentsMdSectionOf(s.name, s.markdown)).join('\n')}${AGENTS_MD_END}\n`;
+}
+
+/**
+ * `path`'s text with the substrio skills block set to `block` (pure but for
+ * the read): replaces an existing begin/end section in place, keeping
+ * everything outside it; appends the block (after a blank line) when there
+ * is none yet.
+ */
+export function withAgentsMdBlock(existing, block) {
+    const start = existing.indexOf(AGENTS_MD_BEGIN);
+    const end = existing.indexOf(AGENTS_MD_END);
+    if (start >= 0 && end > start) {
+        return `${existing.slice(0, start)}${block}${existing.slice(end + AGENTS_MD_END.length).replace(/^\n/, '')}`;
+    }
+    return `${existing}${existing && !existing.endsWith('\n\n') ? (existing.endsWith('\n') ? '\n' : '\n\n') : ''}${block}`;
+}
+
+function writeFileEnsured(path, text) {
+    mkdirSync(dirname(path), { recursive: true });
+    writeFileSync(path, text);
+}
+
+function installClaude(dir, name, markdown) {
+    const path = join(dir, '.claude', 'skills', name, 'SKILL.md');
+    writeFileEnsured(path, markdown);
+    return path;
+}
+
+function installCursor(dir, name, markdown) {
+    const { frontmatter, body } = splitFrontmatter(markdown);
+    const path = join(dir, '.cursor', 'rules', `substrio-${name}.mdc`);
+    writeFileEnsured(path, cursorRuleOf(frontmatter.description ?? '', body));
+    return path;
+}
+
+function installAgentsMd(dir, skills) {
+    const path = join(dir, 'AGENTS.md');
+    const existing = existsSync(path) ? readFileSync(path, 'utf8') : '';
+    writeFileEnsured(path, withAgentsMdBlock(existing, agentsMdBlockOf(skills)));
+    return path;
+}
+
+/** The targets `--for` names, expanded and de-duplicated ("all" -> every target; codex and agents-md share one writer); pure. */
+export function targetsOf(forFlag) {
+    if (!forFlag || forFlag === SkillTarget.ALL) return INSTALL_TARGETS;
+    const names = forFlag.split(',').map((s) => s.trim());
+    for (const name of names) {
+        if (!INSTALL_TARGETS.includes(name)) {
+            throw new CliError(`unknown --for target "${name}"`, { code: ErrorCode.INVALID_ARGUMENT, hint: `one of ${INSTALL_TARGETS.join(', ')}, all` });
+        }
+    }
+    return names;
+}
+
+async function list(api) {
+    const data = await invokeOperation(api, 'documentation.skill.list', {});
+    emit(data, showSkillList);
+}
+
+async function show(api, name) {
+    if (!name) fail('Usage: substrio skills show NAME');
+    const data = await invokeOperation(api, 'documentation.skill.get', { name });
+    emit(data, (d) => console.log(d.markdown));
+}
+
+const INSTALL_FLAGS = Object.freeze({ '--for': FlagKind.VALUE, '--dir': FlagKind.VALUE });
+
+async function install(api, args) {
+    let flags;
+    let names;
+    try {
+        ({ flags, positional: names } = parseFlags(args, INSTALL_FLAGS));
+    } catch (err) {
+        return fail(err);
+    }
+    let targets;
+    try {
+        targets = targetsOf(flags.get('--for') ?? null);
+    } catch (err) {
+        return fail(err);
+    }
+    const dir = flags.get('--dir') ?? process.cwd();
+    if (!names.length) {
+        const { skills } = await invokeOperation(api, 'documentation.skill.list', {});
+        names = skills.map((s) => s.name);
+    }
+    const fetched = [];
+    for (const name of names) {
+        fetched.push(await invokeOperation(api, 'documentation.skill.get', { name }));
+    }
+    const written = [];
+    for (const skill of fetched) {
+        if (targets.includes(SkillTarget.CLAUDE)) written.push(installClaude(dir, skill.name, skill.markdown));
+        if (targets.includes(SkillTarget.CURSOR)) written.push(installCursor(dir, skill.name, skill.markdown));
+    }
+    if (targets.includes(SkillTarget.CODEX) || targets.includes(SkillTarget.AGENTS_MD)) {
+        written.push(installAgentsMd(dir, fetched));
+    }
+    emit({ installed: fetched.map((s) => s.name), written }, () => {
+        for (const path of written) console.log(`${C.green}✓${C.reset} ${path}`);
+    });
+}
+
+export async function cmdSkills(api, args) {
+    switch (args[0]) {
+        case 'list':
+        case undefined:
+            return list(api);
+        case 'show':
+            return show(api, args[1]);
+        case 'install':
+            return install(api, args.slice(1));
+        default:
+            return fail(`Usage: ${USAGE}`);
+    }
+}

package/src/commands/status.mjs

@@ -0,0 +1,78 @@
+/**
+ * Substrio CLI: `substrio status` (server health and config) and `substrio whoami`
+ * (config and where each value came from). Both print JSON under --json.
+ */
+
+import { errorText } from '../api.mjs';
+import { CliError, ErrorCode, emit, exitCodeFor } from '../cli.mjs';
+import { callOperation, loadOperations } from './op.mjs';
+import { getConfigSources, listProfiles } from '../config.mjs';
+
+const C = {
+    reset: '\x1b[0m', bold: '\x1b[1m', dim: '\x1b[2m',
+    red: '\x1b[91m', green: '\x1b[92m', cyan: '\x1b[96m',
+};
+
+// The resolved config as data. No part of the key is shown: terminals and
+// logs are not secret stores.
+function configView(config) {
+    const sources = getConfigSources();
+    return {
+        url: config.url || null, url_source: sources.url,
+        tenant: config.tenant, tenant_source: sources.tenant,
+        key_set: Boolean(config.master_key), key_length: config.master_key ? config.master_key.length : 0,
+        key_source: sources.master_key,
+        profile: config.profile || null,
+        functions_dir: config.functions_dir, public_dir: config.public_dir,
+    };
+}
+
+function printConfig(view) {
+    console.log(`  URL:        ${view.url || `${C.red}not set${C.reset}`} ${C.dim}(${view.url_source})${C.reset}`);
+    console.log(`  Tenant:     ${view.tenant} ${C.dim}(${view.tenant_source})${C.reset}`);
+    const keyState = view.key_set ? `set (${view.key_length} characters)` : `${C.red}not set${C.reset}`;
+    console.log(`  Key:        ${keyState} ${C.dim}(${view.key_source})${C.reset}`);
+    if (view.profile) console.log(`  Profile:    ${view.profile}`);
+}
+
+export async function cmdStatus(api, config) {
+    const server = { healthy: false, version: null, error: null };
+    // system.health; a failed call is the server's typed error, and the
+    // run's exit code is that error's (exitCodeFor).
+    let failure = null;
+    try {
+        const result = await callOperation(api, await loadOperations(api), 'system.health', undefined);
+        server.healthy = result.ok && result.data?.status === 'ok';
+        server.version = result.data?.version || null;
+        if (!result.ok) failure = CliError.fromResponse(errorText(result.data, result.status), result.data, result.status);
+    } catch (err) {
+        failure = err instanceof CliError ? err : new CliError(err.message, { code: ErrorCode.UNKNOWN });
+    }
+    if (failure) server.error = failure.toJSON();
+    emit({ server, config: configView(config) }, ({ server: s, config: view }) => {
+        console.log(`\n${C.bold}${C.cyan}Substrio Status${C.reset}\n`);
+        if (s.error) console.log(`  ${C.red}●${C.reset} Server: ${C.red}${s.healthy ? 'healthy' : 'unhealthy or unreachable'}${C.reset} (${s.error.error})`);
+        else console.log(`  ${s.healthy ? C.green : C.red}●${C.reset} Server: ${s.healthy ? `${C.green}healthy` : `${C.red}unhealthy`}${C.reset}`);
+        if (s.version) console.log(`  ${C.dim}Version:${C.reset} ${s.version}`);
+        console.log(`\n  ${C.bold}Configuration${C.reset}`);
+        printConfig(view);
+        console.log('');
+    });
+    // A script checks the server by the exit code: 0 only when it is healthy.
+    if (!server.healthy) process.exitCode = failure ? exitCodeFor(failure) : 1;
+}
+
+export function cmdWhoami(config) {
+    const view = { ...configView(config), profiles: listProfiles() };
+    emit(view, (v) => {
+        console.log(`\n${C.bold}${C.cyan}Substrio Whoami${C.reset}\n`);
+        printConfig(v);
+        console.log(`  Functions:  ${v.functions_dir}/`);
+        console.log(`  Public:     ${v.public_dir}/`);
+        if (v.profiles.length) {
+            console.log(`\n  ${C.bold}Saved Profiles:${C.reset}`);
+            for (const p of v.profiles) console.log(`    ${p.name}: ${p.url}${p.isDefault ? ` ${C.green}(default)${C.reset}` : ''}`);
+        }
+        console.log('');
+    });
+}

package/src/commands/tenants.mjs

@@ -0,0 +1,172 @@
+/**
+ * Substrio CLI: `substrio tenants` (alias `substrio apps`) command
+ *
+ * A tenant is an app: its own data, functions, users, site and domains.
+ * Listing tenants takes a platform-admin key (the profile in use must hold
+ * one). Creating one takes either that same master key (tenant.create, any
+ * slug, no owning account) or an account key (account.app.create: the app is
+ * owned by that account, the key a self-serve `substrio signup` saved); which one
+ * the profile in use holds is read with auth.whoami, falling back to the
+ * master-key path whenever whoami cannot say (no such route, or any other
+ * failure). The new tenant's own key is saved as a profile of its own, so
+ * its owner (a person, CI or an AI agent) deploys with it from then on.
+ *
+ *   substrio tenants list                    List every tenant
+ *   substrio tenants show SLUG               One tenant's settings and domains
+ *   substrio tenants create SLUG             Create a tenant; its key is saved to
+ *        [--save-profile NAME]               the profile NAME (default: SLUG),
+ *        [--print]                       never printed unless --print, which
+ *                                        writes it alone on stdout (for CI).
+ *   substrio tenants delete SLUG --yes       Delete a tenant and all its data;
+ *                                        --yes is required, there is no undo.
+ */
+
+import { ErrorCode, confirmDestructive, emit, emitIssuedKey, fail } from '../cli.mjs';
+import { cmdRegistry } from './groups-runtime.mjs';
+import { OpError, callOperation, invokeOperation, loadOperations, runOperation } from './op.mjs';
+import { listProfiles, writeProfile } from '../config.mjs';
+
+const C = {
+  reset: '\x1b[0m',
+  bold: '\x1b[1m',
+  dim: '\x1b[2m',
+  red: '\x1b[91m',
+  green: '\x1b[92m',
+  yellow: '\x1b[93m',
+  cyan: '\x1b[96m',
+};
+
+const USAGE =
+  'substrio tenants list | show SLUG | create SLUG [--save-profile NAME] [--print] | delete SLUG --yes';
+
+
+function flag(args, name) {
+  const i = args.indexOf(name);
+  return i === -1 ? null : (args[i + 1] ?? null);
+}
+
+export async function cmdTenants(api, config, args) {
+  // list, create and delete are about the account's apps, not one tenant: an
+  // account key presented at a tenant it does not own (the 'default'
+  // fallback of a profile `substrio signup` saved) proves nothing, so the
+  // fallback is not sent; a named tenant still is.
+  if (!config.tenant_named && ['list', 'ls', 'create', 'new', 'delete', 'rm'].includes(args[0])) api.tenant = null;
+  switch (args[0]) {
+    case 'list':
+    case 'ls':
+      return tenantsList(api, args.slice(1));
+    case 'show':
+    case 'get':
+      return tenantsShow(api, args.slice(1));
+    case 'create':
+    case 'new':
+      return tenantsCreate(api, config, args.slice(1));
+    case 'delete':
+    case 'rm':
+      return tenantsDelete(api, args.slice(1));
+    default:
+      // Any other tenant.* or app.* operation by its words (substrio tenants usage).
+      if (args[0] && !args[0].startsWith('-')) return cmdRegistry(api, 'tenants', args);
+      fail(`Usage: ${USAGE}`);
+  }
+}
+
+// tenant.list answers { data: [tenant...], count, tenant_domains,
+// next_cursor } and account.app.list { apps: [tenant...], next_cursor },
+// which --json prints whole; a tenant names itself by `subdomain` and lists
+// the hosts it answers on (`hosts`, then `domains`).
+function printTenants(data) {
+  const tenants = Array.isArray(data.data) ? data.data : Array.isArray(data.apps) ? data.apps : [];
+  if (tenants.length === 0) {
+    console.log(`${C.dim}No tenants.${C.reset}`);
+    return;
+  }
+  const slugOf = (t) => String(t.subdomain ?? t.slug ?? t.name ?? '');
+  const width = Math.max(4, ...tenants.map((t) => slugOf(t).length));
+  console.log(`\n  ${'SLUG'.padEnd(width)}  HOSTS`);
+  console.log(`  ${'─'.repeat(width)}  ${'─'.repeat(30)}`);
+  for (const t of tenants) {
+    const hosts = [...(t.hosts ?? []), ...(t.domains ?? [])].join(', ');
+    console.log(`  ${slugOf(t).padEnd(width)}  ${hosts}`);
+  }
+  console.log(`\n  ${C.dim}${tenants.length} tenant(s)${C.reset}\n`);
+}
+
+async function tenantsShow(api, args) {
+  if (!args[0] || args[0].startsWith('--')) fail(`Usage: ${USAGE}`);
+  return runOperation(api, 'tenant.get', args.slice(1), { positional: [args[0]] });
+}
+
+// The account id of the profile's key (auth.whoami), when it is an account
+// key; null for anything else, and for a server whoami cannot answer (no
+// such route, or any other failure) -- tenant.create, the master-key path,
+// stays the default.
+async function accountKeyId(api, ops) {
+  try {
+    const result = await callOperation(api, ops, 'auth.whoami', undefined);
+    return result.ok && result.data?.key === 'account' && typeof result.data.account_id === 'number' ? result.data.account_id : null;
+  } catch (err) {
+    if (err instanceof OpError) return null;
+    throw err;
+  }
+}
+
+async function tenantsCreate(api, config, args) {
+  const slug = args[0];
+  if (!slug || slug.startsWith('--')) fail(`Usage: ${USAGE}`);
+  const profile = flag(args, '--save-profile') ?? slug;
+  const print = args.includes('--print');
+  // Never overwrite a saved key: that would lose the only copy of it.
+  if (listProfiles().some((p) => p.name === profile)) {
+    fail(
+      `A profile named "${profile}" already exists; pass --save-profile with another name.`
+    );
+  }
+
+  // auth.whoami says which key this profile holds: an account key (from
+  // `substrio signup`, no platform access) makes its app with account.app.create,
+  // owned by that account; anything else, or a server whoami cannot answer,
+  // keeps the master-key path, tenant.create.
+  const ops = await loadOperations(api);
+  const accountId = await accountKeyId(api, ops);
+  const data = accountId !== null
+    ? await invokeOperation(api, 'account.app.create', { id: accountId, slug }, { ops })
+    : await invokeOperation(api, 'tenant.create', { slug }, { ops });
+  if (typeof data?.key !== 'string' || !data.key) {
+    fail(`Tenant "${slug}" was created but the server returned no key.`, null, ErrorCode.UNKNOWN);
+  }
+
+  writeProfile(profile, config.url, data.key, data.slug);
+  emitIssuedKey(data, print);
+  console.error(
+    `${C.green}✓${C.reset} Tenant ${C.bold}${data.slug}${C.reset} created; its key is saved to profile ${C.bold}${profile}${C.reset}.`
+  );
+  console.error(
+    `${C.dim}  In the app's substrio.toml: tenant = "${data.slug}", profile = "${profile}".${C.reset}`
+  );
+}
+
+// list and delete take the same branch create does: an account key (no
+// platform access, so tenant.list and tenant.delete refuse it) reads and
+// deletes its own apps through account.app.list and account.app.delete.
+async function tenantsList(api, args) {
+  const ops = await loadOperations(api);
+  const accountId = await accountKeyId(api, ops);
+  return accountId !== null
+    ? runOperation(api, 'account.app.list', args, { defaults: { id: accountId }, render: printTenants, ops })
+    : runOperation(api, 'tenant.list', args, { render: printTenants, ops });
+}
+
+async function tenantsDelete(api, args) {
+  const slug = args[0];
+  if (!slug || slug.startsWith('--')) fail(`Usage: ${USAGE}`);
+  await confirmDestructive(`Deleting "${slug}" removes all its data`, `substrio tenants delete ${slug} --yes`);
+  const ops = await loadOperations(api);
+  const accountId = await accountKeyId(api, ops);
+  const data = accountId !== null
+    ? await invokeOperation(api, 'account.app.delete', { id: accountId, slug }, { ops })
+    : await invokeOperation(api, 'tenant.delete', { slug }, { ops });
+  emit(data, () => console.error(
+    `${C.green}✓${C.reset} Tenant ${C.bold}${slug}${C.reset} deleted.`
+  ));
+}

package/src/commands/test.mjs

@@ -0,0 +1,167 @@
+/**
+ * Substrio CLI: `substrio test`, the tests of an app on a local server.
+ *
+ *   substrio test [FILES...] [--server PATH] [--attach URL] [--no-build]
+ *             [--filter NAME] [--timeout MS] [--keep]
+ *
+ * Starts one substrio_server of its own (or attaches to the one at --attach URL),
+ * and runs the test files with node's test runner (`node --test`): the files
+ * of the arguments, else every *.test.mjs under the app's test/ directory.
+ * Each test makes its own test tenant with startApp() of `@substrio/cli/test`,
+ * so nothing is shared between tests: no data, no stub, no clock. The server
+ * and everything it stored are removed at the end (--keep: the data
+ * directory stays). The exit code is the test runner's.
+ *
+ * The test files find the server through SUBSTRIO_TEST_URL, SUBSTRIO_TEST_APP_DIR and
+ * SUBSTRIO_TEST_KEY_FILE, the last a 0600 file holding the master key: it is never
+ * in a process environment.
+ */
+
+import { spawn } from 'node:child_process';
+import { mkdtempSync, readdirSync, rmSync, statSync, writeFileSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { basename, join, resolve } from 'node:path';
+
+import { readApp, runBuild } from '../apply.mjs';
+import { CliError, ErrorCode, fail } from '../cli.mjs';
+import { loadConfig } from '../config.mjs';
+import { FlagKind, parseFlags, wholeNumber } from '../local/args.mjs';
+import { LocalServer, resolveServerBinary } from '../local/server.mjs';
+import { testEnvFor } from '../testing/env.mjs';
+
+export const TEST_FLAGS = Object.freeze({
+    '--attach': FlagKind.VALUE,
+    '--server': FlagKind.VALUE,
+    '--no-build': FlagKind.SWITCH,
+    '--filter': FlagKind.VALUE,
+    '--timeout': FlagKind.VALUE,
+    '--keep': FlagKind.SWITCH,
+});
+
+/** The directory (under the app) the default test files are in. */
+export const TEST_DIR = 'test';
+
+/** The suffix of a test file's name. */
+export const TEST_SUFFIX = '.test.mjs';
+
+/**
+ * The test files to run: `given` (relative to `cwd`) when there are any, each
+ * required to exist, else every file of `cwd/test` named *.test.mjs, in path
+ * order. A CliError when there is none. Returns absolute paths.
+ */
+export function testFiles(cwd, given) {
+    if (given.length > 0) {
+        return given.map((file) => {
+            const path = resolve(cwd, file);
+            let stat;
+            try {
+                stat = statSync(path);
+            } catch {
+                throw new CliError(`No test file ${file}`);
+            }
+            if (!stat.isFile()) throw new CliError(`${file} is not a test file`);
+            return path;
+        });
+    }
+    const dir = join(cwd, TEST_DIR);
+    let names;
+    try {
+        names = readdirSync(dir, { recursive: true });
+    } catch {
+        throw new CliError(`No test files: the app has no ${TEST_DIR}/ directory (write ${TEST_DIR}/NAME${TEST_SUFFIX} or name the files)`);
+    }
+    const files = names.filter((name) => basename(name).endsWith(TEST_SUFFIX)).sort().map((name) => join(dir, name));
+    if (files.length === 0) throw new CliError(`No *${TEST_SUFFIX} files under ${TEST_DIR}/`);
+    return files;
+}
+
+/** The arguments of the `node` that runs the tests (pure). */
+export function nodeTestArgs({ files, filter = null, timeoutMs = null }) {
+    return [
+        '--test',
+        ...(filter === null ? [] : [`--test-name-pattern=${filter}`]),
+        ...(timeoutMs === null ? [] : [`--test-timeout=${timeoutMs}`]),
+        ...files,
+    ];
+}
+
+/** Runs node's test runner; resolves with its exit code (128 + signal number when a signal ended it). */
+function runNode(args, env, cwd) {
+    return new Promise((resolveRun, reject) => {
+        const child = spawn(process.execPath, args, { cwd, env, stdio: 'inherit' });
+        const forward = (signal) => () => { child.kill(signal); };
+        const handlers = ['SIGINT', 'SIGTERM'].map((signal) => [signal, forward(signal)]);
+        for (const [signal, handler] of handlers) process.on(signal, handler);
+        const release = () => { for (const [signal, handler] of handlers) process.off(signal, handler); };
+        child.once('error', (err) => { release(); reject(err); });
+        child.once('exit', (code, signal) => {
+            release();
+            resolveRun(code ?? 128 + (signal === 'SIGINT' ? 2 : 15));
+        });
+    });
+}
+
+export async function cmdTest(args) {
+    const cwd = process.cwd();
+    let parsed;
+    let app;
+    let files;
+    let timeoutMs = null;
+    try {
+        parsed = parseFlags(args, TEST_FLAGS);
+        app = readApp(cwd);
+        files = testFiles(cwd, parsed.positional);
+        if (parsed.flags.has('--timeout')) timeoutMs = wholeNumber(parsed.flags, '--timeout', 1, 3_600_000, 0);
+    } catch (err) {
+        fail(err);
+    }
+    const { flags } = parsed;
+
+    if (!flags.has('--no-build') && app.manifest.build.length > 0) {
+        try {
+            runBuild(app.manifest.build, cwd, (step) => console.log(`== build (${step.dir}) ${step.run}`));
+        } catch (err) {
+            fail(err);
+        }
+    }
+
+    // The master key goes to the tests through a file only this user can read.
+    const keyDir = mkdtempSync(join(tmpdir(), 'substrio-test-'));
+    const keyFile = join(keyDir, 'master.key');
+    let server;
+    try {
+        const attach = flags.get('--attach');
+        if (attach !== undefined) {
+            const config = loadConfig(cwd);
+            if (!config.master_key) throw new CliError('--attach needs a key: SUBSTRIO_MASTER_KEY or the profile', { code: ErrorCode.CREDENTIAL_REQUIRED });
+            server = LocalServer.attach({ url: attach, masterKey: config.master_key });
+        } else {
+            server = await LocalServer.spawn({ binary: resolveServerBinary(flags.get('--server')), port: 0, keep: flags.has('--keep') });
+        }
+        writeFileSync(keyFile, `${server.masterKey}\n`, { mode: 0o600 });
+    } catch (err) {
+        await server?.stop();
+        rmSync(keyDir, { recursive: true, force: true });
+        fail(err);
+    }
+
+    let code = 1;
+    try {
+        const env = testEnvFor({ url: server.url, keyFile, appDir: cwd });
+        const ended = Promise.race([
+            runNode(nodeTestArgs({ files, filter: flags.get('--filter') ?? null, timeoutMs }), env, cwd),
+            server.exited.then((how) => {
+                if (how === null) return new Promise(() => {});
+                throw new CliError(`The server ended during the tests (${how.signal ?? `exit ${how.code}`})`);
+            }),
+        ]);
+        code = await ended;
+    } catch (err) {
+        console.error(err.message);
+    } finally {
+        await server.stop();
+        rmSync(keyDir, { recursive: true, force: true });
+    }
+    if (flags.has('--keep') && server.dataDir) console.log(`The server's data is kept in ${server.dataDir}`);
+    process.exitCode = code;
+}

package/src/commands/tools.mjs

@@ -0,0 +1,63 @@
+/**
+ * Substrio CLI: `substrio tools install` (tool.install, PUT /v1/tools/{name}/{sha256}).
+ *
+ * The image's bytes never sit whole in memory: the file is streamed once to
+ * hash it (sha256, which the route names by), then streamed again as the PUT
+ * body. Stdin ("-") cannot be streamed twice, so it is buffered to an
+ * owner-only temp file first (removed after); a given file is streamed from
+ * disk both times.
+ */
+
+import { createHash } from 'node:crypto';
+import { createReadStream, createWriteStream, existsSync, statSync, unlinkSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { Readable } from 'node:stream';
+
+import { emit, fail } from '../cli.mjs';
+import { invokeOperation } from './op.mjs';
+
+const C = { reset: '\x1b[0m', bold: '\x1b[1m', green: '\x1b[92m' };
+
+function sha256Of(path) {
+    return new Promise((resolve, reject) => {
+        const hash = createHash('sha256');
+        createReadStream(path)
+            .on('data', (chunk) => hash.update(chunk))
+            .on('end', () => resolve(hash.digest('hex')))
+            .on('error', reject);
+    });
+}
+
+// Stdin buffered to an owner-only temp file: the hash is in the PUT's path,
+// so it must be known before the body is sent, and stdin cannot be read twice.
+function bufferStdin() {
+    const path = join(tmpdir(), `substrio-tool-${process.pid}-${Date.now()}`);
+    return new Promise((resolve, reject) => {
+        const out = createWriteStream(path, { mode: 0o600 });
+        process.stdin.pipe(out);
+        out.on('finish', () => resolve(path));
+        out.on('error', reject);
+        process.stdin.on('error', reject);
+    });
+}
+
+export async function cmdToolInstall(api, resolved) {
+    const [name, source] = resolved.positional;
+    if (!name || !source) fail('Usage: substrio tools install NAME FILE|-', 'FILE is a path to the image, or - for stdin');
+    const fromStdin = source === '-';
+    if (!fromStdin && !existsSync(source)) fail(`File not found: ${source}`);
+    const path = fromStdin ? await bufferStdin() : source;
+    try {
+        const sha256 = await sha256Of(path);
+        const size = statSync(path).size;
+        const data = await invokeOperation(api, 'tool.install', { name, sha256 }, {
+            method: 'PUT',
+            body: Readable.toWeb(createReadStream(path)),
+            headers: { 'Content-Type': 'application/octet-stream', 'Content-Length': String(size) },
+        });
+        emit(data, () => console.log(`${C.green}✓${C.reset} Installed ${C.bold}${name}${C.reset} (${sha256.slice(0, 16)})`));
+    } finally {
+        if (fromStdin) unlinkSync(path);
+    }
+}