@ankhorage/infra 4.1.10 → 5.0.0

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 },
+  };
+}

package/src/cli/utils/requireInfraSuccess.ts

@@ -0,0 +1,24 @@
+import type { InfraDiagnostic, InfraResult } from '@ankhorage/contracts/infra';
+
+import type { InfraCommandContext } from '../../types/infraCli.js';
+
+/*** Emit diagnostics and narrow a provider-neutral result before command rendering continues. */
+export function requireInfraSuccess<T>(
+  result: InfraResult<T>,
+  context: InfraCommandContext,
+): asserts result is Extract<InfraResult<T>, { readonly ok: true }> {
+  writeDiagnostics(context, result.diagnostics);
+  if (!result.ok) throw new Error(result.diagnostics.map(({ message }) => message).join(' '));
+}
+
+/*** Render diagnostics to the matching process channel without provider-specific formatting. */
+function writeDiagnostics(
+  context: InfraCommandContext,
+  diagnostics: readonly InfraDiagnostic[],
+): void {
+  for (const diagnostic of diagnostics) {
+    const line = `${diagnostic.severity}: ${diagnostic.code}: ${diagnostic.message}\n`;
+    if (diagnostic.severity === 'info') context.writeStdout(line);
+    else context.writeStderr(line);
+  }
+}

package/src/cli/utils/resolveInfraPersistence.ts

@@ -0,0 +1,22 @@
+import type { InfraDestroyRequest, InfraLedger } from '@ankhorage/contracts/infra';
+
+/*** Convert explicit owned-resource selectors into the canonical persistent deletion policy. */
+export function resolveInfraPersistence(
+  ledger: InfraLedger | undefined,
+  resourceSelectors: readonly string[],
+): InfraDestroyRequest['persistence'] {
+  if (resourceSelectors.length === 0) return { policy: 'retain' };
+  if (ledger === undefined) {
+    throw new Error('Persistent deletion requires stored Infra ownership state.');
+  }
+  const confirmedResources = resourceSelectors.map((selector) => {
+    const resource = ledger.resources.find(
+      ({ identity }) => `${identity.adapter}:${identity.resourceId}` === selector,
+    );
+    if (!resource?.persistent) {
+      throw new Error(`Persistent resource is not owned by this environment: ${selector}`);
+    }
+    return resource.identity;
+  });
+  return { policy: 'delete', confirmedResources };
+}

package/src/cli/utils/writeInfraEnvironmentOutputs.ts

@@ -0,0 +1,24 @@
+import type { InfraOutput } from '@ankhorage/contracts/infra';
+
+import type { InfraCommandContext } from '../../types/infraCli.js';
+
+/*** Print public environment-variable outputs while keeping secret values as references. */
+export function writeInfraEnvironmentOutputs(
+  context: InfraCommandContext,
+  outputs: readonly InfraOutput[],
+): void {
+  for (const output of outputs) {
+    if (output.visibility === 'public' && output.environmentVariable !== undefined) {
+      context.writeStdout(`${output.environmentVariable}=${quoteEnvironmentValue(output.value)}\n`);
+    } else if (output.visibility === 'secret') {
+      context.writeStderr(
+        `Secret output ${output.owner.adapter}/${output.owner.resourceId}/${output.name} remains a reference and was not printed.\n`,
+      );
+    }
+  }
+}
+
+/*** Quote one scalar value for portable shell environment consumption. */
+function quoteEnvironmentValue(value: string | number | boolean): string {
+  return `'${String(value).replaceAll("'", "'\\''")}'`;
+}

package/src/cli/utils/writeInfraStructured.ts

@@ -0,0 +1,11 @@
+import type { InfraCommandContext, ParsedInfraArguments } from '../../types/infraCli.js';
+
+/*** Render one serializable command result in the requested human or compact JSON form. */
+export function writeInfraStructured(
+  context: InfraCommandContext,
+  format: ParsedInfraArguments['format'],
+  value: unknown,
+): void {
+  if (format === 'json') context.writeStdout(`${JSON.stringify(value)}\n`);
+  else context.writeStdout(`${JSON.stringify(value, null, 2)}\n`);
+}