@ankhorage/infra 4.1.12 → 5.1.0

package/src/cli/commands/down.ts

@@ -0,0 +1,28 @@
+import { INFRA_CAPABILITIES } from '../../constants.js';
+import type { InfraCommandDefinition } from '../../types/infraCli.js';
+import { prepareInfraCommandOperationAsync } from '../utils/prepareInfraCommandOperationAsync.js';
+import { requireInfraSuccess } from '../utils/requireInfraSuccess.js';
+import { writeInfraStructured } from '../utils/writeInfraStructured.js';
+
+/*** Define reversible runtime suspension while retaining persistent resources. */
+export const down = {
+  standaloneName: 'down',
+  path: ['down'],
+  capability: INFRA_CAPABILITIES[6],
+  summary: 'Reversibly suspend runtime workloads while retaining persistent data.',
+  async run(request, services) {
+    const operation = await prepareInfraCommandOperationAsync(request, services);
+    const result = await services.operations.down(operation.operation, operation.dependencies);
+    requireInfraSuccess(result, request.context);
+    await services.writeState(operation.project.projectPath, {
+      schemaVersion: 1,
+      desired: operation.desired,
+      ledger: result.value.ledger,
+    });
+    writeInfraStructured(request.context, request.arguments.format, {
+      environment: result.value.environment,
+      state: 'stopped',
+    });
+    return { exitCode: 0 };
+  },
+} as const satisfies InfraCommandDefinition;

package/src/cli/commands/generate.ts

@@ -0,0 +1,34 @@
+import { INFRA_CAPABILITIES } from '../../constants.js';
+import type { InfraCommandDefinition } from '../../types/infraCli.js';
+import { prepareInfraCommandOperationAsync } from '../utils/prepareInfraCommandOperationAsync.js';
+import { requireInfraSuccess } from '../utils/requireInfraSuccess.js';
+import { writeInfraStructured } from '../utils/writeInfraStructured.js';
+
+/*** Define deterministic review-artifact generation without remote side effects. */
+export const generate = {
+  standaloneName: 'generate',
+  path: ['generate'],
+  capability: INFRA_CAPABILITIES[2],
+  summary: 'Generate deterministic review artifacts without remote side effects.',
+  async run(request, services) {
+    const operation = await prepareInfraCommandOperationAsync(request, services);
+    const result = await services.operations.generate(operation.operation, operation.dependencies);
+    requireInfraSuccess(result, request.context);
+    const written = await services.writeArtifacts(
+      operation.project.projectPath,
+      result.value.artifacts,
+      operation.state?.ledger,
+    );
+    await services.writeState(operation.project.projectPath, {
+      schemaVersion: 1,
+      desired: operation.desired,
+      ledger: result.value.ledger,
+    });
+    writeInfraStructured(request.context, request.arguments.format, {
+      environment: result.value.environment,
+      ...written,
+      artifacts: result.value.artifacts.map(({ path }) => path),
+    });
+    return { exitCode: 0 };
+  },
+} as const satisfies InfraCommandDefinition;

package/src/cli/commands/outputs.ts

@@ -0,0 +1,25 @@
+import { INFRA_CAPABILITIES } from '../../constants.js';
+import type { InfraCommandDefinition } from '../../types/infraCli.js';
+import { prepareInfraCommandOperationAsync } from '../utils/prepareInfraCommandOperationAsync.js';
+import { requireInfraSuccess } from '../utils/requireInfraSuccess.js';
+import { writeInfraEnvironmentOutputs } from '../utils/writeInfraEnvironmentOutputs.js';
+import { writeInfraStructured } from '../utils/writeInfraStructured.js';
+
+/*** Define safe public-output and secret-reference presentation. */
+export const outputs = {
+  standaloneName: 'outputs',
+  path: ['outputs'],
+  capability: INFRA_CAPABILITIES[5],
+  summary: 'Print safe public outputs and secret references.',
+  async run(request, services) {
+    const operation = await prepareInfraCommandOperationAsync(request, services);
+    const result = services.operations.outputs(operation.operation);
+    requireInfraSuccess(result, request.context);
+    if (request.arguments.format === 'env') {
+      writeInfraEnvironmentOutputs(request.context, result.value.outputs);
+    } else {
+      writeInfraStructured(request.context, request.arguments.format, result.value);
+    }
+    return { exitCode: 0 };
+  },
+} as const satisfies InfraCommandDefinition;

package/src/cli/commands/plan.ts

@@ -0,0 +1,20 @@
+import { INFRA_CAPABILITIES } from '../../constants.js';
+import type { InfraCommandDefinition } from '../../types/infraCli.js';
+import { prepareInfraCommandOperationAsync } from '../utils/prepareInfraCommandOperationAsync.js';
+import { requireInfraSuccess } from '../utils/requireInfraSuccess.js';
+import { writeInfraStructured } from '../utils/writeInfraStructured.js';
+
+/*** Define the ordered side-effect-free infrastructure planning command. */
+export const plan = {
+  standaloneName: 'plan',
+  path: ['plan'],
+  capability: INFRA_CAPABILITIES[1],
+  summary: 'Print an ordered side-effect-free infrastructure plan.',
+  async run(request, services) {
+    const operation = await prepareInfraCommandOperationAsync(request, services);
+    const result = await services.operations.plan(operation.operation, operation.dependencies);
+    requireInfraSuccess(result, request.context);
+    writeInfraStructured(request.context, request.arguments.format, result.value);
+    return { exitCode: 0 };
+  },
+} as const satisfies InfraCommandDefinition;

package/src/cli/commands/status.ts

@@ -0,0 +1,20 @@
+import { INFRA_CAPABILITIES } from '../../constants.js';
+import type { InfraCommandDefinition } from '../../types/infraCli.js';
+import { prepareInfraCommandOperationAsync } from '../utils/prepareInfraCommandOperationAsync.js';
+import { requireInfraSuccess } from '../utils/requireInfraSuccess.js';
+import { writeInfraStructured } from '../utils/writeInfraStructured.js';
+
+/*** Define provider-neutral environment status aggregation. */
+export const status = {
+  standaloneName: 'status',
+  path: ['status'],
+  capability: INFRA_CAPABILITIES[4],
+  summary: 'Aggregate provider-neutral environment status.',
+  async run(request, services) {
+    const operation = await prepareInfraCommandOperationAsync(request, services);
+    const result = await services.operations.status(operation.operation, operation.dependencies);
+    requireInfraSuccess(result, request.context);
+    writeInfraStructured(request.context, request.arguments.format, result.value);
+    return { exitCode: 0 };
+  },
+} as const satisfies InfraCommandDefinition;

package/src/cli/commands/up.ts

@@ -0,0 +1,29 @@
+import { INFRA_CAPABILITIES } from '../../constants.js';
+import type { InfraCommandDefinition } from '../../types/infraCli.js';
+import { prepareInfraCommandOperationAsync } from '../utils/prepareInfraCommandOperationAsync.js';
+import { requireInfraSuccess } from '../utils/requireInfraSuccess.js';
+import { writeInfraStructured } from '../utils/writeInfraStructured.js';
+
+/*** Define idempotent environment creation and reconciliation. */
+export const up = {
+  standaloneName: 'up',
+  path: ['up'],
+  capability: INFRA_CAPABILITIES[3],
+  summary: 'Idempotently ensure and reconcile the selected environment.',
+  async run(request, services) {
+    const operation = await prepareInfraCommandOperationAsync(request, services);
+    const result = await services.operations.up(operation.operation, operation.dependencies);
+    requireInfraSuccess(result, request.context);
+    await services.writeState(operation.project.projectPath, {
+      schemaVersion: 1,
+      desired: operation.desired,
+      ledger: result.value.ledger,
+    });
+    writeInfraStructured(request.context, request.arguments.format, {
+      environment: result.value.environment,
+      resources: result.value.resources.length,
+      outputs: result.value.outputs,
+    });
+    return { exitCode: 0 };
+  },
+} as const satisfies InfraCommandDefinition;

package/src/cli/commands/validate.ts

@@ -0,0 +1,20 @@
+import { INFRA_CAPABILITIES } from '../../constants.js';
+import type { InfraCommandDefinition } from '../../types/infraCli.js';
+import { prepareInfraCommandOperationAsync } from '../utils/prepareInfraCommandOperationAsync.js';
+import { requireInfraSuccess } from '../utils/requireInfraSuccess.js';
+import { writeInfraStructured } from '../utils/writeInfraStructured.js';
+
+/*** Define the manifest, compatibility, credential and selected-adapter validation command. */
+export const validate = {
+  standaloneName: 'validate',
+  path: ['validate'],
+  capability: INFRA_CAPABILITIES[0],
+  summary: 'Validate manifest, compatibility, credentials and selected adapters.',
+  async run(request, services) {
+    const operation = await prepareInfraCommandOperationAsync(request, services);
+    const result = await services.operations.validate(operation.operation, operation.dependencies);
+    requireInfraSuccess(result, request.context);
+    writeInfraStructured(request.context, request.arguments.format, result.value);
+    return { exitCode: 0 };
+  },
+} as const satisfies InfraCommandDefinition;

package/src/cli/constants.ts

@@ -0,0 +1,19 @@
+import { destroy } from './commands/destroy.js';
+import { down } from './commands/down.js';
+import { generate } from './commands/generate.js';
+import { outputs } from './commands/outputs.js';
+import { plan } from './commands/plan.js';
+import { status } from './commands/status.js';
+import { up } from './commands/up.js';
+import { validate } from './commands/validate.js';
+
+export const INFRA_COMMANDS = [
+  validate,
+  plan,
+  generate,
+  up,
+  status,
+  outputs,
+  down,
+  destroy,
+] as const;

package/src/cli/createDefaultInfraCommandContext.ts

@@ -0,0 +1,17 @@
+import { INFRA_PACKAGE_VERSION } from '../constants.js';
+import type { InfraCommandContext } from '../types/infraCli.js';
+
+/*** Create the process-backed command context used by the standalone executable. */
+export function createDefaultInfraCommandContext(): InfraCommandContext {
+  return {
+    cwd: process.cwd(),
+    env: process.env,
+    version: INFRA_PACKAGE_VERSION,
+    writeStdout(text: string) {
+      process.stdout.write(text);
+    },
+    writeStderr(text: string) {
+      process.stderr.write(text);
+    },
+  };
+}

package/src/cli/createInfraRuntimeProvider.ts

@@ -0,0 +1,35 @@
+import type { AnkhRuntimeCommandProvider } from '@ankhorage/ankh';
+
+import {
+  INFRA_CAPABILITIES,
+  INFRA_COMMAND_CATEGORY,
+  INFRA_PACKAGE_NAME,
+  INFRA_PACKAGE_VERSION,
+} from '../constants.js';
+import type { CreateInfraRuntimeProviderOptions } from '../types/infraCli.js';
+import { INFRA_COMMANDS } from './constants.js';
+import { createProviderCommandDescriptors } from './createProviderCommandDescriptors.js';
+import { runInfraCommandAsync } from './runInfraCommandAsync.js';
+
+/*** Compose the canonical Infra command surface as an Ankh runtime provider. */
+export function createInfraRuntimeProvider(
+  options: CreateInfraRuntimeProviderOptions = {},
+): AnkhRuntimeCommandProvider {
+  const runCommandImpl = options.runCommandImpl ?? runInfraCommandAsync;
+  return {
+    id: INFRA_PACKAGE_NAME,
+    category: INFRA_COMMAND_CATEGORY,
+    version: INFRA_PACKAGE_VERSION,
+    capabilities: [...INFRA_CAPABILITIES],
+    commands: createProviderCommandDescriptors(),
+    handlers: INFRA_COMMANDS.map((command) => ({
+      path: command.path,
+      handler(request) {
+        return runCommandImpl(
+          { argv: request.argv, command, context: request.context },
+          { services: options.services },
+        );
+      },
+    })),
+  } satisfies AnkhRuntimeCommandProvider;
+}

package/src/cli/createProviderCommandDescriptors.ts

@@ -0,0 +1,8 @@
+import type { AnkhCommandDescriptor } from '@ankhorage/contracts/cli';
+
+import { INFRA_COMMANDS } from './constants.js';
+
+/*** Expose the same eight commands through Ankh provider discovery. */
+export function createProviderCommandDescriptors(): readonly AnkhCommandDescriptor[] {
+  return INFRA_COMMANDS.map(({ capability, path, summary }) => ({ capability, path, summary }));
+}

package/src/cli/findInfraCommand.ts

@@ -0,0 +1,7 @@
+import type { InfraCommandDefinition } from '../types/infraCli.js';
+import { INFRA_COMMANDS } from './constants.js';
+
+/*** Resolve one exact standalone Infra command name without guessing intent. */
+export function findInfraCommand(value: string): InfraCommandDefinition | null {
+  return INFRA_COMMANDS.find((candidate) => candidate.standaloneName === value) ?? null;
+}

package/src/cli/index.test.ts

@@ -1,32 +1,24 @@
 import type { AnkhRuntimeCommandProvider } from '@ankhorage/ankh';
 import { describe, expect, test } from 'bun:test';
 
-import { createProviderCommandDescriptors, INFRA_COMMANDS } from '../commands.js';
+import { createProviderCommandDescriptors } from './createProviderCommandDescriptors.js';
 import provider, { createInfraRuntimeProvider } from './index.js';
 
-describe('infra package cli provider', () => {
-  test('publishes the expected runtime provider shape', () => {
-    const expectedProvider = createInfraRuntimeProvider() satisfies AnkhRuntimeCommandProvider;
-
-    expect(expectedProvider.id).toBe('@ankhorage/infra');
-    expect(expectedProvider.category).toBe('infra');
-    expect(expectedProvider.capabilities).toEqual([
+describe('Infra Ankh provider', () => {
+  test('publishes all eight canonical capabilities and handlers', () => {
+    const expected = createInfraRuntimeProvider() satisfies AnkhRuntimeCommandProvider;
+    expect(expected.capabilities).toEqual([
       'infra.validate',
+      'infra.plan',
       'infra.generate',
-      'infra.status',
       'infra.up',
+      'infra.status',
+      'infra.outputs',
       'infra.down',
+      'infra.destroy',
     ]);
-    expect(expectedProvider.commands).toEqual(createProviderCommandDescriptors());
-    expect(expectedProvider.handlers?.map((handler) => handler.path.join(' '))).toEqual(
-      INFRA_COMMANDS.map((command) => command.path.join(' ')),
-    );
-    expect(JSON.stringify(expectedProvider)).not.toContain('port-forward');
-  });
-
-  test('default export is the runtime provider', () => {
-    expect(provider.category).toBe('infra');
-    expect(provider.commands).toHaveLength(5);
-    expect(provider.handlers).toHaveLength(5);
+    expect(expected.commands).toEqual(createProviderCommandDescriptors());
+    expect(expected.handlers).toHaveLength(8);
+    expect(provider.handlers).toHaveLength(8);
   });
 });

package/src/cli/index.ts

@@ -1,53 +1,11 @@
-import type { AnkhRuntimeCommandProvider } from '@ankhorage/ankh';
-
-import {
-  createProviderCommandDescriptors,
-  INFRA_COMMANDS,
-  type InfraCommandServices,
-  runInfraCommand,
-  type RunInfraCommandImpl,
-} from '../commands.js';
-import {
-  INFRA_CAPABILITIES,
-  INFRA_COMMAND_CATEGORY,
-  INFRA_PACKAGE_NAME,
-  INFRA_PACKAGE_VERSION,
-} from '../packageMetadata.js';
-
-export interface CreateInfraRuntimeProviderOptions {
-  readonly runCommandImpl?: RunInfraCommandImpl;
-  readonly services?: Partial<InfraCommandServices>;
-}
-
-export function createInfraRuntimeProvider(
-  options: CreateInfraRuntimeProviderOptions = {},
-): AnkhRuntimeCommandProvider {
-  const runCommandImpl = options.runCommandImpl ?? runInfraCommand;
-
-  return {
-    id: INFRA_PACKAGE_NAME,
-    category: INFRA_COMMAND_CATEGORY,
-    version: INFRA_PACKAGE_VERSION,
-    capabilities: [...INFRA_CAPABILITIES],
-    commands: createProviderCommandDescriptors(),
-    handlers: INFRA_COMMANDS.map((command) => ({
-      path: command.path,
-      handler(request) {
-        return runCommandImpl(
-          {
-            argv: request.argv,
-            command,
-            context: request.context,
-          },
-          {
-            services: options.services,
-          },
-        );
-      },
-    })),
-  } satisfies AnkhRuntimeCommandProvider;
-}
+import { createInfraRuntimeProvider } from './createInfraRuntimeProvider.js';
 
 const provider = createInfraRuntimeProvider();
 
+export type {
+  CreateInfraRuntimeProviderOptions,
+  InfraCommandServices,
+  RunInfraCommandImpl,
+} from '../types/infraCli.js';
+export { createInfraRuntimeProvider } from './createInfraRuntimeProvider.js';
 export default provider;

package/src/cli/renderInfraRootHelp.ts

@@ -0,0 +1,23 @@
+import { INFRA_COMMAND_CATEGORY } from '../constants.js';
+import { INFRA_COMMANDS } from './constants.js';
+
+/*** Render the standalone Infra command surface and environment safety rules. */
+export function renderInfraRootHelp(version: string): string {
+  const commands = INFRA_COMMANDS.map(
+    ({ standaloneName, summary }) => `  ${standaloneName.padEnd(8, ' ')} ${summary}`,
+  ).join('\n');
+  return [
+    `@ankhorage/infra v${version}`,
+    '',
+    'Usage:',
+    '  ankhorage-infra <command> [project] [--environment <environment>]',
+    `  ankh ${INFRA_COMMAND_CATEGORY} <command> [project] [--environment <environment>]`,
+    '',
+    'Commands:',
+    commands,
+    '',
+    'Safety:',
+    '  local is the only implicit environment; destroy always requires --environment and --confirm.',
+    '',
+  ].join('\n');
+}

package/src/cli/renderUnknownInfraCommand.ts

@@ -0,0 +1,4 @@
+/*** Render an invalid standalone Infra command without guessing intent. */
+export function renderUnknownInfraCommand(value: string): string {
+  return [`Unknown infra command: ${value}`, '', 'Run ankhorage-infra --help', ''].join('\n');
+}

package/src/cli/runInfraCliAsync.ts

@@ -0,0 +1,51 @@
+import type {
+  InfraCommandContext,
+  InfraCommandRunResult,
+  InfraCommandServices,
+  RunInfraCommandImpl,
+} from '../types/infraCli.js';
+import { createDefaultInfraCommandContext } from './createDefaultInfraCommandContext.js';
+import { findInfraCommand } from './findInfraCommand.js';
+import { renderInfraRootHelp } from './renderInfraRootHelp.js';
+import { renderUnknownInfraCommand } from './renderUnknownInfraCommand.js';
+import { runInfraCommandAsync } from './runInfraCommandAsync.js';
+
+/*** Dispatch the standalone executable arguments through the canonical Infra command surface. */
+export async function runInfraCliAsync(
+  argv: readonly string[],
+  options: InfraCliOptions = {},
+): Promise<InfraCommandRunResult> {
+  const context = options.context ?? createDefaultInfraCommandContext();
+  const runCommand = options.runCommandImpl ?? runInfraCommandAsync;
+  const [firstToken, ...restTokens] = argv;
+  if (firstToken === undefined || isHelpToken(firstToken)) {
+    context.writeStdout(renderInfraRootHelp(context.version));
+    return { exitCode: 0 };
+  }
+  if (isVersionToken(firstToken)) {
+    context.writeStdout(`${context.version}\n`);
+    return { exitCode: 0 };
+  }
+  const command = findInfraCommand(firstToken);
+  if (command === null) {
+    context.writeStderr(renderUnknownInfraCommand(firstToken));
+    return { exitCode: 1 };
+  }
+  return runCommand({ argv: restTokens, command, context }, { services: options.services });
+}
+
+interface InfraCliOptions {
+  readonly context?: InfraCommandContext;
+  readonly runCommandImpl?: RunInfraCommandImpl;
+  readonly services?: Partial<InfraCommandServices>;
+}
+
+/*** Recognize standalone help tokens. */
+function isHelpToken(value: string): boolean {
+  return value === '--help' || value === '-h' || value === 'help';
+}
+
+/*** Recognize standalone version tokens. */
+function isVersionToken(value: string): boolean {
+  return value === '--version' || value === '-v' || value === 'version';
+}

package/src/cli/runInfraCommandAsync.ts

@@ -0,0 +1,114 @@
+import { APP_ENVIRONMENT_IDS } from '@ankhorage/contracts/environments';
+
+import { INFRA_COMMAND_CATEGORY } from '../constants.js';
+import { createInfraCommandServices } from '../features/environment-lifecycle/composition/createInfraCommandServices.js';
+import type {
+  InfraCommandDefinition,
+  InfraCommandInvocation,
+  InfraCommandRunResult,
+  ParsedInfraArguments,
+  RunInfraCommandOptions,
+} from '../types/infraCli.js';
+
+/*** Run one standalone or provider-backed Infra command through the shared typed lifecycle. */
+export async function runInfraCommandAsync(
+  request: InfraCommandInvocation,
+  options: RunInfraCommandOptions = {},
+): Promise<InfraCommandRunResult> {
+  const services = createInfraCommandServices(options.services);
+  try {
+    const parsed = parseCommandArguments(request.command, request.argv);
+    if (parsed === null) {
+      request.context.writeStdout(renderCommandHelp(request.command));
+      return { exitCode: 0 };
+    }
+    return await request.command.run({ context: request.context, arguments: parsed }, services);
+  } catch (error) {
+    request.context.writeStderr(
+      `Infra ${request.command.standaloneName} failed: ${getErrorMessage(error)}\n`,
+    );
+    return { exitCode: 1 };
+  }
+}
+
+/*** Parse the common project, environment, output and destruction options. */
+function parseCommandArguments(
+  commandDefinition: InfraCommandDefinition,
+  argv: readonly string[],
+): ParsedInfraArguments | null {
+  if (argv.length === 1 && isHelpToken(argv.at(0))) return null;
+  let projectId: string | undefined;
+  let environment: ParsedInfraArguments['environment'];
+  let format: ParsedInfraArguments['format'] = 'human';
+  let confirmation: string | undefined;
+  const deleteResources: string[] = [];
+  for (let index = 0; index < argv.length; index += 1) {
+    const token = argv.at(index);
+    if (token === '--environment') {
+      environment = parseEnvironment(readOptionValue(argv, ++index, token));
+    } else if (token === '--format') {
+      format = parseFormat(readOptionValue(argv, ++index, token));
+    } else if (token === '--confirm') {
+      confirmation = readOptionValue(argv, ++index, token);
+    } else if (token === '--delete-resource') {
+      deleteResources.push(readOptionValue(argv, ++index, token));
+    } else if (token?.startsWith('-') === true) {
+      throw new Error(`Unknown Infra ${commandDefinition.standaloneName} option: ${token}`);
+    } else if (projectId === undefined && token !== undefined) {
+      projectId = token;
+    } else {
+      throw new Error(
+        `Infra ${commandDefinition.standaloneName} accepts at most one project argument.`,
+      );
+    }
+  }
+  if (format === 'env' && commandDefinition.standaloneName !== 'outputs') {
+    throw new Error('--format env is supported only by Infra outputs.');
+  }
+  if (commandDefinition.standaloneName === 'destroy' && environment === undefined) {
+    throw new Error('Infra destroy requires --environment <local|preview|production>.');
+  }
+  return { projectId, environment, format, confirmation, deleteResources };
+}
+
+/*** Parse one environment identifier against the canonical closed set. */
+function parseEnvironment(value: string): ParsedInfraArguments['environment'] {
+  const environment = APP_ENVIRONMENT_IDS.find((candidate) => candidate === value);
+  if (environment === undefined) throw new Error(`Unknown Infra environment: ${value}.`);
+  return environment;
+}
+
+/*** Parse the supported command output formats. */
+function parseFormat(value: string): ParsedInfraArguments['format'] {
+  if (value === 'human' || value === 'json' || value === 'env') return value;
+  throw new Error(`Unknown Infra output format: ${value}.`);
+}
+
+/*** Read one required CLI option value. */
+function readOptionValue(argv: readonly string[], index: number, option: string): string {
+  const value = argv.at(index);
+  if (value === undefined || value.startsWith('-')) throw new Error(`${option} requires a value.`);
+  return value;
+}
+
+/*** Render command-specific standalone and provider usage. */
+function renderCommandHelp(commandDefinition: InfraCommandDefinition): string {
+  return [
+    commandDefinition.summary,
+    '',
+    'Usage:',
+    `  ankhorage-infra ${commandDefinition.standaloneName} [project] [--environment <environment>]`,
+    `  ankh ${INFRA_COMMAND_CATEGORY} ${commandDefinition.path.join(' ')} [project] [--environment <environment>]`,
+    '',
+  ].join('\n');
+}
+
+/*** Normalize arbitrary command failures for the CLI boundary. */
+function getErrorMessage(error: unknown): string {
+  return error instanceof Error ? error.message : String(error);
+}
+
+/*** Recognize the command-local help tokens. */
+function isHelpToken(value: string | undefined): boolean {
+  return value === '--help' || value === '-h' || value === 'help';
+}

package/src/cli/utils/prepareInfraCommandOperationAsync.ts

@@ -0,0 +1,64 @@
+import type { AppEnvironmentId } from '@ankhorage/contracts/environments';
+import type { InfraEnvironmentSpec, InfraManifest } from '@ankhorage/contracts/infra';
+
+import type {
+  InfraCommandRunRequest,
+  InfraCommandServices,
+  PreparedInfraCommandOperation,
+} from '../../types/infraCli.js';
+
+/*** Resolve one command's project, desired environment, stored ownership and adapter dependencies. */
+export async function prepareInfraCommandOperationAsync(
+  request: InfraCommandRunRequest,
+  services: InfraCommandServices,
+  useStoredDesired = false,
+): Promise<PreparedInfraCommandOperation> {
+  const project = await services.resolveProject({
+    cwd: request.context.cwd,
+    ...(request.arguments.projectId === undefined
+      ? {}
+      : { projectId: request.arguments.projectId }),
+  });
+  const environment = request.arguments.environment ?? 'local';
+  const state = await services.readState(project.projectPath, environment);
+  const currentDesired = environmentDesired(project.manifest.infra, environment);
+  const desired = useStoredDesired && state !== null ? state.desired : currentDesired;
+  if (desired === undefined) {
+    throw new Error(`Infra environment "${environment}" is not configured.`);
+  }
+  const manifest = replaceEnvironment(project.manifest.infra, environment, desired);
+  return {
+    project,
+    state,
+    desired,
+    operation: {
+      projectId: project.projectId,
+      manifest,
+      ...(request.arguments.environment === undefined ? {} : { environment }),
+      ...(state === null ? {} : { previous: state.ledger, previousDesired: state.desired }),
+    },
+    dependencies: services.createDependencies(request.context),
+  };
+}
+
+/*** Select one exact environment specification from the canonical manifest. */
+function environmentDesired(
+  manifest: InfraManifest,
+  environment: AppEnvironmentId,
+): InfraEnvironmentSpec | undefined {
+  if (environment === 'local') return manifest.environments.local;
+  if (environment === 'preview') return manifest.environments.preview;
+  return manifest.environments.production;
+}
+
+/*** Replace one environment while preserving the rest of the canonical manifest. */
+function replaceEnvironment(
+  manifest: InfraManifest,
+  environment: AppEnvironmentId,
+  desired: InfraEnvironmentSpec,
+): InfraManifest {
+  return {
+    ...manifest,
+    environments: { ...manifest.environments, [environment]: desired },
+  };
+}