@malmhq/intermesh-cli 0.1.0

package/dist/generation/templates/npm-cli/src/auth/prompt.ts

@@ -0,0 +1,27 @@
+import { createInterface } from 'node:readline/promises';
+import { Writable, type Readable } from 'node:stream';
+import { CliError, cliErrors } from '../shared/errors.js';
+
+export async function readHiddenToken(
+  prompt: string,
+  input: Readable = process.stdin,
+  output: Writable = process.stderr,
+): Promise<string> {
+  const terminal = Boolean('isTTY' in input && input.isTTY);
+  if (!terminal)
+    throw new CliError(
+      cliErrors.invalidInput(
+        'Interactive token entry requires a terminal. Use the configured token environment variable.',
+      ),
+    );
+  const muted = new Writable({ write: (_chunk, _encoding, done) => done() });
+  output.write(`${prompt}: `);
+  const lines = createInterface({ input, output: terminal ? muted : output, terminal });
+  try {
+    const token = (await lines.question('')).trim();
+    output.write('\n');
+    return token;
+  } finally {
+    lines.close();
+  }
+}

package/dist/generation/templates/npm-cli/src/cli.ts

@@ -0,0 +1,53 @@
+import { readFileSync } from 'node:fs';
+import { Command, CommanderError, Option } from 'commander';
+import { CliError, cliErrors } from './shared/errors.js';
+import { printError, printSuccess } from './shared/output.js';
+import { dryRun, DryRunComplete } from './shared/dry-run.js';
+
+export function createProgram(): Command {
+  const pkg = JSON.parse(readFileSync(new URL('../package.json', import.meta.url), 'utf8'));
+  return new Command()
+    .name(Object.keys(pkg.bin)[0])
+    .description(pkg.description)
+    .version(pkg.version)
+    .option('--json', 'Emit stable JSON without interactive prompts')
+    .option('--dry-run', 'Validate and preview without API calls or changes')
+    .hook('preAction', (_root, command) =>
+      dryRun.enterWith(Boolean(command.optsWithGlobals().dryRun)),
+    )
+    .addOption(new Option('--base-url <url>', 'Loopback mock URL for tests only').hideHelp())
+    .allowExcessArguments(false)
+    .exitOverride()
+    .configureOutput({
+      writeErr: () => {},
+      writeOut: (text) => {
+        if (process.argv.includes('--json') || !process.stdin.isTTY || !process.stdout.isTTY)
+          printSuccess({ help: text }, 'help');
+        else process.stdout.write(text);
+      },
+    })
+    .showSuggestionAfterError(false);
+}
+
+export async function runCli(program: Command, argv: string[]): Promise<void> {
+  try {
+    if (argv.length === 0) program.outputHelp();
+    else await dryRun.run(false, () => program.parseAsync(argv, { from: 'user' }));
+  } catch (error) {
+    if (error instanceof DryRunComplete) return;
+    if (error instanceof CommanderError) {
+      if (error.exitCode === 0) return;
+      printError(
+        new CliError(
+          error.code === 'commander.unknownCommand'
+            ? cliErrors.unknownCommand
+            : cliErrors.invalidInput(
+                'Invalid command input; see --help for supported commands and options.',
+              ),
+        ),
+      );
+    } else {
+      printError(error instanceof CliError ? error : new CliError(cliErrors.internal));
+    }
+  }
+}

package/dist/generation/templates/npm-cli/src/commands.ts

@@ -0,0 +1,6 @@
+import type { Command } from 'commander';
+
+export function registerCommands(program: Command): void {
+  // Integration registers customer command families here.
+  void program;
+}

package/dist/generation/templates/npm-cli/src/customer.ts

@@ -0,0 +1,16 @@
+export const customer = {
+  integration_id: 'customer-api',
+  package: {
+    name: 'customer-cli-starter',
+    binary: 'customer-cli',
+    display_name: 'Customer CLI',
+  },
+  api: {
+    base_url: 'https://api.example.com',
+    auth: {
+      type: 'bearer_token',
+      environment_variable: 'CUSTOMER_API_TOKEN',
+      login_prompt: 'Paste your API token',
+    },
+  },
+} as const;

package/dist/generation/templates/npm-cli/src/index.ts

@@ -0,0 +1,11 @@
+#!/usr/bin/env node
+import { createProgram, runCli } from './cli.js';
+import { registerAuthCommands } from './auth/commands.js';
+import { registerCommands } from './commands.js';
+import { registerLifecycleCommands } from './lifecycle/commands.js';
+
+const program = createProgram();
+registerAuthCommands(program);
+registerLifecycleCommands(program);
+registerCommands(program);
+await runCli(program, process.argv.slice(2));

package/dist/generation/templates/npm-cli/src/lifecycle/commands.ts

@@ -0,0 +1,344 @@
+import { execFile } from 'node:child_process';
+import { homedir } from 'node:os';
+import { resolve } from 'node:path';
+import { createInterface } from 'node:readline/promises';
+import { promisify } from 'node:util';
+import type { Command } from 'commander';
+import { login } from '../auth/commands.js';
+import { credentialStatus, keyringStore } from '../auth/credentials.js';
+import { readHiddenToken } from '../auth/prompt.js';
+import { customer } from '../customer.js';
+import { dryRun } from '../shared/dry-run.js';
+import { CliError, type ErrorDetails } from '../shared/errors.js';
+import { printSuccess } from '../shared/output.js';
+import {
+  CompatibilitySkillError,
+  inspectCompatibilityLinks,
+  inspectDiscoveryCopies,
+  PartialSkillInstallationError,
+  resolveDestinations,
+  SkillInstallerError,
+  synchronizeSkillSuite,
+  type InstallScope,
+  type SkillDestination,
+} from './installer/index.js';
+import { bundledSuite, packageIdentity } from './config.js';
+
+const execute = promisify(execFile);
+const sharedAgents = ['codex', 'claude', 'opencode', 'cursor'];
+type LifecycleSelection = {
+  json: boolean;
+  scope?: InstallScope;
+  projectDir?: string;
+};
+
+function lifecycleError(error: SkillInstallerError): CliError {
+  const details: ErrorDetails | undefined =
+    error instanceof PartialSkillInstallationError
+      ? {
+          destinations: error.receipt.destinations.map((destination) => ({
+            agents: destination.agents,
+            scope: destination.scope,
+            location: destination.location,
+            status: destination.status,
+            ...(destination.code ? { code: destination.code } : {}),
+          })),
+        }
+      : error instanceof CompatibilitySkillError
+        ? { destinations: [error.destination] }
+        : undefined;
+  return new CliError({
+    code: error.code,
+    message: error.message,
+    hint: error.hint,
+    ...(details ? { details } : {}),
+  });
+}
+
+function parseScope(value: string | undefined): InstallScope | undefined {
+  if (value === undefined) return undefined;
+  if (value !== 'project' && value !== 'global')
+    throw new CliError({
+      code: 'INVALID_INPUT',
+      message: `Unsupported scope: ${value}`,
+      hint: 'Choose project or global.',
+      exitCode: 2,
+    });
+  return value;
+}
+
+async function completeSelection(input: LifecycleSelection): Promise<LifecycleSelection> {
+  if (input.scope && (input.scope !== 'project' || input.projectDir)) return input;
+  if (input.json || !process.stdin.isTTY || !process.stdout.isTTY)
+    throw new CliError({
+      code: 'INVALID_INPUT',
+      message: 'Setup requires --scope, plus --project-dir for project scope.',
+      hint: 'Run setup --help for valid inputs.',
+      exitCode: 2,
+    });
+  const prompt = createInterface({ input: process.stdin, output: process.stderr });
+  try {
+    const chosenScope =
+      input.scope ?? parseScope((await prompt.question('Scope [project]: ')).trim() || 'project');
+    const projectDir =
+      chosenScope === 'project'
+        ? (input.projectDir ??
+          ((await prompt.question(`Project directory [${process.cwd()}]: `)).trim() ||
+            process.cwd()))
+        : undefined;
+    return { ...input, scope: chosenScope, projectDir };
+  } finally {
+    prompt.close();
+  }
+}
+
+async function authentication() {
+  try {
+    const value = await credentialStatus(keyringStore());
+    return value.configured
+      ? { status: 'connected' as const }
+      : { status: 'missing' as const, hint: `Run ${(await packageIdentity()).binary} login.` };
+  } catch {
+    return {
+      status: 'unavailable' as const,
+      hint: 'Check access to the operating system credential store and try again.',
+    };
+  }
+}
+
+async function offerLogin(state: Awaited<ReturnType<typeof authentication>>) {
+  if (state.status !== 'missing' || !process.stdin.isTTY || !process.stdout.isTTY) return state;
+  const prompt = createInterface({ input: process.stdin, output: process.stderr });
+  try {
+    const answer = (await prompt.question(`Run ${customer.package.binary} login now? [Y/n]: `))
+      .trim()
+      .toLowerCase();
+    if (answer === 'n' || answer === 'no') return state;
+  } finally {
+    prompt.close();
+  }
+  await login(keyringStore(), () => readHiddenToken(customer.api.auth.login_prompt));
+  return { status: 'connected' as const };
+}
+
+async function setup(input: { json: boolean; scope?: InstallScope; projectDir?: string }) {
+  input = await completeSelection(input);
+  if (!input.scope) throw new TypeError('Setup selection is incomplete');
+  const suite = await bundledSuite();
+  const projectDir = resolve(input.projectDir ?? process.cwd());
+  const copies = await inspectDiscoveryCopies({
+    suite,
+    projectDir,
+    homeDir: homedir(),
+  });
+  const conflicts = copies.filter(
+    (copy) => copy.state === 'unmanaged' || copy.state === 'different_owner',
+  );
+  if (conflicts.length > 0)
+    throw new CliError({
+      code: 'SKILL_CONFLICT',
+      message: 'A same-named Skill is not managed by this CLI.',
+      hint: 'Remove the conflicting Skill or choose another destination.',
+      details: {
+        destinations: conflicts.map(({ agent, scope, location, skill, state }) => ({
+          agent,
+          scope,
+          location,
+          skill,
+          state,
+        })),
+      },
+    });
+  const destinations = new Map<string, SkillDestination>();
+  for (const destination of [
+    ...resolveDestinations({
+      scope: input.scope,
+      projectDir,
+      homeDir: homedir(),
+    }),
+  ])
+    destinations.set(destination.root, destination);
+  try {
+    const compatibility = await inspectCompatibilityLinks(suite, [...destinations.values()]);
+    if (dryRun.getStore())
+      return {
+        dry_run: true,
+        effect: 'Install managed Skills',
+        summary: 'Would install managed Skills in the shared Agent Skills directory.',
+        checks: ['Installation scope', 'Skill conflicts', 'Compatibility links'],
+        not_checked: ['Destination write permissions', 'Credential validity'],
+        scope: input.scope,
+        project_dir: input.projectDir,
+        destinations: [
+          ...destinations.values(),
+          ...compatibility.map(({ agents, scope, location, actions }) => ({
+            agents,
+            scope,
+            location,
+            actions: actions.map(({ action, name }) => ({ action, skill: name })),
+          })),
+        ],
+      };
+    const receipt = await synchronizeSkillSuite(suite, [...destinations.values()]);
+    let auth = await authentication();
+    if (!input.json) auth = await offerLogin(auth);
+    return {
+      ready: auth.status === 'connected',
+      skills: {
+        status: 'installed' as const,
+        package_version: suite.version,
+        destinations: receipt.destinations.map((destination) => ({
+          ...destination,
+          skill_hashes: suite.skills,
+        })),
+      },
+      authentication: auth,
+    };
+  } catch (error) {
+    if (error instanceof SkillInstallerError) throw lifecycleError(error);
+    throw error;
+  }
+}
+
+async function status(projectDir = process.cwd()) {
+  const suite = await bundledSuite();
+  const copies = await inspectDiscoveryCopies({
+    suite,
+    projectDir: resolve(projectDir),
+    homeDir: homedir(),
+  });
+  const uniqueCopies = [
+    ...new Map(copies.map((copy) => [`${copy.root}:${copy.skill}`, copy])).values(),
+  ];
+  const conflicts = uniqueCopies.some(
+    (copy) => copy.state === 'unmanaged' || copy.state === 'different_owner',
+  );
+  const outdated = uniqueCopies.some(
+    (copy) => copy.state === 'outdated' || copy.state === 'managed_modified',
+  );
+  const rootsBySkill = new Map<string, Set<string>>();
+  for (const copy of uniqueCopies) {
+    const roots = rootsBySkill.get(copy.skill) ?? new Set<string>();
+    roots.add(copy.root);
+    rootsBySkill.set(copy.skill, roots);
+  }
+  const shadowed = [...rootsBySkill.values()].some((roots) => roots.size > 1);
+  const present = new Set(uniqueCopies.map((copy) => copy.skill));
+  const expected = Object.keys(suite.skills);
+  const scopes = [...new Set(uniqueCopies.map((copy) => copy.scope))];
+  let compatibilityMissing = false;
+  let compatibilityConflict = false;
+  for (const scope of scopes) {
+    try {
+      const plans = await inspectCompatibilityLinks(
+        suite,
+        resolveDestinations({ scope, projectDir: resolve(projectDir), homeDir: homedir() }),
+      );
+      compatibilityMissing ||= plans.some((plan) =>
+        plan.actions.some((action) => action.action !== 'reuse'),
+      );
+    } catch {
+      compatibilityConflict = true;
+    }
+  }
+  const skillStatus =
+    conflicts || compatibilityConflict
+      ? 'conflicting'
+      : shadowed
+        ? 'shadowed'
+        : outdated
+          ? 'outdated'
+          : present.size === 0
+            ? 'missing'
+            : expected.every((name) => present.has(name))
+              ? compatibilityMissing
+                ? 'partial'
+                : 'installed'
+              : 'partial';
+  const auth = await authentication();
+  return {
+    ready: skillStatus === 'installed' && auth.status === 'connected',
+    skills: {
+      status: skillStatus,
+      package_version: suite.version,
+      destinations: uniqueCopies.map(({ scope, location }) => ({
+        agents: sharedAgents,
+        scope,
+        location,
+        skill_hashes: suite.skills,
+      })),
+    },
+    authentication: auth,
+  };
+}
+
+async function update(input: { json: boolean; scope?: InstallScope; projectDir?: string }) {
+  input = await completeSelection(input);
+  if (!input.scope) throw new TypeError('Update selection is incomplete');
+  if (dryRun.getStore())
+    return {
+      dry_run: true,
+      effect: 'Update npm package and managed Skills',
+      summary: 'Would update the npm package and shared managed Skills.',
+      checks: ['Installation scope'],
+      not_checked: ['Registry availability', 'Destination write permissions'],
+      scope: input.scope,
+      project_dir: input.projectDir,
+    };
+  const previous = await packageIdentity();
+  try {
+    await execute('npm', ['install', '--global', `${previous.name}@latest`], {
+      encoding: 'utf8',
+      timeout: 120_000,
+    });
+  } catch {
+    throw new CliError({
+      code: 'UPDATE_FAILED',
+      message: 'The npm package update failed.',
+      hint: `Check npm access, then retry ${previous.binary} update.`,
+    });
+  }
+  const current = await packageIdentity();
+  const result = await setup({ ...input, json: true });
+  return { previous_version: previous.version, version: current.version, ...result };
+}
+
+function lifecycleOptions(command: Command): Command {
+  return command
+    .option('--scope <scope>', 'Installation scope: project or global')
+    .option('--project-dir <path>', 'Project directory for project scope');
+}
+
+export function registerLifecycleCommands(program: Command): void {
+  lifecycleOptions(program.command('setup').description("Install this CLI's Agent Skills")).action(
+    async (options: { scope?: string; projectDir?: string }) => {
+      printSuccess(
+        await setup({
+          json: Boolean(program.opts().json || program.opts().dryRun),
+          scope: parseScope(options.scope),
+          projectDir: options.projectDir,
+        }),
+        'setup',
+      );
+    },
+  );
+  program
+    .command('status')
+    .description('Show Skill installation and authentication status')
+    .option('--project-dir <path>', 'Project directory to inspect')
+    .action(async (options: { projectDir?: string }) =>
+      printSuccess(await status(options.projectDir), 'status'),
+    );
+  lifecycleOptions(
+    program.command('update').description('Update the npm CLI and managed Skills'),
+  ).action(async (options: { scope?: string; projectDir?: string }) => {
+    printSuccess(
+      await update({
+        json: Boolean(program.opts().json || program.opts().dryRun),
+        scope: parseScope(options.scope),
+        projectDir: options.projectDir,
+      }),
+      'update',
+    );
+  });
+}

package/dist/generation/templates/npm-cli/src/lifecycle/config.ts

@@ -0,0 +1,32 @@
+import { readFile } from 'node:fs/promises';
+import { fileURLToPath } from 'node:url';
+import { inspectBundledSuite } from './installer/index.js';
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+
+export async function packageIdentity(): Promise<{
+  name: string;
+  binary: string;
+  version: string;
+}> {
+  const value: unknown = JSON.parse(
+    await readFile(new URL('../../package.json', import.meta.url), 'utf8'),
+  );
+  if (!isRecord(value) || typeof value.name !== 'string' || typeof value.version !== 'string')
+    throw new TypeError('CLI package identity is invalid');
+  if (!isRecord(value.bin) || Object.keys(value.bin).length !== 1)
+    throw new TypeError('CLI package binary is invalid');
+  return { name: value.name, binary: Object.keys(value.bin)[0], version: value.version };
+}
+
+export async function bundledSuite() {
+  const identity = await packageIdentity();
+  return inspectBundledSuite({
+    sourceRoot: fileURLToPath(new URL('../../skills', import.meta.url)),
+    packageName: identity.name,
+    binary: identity.binary,
+    version: identity.version,
+  });
+}

package/dist/generation/templates/npm-cli/src/shared/dry-run.ts

@@ -0,0 +1,32 @@
+import { AsyncLocalStorage } from 'node:async_hooks';
+import { printSuccess } from './output.js';
+
+export const dryRun = new AsyncLocalStorage<boolean>();
+export class DryRunComplete extends Error {}
+
+export interface WorkflowPreview {
+  summary: string;
+  steps: Array<{ summary: string; depends_on_response?: boolean }>;
+}
+
+export function previewWorkflow(workflow: WorkflowPreview, command: string): void {
+  if (!dryRun.getStore()) return;
+  printSuccess(
+    {
+      dry_run: true,
+      summary: workflow.summary,
+      steps: workflow.steps.map((step) => ({
+        summary: step.summary,
+        status: step.depends_on_response ? 'resolved_during_execution' : 'planned',
+      })),
+      checks: ['Local command validation completed'],
+      not_checked: [
+        'API permissions and server state',
+        'Response-dependent values',
+        'Execution results',
+      ],
+    },
+    command,
+  );
+  throw new DryRunComplete();
+}

package/dist/generation/templates/npm-cli/src/shared/errors.ts

@@ -0,0 +1,162 @@
+type JsonValue = boolean | number | string | null | JsonValue[] | { [key: string]: JsonValue };
+export type ErrorDetails = Readonly<Record<string, JsonValue>>;
+
+type ErrorCode =
+  | 'UNKNOWN_COMMAND'
+  | 'INVALID_INPUT'
+  | 'INVALID_CONFIG'
+  | 'AUTH_REQUIRED'
+  | 'AUTH_FAILED'
+  | 'CREDENTIAL_STORE_UNAVAILABLE'
+  | 'UPSTREAM_ERROR'
+  | 'REQUEST_TIMEOUT'
+  | 'REQUEST_FAILED'
+  | 'FILE_WRITE_FAILED'
+  | 'SKILL_CONFLICT'
+  | 'SKILL_PATH_UNSAFE'
+  | 'SKILL_INSTALLATION_BUSY'
+  | 'SKILL_INSTALLATION_FAILED'
+  | 'UPDATE_FAILED';
+
+export interface ErrorDefinition {
+  code: ErrorCode;
+  message: string;
+  hint?: string;
+  details?: ErrorDetails;
+  retryable?: boolean;
+  exitCode?: number;
+}
+
+export const cliErrors = {
+  unknownCommand: {
+    code: 'UNKNOWN_COMMAND',
+    message: 'Invalid command input; see --help for supported commands and options.',
+    hint: 'Run the CLI with --help to see available commands.',
+    details: { reason: 'unknown_command' },
+    exitCode: 2,
+  },
+  invalidInput: (message: string): ErrorDefinition => ({
+    code: 'INVALID_INPUT',
+    message,
+    hint: 'Run the command with --help to see valid inputs.',
+    details: { reason: 'invalid_arguments' },
+    exitCode: 2,
+  }),
+  invalidLoopbackUrl: {
+    code: 'INVALID_CONFIG',
+    message: 'Provide a valid loopback --base-url.',
+    hint: 'Use an HTTP or HTTPS URL on localhost, 127.0.0.1, or ::1.',
+    details: { reason: 'invalid_loopback_url' },
+    exitCode: 2,
+  },
+  loopbackUrlNotPermitted: {
+    code: 'INVALID_CONFIG',
+    message: 'Only credential-free loopback mock URLs are supported.',
+    hint: 'Remove credentials and use localhost, 127.0.0.1, or ::1.',
+    details: { reason: 'loopback_url_not_permitted' },
+    exitCode: 2,
+  },
+  customerApiConfigurationInvalid: {
+    code: 'INVALID_CONFIG',
+    message: 'Customer API configuration is invalid.',
+    hint: 'Regenerate the CLI from a credential-free HTTPS API URL.',
+    details: { reason: 'customer_api_url_invalid' },
+    exitCode: 2,
+  },
+  operationPathInvalid: {
+    code: 'INVALID_CONFIG',
+    message: 'Operation path is invalid.',
+    hint: 'Regenerate the CLI from a valid API operation path.',
+    details: { reason: 'operation_path_invalid' },
+    exitCode: 2,
+  },
+  operationOriginMismatch: {
+    code: 'INVALID_CONFIG',
+    message: 'Operation must use the configured API origin.',
+    hint: 'Regenerate the CLI and verify the configured API origin.',
+    details: { reason: 'operation_origin_mismatch' },
+    exitCode: 2,
+  },
+  invalidToken: {
+    code: 'INVALID_INPUT',
+    message: 'API token is invalid.',
+    hint: 'Paste a non-empty API token without line breaks.',
+    details: { reason: 'invalid_token' },
+    exitCode: 2,
+  },
+  credentialStoreUnavailable: {
+    code: 'CREDENTIAL_STORE_UNAVAILABLE',
+    message: 'The operating system credential store is unavailable.',
+    hint: 'Check access to the system credential store and try again.',
+    exitCode: 2,
+  },
+  authRequired: (binary: string): ErrorDefinition => ({
+    code: 'AUTH_REQUIRED',
+    message: `Run ${binary} login before using this command.`,
+    hint: `Run ${binary} login or provide the configured token environment variable.`,
+    exitCode: 2,
+  }),
+  authFailed: {
+    code: 'AUTH_FAILED',
+    message: 'API authentication failed.',
+    hint: 'Check or replace the configured API token, then retry.',
+  },
+  redirectNotAllowed: {
+    code: 'REQUEST_FAILED',
+    message: 'Redirects are not allowed.',
+    hint: 'Verify the configured API URL and operation path.',
+    details: { reason: 'redirect_rejected' },
+  },
+  upstream: (status: number): ErrorDefinition => ({
+    code: 'UPSTREAM_ERROR',
+    message: `API returned HTTP ${String(status)}.`,
+    hint: 'Check the API status and request inputs, then retry when appropriate.',
+    details: { status },
+  }),
+  timeout: {
+    code: 'REQUEST_TIMEOUT',
+    message: 'Request timed out.',
+    hint: 'Retry the command. If it continues to time out, check the API status.',
+    retryable: true,
+  },
+  requestFailed: {
+    code: 'REQUEST_FAILED',
+    message: 'Could not reach the customer API.',
+    hint: 'Check network access and the customer API status, then retry.',
+    retryable: true,
+  },
+  invalidJson: {
+    code: 'REQUEST_FAILED',
+    message: 'API returned invalid JSON.',
+    hint: 'Check that the selected operation returns JSON and retry.',
+    details: { reason: 'invalid_json' },
+  },
+  internal: {
+    code: 'REQUEST_FAILED',
+    message: 'Request could not be completed.',
+    hint: 'Retry the command. If it fails again, inspect the API status.',
+  },
+  fileWriteFailed: {
+    code: 'FILE_WRITE_FAILED',
+    message: 'Cannot write output; choose a new, writable file path.',
+    hint: 'Choose a path that does not exist in a writable directory.',
+  },
+} as const;
+
+export class CliError extends Error {
+  readonly code: ErrorCode;
+  readonly hint: string | undefined;
+  readonly details: ErrorDetails | undefined;
+  readonly retryable: boolean;
+  readonly exitCode: number;
+
+  constructor(definition: ErrorDefinition) {
+    super(definition.message);
+    this.name = 'CliError';
+    this.code = definition.code;
+    this.hint = definition.hint ?? 'Run the command with --help to check the required inputs.';
+    this.details = definition.details;
+    this.retryable = definition.retryable ?? false;
+    this.exitCode = definition.exitCode ?? 1;
+  }
+}