@ankhorage/infra 3.0.0 → 3.2.0

package/src/projectInfrastructure.ts

@@ -25,6 +25,18 @@ export interface InfraSyncResult {
   };
 }
 
+export interface InfraProjectInspection {
+  readonly generated: boolean;
+  readonly generatedAt: string | null;
+  readonly hasDeployment: boolean;
+  readonly target: string | null;
+  readonly trackedFiles: number;
+  readonly warnings: readonly string[];
+  readonly skipped?: {
+    readonly reason: string;
+  };
+}
+
 export async function syncProjectInfrastructure(args: {
   readonly generateInfrastructureImpl?: typeof generateInfrastructure;
   readonly manifest: AppManifest;
@@ -97,6 +109,38 @@ export async function syncProjectInfrastructure(args: {
   };
 }
 
+export async function inspectProjectInfrastructure(args: {
+  readonly manifest: AppManifest;
+  readonly projectId: string;
+  readonly projectPath: string;
+}): Promise<InfraProjectInspection> {
+  const supportWarnings = validateInfraSupport(args.manifest.infra);
+
+  if (args.projectId === STUDIO_PROJECT_ID) {
+    return {
+      generated: false,
+      generatedAt: null,
+      hasDeployment: false,
+      target: null,
+      trackedFiles: 0,
+      warnings: supportWarnings,
+      skipped: {
+        reason: 'apps/studio is the dashboard and is not a generated app target.',
+      },
+    };
+  }
+
+  const ledger = await readInfraLedger(args.projectPath);
+  return {
+    generated: ledger !== null,
+    generatedAt: ledger?.generatedAt ?? null,
+    hasDeployment: args.manifest.infra.deployment !== undefined,
+    target: args.manifest.infra.deployment?.target ?? ledger?.target ?? null,
+    trackedFiles: ledger?.files.length ?? 0,
+    warnings: uniqueStrings([...supportWarnings, ...(ledger?.warnings ?? [])]),
+  };
+}
+
 export async function resolveProjectInfrastructureTarget(args: {
   readonly manifest: AppManifest;
   readonly projectPath: string;

package/src/readme-usage.ts

@@ -1,11 +1,17 @@
 import { runCli } from './cli/bin.js';
 
 /***
- * Provider and CLI surface
+ * Provider, CLI, and project API surface
  *
- * `@ankhorage/infra` owns infra command behavior.
+ * `@ankhorage/infra` owns infrastructure generation, project reconciliation,
+ * and generated lifecycle execution.
  *
- * The same shared command implementation backs both:
+ * The same owner implementation backs CLI consumers and the public
+ * `@ankhorage/infra/project` application-service boundary. Trusted hosts such
+ * as Studio should call that subpath instead of reproducing ledger, generated
+ * file, lifecycle-script, or port-forward configuration semantics.
+ *
+ * CLI entrypoints:
  *
  * - `ankh infra ...`
  * - `bunx @ankhorage/infra ...`
@@ -18,12 +24,10 @@ import { runCli } from './cli/bin.js';
  * - `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>`
+ * Project resolution for the CLI is workspace-aware: pass `[project]`, or
+ * omit it when cwd is already inside `apps/<project>`. Programmatic project
+ * operations accept an explicit project path and do not require Studio or a
+ * particular workspace layout.
  *
  * @usage
  */

package/src/runtime.ts

@@ -3,8 +3,19 @@ import { promises as fs } from 'fs';
 import path from 'path';
 
 import type { InfraCommandContext } from './commandContext.js';
+import { readProjectInfrastructureEnvironment } from './projectEnvironment.js';
 
-export type InfraLifecycleScript = 'down' | 'status' | 'up';
+export type InfraLifecycleScript = 'destroy' | 'down' | 'port-forward' | 'reset' | 'status' | 'up';
+
+export interface InfraScriptOutput {
+  readonly stderr: string;
+  readonly stdout: string;
+}
+
+export interface InfraPortForwardInfo {
+  readonly localPort: number;
+  readonly url: string;
+}
 
 export class InfraScriptExecutionError extends Error {
   readonly exitCode: number | null;
@@ -25,13 +36,16 @@ export class InfraScriptExecutionError extends Error {
   }
 }
 
-export async function runProjectInfraScript(args: {
-  readonly context: InfraCommandContext;
+export async function runProjectInfrastructureLifecycle(args: {
+  readonly args?: readonly string[];
+  readonly env?: Readonly<Record<string, string | undefined>>;
+  readonly onStderr?: (chunk: string) => void;
+  readonly onStdout?: (chunk: string) => void;
   readonly projectId: string;
   readonly projectPath: string;
   readonly script: InfraLifecycleScript;
   readonly target: string;
-}): Promise<void> {
+}): Promise<InfraScriptOutput> {
   const scriptPath = resolveProjectInfraScriptPath(args);
   if (!(await pathExists(scriptPath))) {
     throw new Error(
@@ -39,12 +53,56 @@ export async function runProjectInfraScript(args: {
     );
   }
 
-  await runShellScript({
-    context: args.context,
+  return runShellScript({
+    args: args.args ?? [],
+    env: args.env ?? process.env,
+    onStderr: args.onStderr,
+    onStdout: args.onStdout,
     scriptPath,
   });
 }
 
+export async function resolveProjectInfrastructurePortForward(args: {
+  readonly projectPath: string;
+  readonly target: string;
+}): Promise<InfraPortForwardInfo> {
+  const environment = await readProjectInfrastructureEnvironment({
+    keys: ['APP_PORT_FORWARD_LOCAL_PORT'],
+    projectPath: args.projectPath,
+    target: args.target,
+  });
+  const localPort = parsePositivePort(environment.APP_PORT_FORWARD_LOCAL_PORT);
+
+  if (localPort === null) {
+    throw new Error(
+      'Generated Infra did not provide a valid APP_PORT_FORWARD_LOCAL_PORT. Regenerate infrastructure first.',
+    );
+  }
+
+  return {
+    localPort,
+    url: `http://127.0.0.1:${localPort}`,
+  };
+}
+
+export async function runProjectInfraScript(args: {
+  readonly context: InfraCommandContext;
+  readonly projectId: string;
+  readonly projectPath: string;
+  readonly script: InfraLifecycleScript;
+  readonly target: string;
+}): Promise<void> {
+  await runProjectInfrastructureLifecycle({
+    env: args.context.env,
+    onStderr: (chunk) => args.context.writeStderr(chunk),
+    onStdout: (chunk) => args.context.writeStdout(chunk),
+    projectId: args.projectId,
+    projectPath: args.projectPath,
+    script: args.script,
+    target: args.target,
+  });
+}
+
 export function resolveProjectInfraScriptPath(args: {
   readonly projectPath: string;
   readonly script: InfraLifecycleScript;
@@ -63,60 +121,78 @@ function getInfraScriptsDirectory(target: string): string {
 }
 
 async function runShellScript(args: {
-  readonly context: InfraCommandContext;
+  readonly args: readonly string[];
+  readonly env: Readonly<Record<string, string | undefined>>;
+  readonly onStderr?: (chunk: string) => void;
+  readonly onStdout?: (chunk: string) => void;
   readonly scriptPath: string;
-}): Promise<void> {
-  await new Promise<void>((resolve, reject) => {
-    const child = spawn('bash', [args.scriptPath], {
+}): Promise<InfraScriptOutput> {
+  return new Promise<InfraScriptOutput>((resolve, reject) => {
+    const child = spawn('bash', [args.scriptPath, ...args.args], {
       cwd: path.dirname(args.scriptPath),
-      env: { ...args.context.env },
+      env: { ...args.env },
       stdio: ['ignore', 'pipe', 'pipe'],
     });
 
     let stdout = '';
     let stderr = '';
-
     child.stdout.setEncoding('utf8');
+    child.stderr.setEncoding('utf8');
     child.stdout.on('data', (chunk: string) => {
       stdout += chunk;
-      args.context.writeStdout(chunk);
+      args.onStdout?.(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,
-        }),
-      );
+      args.onStderr?.(chunk);
     });
-
+    child.once('error', (error) =>
+      reject(createStartError(args.scriptPath, error, stdout, stderr)),
+    );
     child.once('close', (exitCode) => {
       if (exitCode === 0) {
-        resolve();
+        resolve({ stderr, stdout });
         return;
       }
-
-      reject(
-        new InfraScriptExecutionError({
-          exitCode,
-          message: `Infra script '${args.scriptPath}' exited with code ${exitCode ?? 'unknown'}.`,
-          stderr,
-          stdout,
-        }),
-      );
+      reject(createExitError(args.scriptPath, exitCode, stdout, stderr));
     });
   });
 }
 
+function createStartError(
+  scriptPath: string,
+  error: Error,
+  stdout: string,
+  stderr: string,
+): InfraScriptExecutionError {
+  return new InfraScriptExecutionError({
+    exitCode: null,
+    message: `Failed to start infra script '${scriptPath}': ${error.message}`,
+    stderr,
+    stdout,
+  });
+}
+
+function createExitError(
+  scriptPath: string,
+  exitCode: number | null,
+  stdout: string,
+  stderr: string,
+): InfraScriptExecutionError {
+  return new InfraScriptExecutionError({
+    exitCode,
+    message: `Infra script '${scriptPath}' exited with code ${exitCode ?? 'unknown'}.`,
+    stderr,
+    stdout,
+  });
+}
+
+function parsePositivePort(value: string | undefined): number | null {
+  if (value === undefined) return null;
+  const parsed = Number.parseInt(value.trim(), 10);
+  return Number.isInteger(parsed) && parsed >= 1 && parsed <= 65_535 ? parsed : null;
+}
+
 async function pathExists(filePath: string): Promise<boolean> {
   try {
     await fs.access(filePath);