@ankhorage/contracts 19.0.0 → 19.2.0

package/dist/types/infraWorkload.js.map

@@ -1 +1 @@
-{"version":3,"file":"infraWorkload.js","sourceRoot":"","sources":["../../src/types/infraWorkload.ts"],"names":[],"mappings":"","sourcesContent":["import type { InfraControlPlaneCredentialRef, InfraSecretReference } from './infraSecrets';\n\nexport interface InfraWorkloadArtifact {\n  readonly kind: 'image';\n  /** Prebuilt image, optionally pinned by digest. No registry/build provider requirement. */\n  readonly image: string;\n}\n\nexport type InfraWorkloadScalarValue =\n  | { readonly kind: 'literal'; readonly value: string }\n  | { readonly kind: 'secret'; readonly reference: InfraSecretReference }\n  | {\n      readonly kind: 'credential';\n      readonly reference: InfraControlPlaneCredentialRef;\n      readonly key: string;\n    }\n  | { readonly kind: 'output'; readonly resourceId: string; readonly output: string };\n\nexport type InfraWorkloadValue =\n  | InfraWorkloadScalarValue\n  | {\n      readonly kind: 'template';\n      /** Ordered scalar segments materialized into one value only at the runtime boundary. */\n      readonly segments: readonly InfraWorkloadScalarValue[];\n    };\n\nexport interface InfraWorkloadPort {\n  readonly name: string;\n  readonly port: number;\n  readonly protocol?: 'tcp' | 'udp';\n}\n\nexport type InfraWorkloadHealthSpec = {\n  readonly intervalSeconds?: number;\n  readonly timeoutSeconds?: number;\n  readonly failureThreshold?: number;\n} & (\n  | { readonly kind: 'http'; readonly port: number; readonly path: string }\n  | { readonly kind: 'tcp'; readonly port: number }\n  | { readonly kind: 'command'; readonly command: readonly string[] }\n);\n\nexport interface InfraWorkloadResourceSpec {\n  readonly cpuMillis?: number;\n  readonly memoryMiB?: number;\n}\n\nexport interface InfraWorkloadVolumeSpec {\n  readonly id: string;\n  readonly mountPath: string;\n  readonly sizeGiB: number;\n  /** Persistence survives down and is retained by default on destroy. */\n  readonly retention: 'retain' | 'delete-on-destroy';\n}\n\n/** Portable config/policy files; secret values are materialized by the runtime. */\nexport interface InfraWorkloadFileSpec {\n  readonly path: string;\n  readonly content: InfraWorkloadValue;\n}\n\nexport interface InfraWorkloadSpec {\n  readonly id: string;\n  readonly artifact: InfraWorkloadArtifact;\n  readonly command?: readonly string[];\n  readonly args?: readonly string[];\n  readonly ports?: readonly InfraWorkloadPort[];\n  readonly environment?: Readonly<Record<string, InfraWorkloadValue>>;\n  readonly files?: readonly InfraWorkloadFileSpec[];\n  readonly health?: InfraWorkloadHealthSpec;\n  readonly resources?: InfraWorkloadResourceSpec;\n  readonly persistence?: readonly InfraWorkloadVolumeSpec[];\n  readonly exposure?: 'internal' | 'public';\n  readonly replicas?: number;\n  /** IDs in the composed desired-state graph; the orchestrator validates missing/cyclic edges. */\n  readonly dependsOn?: readonly string[];\n}\n"]}
+{"version":3,"file":"infraWorkload.js","sourceRoot":"","sources":["../../src/types/infraWorkload.ts"],"names":[],"mappings":"","sourcesContent":["import type { InfraControlPlaneCredentialRef, InfraSecretReference } from './infraSecrets';\n\nexport interface InfraWorkloadArtifact {\n  readonly kind: 'image';\n  /** Prebuilt image, optionally pinned by digest. No registry/build provider requirement. */\n  readonly image: string;\n}\n\nexport type InfraWorkloadScalarValue =\n  | { readonly kind: 'literal'; readonly value: string }\n  | { readonly kind: 'secret'; readonly reference: InfraSecretReference }\n  | {\n      readonly kind: 'credential';\n      readonly reference: InfraControlPlaneCredentialRef;\n      readonly key: string;\n    }\n  | { readonly kind: 'output'; readonly resourceId: string; readonly output: string };\n\nexport type InfraWorkloadValue =\n  | InfraWorkloadScalarValue\n  | {\n      readonly kind: 'template';\n      /** Ordered scalar segments materialized into one value only at the runtime boundary. */\n      readonly segments: readonly InfraWorkloadScalarValue[];\n    };\n\nexport interface InfraWorkloadPort {\n  readonly name: string;\n  readonly port: number;\n  readonly protocol?: 'tcp' | 'udp';\n  /** Exact external listener port requested for a public single-replica workload. */\n  readonly publishedPort?: number;\n}\n\nexport type InfraWorkloadHealthSpec = {\n  readonly intervalSeconds?: number;\n  readonly timeoutSeconds?: number;\n  readonly failureThreshold?: number;\n} & (\n  | { readonly kind: 'http'; readonly port: number; readonly path: string }\n  | { readonly kind: 'tcp'; readonly port: number }\n  | { readonly kind: 'command'; readonly command: readonly string[] }\n);\n\nexport interface InfraWorkloadResourceSpec {\n  readonly cpuMillis?: number;\n  readonly memoryMiB?: number;\n}\n\nexport interface InfraWorkloadVolumeSpec {\n  readonly id: string;\n  readonly mountPath: string;\n  readonly sizeGiB: number;\n  /** Persistence survives down and is retained by default on destroy. */\n  readonly retention: 'retain' | 'delete-on-destroy';\n}\n\n/** Portable config/policy files; secret values are materialized by the runtime. */\nexport interface InfraWorkloadFileSpec {\n  readonly path: string;\n  readonly content: InfraWorkloadValue;\n}\n\nexport interface InfraWorkloadSpec {\n  readonly id: string;\n  readonly artifact: InfraWorkloadArtifact;\n  readonly command?: readonly string[];\n  readonly args?: readonly string[];\n  readonly ports?: readonly InfraWorkloadPort[];\n  readonly environment?: Readonly<Record<string, InfraWorkloadValue>>;\n  readonly files?: readonly InfraWorkloadFileSpec[];\n  readonly health?: InfraWorkloadHealthSpec;\n  readonly resources?: InfraWorkloadResourceSpec;\n  readonly persistence?: readonly InfraWorkloadVolumeSpec[];\n  readonly exposure?: 'internal' | 'public';\n  readonly replicas?: number;\n  /** IDs in the composed desired-state graph; the orchestrator validates missing/cyclic edges. */\n  readonly dependsOn?: readonly string[];\n}\n"]}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ankhorage/contracts",
-  "version": "19.0.0",
+  "version": "19.2.0",
   "main": "./dist/index.js",
   "ankh": {
     "category": "contracts",
@@ -58,6 +58,10 @@
       "types": "./dist/deploy.d.ts",
       "default": "./dist/deploy.js"
     },
+    "./deploy-provider": {
+      "types": "./dist/deployProvider.d.ts",
+      "default": "./dist/deployProvider.js"
+    },
     "./runtime": {
       "types": "./dist/runtimeCallbacks.d.ts",
       "default": "./dist/runtimeCallbacks.js"

package/src/deployProvider.test.ts

@@ -0,0 +1,82 @@
+import { readFile } from 'node:fs/promises';
+import { join } from 'node:path';
+
+import { describe, expect, it } from 'bun:test';
+
+import {
+  DEPLOYMENT_PROVIDER_CAPABILITY_IDS,
+  type DeploymentProviderRegistration,
+} from './deployProvider';
+
+const fakeProvider: DeploymentProviderRegistration = {
+  descriptor: {
+    id: 'fake',
+    packageName: '@ankhorage/deploy-provider-fake',
+    displayName: 'Fake provider',
+    capabilities: [{ id: 'web-publish', targets: ['web'] }],
+  },
+  webPublisher: {
+    publishAsync: (request) =>
+      Promise.resolve({
+        status: 'completed',
+        value: {
+          target: 'web',
+          revision: request.revision,
+          provider: 'fake',
+          deploymentId: 'fake-deployment',
+          url: 'https://example.test',
+          production: request.intent.mode === 'production',
+        },
+      }),
+  },
+};
+
+describe('deployment provider contracts', () => {
+  it('defines the portable provider capability vocabulary', () => {
+    expect(DEPLOYMENT_PROVIDER_CAPABILITY_IDS).toEqual([
+      'setup',
+      'web-publish',
+      'android-build',
+      'android-publish',
+      'ios-build',
+      'ios-publish',
+      'store-listing',
+      'monetization',
+      'release',
+    ]);
+  });
+
+  it('supports an external provider registration without Deploy implementation types', async () => {
+    const result = await fakeProvider.webPublisher?.publishAsync({
+      projectRoot: '/project',
+      exportDirectory: '/tmp/export',
+      revision: 'revision-1',
+      intent: { mode: 'production' },
+      credentials: [],
+      resolveSecret: () => Promise.resolve(null),
+    });
+
+    expect(result).toEqual({
+      status: 'completed',
+      value: {
+        target: 'web',
+        revision: 'revision-1',
+        provider: 'fake',
+        deploymentId: 'fake-deployment',
+        url: 'https://example.test',
+        production: true,
+      },
+    });
+  });
+
+  it('publishes the focused deployment provider contract subpath', async () => {
+    const packageJson = JSON.parse(await readFile(join(process.cwd(), 'package.json'), 'utf8')) as {
+      exports?: Record<string, { default?: string; types?: string }>;
+    };
+
+    expect(packageJson.exports?.['./deploy-provider']).toEqual({
+      types: './dist/deployProvider.d.ts',
+      default: './dist/deployProvider.js',
+    });
+  });
+});

package/src/deployProvider.ts

@@ -0,0 +1,4 @@
+export * from './types/deployMonetization';
+export * from './types/deployProvider';
+export * from './types/deployRelease';
+export * from './types/deployStoreListing';

package/src/index.ts

@@ -5,6 +5,7 @@ export * from './cli';
 export * from './data';
 export * from './db';
 export * from './deploy';
+export * from './deployProvider';
 export * from './environments';
 export * from './infra';
 export * from './media';

package/src/infra/infraFields.ts

@@ -17,4 +17,7 @@ export const infraFields = {
     value === undefined || (typeof value === 'number' && Number.isSafeInteger(value) && value >= 0),
   port: (value: unknown): boolean =>
     typeof value === 'number' && Number.isInteger(value) && value > 0 && value <= 65535,
+  optionalPort: (value: unknown): boolean =>
+    value === undefined ||
+    (typeof value === 'number' && Number.isInteger(value) && value > 0 && value <= 65535),
 };

package/src/infra/isInfraEnvironmentSpec.ts

@@ -13,7 +13,9 @@ import { isInfraWorkloadSpec } from './isInfraWorkloadSpec';
 
 /*** Validate sibling capabilities and their required relationships within one environment. */
 export function isInfraEnvironmentSpec(value: unknown): value is InfraEnvironmentSpec {
-  return isEnvironmentShape(value) && hasServiceDependencies(value);
+  return (
+    isEnvironmentShape(value) && hasServiceDependencies(value) && hasUniquePublishedPorts(value)
+  );
 }
 
 /*** Check all environment field shapes before inspecting canonical dependency metadata. */
@@ -104,6 +106,16 @@ function isWorkloads(value: unknown): boolean {
   );
 }
 
+/*** Prevent two workloads in one environment from claiming the same external listener. */
+function hasUniquePublishedPorts(value: InfraEnvironmentSpec): boolean {
+  const ports = (value.workloads ?? []).flatMap((workload) =>
+    (workload.ports ?? []).flatMap(({ publishedPort }) =>
+      publishedPort === undefined ? [] : [publishedPort],
+    ),
+  );
+  return new Set(ports).size === ports.length;
+}
+
 /*** Check catalog dependencies against selected sibling capabilities and runtime capabilities. */
 function hasServiceDependencies(value: InfraEnvironmentSpec): boolean {
   const selections = [

package/src/infra/isInfraWorkloadSpec.ts

@@ -11,39 +11,44 @@ import { isInfraWorkloadValue } from './isInfraWorkloadValue';
 
 /*** Validate the portable desired workload; runtime-specific fields and plaintext secret objects fail. */
 export function isInfraWorkloadSpec(value: unknown): value is InfraWorkloadSpec {
-  return isInfraShape(value, {
-    id: isNonEmptyString,
-    artifact: (artifact) =>
-      isInfraShape(artifact, { kind: (kind) => kind === 'image', image: isNonEmptyString }),
-    command: infraFields.optionalStrings,
-    args: (args) => args === undefined || isStringArray(args),
-    ports: (ports) =>
-      ports === undefined ||
-      (Array.isArray(ports) && ports.every(isPort) && hasUniqueField(ports, 'name')),
-    environment: (environment) =>
-      environment === undefined ||
-      (isRecord(environment) && Object.values(environment).every(isInfraWorkloadValue)),
-    files: (files) =>
-      files === undefined ||
-      (Array.isArray(files) && files.every(isFile) && hasUniqueField(files, 'path')),
-    health: (health) => health === undefined || isInfraWorkloadHealth(health),
-    resources: (resources) =>
-      resources === undefined ||
-      isInfraShape(resources, {
-        cpuMillis: infraFields.optionalPositiveInteger,
-        memoryMiB: infraFields.optionalPositiveInteger,
-      }),
-    persistence: (volumes) =>
-      volumes === undefined ||
-      (Array.isArray(volumes) &&
-        volumes.every(isVolume) &&
-        hasUniqueField(volumes, 'id') &&
-        hasUniqueField(volumes, 'mountPath')),
-    exposure: (exposure) =>
-      exposure === undefined || exposure === 'internal' || exposure === 'public',
-    replicas: infraFields.optionalNonnegativeInteger,
-    dependsOn: infraFields.optionalStrings,
-  } satisfies InfraShape<InfraWorkloadSpec>);
+  if (
+    !isInfraShape(value, {
+      id: isNonEmptyString,
+      artifact: (artifact) =>
+        isInfraShape(artifact, { kind: (kind) => kind === 'image', image: isNonEmptyString }),
+      command: infraFields.optionalStrings,
+      args: (args) => args === undefined || isStringArray(args),
+      ports: (ports) =>
+        ports === undefined ||
+        (Array.isArray(ports) && ports.every(isPort) && hasUniqueField(ports, 'name')),
+      environment: (environment) =>
+        environment === undefined ||
+        (isRecord(environment) && Object.values(environment).every(isInfraWorkloadValue)),
+      files: (files) =>
+        files === undefined ||
+        (Array.isArray(files) && files.every(isFile) && hasUniqueField(files, 'path')),
+      health: (health) => health === undefined || isInfraWorkloadHealth(health),
+      resources: (resources) =>
+        resources === undefined ||
+        isInfraShape(resources, {
+          cpuMillis: infraFields.optionalPositiveInteger,
+          memoryMiB: infraFields.optionalPositiveInteger,
+        }),
+      persistence: (volumes) =>
+        volumes === undefined ||
+        (Array.isArray(volumes) &&
+          volumes.every(isVolume) &&
+          hasUniqueField(volumes, 'id') &&
+          hasUniqueField(volumes, 'mountPath')),
+      exposure: (exposure) =>
+        exposure === undefined || exposure === 'internal' || exposure === 'public',
+      replicas: infraFields.optionalNonnegativeInteger,
+      dependsOn: infraFields.optionalStrings,
+    } satisfies InfraShape<InfraWorkloadSpec>)
+  ) {
+    return false;
+  }
+  return hasValidPublishedPorts(value);
 }
 
 /*** Named transport ports stay independent from runtime resource types. */
@@ -52,9 +57,27 @@ function isPort(value: unknown): boolean {
     name: isNonEmptyString,
     port: infraFields.port,
     protocol: (protocol) => protocol === undefined || protocol === 'tcp' || protocol === 'udp',
+    publishedPort: infraFields.optionalPort,
   });
 }
 
+/*** Require fixed external listeners to belong to one public workload replica. */
+function hasValidPublishedPorts(workload: unknown): boolean {
+  if (!isRecord(workload)) return false;
+  const ports = Array.isArray(workload.ports) ? workload.ports : [];
+  const published = ports.flatMap((port) => {
+    if (!isRecord(port) || typeof port.publishedPort !== 'number') return [];
+    return [port.publishedPort];
+  });
+  return (
+    new Set(published).size === published.length &&
+    (published.length === 0 ||
+      (workload.exposure === 'public' &&
+        (workload.replicas === undefined ||
+          (typeof workload.replicas === 'number' && workload.replicas <= 1))))
+  );
+}
+
 /*** Portable files model policy/config materialization without host filesystem access. */
 function isFile(value: unknown): boolean {
   return isInfraShape(value, { path: isAbsoluteWorkloadPath, content: isInfraWorkloadValue });

package/src/infra-published-port.test.ts

@@ -0,0 +1,43 @@
+import { describe, expect, it } from 'bun:test';
+
+import { isInfraEnvironmentSpec, isInfraWorkloadSpec } from './infra';
+
+const publicWorkload = {
+  id: 'api',
+  artifact: { kind: 'image', image: 'example/api:1' },
+  ports: [{ name: 'http', port: 8080, publishedPort: 18_080 }],
+  exposure: 'public',
+} as const;
+
+describe('published workload ports', () => {
+  it('accepts one exact external listener for a public workload', () => {
+    expect(isInfraWorkloadSpec(publicWorkload)).toBe(true);
+    expect(isInfraWorkloadSpec({ ...publicWorkload, replicas: 0 })).toBe(true);
+    expect(isInfraWorkloadSpec({ ...publicWorkload, replicas: 1 })).toBe(true);
+  });
+
+  it.each([
+    { ...publicWorkload, ports: [{ name: 'http', port: 80, publishedPort: 0 }] },
+    { ...publicWorkload, ports: [{ name: 'http', port: 80, publishedPort: 65_536 }] },
+    { ...publicWorkload, exposure: 'internal' },
+    { ...publicWorkload, replicas: 2 },
+    {
+      ...publicWorkload,
+      ports: [
+        { name: 'http', port: 80, publishedPort: 8080 },
+        { name: 'admin', port: 81, publishedPort: 8080 },
+      ],
+    },
+  ])('rejects an invalid fixed external listener: %j', (workload) => {
+    expect(isInfraWorkloadSpec(workload)).toBe(false);
+  });
+
+  it('rejects external listener collisions across workloads', () => {
+    expect(
+      isInfraEnvironmentSpec({
+        deployment: { compute: { provider: 'local' }, runtime: { provider: 'minikube' } },
+        workloads: [publicWorkload, { ...publicWorkload, id: 'admin' }],
+      }),
+    ).toBe(false);
+  });
+});

package/src/infra-workload.test.ts

@@ -22,7 +22,7 @@ const workload = {
   artifact: { kind: 'image', image: 'example/backend@sha256:abc' },
   command: ['server'],
   args: ['--verbose'],
-  ports: [{ name: 'http', port: 8080 }],
+  ports: [{ name: 'http', port: 8080, publishedPort: 18_080 }],
   environment: {
     NODE_ENV: { kind: 'literal', value: 'production' },
     DB_PASSWORD: { kind: 'secret', reference },

package/src/types/deployMonetization.ts

@@ -0,0 +1,106 @@
+import type {
+  DeploymentCredentialReference,
+  DeploymentProviderResult,
+  DeploymentSecretResolver,
+  DeploymentStoreIdentity,
+} from './deployProvider';
+
+export type MonetizationProductKind = 'consumable' | 'non-consumable' | 'subscription';
+
+export interface MonetizationLocalization {
+  readonly locale: string;
+  readonly name: string;
+  readonly description: string;
+}
+
+export interface MonetizationBasePrice {
+  readonly country: string;
+  readonly currency: string;
+  readonly amount: string;
+}
+
+export type MonetizationSubscriptionPeriod = 'P1W' | 'P1M' | 'P2M' | 'P3M' | 'P6M' | 'P1Y';
+
+export interface MonetizationSubscription {
+  readonly family: string;
+  readonly period: MonetizationSubscriptionPeriod;
+  readonly level?: number;
+}
+
+export interface MonetizationProduct {
+  readonly id: string;
+  readonly kind: MonetizationProductKind;
+  readonly localizations: readonly MonetizationLocalization[];
+  readonly basePrice: MonetizationBasePrice;
+  readonly subscription?: MonetizationSubscription;
+}
+
+export interface MonetizationObservedProduct {
+  readonly id: string;
+  readonly kind: MonetizationProductKind | 'one-time';
+  readonly localizations: readonly MonetizationLocalization[];
+  readonly basePrice?: MonetizationBasePrice;
+  readonly subscription?: MonetizationSubscription;
+}
+
+export interface MonetizationDesiredState {
+  readonly revision: string;
+  readonly products: readonly MonetizationProduct[];
+}
+
+export interface MonetizationDiagnostic {
+  readonly severity: 'warning' | 'error';
+  readonly code: string;
+  readonly message: string;
+  readonly target?: 'android' | 'ios';
+  readonly productId?: string;
+  readonly locale?: string;
+}
+
+export interface MonetizationTargetState {
+  readonly target: 'android' | 'ios';
+  readonly products: readonly MonetizationObservedProduct[];
+  readonly subscriptionFamilies: readonly string[];
+  readonly diagnostics: readonly MonetizationDiagnostic[];
+}
+
+export interface MonetizationPlanStep {
+  readonly id: string;
+  readonly target: 'android' | 'ios';
+  readonly productId: string;
+  readonly operation:
+    | 'ensure-subscription-family'
+    | 'create-product'
+    | 'update-metadata'
+    | 'update-price'
+    | 'update-subscription';
+}
+
+export interface MonetizationPlan {
+  readonly status: 'no-change' | 'changes' | 'blocked';
+  readonly desiredRevision: string;
+  readonly currentRevision: string;
+  readonly steps: readonly MonetizationPlanStep[];
+  readonly diagnostics: readonly MonetizationDiagnostic[];
+}
+
+export interface MonetizationAdapterContext {
+  readonly identity: DeploymentStoreIdentity;
+  readonly credentials: readonly DeploymentCredentialReference[];
+  readonly resolveSecret: DeploymentSecretResolver;
+}
+
+export interface MonetizationSyncRequest extends MonetizationAdapterContext {
+  readonly desired: MonetizationDesiredState;
+  readonly plan: MonetizationPlan;
+}
+
+export interface DeploymentMonetizationAdapter {
+  readonly target: 'android' | 'ios';
+  inspectAsync(
+    context: MonetizationAdapterContext,
+  ): Promise<DeploymentProviderResult<MonetizationTargetState>>;
+  syncAsync(
+    request: MonetizationSyncRequest,
+  ): Promise<DeploymentProviderResult<MonetizationTargetState>>;
+}