@ankhorage/infra 3.0.0 → 3.1.1

package/CHANGELOG.md

@@ -1,5 +1,17 @@
 # @ankhorage/infra
 
+## 3.1.1
+
+### Patch Changes
+
+- f38e50b: Delegate project `AppManifest` structural validation to the canonical parser published by `@ankhorage/contracts` and remove Infra's duplicate manifest guard implementation.
+
+## 3.1.0
+
+### Minor Changes
+
+- 2e90e4a: Expose the canonical project and lifecycle application-service boundary through `@ankhorage/infra/project`, including project reconciliation, lifecycle execution, and generated port-forward endpoint resolution for trusted consumers such as Studio.
+
 ## 3.0.0
 
 ### Major Changes

package/dist/project/index.d.ts

@@ -0,0 +1,4 @@
+export { type ResolvedInfraProject, resolveInfraProject as resolveInfraWorkspaceProject, } from '../project.js';
+export { type InfraSyncResult, resolveProjectInfrastructureTarget, syncProjectInfrastructure, } from '../projectInfrastructure.js';
+export { type InfraLifecycleScript, type InfraPortForwardInfo, InfraScriptExecutionError, type InfraScriptOutput, resolveProjectInfrastructurePortForward, runProjectInfrastructureLifecycle, } from '../runtime.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/project/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/project/index.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,KAAK,oBAAoB,EACzB,mBAAmB,IAAI,4BAA4B,GACpD,MAAM,eAAe,CAAC;AACvB,OAAO,EACL,KAAK,eAAe,EACpB,kCAAkC,EAClC,yBAAyB,GAC1B,MAAM,6BAA6B,CAAC;AACrC,OAAO,EACL,KAAK,oBAAoB,EACzB,KAAK,oBAAoB,EACzB,yBAAyB,EACzB,KAAK,iBAAiB,EACtB,uCAAuC,EACvC,iCAAiC,GAClC,MAAM,eAAe,CAAC"}

package/dist/project/index.js

@@ -0,0 +1,4 @@
+export { resolveInfraProject as resolveInfraWorkspaceProject, } from '../project.js';
+export { resolveProjectInfrastructureTarget, syncProjectInfrastructure, } from '../projectInfrastructure.js';
+export { InfraScriptExecutionError, resolveProjectInfrastructurePortForward, runProjectInfrastructureLifecycle, } from '../runtime.js';
+//# sourceMappingURL=index.js.map

package/dist/project/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/project/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAEL,mBAAmB,IAAI,4BAA4B,GACpD,MAAM,eAAe,CAAC;AACvB,OAAO,EAEL,kCAAkC,EAClC,yBAAyB,GAC1B,MAAM,6BAA6B,CAAC;AACrC,OAAO,EAGL,yBAAyB,EAEzB,uCAAuC,EACvC,iCAAiC,GAClC,MAAM,eAAe,CAAC","sourcesContent":["export {\n  type ResolvedInfraProject,\n  resolveInfraProject as resolveInfraWorkspaceProject,\n} from '../project.js';\nexport {\n  type InfraSyncResult,\n  resolveProjectInfrastructureTarget,\n  syncProjectInfrastructure,\n} from '../projectInfrastructure.js';\nexport {\n  type InfraLifecycleScript,\n  type InfraPortForwardInfo,\n  InfraScriptExecutionError,\n  type InfraScriptOutput,\n  resolveProjectInfrastructurePortForward,\n  runProjectInfrastructureLifecycle,\n} from '../runtime.js';\n"]}

package/dist/project.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"project.d.ts","sourceRoot":"","sources":["../src/project.ts"],"names":[],"mappings":"AAAA,OAAO,EAAkB,KAAK,WAAW,EAAsB,MAAM,sBAAsB,CAAC;AAI5F,MAAM,WAAW,oBAAoB;IACnC,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,QAAQ,CAAC,QAAQ,EAAE,WAAW,CAAC;IAC/B,QAAQ,CAAC,YAAY,EAAE,MAAM,CAAC;IAC9B,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAC7B,QAAQ,CAAC,aAAa,EAAE,MAAM,CAAC;CAChC;AAED,wBAAsB,mBAAmB,CAAC,OAAO,EAAE;IACjD,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;IACrB,QAAQ,CAAC,SAAS,CAAC,EAAE,MAAM,CAAC;CAC7B,GAAG,OAAO,CAAC,oBAAoB,CAAC,CAqChC"}
+{"version":3,"file":"project.d.ts","sourceRoot":"","sources":["../src/project.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,KAAK,WAAW,EAAiB,MAAM,sBAAsB,CAAC;AAIvE,MAAM,WAAW,oBAAoB;IACnC,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,QAAQ,CAAC,QAAQ,EAAE,WAAW,CAAC;IAC/B,QAAQ,CAAC,YAAY,EAAE,MAAM,CAAC;IAC9B,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAC7B,QAAQ,CAAC,aAAa,EAAE,MAAM,CAAC;CAChC;AAED,wBAAsB,mBAAmB,CAAC,OAAO,EAAE;IACjD,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;IACrB,QAAQ,CAAC,SAAS,CAAC,EAAE,MAAM,CAAC;CAC7B,GAAG,OAAO,CAAC,oBAAoB,CAAC,CAiChC"}

package/dist/project.js

@@ -1,4 +1,4 @@
-import { APP_CATEGORIES } from '@ankhorage/contracts';
+import { isAppManifest } from '@ankhorage/contracts';
 import { promises as fs } from 'fs';
 import path from 'path';
 export async function resolveInfraProject(options) {
@@ -18,11 +18,7 @@ export async function resolveInfraProject(options) {
         throw new Error(`Project '${projectId}' not found.`);
     }
     const manifestPath = path.join(projectPath, 'ankh.config.json');
-    const manifest = await readProjectManifest({
-        manifestPath,
-        projectId,
-        projectPath,
-    });
+    const manifest = await readProjectManifest({ manifestPath, projectId });
     return {
         appsRoot,
         manifest,
@@ -51,9 +47,7 @@ function createFallbackManifest(projectId) {
         },
         themes: [],
         activeThemeId: 'default',
-        infra: {
-            modules: [],
-        },
+        infra: { modules: [] },
         navigator: {
             type: 'stack',
             routes: [{ name: 'index', screenId: 'index' }],
@@ -88,13 +82,11 @@ async function findWorkspaceRoot(startPath) {
     let currentPath = path.resolve(startPath);
     for (;;) {
         const appsRoot = path.join(currentPath, 'apps');
-        if (await isDirectory(appsRoot)) {
+        if (await isDirectory(appsRoot))
             return currentPath;
-        }
         const parentPath = path.dirname(currentPath);
-        if (parentPath === currentPath) {
+        if (parentPath === currentPath)
             return null;
-        }
         currentPath = parentPath;
     }
 }
@@ -119,51 +111,6 @@ function validateExplicitProjectId(projectId) {
     }
     return projectId;
 }
-function isAppManifest(value) {
-    if (!isRecord(value)) {
-        return false;
-    }
-    return (isAppManifestMetadata(value.metadata) &&
-        Array.isArray(value.themes) &&
-        typeof value.activeThemeId === 'string' &&
-        isInfraManifestRecord(value.infra) &&
-        isNavigatorSpec(value.navigator) &&
-        isRecord(value.screens) &&
-        isSettingsRecord(value.settings));
-}
-function isAppManifestMetadata(value) {
-    return (isRecord(value) &&
-        typeof value.name === 'string' &&
-        typeof value.slug === 'string' &&
-        typeof value.version === 'string' &&
-        APP_CATEGORIES.some((category) => category === value.category) &&
-        typeof value.themeId === 'string' &&
-        (value.created === undefined || typeof value.created === 'string') &&
-        (value.updated === undefined || typeof value.updated === 'string'));
-}
-function isInfraManifestRecord(value) {
-    return isRecord(value) && Array.isArray(value.modules);
-}
-function isNavigatorSpec(value) {
-    return (isRecord(value) &&
-        typeof value.type === 'string' &&
-        Array.isArray(value.routes) &&
-        (value.initialRouteName === undefined || typeof value.initialRouteName === 'string'));
-}
-function isSettingsRecord(value) {
-    return (isRecord(value) &&
-        (value.apiBaseUrl === undefined || typeof value.apiBaseUrl === 'string') &&
-        isLocalizationRecord(value.localization));
-}
-function isLocalizationRecord(value) {
-    return (isRecord(value) &&
-        typeof value.defaultLocale === 'string' &&
-        Array.isArray(value.locales) &&
-        value.locales.every((locale) => typeof locale === 'string'));
-}
-function isRecord(value) {
-    return typeof value === 'object' && value !== null;
-}
 async function isDirectory(filePath) {
     try {
         const stat = await fs.stat(filePath);

package/dist/project.js.map

@@ -1 +1 @@
-{"version":3,"file":"project.js","sourceRoot":"","sources":["../src/project.ts"],"names":[],"mappings":"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","sourcesContent":["import { APP_CATEGORIES, type AppManifest, type NavigatorSpec } from '@ankhorage/contracts';\nimport { promises as fs } from 'fs';\nimport path from 'path';\n\nexport interface ResolvedInfraProject {\n  readonly appsRoot: string;\n  readonly manifest: AppManifest;\n  readonly manifestPath: string;\n  readonly projectId: string;\n  readonly projectPath: string;\n  readonly workspaceRoot: string;\n}\n\nexport async function resolveInfraProject(options: {\n  readonly cwd: string;\n  readonly projectId?: string;\n}): Promise<ResolvedInfraProject> {\n  const workspaceRoot = await findWorkspaceRoot(options.cwd);\n  if (workspaceRoot === null) {\n    throw new Error(`Could not find an Ankh workspace root from cwd: ${options.cwd}`);\n  }\n\n  const appsRoot = path.join(workspaceRoot, 'apps');\n  const projectId =\n    options.projectId === undefined\n      ? inferProjectId(options.cwd, appsRoot)\n      : validateExplicitProjectId(options.projectId);\n  if (projectId === null) {\n    throw new Error(\n      'Could not infer a project from cwd. Pass a project id or run the command inside apps/<project>.',\n    );\n  }\n\n  const projectPath = resolveProjectPath(appsRoot, projectId);\n  if (!(await pathExists(projectPath))) {\n    throw new Error(`Project '${projectId}' not found.`);\n  }\n\n  const manifestPath = path.join(projectPath, 'ankh.config.json');\n  const manifest = await readProjectManifest({\n    manifestPath,\n    projectId,\n    projectPath,\n  });\n\n  return {\n    appsRoot,\n    manifest,\n    manifestPath,\n    projectId,\n    projectPath,\n    workspaceRoot,\n  };\n}\n\nfunction resolveProjectPath(appsRoot: string, projectId: string): string {\n  const projectPath = path.resolve(appsRoot, projectId);\n  const appsRootPath = `${path.resolve(appsRoot)}${path.sep}`;\n\n  if (!projectPath.startsWith(appsRootPath)) {\n    throw new Error('Security check failed while resolving the project path.');\n  }\n\n  return projectPath;\n}\n\nfunction createFallbackManifest(projectId: string): AppManifest {\n  return {\n    metadata: {\n      name: projectId,\n      slug: projectId,\n      version: '0.0.0',\n      category: 'developer_tools',\n      themeId: 'default',\n    },\n    themes: [],\n    activeThemeId: 'default',\n    infra: {\n      modules: [],\n    },\n    navigator: {\n      type: 'stack',\n      routes: [{ name: 'index', screenId: 'index' }],\n    },\n    screens: {},\n    settings: {\n      localization: {\n        defaultLocale: 'en',\n        locales: ['en'],\n      },\n    },\n  };\n}\n\nasync function readProjectManifest(args: {\n  readonly manifestPath: string;\n  readonly projectId: string;\n  readonly projectPath: string;\n}): Promise<AppManifest> {\n  if (!(await pathExists(args.manifestPath))) {\n    return createFallbackManifest(args.projectId);\n  }\n\n  const rawManifest = await fs.readFile(args.manifestPath, 'utf8');\n\n  let parsed: unknown;\n  try {\n    parsed = JSON.parse(rawManifest);\n  } catch (error) {\n    throw new Error(\n      `Project manifest is not valid JSON: ${args.manifestPath}: ${getErrorMessage(error)}`,\n      { cause: error },\n    );\n  }\n\n  if (!isAppManifest(parsed)) {\n    throw new Error(`Project manifest has an invalid shape: ${args.manifestPath}`);\n  }\n\n  return parsed;\n}\n\nasync function findWorkspaceRoot(startPath: string): Promise<string | null> {\n  let currentPath = path.resolve(startPath);\n\n  for (;;) {\n    const appsRoot = path.join(currentPath, 'apps');\n    if (await isDirectory(appsRoot)) {\n      return currentPath;\n    }\n\n    const parentPath = path.dirname(currentPath);\n    if (parentPath === currentPath) {\n      return null;\n    }\n\n    currentPath = parentPath;\n  }\n}\n\nfunction inferProjectId(cwd: string, appsRoot: string): string | null {\n  const relativePath = path.relative(path.resolve(appsRoot), path.resolve(cwd));\n  if (relativePath === '' || relativePath.startsWith('..') || path.isAbsolute(relativePath)) {\n    return null;\n  }\n\n  const [projectId] = relativePath.split(path.sep);\n  return projectId === undefined || projectId.length === 0 ? null : path.basename(projectId);\n}\n\nfunction validateExplicitProjectId(projectId: string): string {\n  if (projectId.trim().length === 0) {\n    throw new Error('Invalid project id: expected a single safe project segment.');\n  }\n\n  if (\n    projectId === '.' ||\n    projectId === '..' ||\n    path.isAbsolute(projectId) ||\n    projectId.includes('/') ||\n    projectId.includes('\\\\')\n  ) {\n    throw new Error(`Invalid project id: ${projectId}. Expected a single safe project segment.`);\n  }\n\n  return projectId;\n}\n\nfunction isAppManifest(value: unknown): value is AppManifest {\n  if (!isRecord(value)) {\n    return false;\n  }\n\n  return (\n    isAppManifestMetadata(value.metadata) &&\n    Array.isArray(value.themes) &&\n    typeof value.activeThemeId === 'string' &&\n    isInfraManifestRecord(value.infra) &&\n    isNavigatorSpec(value.navigator) &&\n    isRecord(value.screens) &&\n    isSettingsRecord(value.settings)\n  );\n}\n\nfunction isAppManifestMetadata(value: unknown): value is AppManifest['metadata'] {\n  return (\n    isRecord(value) &&\n    typeof value.name === 'string' &&\n    typeof value.slug === 'string' &&\n    typeof value.version === 'string' &&\n    APP_CATEGORIES.some((category) => category === value.category) &&\n    typeof value.themeId === 'string' &&\n    (value.created === undefined || typeof value.created === 'string') &&\n    (value.updated === undefined || typeof value.updated === 'string')\n  );\n}\n\nfunction isInfraManifestRecord(value: unknown): value is AppManifest['infra'] {\n  return isRecord(value) && Array.isArray(value.modules);\n}\n\nfunction isNavigatorSpec(value: unknown): value is NavigatorSpec {\n  return (\n    isRecord(value) &&\n    typeof value.type === 'string' &&\n    Array.isArray(value.routes) &&\n    (value.initialRouteName === undefined || typeof value.initialRouteName === 'string')\n  );\n}\n\nfunction isSettingsRecord(value: unknown): value is AppManifest['settings'] {\n  return (\n    isRecord(value) &&\n    (value.apiBaseUrl === undefined || typeof value.apiBaseUrl === 'string') &&\n    isLocalizationRecord(value.localization)\n  );\n}\n\nfunction isLocalizationRecord(value: unknown): value is AppManifest['settings']['localization'] {\n  return (\n    isRecord(value) &&\n    typeof value.defaultLocale === 'string' &&\n    Array.isArray(value.locales) &&\n    value.locales.every((locale) => typeof locale === 'string')\n  );\n}\n\nfunction isRecord(value: unknown): value is Record<string, unknown> {\n  return typeof value === 'object' && value !== null;\n}\n\nasync function isDirectory(filePath: string): Promise<boolean> {\n  try {\n    const stat = await fs.stat(filePath);\n    return stat.isDirectory();\n  } catch {\n    return false;\n  }\n}\n\nasync function pathExists(filePath: string): Promise<boolean> {\n  try {\n    await fs.access(filePath);\n    return true;\n  } catch {\n    return false;\n  }\n}\n\nfunction getErrorMessage(error: unknown): string {\n  return error instanceof Error ? error.message : String(error);\n}\n"]}
+{"version":3,"file":"project.js","sourceRoot":"","sources":["../src/project.ts"],"names":[],"mappings":"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","sourcesContent":["import { type AppManifest, isAppManifest } from '@ankhorage/contracts';\nimport { promises as fs } from 'fs';\nimport path from 'path';\n\nexport interface ResolvedInfraProject {\n  readonly appsRoot: string;\n  readonly manifest: AppManifest;\n  readonly manifestPath: string;\n  readonly projectId: string;\n  readonly projectPath: string;\n  readonly workspaceRoot: string;\n}\n\nexport async function resolveInfraProject(options: {\n  readonly cwd: string;\n  readonly projectId?: string;\n}): Promise<ResolvedInfraProject> {\n  const workspaceRoot = await findWorkspaceRoot(options.cwd);\n  if (workspaceRoot === null) {\n    throw new Error(`Could not find an Ankh workspace root from cwd: ${options.cwd}`);\n  }\n\n  const appsRoot = path.join(workspaceRoot, 'apps');\n  const projectId =\n    options.projectId === undefined\n      ? inferProjectId(options.cwd, appsRoot)\n      : validateExplicitProjectId(options.projectId);\n  if (projectId === null) {\n    throw new Error(\n      'Could not infer a project from cwd. Pass a project id or run the command inside apps/<project>.',\n    );\n  }\n\n  const projectPath = resolveProjectPath(appsRoot, projectId);\n  if (!(await pathExists(projectPath))) {\n    throw new Error(`Project '${projectId}' not found.`);\n  }\n\n  const manifestPath = path.join(projectPath, 'ankh.config.json');\n  const manifest = await readProjectManifest({ manifestPath, projectId });\n\n  return {\n    appsRoot,\n    manifest,\n    manifestPath,\n    projectId,\n    projectPath,\n    workspaceRoot,\n  };\n}\n\nfunction resolveProjectPath(appsRoot: string, projectId: string): string {\n  const projectPath = path.resolve(appsRoot, projectId);\n  const appsRootPath = `${path.resolve(appsRoot)}${path.sep}`;\n\n  if (!projectPath.startsWith(appsRootPath)) {\n    throw new Error('Security check failed while resolving the project path.');\n  }\n\n  return projectPath;\n}\n\nfunction createFallbackManifest(projectId: string): AppManifest {\n  return {\n    metadata: {\n      name: projectId,\n      slug: projectId,\n      version: '0.0.0',\n      category: 'developer_tools',\n      themeId: 'default',\n    },\n    themes: [],\n    activeThemeId: 'default',\n    infra: { modules: [] },\n    navigator: {\n      type: 'stack',\n      routes: [{ name: 'index', screenId: 'index' }],\n    },\n    screens: {},\n    settings: {\n      localization: {\n        defaultLocale: 'en',\n        locales: ['en'],\n      },\n    },\n  };\n}\n\nasync function readProjectManifest(args: {\n  readonly manifestPath: string;\n  readonly projectId: string;\n}): Promise<AppManifest> {\n  if (!(await pathExists(args.manifestPath))) {\n    return createFallbackManifest(args.projectId);\n  }\n\n  const rawManifest = await fs.readFile(args.manifestPath, 'utf8');\n  let parsed: unknown;\n\n  try {\n    parsed = JSON.parse(rawManifest);\n  } catch (error) {\n    throw new Error(\n      `Project manifest is not valid JSON: ${args.manifestPath}: ${getErrorMessage(error)}`,\n      { cause: error },\n    );\n  }\n\n  if (!isAppManifest(parsed)) {\n    throw new Error(`Project manifest has an invalid shape: ${args.manifestPath}`);\n  }\n\n  return parsed;\n}\n\nasync function findWorkspaceRoot(startPath: string): Promise<string | null> {\n  let currentPath = path.resolve(startPath);\n\n  for (;;) {\n    const appsRoot = path.join(currentPath, 'apps');\n    if (await isDirectory(appsRoot)) return currentPath;\n\n    const parentPath = path.dirname(currentPath);\n    if (parentPath === currentPath) return null;\n    currentPath = parentPath;\n  }\n}\n\nfunction inferProjectId(cwd: string, appsRoot: string): string | null {\n  const relativePath = path.relative(path.resolve(appsRoot), path.resolve(cwd));\n  if (relativePath === '' || relativePath.startsWith('..') || path.isAbsolute(relativePath)) {\n    return null;\n  }\n\n  const [projectId] = relativePath.split(path.sep);\n  return projectId === undefined || projectId.length === 0 ? null : path.basename(projectId);\n}\n\nfunction validateExplicitProjectId(projectId: string): string {\n  if (projectId.trim().length === 0) {\n    throw new Error('Invalid project id: expected a single safe project segment.');\n  }\n\n  if (\n    projectId === '.' ||\n    projectId === '..' ||\n    path.isAbsolute(projectId) ||\n    projectId.includes('/') ||\n    projectId.includes('\\\\')\n  ) {\n    throw new Error(`Invalid project id: ${projectId}. Expected a single safe project segment.`);\n  }\n\n  return projectId;\n}\n\nasync function isDirectory(filePath: string): Promise<boolean> {\n  try {\n    const stat = await fs.stat(filePath);\n    return stat.isDirectory();\n  } catch {\n    return false;\n  }\n}\n\nasync function pathExists(filePath: string): Promise<boolean> {\n  try {\n    await fs.access(filePath);\n    return true;\n  } catch {\n    return false;\n  }\n}\n\nfunction getErrorMessage(error: unknown): string {\n  return error instanceof Error ? error.message : String(error);\n}\n"]}

package/dist/readme-usage.js

@@ -1,10 +1,16 @@
 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 ...`
@@ -17,12 +23,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/dist/readme-usage.js.map

@@ -1 +1 @@
-{"version":3,"file":"readme-usage.js","sourceRoot":"","sources":["../src/readme-usage.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,MAAM,EAAE,MAAM,cAAc,CAAC;AAEtC;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AACH,MAAM,MAAM,CAAC,CAAC,QAAQ,CAAC,CAAC,CAAC","sourcesContent":["import { runCli } from './cli/bin.js';\n\n/***\n * Provider and CLI surface\n *\n * `@ankhorage/infra` owns infra command behavior.\n *\n * The same shared command implementation backs both:\n *\n * - `ankh infra ...`\n * - `bunx @ankhorage/infra ...`\n *\n * Current command surface:\n *\n * - `validate`\n * - `generate`\n * - `status`\n * - `up`\n * - `down`\n *\n * `status` runs the generated live runtime status script for a project.\n *\n * Project resolution is project-aware:\n *\n * - pass `[project]`, or\n * - omit it when cwd is already inside `apps/<project>`\n *\n * @usage\n */\nawait runCli(['--help']);\n"]}
+{"version":3,"file":"readme-usage.js","sourceRoot":"","sources":["../src/readme-usage.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,MAAM,EAAE,MAAM,cAAc,CAAC;AAEtC;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8BG;AACH,MAAM,MAAM,CAAC,CAAC,QAAQ,CAAC,CAAC,CAAC","sourcesContent":["import { runCli } from './cli/bin.js';\n\n/***\n * Provider, CLI, and project API surface\n *\n * `@ankhorage/infra` owns infrastructure generation, project reconciliation,\n * and generated lifecycle execution.\n *\n * The same owner implementation backs CLI consumers and the public\n * `@ankhorage/infra/project` application-service boundary. Trusted hosts such\n * as Studio should call that subpath instead of reproducing ledger, generated\n * file, lifecycle-script, or port-forward configuration semantics.\n *\n * CLI entrypoints:\n *\n * - `ankh infra ...`\n * - `bunx @ankhorage/infra ...`\n *\n * Current command surface:\n *\n * - `validate`\n * - `generate`\n * - `status`\n * - `up`\n * - `down`\n *\n * Project resolution for the CLI is workspace-aware: pass `[project]`, or\n * omit it when cwd is already inside `apps/<project>`. Programmatic project\n * operations accept an explicit project path and do not require Studio or a\n * particular workspace layout.\n *\n * @usage\n */\nawait runCli(['--help']);\n"]}

package/dist/runtime.d.ts

@@ -1,5 +1,13 @@
 import type { InfraCommandContext } from './commandContext.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 declare class InfraScriptExecutionError extends Error {
     readonly exitCode: number | null;
     readonly stderr: string;
@@ -11,6 +19,20 @@ export declare class InfraScriptExecutionError extends Error {
         readonly stdout: string;
     });
 }
+export declare 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<InfraScriptOutput>;
+export declare function resolveProjectInfrastructurePortForward(args: {
+    readonly projectPath: string;
+    readonly target: string;
+}): Promise<InfraPortForwardInfo>;
 export declare function runProjectInfraScript(args: {
     readonly context: InfraCommandContext;
     readonly projectId: string;

package/dist/runtime.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"runtime.d.ts","sourceRoot":"","sources":["../src/runtime.ts"],"names":[],"mappings":"AAIA,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,qBAAqB,CAAC;AAE/D,MAAM,MAAM,oBAAoB,GAAG,MAAM,GAAG,QAAQ,GAAG,IAAI,CAAC;AAE5D,qBAAa,yBAA0B,SAAQ,KAAK;IAClD,QAAQ,CAAC,QAAQ,EAAE,MAAM,GAAG,IAAI,CAAC;IACjC,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;gBAEZ,IAAI,EAAE;QAChB,QAAQ,CAAC,QAAQ,EAAE,MAAM,GAAG,IAAI,CAAC;QACjC,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;QACzB,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;QACxB,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;KACzB;CAOF;AAED,wBAAsB,qBAAqB,CAAC,IAAI,EAAE;IAChD,QAAQ,CAAC,OAAO,EAAE,mBAAmB,CAAC;IACtC,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAC7B,QAAQ,CAAC,MAAM,EAAE,oBAAoB,CAAC;IACtC,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;CACzB,GAAG,OAAO,CAAC,IAAI,CAAC,CAYhB;AAED,wBAAgB,6BAA6B,CAAC,IAAI,EAAE;IAClD,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAC7B,QAAQ,CAAC,MAAM,EAAE,oBAAoB,CAAC;IACtC,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;CACzB,GAAG,MAAM,CAET"}
+{"version":3,"file":"runtime.d.ts","sourceRoot":"","sources":["../src/runtime.ts"],"names":[],"mappings":"AAIA,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,qBAAqB,CAAC;AAE/D,MAAM,MAAM,oBAAoB,GAAG,SAAS,GAAG,MAAM,GAAG,cAAc,GAAG,OAAO,GAAG,QAAQ,GAAG,IAAI,CAAC;AAEnG,MAAM,WAAW,iBAAiB;IAChC,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;CACzB;AAED,MAAM,WAAW,oBAAoB;IACnC,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;CACtB;AAED,qBAAa,yBAA0B,SAAQ,KAAK;IAClD,QAAQ,CAAC,QAAQ,EAAE,MAAM,GAAG,IAAI,CAAC;IACjC,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;gBAEZ,IAAI,EAAE;QAChB,QAAQ,CAAC,QAAQ,EAAE,MAAM,GAAG,IAAI,CAAC;QACjC,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;QACzB,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;QACxB,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;KACzB;CAOF;AAED,wBAAsB,iCAAiC,CAAC,IAAI,EAAE;IAC5D,QAAQ,CAAC,IAAI,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;IAClC,QAAQ,CAAC,GAAG,CAAC,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,SAAS,CAAC,CAAC,CAAC;IAC5D,QAAQ,CAAC,QAAQ,CAAC,EAAE,CAAC,KAAK,EAAE,MAAM,KAAK,IAAI,CAAC;IAC5C,QAAQ,CAAC,QAAQ,CAAC,EAAE,CAAC,KAAK,EAAE,MAAM,KAAK,IAAI,CAAC;IAC5C,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAC7B,QAAQ,CAAC,MAAM,EAAE,oBAAoB,CAAC;IACtC,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;CACzB,GAAG,OAAO,CAAC,iBAAiB,CAAC,CAe7B;AAED,wBAAsB,uCAAuC,CAAC,IAAI,EAAE;IAClE,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAC7B,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;CACzB,GAAG,OAAO,CAAC,oBAAoB,CAAC,CAkBhC;AAED,wBAAsB,qBAAqB,CAAC,IAAI,EAAE;IAChD,QAAQ,CAAC,OAAO,EAAE,mBAAmB,CAAC;IACtC,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAC7B,QAAQ,CAAC,MAAM,EAAE,oBAAoB,CAAC;IACtC,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;CACzB,GAAG,OAAO,CAAC,IAAI,CAAC,CAUhB;AAED,wBAAgB,6BAA6B,CAAC,IAAI,EAAE;IAClD,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAC7B,QAAQ,CAAC,MAAM,EAAE,oBAAoB,CAAC;IACtC,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;CACzB,GAAG,MAAM,CAET"}

package/dist/runtime.js

@@ -13,16 +13,45 @@ export class InfraScriptExecutionError extends Error {
         this.stdout = args.stdout;
     }
 }
-export async function runProjectInfraScript(args) {
+export async function runProjectInfrastructureLifecycle(args) {
     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,
+    return runShellScript({
+        args: args.args ?? [],
+        env: args.env ?? process.env,
+        onStderr: args.onStderr,
+        onStdout: args.onStdout,
         scriptPath,
     });
 }
+export async function resolveProjectInfrastructurePortForward(args) {
+    const infraRoot = path.join(args.projectPath, 'infra', args.target);
+    const envPath = path.join(infraRoot, '.env');
+    const fallbackEnvPath = path.join(infraRoot, '.env.example');
+    const sourcePath = (await pathExists(envPath)) ? envPath : fallbackEnvPath;
+    const env = await readSimpleEnvMap(sourcePath);
+    const localPort = parsePositivePort(env.get('APP_PORT_FORWARD_LOCAL_PORT'));
+    if (localPort === null) {
+        throw new Error(`Generated Infra did not provide a valid APP_PORT_FORWARD_LOCAL_PORT in ${sourcePath}. Regenerate infrastructure first.`);
+    }
+    return {
+        localPort,
+        url: `http://127.0.0.1:${localPort}`,
+    };
+}
+export async function runProjectInfraScript(args) {
+    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) {
     return path.join(args.projectPath, getInfraScriptsDirectory(args.target), `${args.script}.sh`);
 }
@@ -35,46 +64,75 @@ function getInfraScriptsDirectory(target) {
     }
 }
 async function runShellScript(args) {
-    await new Promise((resolve, reject) => {
-        const child = spawn('bash', [args.scriptPath], {
+    return new Promise((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) => {
             stdout += chunk;
-            args.context.writeStdout(chunk);
+            args.onStdout?.(chunk);
         });
-        child.stderr.setEncoding('utf8');
         child.stderr.on('data', (chunk) => {
             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, error, stdout, stderr) {
+    return new InfraScriptExecutionError({
+        exitCode: null,
+        message: `Failed to start infra script '${scriptPath}': ${error.message}`,
+        stderr,
+        stdout,
+    });
+}
+function createExitError(scriptPath, exitCode, stdout, stderr) {
+    return new InfraScriptExecutionError({
+        exitCode,
+        message: `Infra script '${scriptPath}' exited with code ${exitCode ?? 'unknown'}.`,
+        stderr,
+        stdout,
+    });
+}
+async function readSimpleEnvMap(filePath) {
+    const out = new Map();
+    const content = await fs.readFile(filePath, 'utf8');
+    for (const line of content.split(/\r?\n/u)) {
+        const trimmed = line.trim();
+        if (!trimmed || trimmed.startsWith('#'))
+            continue;
+        const separator = trimmed.indexOf('=');
+        if (separator <= 0)
+            continue;
+        const key = trimmed.slice(0, separator).trim();
+        const value = trimmed
+            .slice(separator + 1)
+            .trim()
+            .replace(/^['"]|['"]$/g, '');
+        out.set(key, value);
+    }
+    return out;
+}
+function parsePositivePort(value) {
+    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) {
     try {
         await fs.access(filePath);

package/dist/runtime.js.map

@@ -1 +1 @@
-{"version":3,"file":"runtime.js","sourceRoot":"","sources":["../src/runtime.ts"],"names":[],"mappings":"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","sourcesContent":["import { spawn } from 'child_process';\nimport { promises as fs } from 'fs';\nimport path from 'path';\n\nimport type { InfraCommandContext } from './commandContext.js';\n\nexport type InfraLifecycleScript = 'down' | 'status' | 'up';\n\nexport class InfraScriptExecutionError extends Error {\n  readonly exitCode: number | null;\n  readonly stderr: string;\n  readonly stdout: string;\n\n  constructor(args: {\n    readonly exitCode: number | null;\n    readonly message: string;\n    readonly stderr: string;\n    readonly stdout: string;\n  }) {\n    super(args.message);\n    this.name = 'InfraScriptExecutionError';\n    this.exitCode = args.exitCode;\n    this.stderr = args.stderr;\n    this.stdout = args.stdout;\n  }\n}\n\nexport async function runProjectInfraScript(args: {\n  readonly context: InfraCommandContext;\n  readonly projectId: string;\n  readonly projectPath: string;\n  readonly script: InfraLifecycleScript;\n  readonly target: string;\n}): Promise<void> {\n  const scriptPath = resolveProjectInfraScriptPath(args);\n  if (!(await pathExists(scriptPath))) {\n    throw new Error(\n      `Infra script not found: ${scriptPath}. Run infra generate for project '${args.projectId}' first.`,\n    );\n  }\n\n  await runShellScript({\n    context: args.context,\n    scriptPath,\n  });\n}\n\nexport function resolveProjectInfraScriptPath(args: {\n  readonly projectPath: string;\n  readonly script: InfraLifecycleScript;\n  readonly target: string;\n}): string {\n  return path.join(args.projectPath, getInfraScriptsDirectory(args.target), `${args.script}.sh`);\n}\n\nfunction getInfraScriptsDirectory(target: string): string {\n  switch (target) {\n    case 'minikube':\n      return 'infra/minikube/scripts';\n    default:\n      throw new Error(`Unsupported deployment target for infra scripts: ${target}`);\n  }\n}\n\nasync function runShellScript(args: {\n  readonly context: InfraCommandContext;\n  readonly scriptPath: string;\n}): Promise<void> {\n  await new Promise<void>((resolve, reject) => {\n    const child = spawn('bash', [args.scriptPath], {\n      cwd: path.dirname(args.scriptPath),\n      env: { ...args.context.env },\n      stdio: ['ignore', 'pipe', 'pipe'],\n    });\n\n    let stdout = '';\n    let stderr = '';\n\n    child.stdout.setEncoding('utf8');\n    child.stdout.on('data', (chunk: string) => {\n      stdout += chunk;\n      args.context.writeStdout(chunk);\n    });\n\n    child.stderr.setEncoding('utf8');\n    child.stderr.on('data', (chunk: string) => {\n      stderr += chunk;\n      args.context.writeStderr(chunk);\n    });\n\n    child.once('error', (error) => {\n      reject(\n        new InfraScriptExecutionError({\n          exitCode: null,\n          message: `Failed to start infra script '${args.scriptPath}': ${error.message}`,\n          stderr,\n          stdout,\n        }),\n      );\n    });\n\n    child.once('close', (exitCode) => {\n      if (exitCode === 0) {\n        resolve();\n        return;\n      }\n\n      reject(\n        new InfraScriptExecutionError({\n          exitCode,\n          message: `Infra script '${args.scriptPath}' exited with code ${exitCode ?? 'unknown'}.`,\n          stderr,\n          stdout,\n        }),\n      );\n    });\n  });\n}\n\nasync function pathExists(filePath: string): Promise<boolean> {\n  try {\n    await fs.access(filePath);\n    return true;\n  } catch {\n    return false;\n  }\n}\n"]}
+{"version":3,"file":"runtime.js","sourceRoot":"","sources":["../src/runtime.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,KAAK,EAAE,MAAM,eAAe,CAAC;AACtC,OAAO,EAAE,QAAQ,IAAI,EAAE,EAAE,MAAM,IAAI,CAAC;AACpC,OAAO,IAAI,MAAM,MAAM,CAAC;AAgBxB,MAAM,OAAO,yBAA0B,SAAQ,KAAK;IACzC,QAAQ,CAAgB;IACxB,MAAM,CAAS;IACf,MAAM,CAAS;IAExB,YAAY,IAKX;QACC,KAAK,CAAC,IAAI,CAAC,OAAO,CAAC,CAAC;QACpB,IAAI,CAAC,IAAI,GAAG,2BAA2B,CAAC;QACxC,IAAI,CAAC,QAAQ,GAAG,IAAI,CAAC,QAAQ,CAAC;QAC9B,IAAI,CAAC,MAAM,GAAG,IAAI,CAAC,MAAM,CAAC;QAC1B,IAAI,CAAC,MAAM,GAAG,IAAI,CAAC,MAAM,CAAC;IAC5B,CAAC;CACF;AAED,MAAM,CAAC,KAAK,UAAU,iCAAiC,CAAC,IASvD;IACC,MAAM,UAAU,GAAG,6BAA6B,CAAC,IAAI,CAAC,CAAC;IACvD,IAAI,CAAC,CAAC,MAAM,UAAU,CAAC,UAAU,CAAC,CAAC,EAAE,CAAC;QACpC,MAAM,IAAI,KAAK,CACb,2BAA2B,UAAU,qCAAqC,IAAI,CAAC,SAAS,UAAU,CACnG,CAAC;IACJ,CAAC;IAED,OAAO,cAAc,CAAC;QACpB,IAAI,EAAE,IAAI,CAAC,IAAI,IAAI,EAAE;QACrB,GAAG,EAAE,IAAI,CAAC,GAAG,IAAI,OAAO,CAAC,GAAG;QAC5B,QAAQ,EAAE,IAAI,CAAC,QAAQ;QACvB,QAAQ,EAAE,IAAI,CAAC,QAAQ;QACvB,UAAU;KACX,CAAC,CAAC;AACL,CAAC;AAED,MAAM,CAAC,KAAK,UAAU,uCAAuC,CAAC,IAG7D;IACC,MAAM,SAAS,GAAG,IAAI,CAAC,IAAI,CAAC,IAAI,CAAC,WAAW,EAAE,OAAO,EAAE,IAAI,CAAC,MAAM,CAAC,CAAC;IACpE,MAAM,OAAO,GAAG,IAAI,CAAC,IAAI,CAAC,SAAS,EAAE,MAAM,CAAC,CAAC;IAC7C,MAAM,eAAe,GAAG,IAAI,CAAC,IAAI,CAAC,SAAS,EAAE,cAAc,CAAC,CAAC;IAC7D,MAAM,UAAU,GAAG,CAAC,MAAM,UAAU,CAAC,OAAO,CAAC,CAAC,CAAC,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC,eAAe,CAAC;IAC3E,MAAM,GAAG,GAAG,MAAM,gBAAgB,CAAC,UAAU,CAAC,CAAC;IAC/C,MAAM,SAAS,GAAG,iBAAiB,CAAC,GAAG,CAAC,GAAG,CAAC,6BAA6B,CAAC,CAAC,CAAC;IAE5E,IAAI,SAAS,KAAK,IAAI,EAAE,CAAC;QACvB,MAAM,IAAI,KAAK,CACb,0EAA0E,UAAU,oCAAoC,CACzH,CAAC;IACJ,CAAC;IAED,OAAO;QACL,SAAS;QACT,GAAG,EAAE,oBAAoB,SAAS,EAAE;KACrC,CAAC;AACJ,CAAC;AAED,MAAM,CAAC,KAAK,UAAU,qBAAqB,CAAC,IAM3C;IACC,MAAM,iCAAiC,CAAC;QACtC,GAAG,EAAE,IAAI,CAAC,OAAO,CAAC,GAAG;QACrB,QAAQ,EAAE,CAAC,KAAK,EAAE,EAAE,CAAC,IAAI,CAAC,OAAO,CAAC,WAAW,CAAC,KAAK,CAAC;QACpD,QAAQ,EAAE,CAAC,KAAK,EAAE,EAAE,CAAC,IAAI,CAAC,OAAO,CAAC,WAAW,CAAC,KAAK,CAAC;QACpD,SAAS,EAAE,IAAI,CAAC,SAAS;QACzB,WAAW,EAAE,IAAI,CAAC,WAAW;QAC7B,MAAM,EAAE,IAAI,CAAC,MAAM;QACnB,MAAM,EAAE,IAAI,CAAC,MAAM;KACpB,CAAC,CAAC;AACL,CAAC;AAED,MAAM,UAAU,6BAA6B,CAAC,IAI7C;IACC,OAAO,IAAI,CAAC,IAAI,CAAC,IAAI,CAAC,WAAW,EAAE,wBAAwB,CAAC,IAAI,CAAC,MAAM,CAAC,EAAE,GAAG,IAAI,CAAC,MAAM,KAAK,CAAC,CAAC;AACjG,CAAC;AAED,SAAS,wBAAwB,CAAC,MAAc;IAC9C,QAAQ,MAAM,EAAE,CAAC;QACf,KAAK,UAAU;YACb,OAAO,wBAAwB,CAAC;QAClC;YACE,MAAM,IAAI,KAAK,CAAC,oDAAoD,MAAM,EAAE,CAAC,CAAC;IAClF,CAAC;AACH,CAAC;AAED,KAAK,UAAU,cAAc,CAAC,IAM7B;IACC,OAAO,IAAI,OAAO,CAAoB,CAAC,OAAO,EAAE,MAAM,EAAE,EAAE;QACxD,MAAM,KAAK,GAAG,KAAK,CAAC,MAAM,EAAE,CAAC,IAAI,CAAC,UAAU,EAAE,GAAG,IAAI,CAAC,IAAI,CAAC,EAAE;YAC3D,GAAG,EAAE,IAAI,CAAC,OAAO,CAAC,IAAI,CAAC,UAAU,CAAC;YAClC,GAAG,EAAE,EAAE,GAAG,IAAI,CAAC,GAAG,EAAE;YACpB,KAAK,EAAE,CAAC,QAAQ,EAAE,MAAM,EAAE,MAAM,CAAC;SAClC,CAAC,CAAC;QAEH,IAAI,MAAM,GAAG,EAAE,CAAC;QAChB,IAAI,MAAM,GAAG,EAAE,CAAC;QAChB,KAAK,CAAC,MAAM,CAAC,WAAW,CAAC,MAAM,CAAC,CAAC;QACjC,KAAK,CAAC,MAAM,CAAC,WAAW,CAAC,MAAM,CAAC,CAAC;QACjC,KAAK,CAAC,MAAM,CAAC,EAAE,CAAC,MAAM,EAAE,CAAC,KAAa,EAAE,EAAE;YACxC,MAAM,IAAI,KAAK,CAAC;YAChB,IAAI,CAAC,QAAQ,EAAE,CAAC,KAAK,CAAC,CAAC;QACzB,CAAC,CAAC,CAAC;QACH,KAAK,CAAC,MAAM,CAAC,EAAE,CAAC,MAAM,EAAE,CAAC,KAAa,EAAE,EAAE;YACxC,MAAM,IAAI,KAAK,CAAC;YAChB,IAAI,CAAC,QAAQ,EAAE,CAAC,KAAK,CAAC,CAAC;QACzB,CAAC,CAAC,CAAC;QACH,KAAK,CAAC,IAAI,CAAC,OAAO,EAAE,CAAC,KAAK,EAAE,EAAE,CAC5B,MAAM,CAAC,gBAAgB,CAAC,IAAI,CAAC,UAAU,EAAE,KAAK,EAAE,MAAM,EAAE,MAAM,CAAC,CAAC,CACjE,CAAC;QACF,KAAK,CAAC,IAAI,CAAC,OAAO,EAAE,CAAC,QAAQ,EAAE,EAAE;YAC/B,IAAI,QAAQ,KAAK,CAAC,EAAE,CAAC;gBACnB,OAAO,CAAC,EAAE,MAAM,EAAE,MAAM,EAAE,CAAC,CAAC;gBAC5B,OAAO;YACT,CAAC;YACD,MAAM,CAAC,eAAe,CAAC,IAAI,CAAC,UAAU,EAAE,QAAQ,EAAE,MAAM,EAAE,MAAM,CAAC,CAAC,CAAC;QACrE,CAAC,CAAC,CAAC;IACL,CAAC,CAAC,CAAC;AACL,CAAC;AAED,SAAS,gBAAgB,CACvB,UAAkB,EAClB,KAAY,EACZ,MAAc,EACd,MAAc;IAEd,OAAO,IAAI,yBAAyB,CAAC;QACnC,QAAQ,EAAE,IAAI;QACd,OAAO,EAAE,iCAAiC,UAAU,MAAM,KAAK,CAAC,OAAO,EAAE;QACzE,MAAM;QACN,MAAM;KACP,CAAC,CAAC;AACL,CAAC;AAED,SAAS,eAAe,CACtB,UAAkB,EAClB,QAAuB,EACvB,MAAc,EACd,MAAc;IAEd,OAAO,IAAI,yBAAyB,CAAC;QACnC,QAAQ;QACR,OAAO,EAAE,iBAAiB,UAAU,sBAAsB,QAAQ,IAAI,SAAS,GAAG;QAClF,MAAM;QACN,MAAM;KACP,CAAC,CAAC;AACL,CAAC;AAED,KAAK,UAAU,gBAAgB,CAAC,QAAgB;IAC9C,MAAM,GAAG,GAAG,IAAI,GAAG,EAAkB,CAAC;IACtC,MAAM,OAAO,GAAG,MAAM,EAAE,CAAC,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC,CAAC;IACpD,KAAK,MAAM,IAAI,IAAI,OAAO,CAAC,KAAK,CAAC,QAAQ,CAAC,EAAE,CAAC;QAC3C,MAAM,OAAO,GAAG,IAAI,CAAC,IAAI,EAAE,CAAC;QAC5B,IAAI,CAAC,OAAO,IAAI,OAAO,CAAC,UAAU,CAAC,GAAG,CAAC;YAAE,SAAS;QAClD,MAAM,SAAS,GAAG,OAAO,CAAC,OAAO,CAAC,GAAG,CAAC,CAAC;QACvC,IAAI,SAAS,IAAI,CAAC;YAAE,SAAS;QAC7B,MAAM,GAAG,GAAG,OAAO,CAAC,KAAK,CAAC,CAAC,EAAE,SAAS,CAAC,CAAC,IAAI,EAAE,CAAC;QAC/C,MAAM,KAAK,GAAG,OAAO;aAClB,KAAK,CAAC,SAAS,GAAG,CAAC,CAAC;aACpB,IAAI,EAAE;aACN,OAAO,CAAC,cAAc,EAAE,EAAE,CAAC,CAAC;QAC/B,GAAG,CAAC,GAAG,CAAC,GAAG,EAAE,KAAK,CAAC,CAAC;IACtB,CAAC;IACD,OAAO,GAAG,CAAC;AACb,CAAC;AAED,SAAS,iBAAiB,CAAC,KAAyB;IAClD,IAAI,KAAK,KAAK,SAAS;QAAE,OAAO,IAAI,CAAC;IACrC,MAAM,MAAM,GAAG,MAAM,CAAC,QAAQ,CAAC,KAAK,CAAC,IAAI,EAAE,EAAE,EAAE,CAAC,CAAC;IACjD,OAAO,MAAM,CAAC,SAAS,CAAC,MAAM,CAAC,IAAI,MAAM,IAAI,CAAC,IAAI,MAAM,IAAI,MAAM,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,IAAI,CAAC;AACrF,CAAC;AAED,KAAK,UAAU,UAAU,CAAC,QAAgB;IACxC,IAAI,CAAC;QACH,MAAM,EAAE,CAAC,MAAM,CAAC,QAAQ,CAAC,CAAC;QAC1B,OAAO,IAAI,CAAC;IACd,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,KAAK,CAAC;IACf,CAAC;AACH,CAAC","sourcesContent":["import { spawn } from 'child_process';\nimport { promises as fs } from 'fs';\nimport path from 'path';\n\nimport type { InfraCommandContext } from './commandContext.js';\n\nexport type InfraLifecycleScript = 'destroy' | 'down' | 'port-forward' | 'reset' | 'status' | 'up';\n\nexport interface InfraScriptOutput {\n  readonly stderr: string;\n  readonly stdout: string;\n}\n\nexport interface InfraPortForwardInfo {\n  readonly localPort: number;\n  readonly url: string;\n}\n\nexport class InfraScriptExecutionError extends Error {\n  readonly exitCode: number | null;\n  readonly stderr: string;\n  readonly stdout: string;\n\n  constructor(args: {\n    readonly exitCode: number | null;\n    readonly message: string;\n    readonly stderr: string;\n    readonly stdout: string;\n  }) {\n    super(args.message);\n    this.name = 'InfraScriptExecutionError';\n    this.exitCode = args.exitCode;\n    this.stderr = args.stderr;\n    this.stdout = args.stdout;\n  }\n}\n\nexport async function runProjectInfrastructureLifecycle(args: {\n  readonly args?: readonly string[];\n  readonly env?: Readonly<Record<string, string | undefined>>;\n  readonly onStderr?: (chunk: string) => void;\n  readonly onStdout?: (chunk: string) => void;\n  readonly projectId: string;\n  readonly projectPath: string;\n  readonly script: InfraLifecycleScript;\n  readonly target: string;\n}): Promise<InfraScriptOutput> {\n  const scriptPath = resolveProjectInfraScriptPath(args);\n  if (!(await pathExists(scriptPath))) {\n    throw new Error(\n      `Infra script not found: ${scriptPath}. Run infra generate for project '${args.projectId}' first.`,\n    );\n  }\n\n  return runShellScript({\n    args: args.args ?? [],\n    env: args.env ?? process.env,\n    onStderr: args.onStderr,\n    onStdout: args.onStdout,\n    scriptPath,\n  });\n}\n\nexport async function resolveProjectInfrastructurePortForward(args: {\n  readonly projectPath: string;\n  readonly target: string;\n}): Promise<InfraPortForwardInfo> {\n  const infraRoot = path.join(args.projectPath, 'infra', args.target);\n  const envPath = path.join(infraRoot, '.env');\n  const fallbackEnvPath = path.join(infraRoot, '.env.example');\n  const sourcePath = (await pathExists(envPath)) ? envPath : fallbackEnvPath;\n  const env = await readSimpleEnvMap(sourcePath);\n  const localPort = parsePositivePort(env.get('APP_PORT_FORWARD_LOCAL_PORT'));\n\n  if (localPort === null) {\n    throw new Error(\n      `Generated Infra did not provide a valid APP_PORT_FORWARD_LOCAL_PORT in ${sourcePath}. Regenerate infrastructure first.`,\n    );\n  }\n\n  return {\n    localPort,\n    url: `http://127.0.0.1:${localPort}`,\n  };\n}\n\nexport async function runProjectInfraScript(args: {\n  readonly context: InfraCommandContext;\n  readonly projectId: string;\n  readonly projectPath: string;\n  readonly script: InfraLifecycleScript;\n  readonly target: string;\n}): Promise<void> {\n  await runProjectInfrastructureLifecycle({\n    env: args.context.env,\n    onStderr: (chunk) => args.context.writeStderr(chunk),\n    onStdout: (chunk) => args.context.writeStdout(chunk),\n    projectId: args.projectId,\n    projectPath: args.projectPath,\n    script: args.script,\n    target: args.target,\n  });\n}\n\nexport function resolveProjectInfraScriptPath(args: {\n  readonly projectPath: string;\n  readonly script: InfraLifecycleScript;\n  readonly target: string;\n}): string {\n  return path.join(args.projectPath, getInfraScriptsDirectory(args.target), `${args.script}.sh`);\n}\n\nfunction getInfraScriptsDirectory(target: string): string {\n  switch (target) {\n    case 'minikube':\n      return 'infra/minikube/scripts';\n    default:\n      throw new Error(`Unsupported deployment target for infra scripts: ${target}`);\n  }\n}\n\nasync function runShellScript(args: {\n  readonly args: readonly string[];\n  readonly env: Readonly<Record<string, string | undefined>>;\n  readonly onStderr?: (chunk: string) => void;\n  readonly onStdout?: (chunk: string) => void;\n  readonly scriptPath: string;\n}): Promise<InfraScriptOutput> {\n  return new Promise<InfraScriptOutput>((resolve, reject) => {\n    const child = spawn('bash', [args.scriptPath, ...args.args], {\n      cwd: path.dirname(args.scriptPath),\n      env: { ...args.env },\n      stdio: ['ignore', 'pipe', 'pipe'],\n    });\n\n    let stdout = '';\n    let stderr = '';\n    child.stdout.setEncoding('utf8');\n    child.stderr.setEncoding('utf8');\n    child.stdout.on('data', (chunk: string) => {\n      stdout += chunk;\n      args.onStdout?.(chunk);\n    });\n    child.stderr.on('data', (chunk: string) => {\n      stderr += chunk;\n      args.onStderr?.(chunk);\n    });\n    child.once('error', (error) =>\n      reject(createStartError(args.scriptPath, error, stdout, stderr)),\n    );\n    child.once('close', (exitCode) => {\n      if (exitCode === 0) {\n        resolve({ stderr, stdout });\n        return;\n      }\n      reject(createExitError(args.scriptPath, exitCode, stdout, stderr));\n    });\n  });\n}\n\nfunction createStartError(\n  scriptPath: string,\n  error: Error,\n  stdout: string,\n  stderr: string,\n): InfraScriptExecutionError {\n  return new InfraScriptExecutionError({\n    exitCode: null,\n    message: `Failed to start infra script '${scriptPath}': ${error.message}`,\n    stderr,\n    stdout,\n  });\n}\n\nfunction createExitError(\n  scriptPath: string,\n  exitCode: number | null,\n  stdout: string,\n  stderr: string,\n): InfraScriptExecutionError {\n  return new InfraScriptExecutionError({\n    exitCode,\n    message: `Infra script '${scriptPath}' exited with code ${exitCode ?? 'unknown'}.`,\n    stderr,\n    stdout,\n  });\n}\n\nasync function readSimpleEnvMap(filePath: string): Promise<Map<string, string>> {\n  const out = new Map<string, string>();\n  const content = await fs.readFile(filePath, 'utf8');\n  for (const line of content.split(/\\r?\\n/u)) {\n    const trimmed = line.trim();\n    if (!trimmed || trimmed.startsWith('#')) continue;\n    const separator = trimmed.indexOf('=');\n    if (separator <= 0) continue;\n    const key = trimmed.slice(0, separator).trim();\n    const value = trimmed\n      .slice(separator + 1)\n      .trim()\n      .replace(/^['\"]|['\"]$/g, '');\n    out.set(key, value);\n  }\n  return out;\n}\n\nfunction parsePositivePort(value: string | undefined): number | null {\n  if (value === undefined) return null;\n  const parsed = Number.parseInt(value.trim(), 10);\n  return Number.isInteger(parsed) && parsed >= 1 && parsed <= 65_535 ? parsed : null;\n}\n\nasync function pathExists(filePath: string): Promise<boolean> {\n  try {\n    await fs.access(filePath);\n    return true;\n  } catch {\n    return false;\n  }\n}\n"]}

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@ankhorage/infra",
   "type": "module",
-  "version": "3.0.0",
+  "version": "3.1.1",
   "description": "Project-aware infrastructure generation library and executable Ankh provider for Ankhorage.",
   "homepage": "https://github.com/ankhorage/infra#readme",
   "bugs": {
@@ -35,7 +35,7 @@
     "openapi"
   ],
   "dependencies": {
-    "@ankhorage/contracts": "^6.0.0",
+    "@ankhorage/contracts": "^7.2.0",
     "@ankhorage/supabase-vault": "^0.2.4"
   },
   "files": [
@@ -62,6 +62,11 @@
       "import": "./dist/metadata/index.js",
       "default": "./dist/metadata/index.js"
     },
+    "./project": {
+      "types": "./dist/project/index.d.ts",
+      "import": "./dist/project/index.js",
+      "default": "./dist/project/index.js"
+    },
     "./package.json": "./package.json"
   },
   "bin": {

package/src/package.test.ts

@@ -24,6 +24,11 @@ describe('package metadata', () => {
       'ankhorage-infra': './dist/cli/bin.js',
     });
     expect(packageJson.ankh).toEqual(expectedAnkhMetadata);
+    expect(packageJson.exports['./project']).toEqual({
+      types: './dist/project/index.d.ts',
+      import: './dist/project/index.js',
+      default: './dist/project/index.js',
+    });
     expect(JSON.parse(JSON.stringify(expectedAnkhMetadata))).toEqual(expectedAnkhMetadata);
 
     const capabilityText = JSON.stringify(packageJson.ankh.capabilities);

package/src/project/index.test.ts

@@ -0,0 +1,70 @@
+import { afterEach, describe, expect, test } from 'bun:test';
+import { promises as fs } from 'fs';
+import os from 'os';
+import path from 'path';
+
+import {
+  resolveProjectInfrastructurePortForward,
+  runProjectInfrastructureLifecycle,
+} from './index.js';
+
+const temporaryPaths: string[] = [];
+
+afterEach(async () => {
+  await Promise.all(
+    temporaryPaths.splice(0).map((entry) => fs.rm(entry, { force: true, recursive: true })),
+  );
+});
+
+async function createProjectFixture(): Promise<string> {
+  const projectPath = await fs.mkdtemp(path.join(os.tmpdir(), 'ankh-infra-project-'));
+  temporaryPaths.push(projectPath);
+  const infraRoot = path.join(projectPath, 'infra', 'minikube');
+  const scriptsRoot = path.join(infraRoot, 'scripts');
+  await fs.mkdir(scriptsRoot, { recursive: true });
+  await fs.writeFile(
+    path.join(scriptsRoot, 'status.sh'),
+    "#!/usr/bin/env bash\nprintf 'status-ok'\nprintf 'status-warning' >&2\n",
+    'utf8',
+  );
+  await fs.writeFile(
+    path.join(infraRoot, '.env.example'),
+    'APP_PORT_FORWARD_LOCAL_PORT=48123\n',
+    'utf8',
+  );
+  return projectPath;
+}
+
+describe('@ankhorage/infra/project', () => {
+  test('executes generated lifecycle scripts without exposing script paths to consumers', async () => {
+    const projectPath = await createProjectFixture();
+    const stdout: string[] = [];
+    const stderr: string[] = [];
+
+    const result = await runProjectInfrastructureLifecycle({
+      projectId: 'example',
+      projectPath,
+      script: 'status',
+      target: 'minikube',
+      onStdout: (chunk) => stdout.push(chunk),
+      onStderr: (chunk) => stderr.push(chunk),
+    });
+
+    expect(result).toEqual({ stdout: 'status-ok', stderr: 'status-warning' });
+    expect(stdout.join('')).toBe('status-ok');
+    expect(stderr.join('')).toBe('status-warning');
+  });
+
+  test('resolves the generated app port-forward endpoint through the owner API', async () => {
+    const projectPath = await createProjectFixture();
+    const result = await resolveProjectInfrastructurePortForward({
+      projectPath,
+      target: 'minikube',
+    });
+
+    expect(result).toEqual({
+      localPort: 48123,
+      url: 'http://127.0.0.1:48123',
+    });
+  });
+});

package/src/project/index.ts

@@ -0,0 +1,17 @@
+export {
+  type ResolvedInfraProject,
+  resolveInfraProject as resolveInfraWorkspaceProject,
+} from '../project.js';
+export {
+  type InfraSyncResult,
+  resolveProjectInfrastructureTarget,
+  syncProjectInfrastructure,
+} from '../projectInfrastructure.js';
+export {
+  type InfraLifecycleScript,
+  type InfraPortForwardInfo,
+  InfraScriptExecutionError,
+  type InfraScriptOutput,
+  resolveProjectInfrastructurePortForward,
+  runProjectInfrastructureLifecycle,
+} from '../runtime.js';

package/src/project.ts

@@ -1,4 +1,4 @@
-import { APP_CATEGORIES, type AppManifest, type NavigatorSpec } from '@ankhorage/contracts';
+import { type AppManifest, isAppManifest } from '@ankhorage/contracts';
 import { promises as fs } from 'fs';
 import path from 'path';
 
@@ -37,11 +37,7 @@ export async function resolveInfraProject(options: {
   }
 
   const manifestPath = path.join(projectPath, 'ankh.config.json');
-  const manifest = await readProjectManifest({
-    manifestPath,
-    projectId,
-    projectPath,
-  });
+  const manifest = await readProjectManifest({ manifestPath, projectId });
 
   return {
     appsRoot,
@@ -75,9 +71,7 @@ function createFallbackManifest(projectId: string): AppManifest {
     },
     themes: [],
     activeThemeId: 'default',
-    infra: {
-      modules: [],
-    },
+    infra: { modules: [] },
     navigator: {
       type: 'stack',
       routes: [{ name: 'index', screenId: 'index' }],
@@ -95,15 +89,14 @@ function createFallbackManifest(projectId: string): AppManifest {
 async function readProjectManifest(args: {
   readonly manifestPath: string;
   readonly projectId: string;
-  readonly projectPath: string;
 }): Promise<AppManifest> {
   if (!(await pathExists(args.manifestPath))) {
     return createFallbackManifest(args.projectId);
   }
 
   const rawManifest = await fs.readFile(args.manifestPath, 'utf8');
-
   let parsed: unknown;
+
   try {
     parsed = JSON.parse(rawManifest);
   } catch (error) {
@@ -125,15 +118,10 @@ async function findWorkspaceRoot(startPath: string): Promise<string | null> {
 
   for (;;) {
     const appsRoot = path.join(currentPath, 'apps');
-    if (await isDirectory(appsRoot)) {
-      return currentPath;
-    }
+    if (await isDirectory(appsRoot)) return currentPath;
 
     const parentPath = path.dirname(currentPath);
-    if (parentPath === currentPath) {
-      return null;
-    }
-
+    if (parentPath === currentPath) return null;
     currentPath = parentPath;
   }
 }
@@ -166,69 +154,6 @@ function validateExplicitProjectId(projectId: string): string {
   return projectId;
 }
 
-function isAppManifest(value: unknown): value is AppManifest {
-  if (!isRecord(value)) {
-    return false;
-  }
-
-  return (
-    isAppManifestMetadata(value.metadata) &&
-    Array.isArray(value.themes) &&
-    typeof value.activeThemeId === 'string' &&
-    isInfraManifestRecord(value.infra) &&
-    isNavigatorSpec(value.navigator) &&
-    isRecord(value.screens) &&
-    isSettingsRecord(value.settings)
-  );
-}
-
-function isAppManifestMetadata(value: unknown): value is AppManifest['metadata'] {
-  return (
-    isRecord(value) &&
-    typeof value.name === 'string' &&
-    typeof value.slug === 'string' &&
-    typeof value.version === 'string' &&
-    APP_CATEGORIES.some((category) => category === value.category) &&
-    typeof value.themeId === 'string' &&
-    (value.created === undefined || typeof value.created === 'string') &&
-    (value.updated === undefined || typeof value.updated === 'string')
-  );
-}
-
-function isInfraManifestRecord(value: unknown): value is AppManifest['infra'] {
-  return isRecord(value) && Array.isArray(value.modules);
-}
-
-function isNavigatorSpec(value: unknown): value is NavigatorSpec {
-  return (
-    isRecord(value) &&
-    typeof value.type === 'string' &&
-    Array.isArray(value.routes) &&
-    (value.initialRouteName === undefined || typeof value.initialRouteName === 'string')
-  );
-}
-
-function isSettingsRecord(value: unknown): value is AppManifest['settings'] {
-  return (
-    isRecord(value) &&
-    (value.apiBaseUrl === undefined || typeof value.apiBaseUrl === 'string') &&
-    isLocalizationRecord(value.localization)
-  );
-}
-
-function isLocalizationRecord(value: unknown): value is AppManifest['settings']['localization'] {
-  return (
-    isRecord(value) &&
-    typeof value.defaultLocale === 'string' &&
-    Array.isArray(value.locales) &&
-    value.locales.every((locale) => typeof locale === 'string')
-  );
-}
-
-function isRecord(value: unknown): value is Record<string, unknown> {
-  return typeof value === 'object' && value !== null;
-}
-
 async function isDirectory(filePath: string): Promise<boolean> {
   try {
     const stat = await fs.stat(filePath);

package/src/projectContractsParser.test.ts

@@ -0,0 +1,49 @@
+import { afterEach, expect, test } from 'bun:test';
+import { promises as fs } from 'fs';
+import path from 'path';
+
+import { resolveInfraProject } from './project.js';
+import { createAppManifest, createWorkspaceFixture } 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();
+});
+
+test('Infra rejects nested manifest shapes rejected by Contracts', async () => {
+  const manifest = createAppManifest('cards', { modules: [] });
+  const fixture = await createWorkspaceFixture({ manifest, projectId: 'cards' });
+  tempRoots.add(fixture.rootPath);
+
+  const malformedManifest = {
+    ...manifest,
+    navigator: {
+      ...manifest.navigator,
+      type: 'not-a-canonical-navigator',
+    },
+  };
+  await fs.writeFile(
+    path.join(fixture.projectPath, 'ankh.config.json'),
+    JSON.stringify(malformedManifest),
+    'utf8',
+  );
+
+  const error = await captureError(
+    resolveInfraProject({ cwd: fixture.rootPath, projectId: fixture.projectId }),
+  );
+  expect(error.message).toContain('Project manifest has an invalid shape');
+});
+
+async function captureError(promise: Promise<unknown>): Promise<Error> {
+  try {
+    await promise;
+  } catch (error) {
+    if (error instanceof Error) return error;
+    throw error;
+  }
+  throw new Error('Expected project resolution to reject.');
+}

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

@@ -4,7 +4,17 @@ import path from 'path';
 
 import type { InfraCommandContext } from './commandContext.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 +35,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 +52,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 infraRoot = path.join(args.projectPath, 'infra', args.target);
+  const envPath = path.join(infraRoot, '.env');
+  const fallbackEnvPath = path.join(infraRoot, '.env.example');
+  const sourcePath = (await pathExists(envPath)) ? envPath : fallbackEnvPath;
+  const env = await readSimpleEnvMap(sourcePath);
+  const localPort = parsePositivePort(env.get('APP_PORT_FORWARD_LOCAL_PORT'));
+
+  if (localPort === null) {
+    throw new Error(
+      `Generated Infra did not provide a valid APP_PORT_FORWARD_LOCAL_PORT in ${sourcePath}. 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 +120,96 @@ 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,
+  });
+}
+
+async function readSimpleEnvMap(filePath: string): Promise<Map<string, string>> {
+  const out = new Map<string, string>();
+  const content = await fs.readFile(filePath, 'utf8');
+  for (const line of content.split(/\r?\n/u)) {
+    const trimmed = line.trim();
+    if (!trimmed || trimmed.startsWith('#')) continue;
+    const separator = trimmed.indexOf('=');
+    if (separator <= 0) continue;
+    const key = trimmed.slice(0, separator).trim();
+    const value = trimmed
+      .slice(separator + 1)
+      .trim()
+      .replace(/^['"]|['"]$/g, '');
+    out.set(key, value);
+  }
+  return out;
+}
+
+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);