@ankhorage/infra 4.1.12 → 5.1.0

package/src/features/environment-lifecycle/utils/isInfraStoredState.ts

@@ -0,0 +1,141 @@
+import { APP_ENVIRONMENT_IDS } from '@ankhorage/contracts/environments';
+import {
+  INFRA_ADAPTER_CATALOG,
+  type InfraLedger,
+  isInfraEnvironmentSpec,
+} from '@ankhorage/contracts/infra';
+
+import type { InfraStoredState } from '../../../types/infraOrchestration.js';
+
+/*** Validate persisted ownership state before any provider receives it. */
+export function isInfraStoredState(value: unknown): value is InfraStoredState {
+  return (
+    isRecord(value) &&
+    value.schemaVersion === 1 &&
+    isInfraEnvironmentSpec(value.desired) &&
+    isInfraLedger(value.ledger)
+  );
+}
+
+/*** Validate the canonical ledger's serializable outer boundary. */
+function isInfraLedger(value: unknown): value is InfraLedger {
+  if (
+    isRecord(value) &&
+    value.schemaVersion === 1 &&
+    typeof value.projectId === 'string' &&
+    typeof value.environment === 'string' &&
+    APP_ENVIRONMENT_IDS.some((environment) => environment === value.environment) &&
+    Array.isArray(value.targets) &&
+    Array.isArray(value.resources) &&
+    Array.isArray(value.outputs) &&
+    Array.isArray(value.artifacts)
+  ) {
+    const { environment, projectId } = value;
+    return (
+      value.targets.every(isComputeTarget) &&
+      value.resources.every((resource) => isOwnedResource(resource, projectId, environment)) &&
+      value.outputs.every((output) => isOutput(output, projectId, environment)) &&
+      value.artifacts.every((artifact) => isArtifactIdentity(artifact, projectId, environment))
+    );
+  }
+  return false;
+}
+
+/*** Validate portable compute targets without accepting resolved credential payloads. */
+function isComputeTarget(value: unknown): boolean {
+  if (
+    !isRecord(value) ||
+    typeof value.id !== 'string' ||
+    !['linux', 'darwin', 'windows'].includes(String(value.os)) ||
+    !['amd64', 'arm64'].includes(String(value.architecture))
+  ) {
+    return false;
+  }
+  if (value.kind === 'local-host') return true;
+  return (
+    value.kind === 'ssh-host' &&
+    typeof value.host === 'string' &&
+    typeof value.port === 'number' &&
+    typeof value.user === 'string' &&
+    typeof value.hostKeyFingerprint === 'string' &&
+    isControlPlaneReference(value.credential)
+  );
+}
+
+/*** Validate one exact resource plus its dependency identities. */
+function isOwnedResource(value: unknown, projectId: string, environment: string): boolean {
+  return (
+    isRecord(value) &&
+    isScopedIdentity(value.identity, projectId, environment) &&
+    typeof value.persistent === 'boolean' &&
+    (value.retention === 'retain' || value.retention === 'delete-on-destroy') &&
+    Array.isArray(value.dependsOn) &&
+    value.dependsOn.every((identity) => isScopedIdentity(identity, projectId, environment))
+  );
+}
+
+/*** Enforce the public-value versus secret-reference output union at rest. */
+function isOutput(value: unknown, projectId: string, environment: string): boolean {
+  if (
+    !isRecord(value) ||
+    !isScopedIdentity(value.owner, projectId, environment) ||
+    typeof value.name !== 'string'
+  ) {
+    return false;
+  }
+  if (value.visibility === 'public') {
+    return (
+      ['string', 'number', 'boolean'].includes(typeof value.value) &&
+      value.reference === undefined &&
+      (value.environmentVariable === undefined || typeof value.environmentVariable === 'string')
+    );
+  }
+  return (
+    value.visibility === 'secret' &&
+    value.value === undefined &&
+    value.environmentVariable === undefined &&
+    isSecretReference(value.reference, projectId, environment)
+  );
+}
+
+/*** Validate one generated-artifact ledger identity without accepting file content. */
+function isArtifactIdentity(value: unknown, projectId: string, environment: string): boolean {
+  return (
+    isRecord(value) &&
+    isScopedIdentity(value.owner, projectId, environment) &&
+    typeof value.path === 'string'
+  );
+}
+
+/*** Validate scope, adapter catalog identity, and resource ID. */
+function isScopedIdentity(value: unknown, projectId: string, environment: string): boolean {
+  return (
+    isRecord(value) &&
+    value.projectId === projectId &&
+    value.environment === environment &&
+    Object.values(INFRA_ADAPTER_CATALOG).some(({ id }) => id === value.adapter) &&
+    typeof value.resourceId === 'string'
+  );
+}
+
+/*** Validate an unresolved control-plane credential identity. */
+function isControlPlaneReference(value: unknown): boolean {
+  return isRecord(value) && value.source === 'control-plane' && typeof value.name === 'string';
+}
+
+/*** Validate an unresolved secret reference scoped to this exact ledger. */
+function isSecretReference(value: unknown, projectId: string, environment: string): boolean {
+  return (
+    isRecord(value) &&
+    value.source === 'secret-store' &&
+    value.projectId === projectId &&
+    value.environment === environment &&
+    typeof value.ref === 'string' &&
+    typeof value.key === 'string'
+  );
+}
+
+/*** Narrow parsed values. */
+function isRecord(value: unknown): value is Readonly<Record<string, unknown>> {
+  return typeof value === 'object' && value !== null;
+}

package/src/features/environment-lifecycle/utils/mergeInfraOutputs.ts

@@ -0,0 +1,14 @@
+import type { InfraOutput } from '@ankhorage/contracts/infra';
+
+import { infraIdentityKey } from './infraIdentityKey.js';
+
+/*** Merge output identities while preferring the last adapter result for each owner and name. */
+export function mergeInfraOutputs(
+  ...groups: readonly (readonly InfraOutput[])[]
+): readonly InfraOutput[] {
+  const outputs = new Map<string, InfraOutput>();
+  for (const output of groups.flat()) {
+    outputs.set(`${infraIdentityKey(output.owner)}\0${output.name}`, output);
+  }
+  return [...outputs.values()];
+}

package/src/features/environment-lifecycle/utils/mergeInfraResources.ts

@@ -0,0 +1,14 @@
+import type { InfraOwnedResource } from '@ankhorage/contracts/infra';
+
+import { infraIdentityKey } from './infraIdentityKey.js';
+
+/*** Merge resource identities while preferring the last adapter result for each owner. */
+export function mergeInfraResources(
+  ...groups: readonly (readonly InfraOwnedResource[])[]
+): readonly InfraOwnedResource[] {
+  const resources = new Map<string, InfraOwnedResource>();
+  for (const resource of groups.flat()) {
+    resources.set(infraIdentityKey(resource.identity), resource);
+  }
+  return [...resources.values()];
+}

package/src/features/environment-lifecycle/utils/normalizeInfraEnvironmentKey.ts

@@ -0,0 +1,7 @@
+/*** Convert arbitrary credential and secret identifiers into stable environment-variable segments. */
+export function normalizeInfraEnvironmentKey(value: string): string {
+  return value
+    .replaceAll(/[^A-Za-z0-9]+/gu, '_')
+    .replaceAll(/^_+|_+$/gu, '')
+    .toUpperCase();
+}

package/src/features/environment-lifecycle/utils/resolveInfraStatePath.ts

@@ -0,0 +1,12 @@
+import { APP_ENVIRONMENT_IDS, type AppEnvironmentId } from '@ankhorage/contracts/environments';
+import path from 'path';
+
+const INFRA_STATE_ROOT = '.ankh/infra';
+
+/*** Build an exact state-file path from a closed canonical environment identifier. */
+export function resolveInfraStatePath(projectPath: string, environment: AppEnvironmentId): string {
+  if (!APP_ENVIRONMENT_IDS.includes(environment)) {
+    throw new Error(`Invalid Infra state environment: ${environment}`);
+  }
+  return path.join(projectPath, INFRA_STATE_ROOT, environment, 'state.json');
+}

package/src/features/environment-lifecycle/utils/resolveProjectFile.ts

@@ -0,0 +1,22 @@
+import path from 'path';
+
+const INFRA_STATE_ROOT = '.ankh/infra';
+
+/*** Resolve one generated path inside the project while protecting Infra state and traversal. */
+export function resolveProjectFile(projectPath: string, filePath: string): string {
+  if (
+    filePath.length === 0 ||
+    path.isAbsolute(filePath) ||
+    filePath === INFRA_STATE_ROOT ||
+    filePath.startsWith(`${INFRA_STATE_ROOT}/`)
+  ) {
+    throw new Error(`Invalid generated Infra artifact path: ${filePath}`);
+  }
+  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 generated Infra artifact path outside project root: ${filePath}`);
+  }
+  return resolvedPath;
+}

package/src/features/environment-lifecycle/utils/retainUnchangedAdapterOutputs.ts

@@ -0,0 +1,15 @@
+import type { InfraOutput } from '@ankhorage/contracts/infra';
+
+import { mergeInfraOutputs } from './mergeInfraOutputs.js';
+
+/*** Keep prior outputs not owned by adapters that returned a replacement snapshot. */
+export function retainUnchangedAdapterOutputs(
+  previous: readonly InfraOutput[],
+  replacements: readonly InfraOutput[],
+  replacedAdapters: ReadonlySet<string>,
+): readonly InfraOutput[] {
+  return mergeInfraOutputs(
+    previous.filter(({ owner }) => !replacedAdapters.has(owner.adapter)),
+    replacements,
+  );
+}

package/src/features/environment-lifecycle/utils/retainUnchangedAdapterResources.ts

@@ -0,0 +1,15 @@
+import type { InfraOwnedResource } from '@ankhorage/contracts/infra';
+
+import { mergeInfraResources } from './mergeInfraResources.js';
+
+/*** Keep prior resources not owned by adapters that returned a replacement snapshot. */
+export function retainUnchangedAdapterResources(
+  previous: readonly InfraOwnedResource[],
+  replacements: readonly InfraOwnedResource[],
+  replacedAdapters: ReadonlySet<string>,
+): readonly InfraOwnedResource[] {
+  return mergeInfraResources(
+    previous.filter(({ identity }) => !replacedAdapters.has(identity.adapter)),
+    replacements,
+  );
+}

package/src/index.test.ts

@@ -1,319 +1,26 @@
-import type { AppManifest } from '@ankhorage/contracts';
 import { describe, expect, test } from 'bun:test';
 
-import { generateInfrastructure } from './index';
-import type { InfraManifestInput } from './types';
-
-describe('generateInfrastructure', () => {
-  test('generates minikube artifacts for app-owned Kubernetes infrastructure', () => {
-    const manifest: InfraManifestInput = {
-      deployment: {
-        target: 'minikube',
-        monitoring: false,
-      },
-      auth: {
-        scope: 'global',
-        provider: 'supabase',
-        authorization: {
-          kind: 'ABAC',
-          engine: 'cerbos',
-        },
-        signIn: {
-          identifiers: ['email', 'username'],
-        },
-        signUp: {
-          requiredFields: ['email', 'password'],
-          optionalFields: ['firstName', 'lastName'],
-          signUpPolicy: 'requireVerification',
-        },
-        profile: {
-          fields: ['email', 'firstName', 'lastName', 'avatarUrl'],
-        },
-      },
-      database: {
-        provider: 'supabase',
-        tier: 'dev',
-      },
-      storage: {
-        provider: 'auto',
-        buckets: ['assets'],
-      },
-      networking: {
-        domain: 'alpha.local',
-        cdn: false,
-      },
-      modules: [],
-    };
-
-    const result = generateInfrastructure(manifest, { appManifest: createAppManifest('alpha') });
-    const paths = result.files.map((file) => file.path);
-
-    expect(result.meta.target).toBe('minikube');
-    expect(result.meta.providers).toEqual(['auto', 'cerbos', 'supabase']);
-    expect(paths).toContain('infra/minikube/k8s/namespaces/app.yaml');
-    expect(paths).toContain('infra/minikube/k8s/namespaces/supabase.yaml');
-    expect(paths).toContain('infra/minikube/k8s/app/deployment.yaml');
-    expect(paths).toContain('infra/minikube/k8s/app/service.yaml');
-    expect(paths).toContain('infra/minikube/k8s/supabase/postgres.yaml');
-    expect(paths).toContain('infra/minikube/k8s/supabase/gateway.yaml');
-    expect(paths).toContain('infra/minikube/k8s/auth/supabase/supabase-auth.configmap.yaml');
-    expect(paths).toContain('infra/minikube/k8s/auth/supabase/app-runtime-auth.env.configmap.yaml');
-    expect(paths).toContain('infra/minikube/k8s/authz/cerbos/cerbos.policy.configmap.yaml');
-    expect(paths).toContain('infra/minikube/k8s/authz/cerbos/cerbos.deployment.yaml');
-    expect(paths).toContain('infra/minikube/k8s/storage/supabase/supabase-storage.configmap.yaml');
-    expect(paths).toContain(
-      'infra/minikube/k8s/storage/supabase/app-runtime-storage.env.configmap.yaml',
-    );
-    expect(paths).toContain('infra/minikube/scripts/up.sh');
-    expect(paths).toContain('infra/minikube/scripts/down.sh');
-    expect(paths).toContain('infra/minikube/scripts/reset.sh');
-    expect(paths).toContain('infra/minikube/scripts/destroy.sh');
-    expect(paths).toContain('infra/minikube/scripts/status.sh');
-    expect(paths).toContain('infra/minikube/scripts/port-forward.sh');
-    expect(paths).not.toContain('infra/minikube/scripts/supabase-local-env.sh');
-
-    const envExample = getFile(result.files, 'infra/minikube/.env.example');
-    expect(envExample).toContain('ANKH_APP_SLUG=alpha');
-    expect(envExample).not.toContain('SUPABASE_RUNTIME_ENABLED=');
-    expect(envExample).toContain('EXPO_PUBLIC_SUPABASE_URL=');
-    expect(envExample).toContain('APP_IMAGE=ankh/alpha:dev');
-    expect(envExample).not.toContain('MINIKUBE_PROFILE=');
-    expect(envExample).not.toContain('SUPABASE_PROJECT_DIR=');
-
-    const upScript = getFile(result.files, 'infra/minikube/scripts/up.sh');
-    expect(upScript).toContain('SUPABASE_RUNTIME_ENABLED="true"');
-    expect(upScript).not.toContain('SUPABASE_RUNTIME_ENABLED="${SUPABASE_RUNTIME_ENABLED');
-    expect(upScript).toContain('minikube start -p "${PROFILE}"');
-    expect(upScript).toContain('kubectl --context "${PROFILE}" apply -k "${K8S_DIR}"');
-    expect(upScript).toContain(
-      'SUPABASE_TELEMETRY_DISABLED=1 supabase --yes migration up --db-url "${SUPABASE_DB_URL}"',
-    );
-    expect(upScript).not.toContain('supabase migration up --db-url "${SUPABASE_DB_URL}"');
-    expect(upScript).toContain('create secret generic supabase-runtime-secrets');
-    expect(upScript).toContain('create secret generic supabase-public-runtime');
-    expect(upScript).toContain('rollout status deployment/app-runtime --timeout=180s');
-    expect(upScript).not.toContain('supabase start');
-    expect(upScript).not.toContain('supabase status');
-
-    const appDeployment = getFile(result.files, 'infra/minikube/k8s/app/deployment.yaml');
-    expect(appDeployment).toContain('namespace: app');
-    expect(appDeployment).toContain('image: ankh/alpha:dev');
-    expect(appDeployment).toContain('name: supabase-public-runtime');
-    expect(appDeployment).not.toContain('supabase-auth-secrets');
-
-    const runtimeGuide = getFile(result.files, 'infra/minikube/auth/supabase-runtime-wiring.md');
-    expect(runtimeGuide).toContain('supabase-public-runtime');
-    expect(runtimeGuide).toContain('${APP_SOURCE_DIR}/.env.local');
-    expect(runtimeGuide).not.toContain('SUPABASE_SERVICE_ROLE_KEY');
-  });
-
-  test('generates minikube storage artifacts for explicit supabase provider with normalized buckets', () => {
-    const manifest: InfraManifestInput = {
-      deployment: {
-        target: 'minikube',
-        monitoring: false,
-      },
-      auth: {
-        scope: 'global',
-        provider: 'supabase',
-      },
-      database: {
-        provider: 'supabase',
-        tier: 'dev',
-      },
-      storage: {
-        provider: 'supabase',
-        buckets: ['assets', ' assets ', '', 'assets', 'uploads'],
-      },
-      modules: [],
-    };
-
-    const result = generateInfrastructure(manifest, {
-      appManifest: createAppManifest('shop'),
-    });
-
-    expect(result.warnings).toContain(
-      'Storage buckets are configured but not created automatically yet. Ensure buckets exist in Supabase Storage: assets,uploads.',
-    );
-
-    const storageConfig = getFile(
-      result.files,
-      'infra/minikube/k8s/storage/supabase/supabase-storage.configmap.yaml',
-    );
-    expect(storageConfig).toContain('namespace: app');
-    expect(storageConfig).toContain('STORAGE_BUCKETS: "assets,uploads"');
-    expect(storageConfig).toContain('STORAGE_DEFAULT_BUCKET: "assets"');
-  });
-
-  test('generates route and screen cerbos policies when app manifest context is provided', () => {
-    const manifest: InfraManifestInput = {
-      deployment: {
-        target: 'minikube',
-        monitoring: false,
-      },
-      auth: {
-        scope: 'global',
-        provider: 'supabase',
-        authorization: {
-          kind: 'ABAC',
-          engine: 'cerbos',
-        },
-      },
-      database: {
-        provider: 'supabase',
-        tier: 'dev',
-      },
-      modules: [],
-    };
-
-    const appManifest: Pick<AppManifest, 'metadata' | 'navigator' | 'screens' | 'settings'> = {
-      metadata: {
-        name: 'Shop',
-        slug: 'shop',
-        version: '1.0.0',
-        themeId: 'default',
-      },
-      navigator: {
-        type: 'stack',
-        routes: [
-          { name: 'sign-in', screenId: 'screen-sign-in' },
-          { name: 'sign-up', screenId: 'screen-sign-up', guards: ['public'] },
-          { name: 'index', screenId: 'screen-home' },
-          { name: 'cart', screenId: 'screen-cart', guards: ['auth'] },
-        ],
-      },
-      screens: {
-        'screen-sign-in': {
-          id: 'screen-sign-in',
-          name: 'SignIn',
-          root: { id: 'sign-in-root', type: 'View', children: [] },
-        },
-        'screen-sign-up': {
-          id: 'screen-sign-up',
-          name: 'SignUp',
-          root: { id: 'sign-up-root', type: 'View', children: [] },
-        },
-        'screen-home': {
-          id: 'screen-home',
-          name: 'Home',
-          root: { id: 'home-root', type: 'View', children: [] },
-        },
-        'screen-cart': {
-          id: 'screen-cart',
-          name: 'Cart',
-          root: { id: 'cart-root', type: 'View', children: [] },
-        },
-      },
-      settings: {
-        localization: {
-          defaultLocale: 'en',
-          locales: ['en'],
-        },
-        authFlow: {
-          signInRoute: '/sign-in',
-          signUpRoute: '/sign-up',
-          signOutRoute: '/sign-out',
-          unauthorizedRoute: '/sign-in',
-          postSignInRoute: '/',
-        },
-      },
-    };
-
-    const result = generateInfrastructure(manifest, { appManifest });
-    const cerbosPolicy = getFile(
-      result.files,
-      'infra/minikube/k8s/authz/cerbos/cerbos.policy.configmap.yaml',
-    );
-
-    expect(cerbosPolicy).toContain('route.resource_policy.yaml: |');
-    expect(cerbosPolicy).toContain('screen.resource_policy.yaml: |');
-    expect(cerbosPolicy).toContain(
-      'expr: "request.resource.attr.route in [\\"sign-in\\",\\"sign-up\\"]"',
-    );
-    expect(cerbosPolicy).toContain(
-      'expr: "request.resource.attr.route in [\\"cart\\",\\"index\\"]"',
-    );
-  });
-
-  test('throws for missing deployment', () => {
-    const manifest: InfraManifestInput = {
-      modules: [],
-    };
-
-    expect(() => generateInfrastructure(manifest)).toThrow('Deployment configuration is missing.');
-  });
-
-  test('throws for unsupported deployment target', () => {
-    const manifest: InfraManifestInput = {
-      deployment: {
-        target: 'kubernetes',
-        monitoring: false,
-      },
-      modules: [],
-    };
-
-    expect(() => generateInfrastructure(manifest)).toThrow(
-      'Unsupported deployment target: kubernetes',
-    );
-  });
-
-  test('requires canonical app slug for minikube infrastructure', () => {
-    const manifest: InfraManifestInput = {
-      deployment: {
-        target: 'minikube',
-        monitoring: false,
-      },
-      database: {
-        provider: 'supabase',
-        tier: 'dev',
-      },
-      modules: [],
-    };
-
-    expect(() => generateInfrastructure(manifest, { namespaceHint: 'shop' })).toThrow(
-      'Cannot generate Minikube infrastructure: appManifest.metadata.slug is required.',
-    );
-    expect(() =>
-      generateInfrastructure(manifest, {
-        appManifest: createAppManifest('Scanner App'),
-      }),
-    ).toThrow('appManifest.metadata.slug must be a canonical lowercase slug up to 40 characters');
+import * as infra from './index.js';
+
+describe('@ankhorage/infra', () => {
+  test('exports only the provider-neutral lifecycle and composition APIs', () => {
+    expect(infra).toContainAllKeys([
+      'createEnvironmentInfraCredentialPort',
+      'createEnvironmentInfraSecretPort',
+      'createNodeInfraAdapterPackageResolver',
+      'destroyInfraEnvironmentAsync',
+      'downInfraEnvironmentAsync',
+      'generateInfraEnvironmentAsync',
+      'getInfraEnvironmentOutputs',
+      'orderInfraPlanActions',
+      'planInfraEnvironmentAsync',
+      'resolveInfraAdaptersAsync',
+      'resolveInfraEnvironment',
+      'statusInfraEnvironmentAsync',
+      'upInfraEnvironmentAsync',
+      'validateInfraEnvironmentAsync',
+    ]);
+    expect(Object.keys(infra)).not.toContain('createMinikubeAdapter');
+    expect(Object.keys(infra)).not.toContain('resolveAuthRedirectConfiguration');
   });
 });
-
-function getFile(files: readonly { path: string; content: string }[], path: string): string {
-  const file = files.find((candidate) => candidate.path === path);
-  if (!file) throw new Error(`Missing generated file: ${path}`);
-  return file.content;
-}
-
-function createAppManifest(
-  slug: string,
-): Pick<AppManifest, 'metadata' | 'navigator' | 'screens' | 'settings'> {
-  return {
-    metadata: {
-      name: slug,
-      slug,
-      version: '1.0.0',
-      themeId: 'default',
-    },
-    navigator: {
-      type: 'stack',
-      routes: [],
-    },
-    screens: {},
-    settings: {
-      localization: {
-        defaultLocale: 'en',
-        locales: ['en'],
-      },
-      authFlow: {
-        signInRoute: '/sign-in',
-        signUpRoute: '/sign-up',
-        signOutRoute: '/sign-out',
-        unauthorizedRoute: '/sign-in',
-        postSignInRoute: '/',
-      },
-    },
-  };
-}