@ankhorage/infra 0.2.1 → 0.3.1

package/src/projectInfrastructure.test.ts

@@ -0,0 +1,207 @@
+import { afterEach, describe, expect, test } from 'bun:test';
+import { promises as fs } from 'fs';
+import os from 'os';
+import path from 'path';
+
+import {
+  resolveProjectFile,
+  resolveProjectInfrastructureTarget,
+  syncProjectInfrastructure,
+} from './projectInfrastructure.js';
+import { createAppManifest } from './testSupport.js';
+
+const tempRoots = new Set<string>();
+
+afterEach(async () => {
+  await Promise.all(
+    [...tempRoots].map((rootPath) => fs.rm(rootPath, { force: true, recursive: true })),
+  );
+  tempRoots.clear();
+});
+
+describe('project infrastructure sync', () => {
+  test('writes generated files and the infra ledger', async () => {
+    const projectPath = await fs.mkdtemp(path.join(os.tmpdir(), 'infra-sync-'));
+    tempRoots.add(projectPath);
+
+    const result = await syncProjectInfrastructure({
+      projectId: 'shop',
+      projectPath,
+      manifest: createAppManifest('shop', {
+        deployment: { target: 'minikube', monitoring: false },
+        plugins: [],
+      }),
+      generateInfrastructureImpl() {
+        return {
+          files: [
+            {
+              path: 'infra/minikube/scripts/status.sh',
+              content: '#!/usr/bin/env bash\n',
+              executable: true,
+            },
+            { path: 'infra/minikube/.env.example', content: 'APP_PORT=1\n' },
+          ],
+          warnings: ['generated warning'],
+          meta: {
+            target: 'minikube',
+            providers: [],
+          },
+          dependencies: [],
+        };
+      },
+    });
+
+    expect(result.generated).toBe(2);
+    expect(result.removed).toBe(0);
+    expect(result.warnings).toEqual(['generated warning']);
+    expect(await fs.readFile(path.join(projectPath, 'infra/minikube/.env.example'), 'utf8')).toBe(
+      'APP_PORT=1\n',
+    );
+
+    const ledger = JSON.parse(
+      await fs.readFile(path.join(projectPath, '.ankh/infra-ledger.json'), 'utf8'),
+    ) as {
+      readonly target: string;
+      readonly files: readonly string[];
+    };
+    expect(ledger.target).toBe('minikube');
+    expect(ledger.files).toEqual([
+      'infra/minikube/.env.example',
+      'infra/minikube/scripts/status.sh',
+    ]);
+  });
+
+  test('removes stale files when regeneration shrinks the output set', async () => {
+    const projectPath = await fs.mkdtemp(path.join(os.tmpdir(), 'infra-stale-'));
+    tempRoots.add(projectPath);
+
+    const manifest = createAppManifest('shop', {
+      deployment: { target: 'minikube', monitoring: false },
+      plugins: [],
+    });
+
+    await syncProjectInfrastructure({
+      projectId: 'shop',
+      projectPath,
+      manifest,
+      generateInfrastructureImpl() {
+        return {
+          files: [
+            { path: 'infra/minikube/scripts/status.sh', content: 'first' },
+            { path: 'infra/minikube/scripts/up.sh', content: 'extra' },
+          ],
+          warnings: [],
+          meta: { target: 'minikube', providers: [] },
+          dependencies: [],
+        };
+      },
+    });
+
+    const result = await syncProjectInfrastructure({
+      projectId: 'shop',
+      projectPath,
+      manifest,
+      generateInfrastructureImpl() {
+        return {
+          files: [{ path: 'infra/minikube/scripts/status.sh', content: 'second' }],
+          warnings: [],
+          meta: { target: 'minikube', providers: [] },
+          dependencies: [],
+        };
+      },
+    });
+
+    expect(result.removed).toBe(1);
+    expect(await pathExists(path.join(projectPath, 'infra/minikube/scripts/up.sh'))).toBe(false);
+  });
+
+  test('cleans generated files when deployment is removed', async () => {
+    const projectPath = await fs.mkdtemp(path.join(os.tmpdir(), 'infra-clean-'));
+    tempRoots.add(projectPath);
+
+    await fs.mkdir(path.join(projectPath, '.ankh'), { recursive: true });
+    await fs.mkdir(path.join(projectPath, 'infra/minikube/scripts'), { recursive: true });
+    await fs.writeFile(
+      path.join(projectPath, 'infra/minikube/scripts/status.sh'),
+      'status',
+      'utf8',
+    );
+    await fs.writeFile(
+      path.join(projectPath, '.ankh/infra-ledger.json'),
+      JSON.stringify({
+        schemaVersion: 1,
+        generatedAt: new Date().toISOString(),
+        target: 'minikube',
+        files: ['infra/minikube/scripts/status.sh'],
+        warnings: [],
+      }),
+      'utf8',
+    );
+
+    const result = await syncProjectInfrastructure({
+      projectId: 'shop',
+      projectPath,
+      manifest: createAppManifest('shop', { plugins: [] }),
+    });
+
+    expect(result.generated).toBe(0);
+    expect(result.removed).toBe(1);
+    expect(await pathExists(path.join(projectPath, '.ankh/infra-ledger.json'))).toBe(false);
+  });
+
+  test('preserves apps/studio skip behavior', async () => {
+    const projectPath = await fs.mkdtemp(path.join(os.tmpdir(), 'infra-studio-'));
+    tempRoots.add(projectPath);
+
+    const result = await syncProjectInfrastructure({
+      projectId: 'studio',
+      projectPath,
+      manifest: createAppManifest('studio', {
+        deployment: { target: 'minikube', monitoring: false },
+        plugins: [],
+      }),
+    });
+
+    expect(result.skipped?.reason).toContain('apps/studio');
+  });
+
+  test('resolves targets from the ledger when deployment metadata is absent', async () => {
+    const projectPath = await fs.mkdtemp(path.join(os.tmpdir(), 'infra-target-'));
+    tempRoots.add(projectPath);
+
+    await fs.mkdir(path.join(projectPath, '.ankh'), { recursive: true });
+    await fs.writeFile(
+      path.join(projectPath, '.ankh/infra-ledger.json'),
+      JSON.stringify({
+        schemaVersion: 1,
+        generatedAt: new Date().toISOString(),
+        target: 'minikube',
+        files: [],
+        warnings: [],
+      }),
+      'utf8',
+    );
+
+    const target = await resolveProjectInfrastructureTarget({
+      manifest: createAppManifest('shop', { plugins: [] }),
+      projectPath,
+    });
+
+    expect(target).toBe('minikube');
+  });
+
+  test('rejects generated file paths outside the project root', () => {
+    expect(() => resolveProjectFile('/workspace/project', '../outside.txt')).toThrow(
+      'Invalid infra output path outside project root',
+    );
+  });
+});
+
+async function pathExists(filePath: string): Promise<boolean> {
+  try {
+    await fs.access(filePath);
+    return true;
+  } catch {
+    return false;
+  }
+}

package/src/projectInfrastructure.ts

@@ -0,0 +1,177 @@
+import type { AppManifest } from '@ankhorage/contracts';
+import { promises as fs } from 'fs';
+import path from 'path';
+
+import { generateInfrastructure } from './index.js';
+import { validateInfraSupport } from './infraValidation.js';
+
+const INFRA_LEDGER_RELATIVE_PATH = '.ankh/infra-ledger.json';
+const STUDIO_PROJECT_ID = 'studio';
+
+interface InfraLedger {
+  readonly schemaVersion: 1;
+  readonly generatedAt: string;
+  readonly target: string;
+  readonly files: readonly string[];
+  readonly warnings: readonly string[];
+}
+
+export interface InfraSyncResult {
+  readonly generated: number;
+  readonly removed: number;
+  readonly warnings: readonly string[];
+  readonly skipped?: {
+    readonly reason: string;
+  };
+}
+
+export async function syncProjectInfrastructure(args: {
+  readonly generateInfrastructureImpl?: typeof generateInfrastructure;
+  readonly manifest: AppManifest;
+  readonly projectId: string;
+  readonly projectPath: string;
+}): Promise<InfraSyncResult> {
+  const supportWarnings = validateInfraSupport(args.manifest.infra);
+
+  if (args.projectId === STUDIO_PROJECT_ID) {
+    return {
+      generated: 0,
+      removed: 0,
+      warnings: supportWarnings,
+      skipped: {
+        reason: 'apps/studio is the dashboard and is not a generated app target.',
+      },
+    };
+  }
+
+  const previousLedger = await readInfraLedger(args.projectPath);
+  const previousFiles = new Set(previousLedger?.files ?? []);
+
+  if (args.manifest.infra.deployment === undefined) {
+    const removed = await removeFiles(args.projectPath, previousFiles);
+    await removeInfraLedger(args.projectPath);
+    return {
+      generated: 0,
+      removed,
+      warnings: supportWarnings,
+    };
+  }
+
+  const generated = (args.generateInfrastructureImpl ?? generateInfrastructure)(
+    args.manifest.infra,
+    {
+      namespaceHint: args.projectId,
+      appManifest: args.manifest,
+    },
+  );
+  const combinedWarnings = uniqueStrings([...supportWarnings, ...generated.warnings]);
+  const nextFiles = new Set<string>();
+
+  for (const file of generated.files) {
+    const outputPath = resolveProjectFile(args.projectPath, file.path);
+    await fs.mkdir(path.dirname(outputPath), { recursive: true });
+    await fs.writeFile(outputPath, file.content, 'utf8');
+
+    if (file.executable === true) {
+      await fs.chmod(outputPath, 0o755);
+    }
+
+    nextFiles.add(file.path);
+  }
+
+  const staleFiles = new Set([...previousFiles].filter((filePath) => !nextFiles.has(filePath)));
+  const removed = await removeFiles(args.projectPath, staleFiles);
+
+  await writeInfraLedger(args.projectPath, {
+    schemaVersion: 1,
+    generatedAt: new Date().toISOString(),
+    target: generated.meta.target,
+    files: [...nextFiles].sort(),
+    warnings: combinedWarnings,
+  });
+
+  return {
+    generated: generated.files.length,
+    removed,
+    warnings: combinedWarnings,
+  };
+}
+
+export async function resolveProjectInfrastructureTarget(args: {
+  readonly manifest: AppManifest;
+  readonly projectPath: string;
+}): Promise<string | null> {
+  const manifestTarget = args.manifest.infra.deployment?.target;
+  if (manifestTarget !== undefined) {
+    return manifestTarget;
+  }
+
+  const ledger = await readInfraLedger(args.projectPath);
+  return ledger?.target ?? null;
+}
+
+export function resolveProjectFile(projectPath: string, filePath: string): string {
+  const rootPath = path.resolve(projectPath);
+  const resolvedPath = path.resolve(rootPath, filePath);
+  const relativePath = path.relative(rootPath, resolvedPath);
+
+  if (relativePath.startsWith('..') || path.isAbsolute(relativePath)) {
+    throw new Error(`Invalid infra output path outside project root: ${filePath}`);
+  }
+
+  return resolvedPath;
+}
+
+async function readInfraLedger(projectPath: string): Promise<InfraLedger | null> {
+  const ledgerPath = path.join(projectPath, INFRA_LEDGER_RELATIVE_PATH);
+
+  try {
+    const rawLedger = await fs.readFile(ledgerPath, 'utf8');
+    const parsedLedger: unknown = JSON.parse(rawLedger);
+    return isInfraLedger(parsedLedger) ? parsedLedger : null;
+  } catch {
+    return null;
+  }
+}
+
+async function writeInfraLedger(projectPath: string, ledger: InfraLedger): Promise<void> {
+  const ledgerPath = path.join(projectPath, INFRA_LEDGER_RELATIVE_PATH);
+  await fs.mkdir(path.dirname(ledgerPath), { recursive: true });
+  await fs.writeFile(ledgerPath, `${JSON.stringify(ledger, null, 2)}\n`, 'utf8');
+}
+
+async function removeInfraLedger(projectPath: string): Promise<void> {
+  await fs.rm(path.join(projectPath, INFRA_LEDGER_RELATIVE_PATH), { force: true });
+}
+
+async function removeFiles(projectPath: string, files: ReadonlySet<string>): Promise<number> {
+  let removedFiles = 0;
+
+  for (const filePath of files) {
+    await fs.rm(resolveProjectFile(projectPath, filePath), { force: true });
+    removedFiles += 1;
+  }
+
+  return removedFiles;
+}
+
+function isInfraLedger(value: unknown): value is InfraLedger {
+  return (
+    isRecord(value) &&
+    value.schemaVersion === 1 &&
+    typeof value.generatedAt === 'string' &&
+    typeof value.target === 'string' &&
+    Array.isArray(value.files) &&
+    value.files.every((filePath) => typeof filePath === 'string') &&
+    Array.isArray(value.warnings) &&
+    value.warnings.every((warning) => typeof warning === 'string')
+  );
+}
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === 'object' && value !== null;
+}
+
+function uniqueStrings(values: readonly string[]): readonly string[] {
+  return [...new Set(values)];
+}

package/src/readme-usage.ts

@@ -0,0 +1,30 @@
+import { runCli } from './cli.js';
+
+/***
+ * Provider and CLI surface
+ *
+ * `@ankhorage/infra` owns infra command behavior.
+ *
+ * The same shared command implementation backs both:
+ *
+ * - `ankh infra ...`
+ * - `bunx @ankhorage/infra ...`
+ *
+ * Current command surface:
+ *
+ * - `validate`
+ * - `generate`
+ * - `status`
+ * - `up`
+ * - `down`
+ *
+ * `status` runs the generated live runtime status script for a project.
+ *
+ * Project resolution is project-aware:
+ *
+ * - pass `[project]`, or
+ * - omit it when cwd is already inside `apps/<project>`
+ *
+ * @usage
+ */
+await runCli(['--help']);

package/src/runtime.test.ts

@@ -0,0 +1,124 @@
+import { afterEach, describe, expect, test } from 'bun:test';
+import { promises as fs } from 'fs';
+import os from 'os';
+import path from 'path';
+
+import {
+  InfraScriptExecutionError,
+  resolveProjectInfraScriptPath,
+  runProjectInfraScript,
+} from './runtime.js';
+import { createCapturedCommandContext } from './testSupport.js';
+
+const tempRoots = new Set<string>();
+
+afterEach(async () => {
+  await Promise.all(
+    [...tempRoots].map((rootPath) => fs.rm(rootPath, { force: true, recursive: true })),
+  );
+  tempRoots.clear();
+});
+
+describe('runtime scripts', () => {
+  test('resolves minikube lifecycle scripts under the project infra directory', () => {
+    expect(
+      resolveProjectInfraScriptPath({
+        projectPath: '/workspace/apps/shop',
+        script: 'status',
+        target: 'minikube',
+      }),
+    ).toBe('/workspace/apps/shop/infra/minikube/scripts/status.sh');
+  });
+
+  test('streams script output to the command context', async () => {
+    const projectPath = await fs.mkdtemp(path.join(os.tmpdir(), 'infra-runtime-'));
+    tempRoots.add(projectPath);
+    const scriptDir = path.join(projectPath, 'infra/minikube/scripts');
+    await fs.mkdir(scriptDir, { recursive: true });
+    await fs.writeFile(
+      path.join(scriptDir, 'status.sh'),
+      '#!/usr/bin/env bash\necho status-ok\necho status-warn 1>&2\n',
+      'utf8',
+    );
+
+    const captured = createCapturedCommandContext(projectPath);
+
+    await runProjectInfraScript({
+      context: captured.context,
+      projectId: 'shop',
+      projectPath,
+      script: 'status',
+      target: 'minikube',
+    });
+
+    expect(captured.stdout.value).toContain('status-ok');
+    expect(captured.stderr.value).toContain('status-warn');
+  });
+
+  test('reports missing scripts clearly', async () => {
+    const projectPath = await fs.mkdtemp(path.join(os.tmpdir(), 'infra-missing-'));
+    tempRoots.add(projectPath);
+    const captured = createCapturedCommandContext(projectPath);
+
+    await expectRejectMessage(
+      runProjectInfraScript({
+        context: captured.context,
+        projectId: 'shop',
+        projectPath,
+        script: 'up',
+        target: 'minikube',
+      }),
+      'Run infra generate for project',
+    );
+  });
+
+  test('wraps non-zero script exits in InfraScriptExecutionError', async () => {
+    const projectPath = await fs.mkdtemp(path.join(os.tmpdir(), 'infra-error-'));
+    tempRoots.add(projectPath);
+    const scriptDir = path.join(projectPath, 'infra/minikube/scripts');
+    await fs.mkdir(scriptDir, { recursive: true });
+    await fs.writeFile(
+      path.join(scriptDir, 'down.sh'),
+      '#!/usr/bin/env bash\necho boom 1>&2\nexit 7\n',
+      'utf8',
+    );
+
+    const captured = createCapturedCommandContext(projectPath);
+
+    try {
+      await runProjectInfraScript({
+        context: captured.context,
+        projectId: 'shop',
+        projectPath,
+        script: 'down',
+        target: 'minikube',
+      });
+      throw new Error('Expected runtime script to fail.');
+    } catch (error) {
+      expect(error).toBeInstanceOf(InfraScriptExecutionError);
+    }
+  });
+
+  test('rejects unsupported deployment targets', () => {
+    expect(() =>
+      resolveProjectInfraScriptPath({
+        projectPath: '/workspace/apps/shop',
+        script: 'status',
+        target: 'aws',
+      }),
+    ).toThrow('Unsupported deployment target for infra scripts');
+  });
+});
+
+async function expectRejectMessage(promise: Promise<unknown>, text: string): Promise<void> {
+  let didReject = false;
+
+  try {
+    await promise;
+  } catch (error) {
+    didReject = true;
+    expect(error instanceof Error ? error.message : String(error)).toContain(text);
+  }
+
+  expect(didReject).toBe(true);
+}

package/src/runtime.ts

@@ -0,0 +1,127 @@
+import { spawn } from 'child_process';
+import { promises as fs } from 'fs';
+import path from 'path';
+
+import type { InfraCommandContext } from './commandContext.js';
+
+export type InfraLifecycleScript = 'down' | 'status' | 'up';
+
+export class InfraScriptExecutionError extends Error {
+  readonly exitCode: number | null;
+  readonly stderr: string;
+  readonly stdout: string;
+
+  constructor(args: {
+    readonly exitCode: number | null;
+    readonly message: string;
+    readonly stderr: string;
+    readonly stdout: string;
+  }) {
+    super(args.message);
+    this.name = 'InfraScriptExecutionError';
+    this.exitCode = args.exitCode;
+    this.stderr = args.stderr;
+    this.stdout = args.stdout;
+  }
+}
+
+export async function runProjectInfraScript(args: {
+  readonly context: InfraCommandContext;
+  readonly projectId: string;
+  readonly projectPath: string;
+  readonly script: InfraLifecycleScript;
+  readonly target: string;
+}): Promise<void> {
+  const scriptPath = resolveProjectInfraScriptPath(args);
+  if (!(await pathExists(scriptPath))) {
+    throw new Error(
+      `Infra script not found: ${scriptPath}. Run infra generate for project '${args.projectId}' first.`,
+    );
+  }
+
+  await runShellScript({
+    context: args.context,
+    scriptPath,
+  });
+}
+
+export function resolveProjectInfraScriptPath(args: {
+  readonly projectPath: string;
+  readonly script: InfraLifecycleScript;
+  readonly target: string;
+}): string {
+  return path.join(args.projectPath, getInfraScriptsDirectory(args.target), `${args.script}.sh`);
+}
+
+function getInfraScriptsDirectory(target: string): string {
+  switch (target) {
+    case 'minikube':
+      return 'infra/minikube/scripts';
+    default:
+      throw new Error(`Unsupported deployment target for infra scripts: ${target}`);
+  }
+}
+
+async function runShellScript(args: {
+  readonly context: InfraCommandContext;
+  readonly scriptPath: string;
+}): Promise<void> {
+  await new Promise<void>((resolve, reject) => {
+    const child = spawn('bash', [args.scriptPath], {
+      cwd: path.dirname(args.scriptPath),
+      env: { ...args.context.env },
+      stdio: ['ignore', 'pipe', 'pipe'],
+    });
+
+    let stdout = '';
+    let stderr = '';
+
+    child.stdout.setEncoding('utf8');
+    child.stdout.on('data', (chunk: string) => {
+      stdout += chunk;
+      args.context.writeStdout(chunk);
+    });
+
+    child.stderr.setEncoding('utf8');
+    child.stderr.on('data', (chunk: string) => {
+      stderr += chunk;
+      args.context.writeStderr(chunk);
+    });
+
+    child.once('error', (error) => {
+      reject(
+        new InfraScriptExecutionError({
+          exitCode: null,
+          message: `Failed to start infra script '${args.scriptPath}': ${error.message}`,
+          stderr,
+          stdout,
+        }),
+      );
+    });
+
+    child.once('close', (exitCode) => {
+      if (exitCode === 0) {
+        resolve();
+        return;
+      }
+
+      reject(
+        new InfraScriptExecutionError({
+          exitCode,
+          message: `Infra script '${args.scriptPath}' exited with code ${exitCode ?? 'unknown'}.`,
+          stderr,
+          stdout,
+        }),
+      );
+    });
+  });
+}
+
+async function pathExists(filePath: string): Promise<boolean> {
+  try {
+    await fs.access(filePath);
+    return true;
+  } catch {
+    return false;
+  }
+}