@antasphere/chassis-cli 0.0.0-stage → 1.0.1

package/src/testing/index.ts

@@ -0,0 +1,129 @@
+import { mkdtemp } from 'node:fs/promises';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import type { ChassisClient } from '@antasphere/chassis-sdk';
+import type { CliIo } from '../context.js';
+import type { Cli } from '../kit.js';
+
+/**
+ * The test harness of a CLI built on this package, shared by the chassis suite
+ * and by the tool's own tests. `./testing` is a test-only entry: it is built
+ * (the tool's tests read it from `dist`) and kept out of the packed artefact
+ * (`files` in package.json) and out of the tool's bundle (nothing under a
+ * tool's `src` imports it).
+ *
+ * Router-style fake fetch: handlers matched by method + path regex, so
+ * order-insensitive flows (parallel uploads) stay assertable. Records every
+ * call with its parsed body (JSON / FormData summary).
+ */
+
+export interface RecordedCall {
+  method: string;
+  path: string;
+  body?: unknown;
+}
+
+/**
+ * The full wire view of a call — origin + authorization header included.
+ * Kept in a SEPARATE array (`wire`) so the legacy strict `toEqual` asserts
+ * on `calls` keep their exact shape; the connect tests use this to prove
+ * which credential went to which host.
+ */
+export interface WireCall {
+  method: string;
+  origin: string;
+  path: string;
+  auth: string | undefined;
+  /** The `x-workspace-id` header, present only when the request carried one. */
+  workspace?: string;
+  body?: unknown;
+}
+
+export interface Route {
+  method: string;
+  path: RegExp;
+  reply: (call: { path: string; body?: unknown; form?: FormData; headers: Headers }) => {
+    status?: number;
+    body?: unknown;
+    raw?: Response;
+  };
+}
+
+export function routedHarness(routes: Route[], env: Record<string, string | undefined> = {}) {
+  const calls: RecordedCall[] = [];
+  const wire: WireCall[] = [];
+  const out: string[] = [];
+  const err: string[] = [];
+  const fetch = (async (input: string | URL | Request, init?: RequestInit) => {
+    const url = new URL(input.toString());
+    const method = (init?.method ?? 'GET').toUpperCase();
+    const path = url.pathname + url.search;
+    let body: unknown;
+    let form: FormData | undefined;
+    if (typeof init?.body === 'string') {
+      try {
+        body = JSON.parse(init.body);
+      } catch {
+        body = init.body;
+      }
+    } else if (init?.body instanceof FormData) {
+      form = init.body;
+      body = { sha256: form.get('sha256') };
+    }
+    calls.push({ method, path, ...(body !== undefined ? { body } : {}) });
+    const headers = new Headers(init?.headers);
+    const auth = headers.get('authorization') ?? undefined;
+    const workspace = headers.get('x-workspace-id') ?? undefined;
+    wire.push({
+      method,
+      origin: url.origin,
+      path,
+      auth,
+      ...(workspace !== undefined ? { workspace } : {}),
+      ...(body !== undefined ? { body } : {})
+    });
+    const route = routes.find((r) => r.method === method && r.path.test(url.pathname));
+    if (!route) {
+      return new Response(
+        JSON.stringify({ error: { code: 'not_found', message: `no fake route ${method} ${path}` } }),
+        {
+          status: 404,
+          headers: { 'content-type': 'application/json' }
+        }
+      );
+    }
+    const result = route.reply({ path, body, headers, ...(form ? { form } : {}) });
+    if (result.raw) return result.raw;
+    return new Response(JSON.stringify(result.body ?? {}), {
+      status: result.status ?? 200,
+      headers: { 'content-type': 'application/json' }
+    });
+  }) as typeof globalThis.fetch;
+
+  const io: CliIo = {
+    env,
+    out: { write: (s) => out.push(s) },
+    err: { write: (s) => err.push(s) },
+    fetch
+  };
+  return { io, calls, wire, out: () => out.join(''), err: () => err.join('') };
+}
+
+/** A temp HOME-like config root, isolated per test. */
+export async function tempConfigEnv(): Promise<Record<string, string>> {
+  const dir = await mkdtemp(join(tmpdir(), 'cli-cfg-'));
+  return { XDG_CONFIG_HOME: dir };
+}
+
+/**
+ * What the chassis suite (`test/suite`) reads from `@chassis-cli-test/host`:
+ * one instantiated CLI and its runner, with the tool's groups and version
+ * already bound. The chassis package aliases the specifier to its minimal
+ * `things` tool; a tool's own CLI package aliases it to its real kit, and the
+ * same files run a second time there. Every literal that spells the tool in
+ * the suite is read from `cli.identity`.
+ */
+export interface CliTestHost<TClient extends ChassisClient<string>> {
+  cli: Cli<TClient>;
+  run(argv: string[], io: CliIo): Promise<number>;
+}

package/src/workspace.ts

@@ -0,0 +1,229 @@
+import { CliUsageError } from '@antasphere/cli-core';
+import type { ChassisClient } from '@antasphere/chassis-sdk';
+import type { CliEnv } from './config.js';
+import type { CliIdentity } from './identity.js';
+
+/**
+ * Which workspace a command runs in (PRDCT-2419, PRDCT-2947).
+ *
+ * A credential identifies a USER (ADR 014, ADR 019): the workspace is a
+ * per-request `X-Workspace-Id`, and the SDK sends it once told which. There
+ * is ONE organization notion in the tool family: the server's default
+ * organization applies when a command names none, and a command may name
+ * one of two ways:
+ *
+ *   --org <hub organization id or name>   or <PREFIX>_ORG
+ *   --workspace <workspace id or name>    or <PREFIX>_WORKSPACE
+ *
+ * `--org` names the organization the Antasphere way (the id the account
+ * site shows, or its name); the instance maps a hub organization id to its
+ * own workspace through `central_account_id`. `--workspace` names a
+ * workspace of this instance (a self-hosted instance has no hub ids). Both
+ * at once is a usage error; a flag wins over its variable. Nothing is saved
+ * on this machine: the default is the server's (`workspace default` on a
+ * self-hosted instance, the Antasphere account on the cloud).
+ *
+ * A value that is a uuid is sent as it is (the server accepts a local id or a
+ * hub organization id, and fails closed on one that is not the person's); a
+ * name is looked up in `/me`'s `workspaces[]` first, by id, by hub
+ * organization id, then by name. Pure functions only: the wiring (the client,
+ * the header) lives in context.ts.
+ */
+
+/** `/me`'s answer, read off the client (the SDK does not export the type by name). */
+export type MeResponse = Awaited<ReturnType<ChassisClient<string>['me']>>;
+export type MeWorkspace = MeResponse['workspaces'][number];
+
+/** Which flag or variable named the selection. */
+export type SelectionKind = 'org' | 'workspace';
+
+/** Where the workspace of this invocation came from; `default` = nothing selected. */
+export type WorkspaceSource = 'flag' | 'env' | 'default';
+
+export interface WorkspaceSelection {
+  /** What the person wrote: an id or a name, trimmed. */
+  value: string;
+  source: Exclude<WorkspaceSource, 'default'>;
+  /** `--org` / `<PREFIX>_ORG`, or `--workspace` / `<PREFIX>_WORKSPACE`. */
+  kind: SelectionKind;
+}
+
+/** The server's own selector shape (resolve-membership.ts): anything else is a name. */
+const UUID_RE = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
+
+export function isWorkspaceId(value: string): boolean {
+  return UUID_RE.test(value);
+}
+
+/** The hub organization id of a listed workspace, when it projects one (an older server sends none). */
+function orgIdOf(w: MeWorkspace): string | null {
+  const id = (w as { centralAccountId?: unknown }).centralAccountId;
+  return typeof id === 'string' && id ? id : null;
+}
+
+/** One line per workspace, for the error messages that list the candidates. */
+export function workspaceLines(workspaces: readonly MeWorkspace[]): string {
+  if (workspaces.length === 0) return '  (none)';
+  return workspaces
+    .map((w) => {
+      const org = orgIdOf(w);
+      return `  ${w.id}  ${w.role.padEnd(6)}  ${w.name}${org ? `  (organization ${org})` : ''}`;
+    })
+    .join('\n');
+}
+
+/**
+ * The membership a value names, or null: the exact workspace id first, then
+ * the exact hub organization id, else the ONE workspace whose name matches
+ * without regard to case. `ambiguous` carries the several a name matched.
+ */
+export function findWorkspace(
+  workspaces: readonly MeWorkspace[],
+  value: string
+): { match: MeWorkspace | null; ambiguous: MeWorkspace[] } {
+  const wanted = value.trim().toLowerCase();
+  const byId = workspaces.find((w) => w.id.toLowerCase() === wanted);
+  if (byId) return { match: byId, ambiguous: [] };
+  const byOrg = workspaces.find((w) => orgIdOf(w)?.toLowerCase() === wanted);
+  if (byOrg) return { match: byOrg, ambiguous: [] };
+  const byName = workspaces.filter((w) => w.name.trim().toLowerCase() === wanted);
+  if (byName.length === 1) return { match: byName[0]!, ambiguous: [] };
+  return { match: null, ambiguous: byName };
+}
+
+/** `findWorkspace`, erroring with the candidates on an unknown or ambiguous value. */
+export function matchWorkspace(workspaces: readonly MeWorkspace[], value: string): MeWorkspace {
+  const { match, ambiguous } = findWorkspace(workspaces, value);
+  if (match) return match;
+  if (ambiguous.length > 1) {
+    throw new CliUsageError(
+      `Several of your workspaces are named "${value}". Name one by its id:\n${workspaceLines(ambiguous)}`
+    );
+  }
+  throw new CliUsageError(`"${value}" is not one of your workspaces. Yours:\n${workspaceLines(workspaces)}`);
+}
+
+/** The workspace functions that spell the tool: its environment variables, its binary. */
+export interface CliWorkspace {
+  WORKSPACE_ENV: string;
+  ORG_ENV: string;
+  pickWorkspaceSelection(input: {
+    workspaceFlag: string | undefined;
+    orgFlag: string | undefined;
+    env: CliEnv;
+  }): WorkspaceSelection | undefined;
+  describeSelection(selection: Pick<WorkspaceSelection, 'source' | 'kind'>): string;
+  describeSource(source: WorkspaceSource, kind: SelectionKind | undefined): string;
+  explainRefusal(input: {
+    code: string;
+    status: number;
+    selection: WorkspaceSelection;
+    workspaceId: string;
+    me: MeResponse;
+    baseUrl: string;
+  }): string | null;
+}
+
+export function createWorkspace(identity: CliIdentity): CliWorkspace {
+  const WORKSPACE_ENV = `${identity.envPrefix}_WORKSPACE`;
+  const ORG_ENV = `${identity.envPrefix}_ORG`;
+
+  /**
+   * The selection of this invocation, or undefined when nothing selects one.
+   *
+   * An empty `--org` or `--workspace` is a usage error (somebody meant to
+   * name one); an empty variable is an unset one (a CI variable that
+   * expanded to nothing) and falls through. Two flags, or two variables, at
+   * once is a usage error: one command runs in one place.
+   */
+  function pickWorkspaceSelection(input: {
+    workspaceFlag: string | undefined;
+    orgFlag: string | undefined;
+    env: CliEnv;
+  }): WorkspaceSelection | undefined {
+    if (input.orgFlag !== undefined && input.workspaceFlag !== undefined) {
+      throw new CliUsageError('Pass --org or --workspace, not both.');
+    }
+    if (input.orgFlag !== undefined) {
+      const value = input.orgFlag.trim();
+      if (!value) throw new CliUsageError('--org needs an organization id or name.');
+      return { value, source: 'flag', kind: 'org' };
+    }
+    if (input.workspaceFlag !== undefined) {
+      const value = input.workspaceFlag.trim();
+      if (!value) throw new CliUsageError('--workspace needs a workspace id or name.');
+      return { value, source: 'flag', kind: 'workspace' };
+    }
+    const org = input.env[ORG_ENV]?.trim();
+    const workspace = input.env[WORKSPACE_ENV]?.trim();
+    if (org && workspace) {
+      throw new CliUsageError(`Set ${ORG_ENV} or ${WORKSPACE_ENV}, not both.`);
+    }
+    if (org) return { value: org, source: 'env', kind: 'org' };
+    if (workspace) return { value: workspace, source: 'env', kind: 'workspace' };
+    return undefined;
+  }
+
+  /** How a selection reads in a sentence: `the --org flag`, `<PREFIX>_WORKSPACE`. */
+  function describeSelection(selection: Pick<WorkspaceSelection, 'source' | 'kind'>): string {
+    if (selection.source === 'flag')
+      return selection.kind === 'org' ? 'the --org flag' : 'the --workspace flag';
+    return selection.kind === 'org' ? ORG_ENV : WORKSPACE_ENV;
+  }
+
+  /** The same, for `whoami`'s `chosen by` line. */
+  function describeSource(source: WorkspaceSource, kind: SelectionKind | undefined): string {
+    if (source === 'default' || kind === undefined) return "the server's default (nothing selected)";
+    return describeSelection({ source, kind });
+  }
+
+  /**
+   * What a refused request really meant, once `/me` answered WITHOUT the
+   * selection (so the key itself is good). Two refusals are the selection's:
+   *
+   *  - 403 `workspace_mismatch`: the key is pinned, and a selector-less `/me`
+   *    always resolves a pinned key to its pin — so `me.workspace` IS the pin.
+   *  - 401 `invalid_api_key`: the server answers a workspace the person does
+   *    not belong to exactly like an unknown key (no oracle, resolve-
+   *    membership.ts), which alone would send the person to check a good key.
+   *
+   * null = the selection does not explain it; the caller prints the plain error.
+   */
+  function explainRefusal(input: {
+    code: string;
+    status: number;
+    selection: WorkspaceSelection;
+    workspaceId: string;
+    me: MeResponse;
+    baseUrl: string;
+  }): string | null {
+    const { selection, me } = input;
+    const by = describeSelection(selection);
+    const noun = selection.kind === 'org' ? 'organization' : 'workspace';
+    const selected = findWorkspace(me.workspaces, input.workspaceId).match;
+    if (input.code === 'workspace_mismatch' && input.status === 403) {
+      const pin = me.workspace ? `"${me.workspace.name}" (${me.workspace.id})` : 'another workspace';
+      const asked = selected ? `"${selected.name}" (${selected.id})` : `"${selection.value}"`;
+      return (
+        `This API key is pinned to the workspace ${pin}, and ${by} selects ${asked}. ` +
+        'A pinned key only ever acts in its own workspace: drop the selection, or use a key that is not pinned.'
+      );
+    }
+    if (input.code === 'invalid_api_key' && input.status === 401 && !selected) {
+      return (
+        `The ${noun} "${selection.value}" (selected by ${by}) is not one of yours on ${input.baseUrl}; ` +
+        `the API key itself works. Yours:\n${workspaceLines(me.workspaces)}`
+      );
+    }
+    return null;
+  }
+
+  return {
+    WORKSPACE_ENV,
+    ORG_ENV,
+    pickWorkspaceSelection,
+    describeSelection,
+    describeSource,
+    explainRefusal
+  };
+}

package/test/host/identity.test.ts

@@ -0,0 +1,229 @@
+import { mkdir, readFile, writeFile } from 'node:fs/promises';
+import { join } from 'node:path';
+import { describe, expect, it } from 'vitest';
+import { routedHarness, tempConfigEnv, type Route } from '@antasphere/chassis-cli/testing';
+import { run } from './minimal-host.js';
+import { cli, registerTool, VERSION } from './minimal-tool.js';
+
+/**
+ * The minimal `things` tool, pinned by RAW BYTES (PRDCT-2530, verifier F-4 /
+ * F-2 / M18). This file is HOST-SPECIFIC: it sits beside the host, outside
+ * `test/suite`, so it runs in this package only and never under a tool.
+ *
+ * The suite reads the identity from the kit under test, so it cannot tell a
+ * wrong identity VALUE from a right one. Here nothing reads `cli.identity`:
+ * every expectation is a literal ('things', 'Things', 'THINGS', 'thk'), which
+ * proves from the chassis side that the six parameters are live. The tool's
+ * CLI package carries the mirror with its own literals
+ * (`packages/cli/test/identity.test.ts`).
+ */
+
+const CLOUD_INSTANCE = {
+  name: 'Things Cloud',
+  instanceId: 'i1',
+  edition: 'cloud',
+  version: '1.0.0',
+  apiVersion: 'v1',
+  setupRequired: false,
+  auth: {
+    methods: ['antasphere', 'api-key', 'oauth'],
+    passwordReset: false,
+    emailChange: false,
+    twoFactor: false
+  },
+  features: { mcp: true, oauth: true, files: true }
+};
+
+const ME = {
+  user: { id: 'u1', name: 'Ada', email: 'ada@x.co' },
+  workspace: { id: 'w1', name: 'Acme' },
+  workspaces: [
+    {
+      id: 'w1',
+      name: 'Acme',
+      role: 'owner',
+      hubOrigin: false,
+      centralAccountId: null,
+      look: { theme: null, pattern: null, field: null, grain: null },
+      suspended: false,
+      default: true
+    }
+  ],
+  activeWorkspaceId: 'w1',
+  role: 'owner',
+  via: 'api_key',
+  scopes: ['items:read'],
+  apiKeyExpiresAt: null
+};
+
+const meRoute: Route = { method: 'GET', path: /\/api\/v1\/me$/, reply: () => ({ body: ME }) };
+
+const LEGACY = {
+  activeProfile: 'work',
+  profiles: { work: { apiKey: 'thk_abcdefgh_0123456789abcdef', baseUrl: 'http://legacy-inst' } }
+};
+
+describe('the `things` identity, by its observable bytes', () => {
+  it('legacyConfigDir: a config left at $XDG_CONFIG_HOME/things/config.json is imported', async () => {
+    const env = await tempConfigEnv();
+    const dir = join(env.XDG_CONFIG_HOME!, 'things');
+    await mkdir(dir, { recursive: true });
+    await writeFile(join(dir, 'config.json'), JSON.stringify(LEGACY, null, 2));
+    const h = routedHarness([meRoute], env);
+    const code = await run(['whoami'], h.io);
+    expect(h.err()).toBe('');
+    expect(code).toBe(0);
+    expect(h.out()).toContain('http://legacy-inst');
+    expect(h.wire).toEqual([
+      {
+        method: 'GET',
+        origin: 'http://legacy-inst',
+        path: '/api/v1/me',
+        auth: 'Bearer thk_abcdefgh_0123456789abcdef'
+      }
+    ]);
+  });
+
+  it('tool: the profiles live in $XDG_CONFIG_HOME/antasphere/tools/things.json', async () => {
+    const env = await tempConfigEnv();
+    const dir = join(env.XDG_CONFIG_HOME!, 'things');
+    await mkdir(dir, { recursive: true });
+    await writeFile(join(dir, 'config.json'), JSON.stringify(LEGACY, null, 2));
+    const h = routedHarness([], env);
+    expect(await run(['profiles'], h.io)).toBe(0);
+    const saved = await readFile(join(env.XDG_CONFIG_HOME!, 'antasphere', 'tools', 'things.json'), 'utf8');
+    expect(JSON.parse(saved)).toEqual(LEGACY);
+  });
+
+  it('bin: the program is called `things`', async () => {
+    const h = routedHarness([]);
+    expect(await run(['--help'], h.io)).toBe(0);
+    expect(h.out().split('\n')[0]).toBe('Usage: things [options] [command]');
+  });
+
+  it('envPrefix: THINGS_URL and THINGS_API_KEY are the variables that are read', async () => {
+    const env = await tempConfigEnv();
+    const h = routedHarness([meRoute], {
+      ...env,
+      THINGS_URL: 'http://from-env',
+      THINGS_API_KEY: 'thk_envkey12_0123456789abcdef'
+    });
+    expect(await run(['whoami'], h.io)).toBe(0);
+    expect(h.wire).toEqual([
+      {
+        method: 'GET',
+        origin: 'http://from-env',
+        path: '/api/v1/me',
+        auth: 'Bearer thk_envkey12_0123456789abcdef'
+      }
+    ]);
+  });
+
+  it('displayName, keyPrefix, envPrefix: the missing-hub-login sentence, whole', async () => {
+    const env = await tempConfigEnv();
+    const h = routedHarness(
+      [{ method: 'GET', path: /\/api\/v1\/instance$/, reply: () => ({ body: CLOUD_INSTANCE }) }],
+      env
+    );
+    expect(await run(['files', 'list', '--api-url', 'http://tool'], h.io)).toBe(1);
+    expect(h.err()).toBe(
+      'Error: This Things instance signs in through Antasphere. Run `things login` once (or `antasphere login`), ' +
+        'then retry — or pass --api-key <thk_…> / set THINGS_API_KEY.\n'
+    );
+  });
+
+  it('bin, envPrefix: the no-key sentence, whole', async () => {
+    const env = await tempConfigEnv();
+    const h = routedHarness([], env);
+    expect(await run(['files', 'list', '--api-url', 'http://x'], h.io)).toBe(1);
+    expect(h.err()).toBe(
+      'Error: An API key is required. Sign in (`things login`), pass --api-key, or set THINGS_API_KEY.\n'
+    );
+  });
+
+  it('cloudUrl: with nothing configured, a command probes https://things.antasphere.test', async () => {
+    const env = await tempConfigEnv();
+    const h = routedHarness([], env);
+    expect(await run(['files', 'list'], h.io)).toBe(1);
+    expect(h.wire).toEqual([
+      {
+        method: 'GET',
+        origin: 'https://things.antasphere.test',
+        path: '/api/v1/instance',
+        auth: undefined
+      }
+    ]);
+    expect(h.err()).toBe(
+      'Error: An API key is required. Sign in (`things login`), pass --api-key, or set THINGS_API_KEY.\n'
+    );
+  });
+
+  it('bin: `things auth login-request` no longer exists', async () => {
+    const h = routedHarness([]);
+    expect(await run(['auth', 'login-request', '--email', 'a@x.co'], h.io)).toBe(1);
+    expect(h.err()).toContain("unknown command 'auth'");
+    expect(h.wire).toEqual([]);
+  });
+
+  it('bin again: the 401 hint names `things verify` (M18)', async () => {
+    const h = routedHarness([
+      {
+        method: 'GET',
+        path: /\/api\/v1\/me$/,
+        reply: () => ({ status: 401, body: { error: { code: 'invalid_api_key', message: 'bad key' } } })
+      }
+    ]);
+    expect(await run(['whoami', '--url', 'http://x', '--api-key', 'thk_k_s'], h.io)).toBe(1);
+    expect(h.err()).toBe('Error: bad key (check the key: `things verify`)\n');
+  });
+});
+
+/** Every top-level command, in the order `--help` and the completion scripts print them. */
+const COMMANDS = [
+  // generic: identity and profiles, then the workspace selection
+  'login',
+  'logout',
+  'whoami',
+  'verify',
+  'use',
+  'profiles',
+  'config',
+  'workspaces',
+  'workspace',
+  // generic: the subgroups of the workspace, its named groups of people, then
+  // the owner's demo links
+  'projects',
+  'teams',
+  'demo',
+  // the tool's own group, at the seam
+  'things',
+  // generic: the platform substrate, then completion LAST
+  'instance',
+  'export',
+  'files',
+  'completion'
+];
+
+describe('the order of the top-level commands (F-2)', () => {
+  it('the built program registers them in this order', () => {
+    const h = routedHarness([]);
+    expect(cli.buildProgram(h.io, registerTool, VERSION).commands.map((c) => c.name())).toEqual(COMMANDS);
+  });
+
+  it('`--help` lists them in this order, `help` last', async () => {
+    const h = routedHarness([]);
+    expect(await run(['--help'], h.io)).toBe(0);
+    const block = h.out().split('Commands:\n')[1]!;
+    const names = block
+      .split('\n')
+      .filter((line) => /^ {2}\S/.test(line))
+      .map((line) => line.trim().split(/[ |]/)[0]);
+    expect(names).toEqual([...COMMANDS, 'help']);
+  });
+
+  it('`completion bash` offers them in this order', async () => {
+    const h = routedHarness([]);
+    expect(await run(['completion', 'bash'], h.io)).toBe(0);
+    expect(h.out()).toContain(`compgen -W "${COMMANDS.join(' ')}" -- "$cur"`);
+  });
+});

package/test/host/minimal-host.ts

@@ -0,0 +1,16 @@
+import type { ChassisClient } from '@antasphere/chassis-sdk';
+import type { CliIo } from '@antasphere/chassis-cli';
+import type { CliTestHost } from '@antasphere/chassis-cli/testing';
+import { cli as thingsCli, registerTool, VERSION, type ThingsScope } from './minimal-tool.js';
+
+/**
+ * The host of the chassis suite in THIS package: the minimal `things` tool.
+ * `@chassis-cli-test/host` resolves here under `vitest.config.ts`; the tool's
+ * CLI package aliases the same specifier to its own kit.
+ */
+const host: CliTestHost<ChassisClient<ThingsScope>> = {
+  cli: thingsCli,
+  run: (argv: string[], io: CliIo) => thingsCli.run(argv, io, registerTool, VERSION)
+};
+
+export const { cli, run } = host;

package/test/host/minimal-tool.ts

@@ -0,0 +1,40 @@
+import { ChassisClient } from '@antasphere/chassis-sdk';
+import { defineCli, type CliIo } from '@antasphere/chassis-cli';
+import type { Command } from 'commander';
+
+/**
+ * The minimal tool of the chassis suite: another identity than any product's
+ * (so a literal left behind in the generic CLI shows), the bare chassis client
+ * over its own scope names, and ONE trivial command group registered at the
+ * seam, so the tool's positional hook in the program is exercised on every
+ * run. It imports nothing from a tool.
+ */
+export type ThingsScope = 'things:read' | 'things:write' | 'things:export';
+
+export const VERSION = '0.0.1';
+
+export const cli = defineCli({
+  identity: {
+    bin: 'things',
+    tool: 'things',
+    legacyConfigDir: 'things',
+    displayName: 'Things',
+    envPrefix: 'THINGS',
+    keyPrefix: 'thk',
+    exportScope: 'things:export',
+    cloudUrl: 'https://things.antasphere.test'
+  },
+  description: 'Command-line client for a Things instance',
+  createClient: (options) => new ChassisClient<ThingsScope>(options)
+});
+
+/** The tool's one group: `things list`, a command that touches nothing. */
+export function registerTool(program: Command, io: CliIo): void {
+  const things = program.command('things').description('the things of this tool');
+  things
+    .command('list')
+    .description('list the things')
+    .action(() => {
+      io.out.write('No things.\n');
+    });
+}