@lukoweb/apitogo 0.2.42 → 0.2.44

package/src/config/v2/manifest.ts

@@ -1,452 +1,472 @@
-import { mkdir, readFile, rename, rm, writeFile } from "node:fs/promises";
-import path from "node:path";
-import { z } from "zod";
-import { ConfigError, type ConfigIssue } from "./errors.js";
-import { manifestPathFor, type StatePaths } from "./paths.js";
-import type { ResolvedConfigV2 } from "./resolve.js";
-
-/** Highest `schemaVersion` this build of the portal understands. */
-export const SUPPORTED_MANIFEST_SCHEMA = 1;
-
-/** Object of booleans with camelCase names. A name that is absent means false (decision 19). */
-const Capabilities = z.record(z.string(), z.boolean()).default({});
-
-const Status = z.string().optional();
-
-/**
- * The service manifest, `services.json` (Reference, section 4.1). Every service owns its entry; a service that is
- * missing from the manifest is disabled or not yet deployed. Unknown fields are kept so a newer deploy does not
- * break an older reader.
- */
-const ServiceManifestSchema = z.looseObject({
-  schemaVersion: z.number().int(),
-  generatedAt: z.string().optional(),
-  /** Set only on the stub written for local runs; never present in a deployed manifest. */
-  preview: z.boolean().optional(),
-  project: z.looseObject({ id: z.string().optional(), name: z.string() }),
-  services: z
-    .looseObject({
-      portal: z
-        .looseObject({
-          url: z.string().optional(),
-          docs: z
-            .looseObject({ provider: z.string(), url: z.string().optional() })
-            .optional(),
-          console: z
-            .looseObject({ links: z.record(z.string(), z.string()).optional() })
-            .optional(),
-        })
-        .optional(),
-      identity: z
-        .looseObject({
-          provider: z.string().default("apitogo"),
-          status: Status,
-          issuer: z.string().optional(),
-          clientId: z.string().optional(),
-          scopes: z.array(z.string()).optional(),
-          audience: z.string().optional(),
-          capabilities: Capabilities,
-        })
-        .optional(),
-      gateway: z
-        .looseObject({
-          provider: z.string().optional(),
-          status: Status,
-          baseUrl: z.string().optional(),
-          openapiUrl: z.string().optional(),
-          openapiHash: z.string().optional(),
-          audience: z.string().optional(),
-          keyHeaderName: z.string().optional(),
-          capabilities: Capabilities,
-        })
-        .optional(),
-      plans: z
-        .looseObject({
-          provider: z.string().optional(),
-          status: Status,
-          apiBaseUrl: z.string().optional(),
-          keysApiBaseUrl: z.string().optional(),
-          billing: z.string().optional(),
-          audience: z.string().optional(),
-          scopes: z.array(z.string()).optional(),
-          catalogRevision: z.number().int().optional(),
-          capabilities: Capabilities,
-        })
-        .optional(),
-    })
-    .default({}),
-});
-
-export type ServiceManifest = z.infer<typeof ServiceManifestSchema>;
-export type ManifestServiceName = "identity" | "gateway" | "plans" | "portal";
-
-const issue = (
-  code: string,
-  path: string,
-  message: string,
-  hint?: string,
-): ConfigIssue => ({ code, path, message, hint });
-
-/** Validates parsed `services.json` content. Throws a ConfigError with stable codes. */
-export function parseManifest(
-  raw: unknown,
-  file = "services.json",
-): ServiceManifest {
-  const version =
-    typeof raw === "object" && raw !== null && "schemaVersion" in raw
-      ? raw.schemaVersion
-      : undefined;
-  if (typeof version === "number" && version > SUPPORTED_MANIFEST_SCHEMA) {
-    throw new ConfigError(file, [
-      issue(
-        "PORTAL_MANIFEST_SCHEMA",
-        "schemaVersion",
-        `services.json has schemaVersion ${version} but this CLI supports ${SUPPORTED_MANIFEST_SCHEMA}.`,
-        "Upgrade @lukoweb/apitogo.",
-      ),
-    ]);
-  }
-  const result = ServiceManifestSchema.safeParse(raw);
-  if (!result.success) {
-    throw new ConfigError(
-      file,
-      result.error.issues.map((problem) =>
-        issue(
-          "PORTAL_MANIFEST_INVALID",
-          problem.path.join("."),
-          problem.message,
-          "Run `apitogo deploy` to write a fresh services.json.",
-        ),
-      ),
-    );
-  }
-  return result.data;
-}
-
-/** Reads `services.json` from the state directory. Returns undefined when the file does not exist. */
-export async function readManifest(
-  state: Pick<StatePaths, "dir">,
-): Promise<ServiceManifest | undefined> {
-  const file = manifestPathFor(state);
-  let text: string;
-  try {
-    text = await readFile(file, "utf8");
-  } catch (error) {
-    if ((error as NodeJS.ErrnoException).code === "ENOENT") return undefined;
-    throw error;
-  }
-  try {
-    return parseManifest(JSON.parse(text), file);
-  } catch (error) {
-    if (error instanceof SyntaxError) {
-      throw new ConfigError(file, [
-        issue(
-          "PORTAL_MANIFEST_INVALID",
-          "",
-          `is not valid JSON (${error.message}).`,
-          "Run `apitogo deploy` to write a fresh services.json.",
-        ),
-      ]);
-    }
-    throw error;
-  }
-}
-
-type Entry = { status?: string; capabilities: Record<string, boolean> };
-
-/** A service is usable when it has an entry and is not still provisioning. A missing status counts as ready. */
-export function serviceReady(entry: { status?: string } | undefined): boolean {
-  return entry !== undefined && (entry.status ?? "ready") === "ready";
-}
-
-/** True only when the service exists, is ready and declares the capability. Absent means false. */
-export function hasCapability(entry: Entry | undefined, name: string): boolean {
-  return serviceReady(entry) && entry?.capabilities[name] === true;
-}
-
-/**
- * Services the configured portal depends on. A production build needs a manifest entry for each of them
- * (PORTAL_MANIFEST_MISSING); a docs-only portal with no gateway needs none.
- */
-export function requiredServices(
-  resolved: ResolvedConfigV2,
-): ManifestServiceName[] {
-  const portal = resolved.portal;
-  if (!portal?.enabled) return [];
-  const needs: ManifestServiceName[] = [];
-  const consoleOn = portal.console.enabled;
-  const gatewayOn = resolved.gateway?.enabled === true;
-  const identityOn = resolved.identity?.enabled === true;
-  if (identityOn && (consoleOn || portal.requireAuth)) needs.push("identity");
-  if (gatewayOn && (consoleOn || portal.docs.enabled)) needs.push("gateway");
-  if (resolved.plans?.enabled === true && consoleOn) needs.push("plans");
-  return needs;
-}
-
-/** Problems that stop a production build: a required service without a manifest entry. */
-export function missingManifestServices(
-  resolved: ResolvedConfigV2,
-  manifest: ServiceManifest | undefined,
-): ConfigIssue[] {
-  return requiredServices(resolved)
-    .filter((name) => manifest?.services[name] === undefined)
-    .map((name) =>
-      issue(
-        "PORTAL_MANIFEST_MISSING",
-        `services.${name}`,
-        `the portal needs the ${name} service, but services.json has no entry for it.`,
-        `Run \`apitogo deploy --only ${name}\` first.`,
-      ),
-    );
-}
-
-/**
- * The stand-in manifest for local runs before identity and plans exist. It is labelled `preview: true`, uses
- * the demo issuer-less shape (no URLs are invented) and is refused by production builds.
- */
-export function stubManifest(resolved: ResolvedConfigV2): ServiceManifest {
-  const portal = resolved.portal;
-  const consoleOn = portal?.enabled === true && portal.console.enabled;
-  return parseManifest({
-    schemaVersion: SUPPORTED_MANIFEST_SCHEMA,
-    preview: true,
-    project: { id: resolved.project.id, name: resolved.project.name },
-    services: {
-      ...(consoleOn && resolved.identity?.enabled
-        ? {
-            identity: {
-              provider: "apitogo",
-              status: "ready",
-              capabilities: { nativeSignup: true },
-            },
-          }
-        : {}),
-      ...(consoleOn && resolved.plans?.enabled
-        ? {
-            plans: {
-              status: "ready",
-              capabilities: { catalog: true },
-            },
-          }
-        : {}),
-    },
-  });
-}
-
-/**
- * Adds what a portal deploy learned (project, public URL, docs provider) to the manifest. Entries of other services
- * are kept as they are, so deploying the portal never erases what identity or plans wrote.
- */
-export function withPortalEntry(
-  existing: ServiceManifest | undefined,
-  info: {
-    projectId: string;
-    projectName: string;
-    url: string;
-    docs: { provider: string; url?: string };
-    now?: Date;
-  },
-): ServiceManifest {
-  const base: ServiceManifest =
-    existing ??
-    parseManifest({
-      schemaVersion: SUPPORTED_MANIFEST_SCHEMA,
-      project: { name: info.projectName },
-    });
-  const previousPortal = base.services.portal;
-  return {
-    ...base,
-    schemaVersion: SUPPORTED_MANIFEST_SCHEMA,
-    generatedAt: (info.now ?? new Date()).toISOString(),
-    preview: undefined,
-    project: { ...base.project, id: info.projectId, name: info.projectName },
-    services: {
-      ...base.services,
-      portal: {
-        ...previousPortal,
-        url: info.url.replace(/\/+$/, ""),
-        docs: info.docs,
-      },
-    },
-  };
-}
-
-/**
- * Adds the gateway entry a gateway deploy learned. Only public values: the base URL and what the platform says the
- * gateway can do. Entries of other services are kept as they are.
- */
-export function withGatewayEntry(
-  existing: ServiceManifest | undefined,
-  info: {
-    projectId: string;
-    projectName: string;
-    provider: string;
-    baseUrl: string;
-    capabilities: Record<string, boolean>;
-    openapiUrl?: string;
-    openapiHash?: string;
-    keyHeaderName?: string;
-    now?: Date;
-  },
-): ServiceManifest {
-  const base: ServiceManifest =
-    existing ??
-    parseManifest({
-      schemaVersion: SUPPORTED_MANIFEST_SCHEMA,
-      project: { name: info.projectName },
-    });
-  const baseUrl = info.baseUrl.replace(/\/+$/, "");
-  return {
-    ...base,
-    schemaVersion: SUPPORTED_MANIFEST_SCHEMA,
-    generatedAt: (info.now ?? new Date()).toISOString(),
-    preview: undefined,
-    project: { ...base.project, id: info.projectId, name: info.projectName },
-    services: {
-      ...base.services,
-      gateway: {
-        ...base.services.gateway,
-        provider: info.provider,
-        status: "ready",
-        baseUrl,
-        audience: baseUrl,
-        capabilities: info.capabilities,
-        ...(info.openapiUrl ? { openapiUrl: info.openapiUrl } : {}),
-        ...(info.openapiHash ? { openapiHash: info.openapiHash } : {}),
-        ...(info.keyHeaderName ? { keyHeaderName: info.keyHeaderName } : {}),
-      },
-    },
-  };
-}
-
-/**
- * Adds the identity entry an identity deploy learned: the issuer address, the portal's sign-in client and the audience
- * of its tokens. Public values only. Entries of other services are kept as they are.
- */
-export function withIdentityEntry(
-  existing: ServiceManifest | undefined,
-  info: {
-    projectId: string;
-    projectName: string;
-    /** `apitogo` for the platform's own identity, `oidc` for the customer's provider (nothing is made for it). */
-    provider?: "apitogo" | "oidc";
-    issuer: string;
-    clientId: string;
-    audience?: string;
-    nativeSignup: boolean;
-    now?: Date;
-  },
-): ServiceManifest {
-  const base: ServiceManifest =
-    existing ??
-    parseManifest({
-      schemaVersion: SUPPORTED_MANIFEST_SCHEMA,
-      project: { name: info.projectName },
-    });
-  return {
-    ...base,
-    schemaVersion: SUPPORTED_MANIFEST_SCHEMA,
-    generatedAt: (info.now ?? new Date()).toISOString(),
-    preview: undefined,
-    project: { ...base.project, id: info.projectId, name: info.projectName },
-    services: {
-      ...base.services,
-      identity: {
-        ...base.services.identity,
-        provider: info.provider ?? "apitogo",
-        status: "ready",
-        issuer: info.issuer.replace(/\/+$/, ""),
-        clientId: info.clientId,
-        scopes: ["openid", "profile", "email"],
-        ...(info.audience ? { audience: info.audience } : {}),
-        capabilities: { nativeSignup: info.nativeSignup },
-      },
-    },
-  };
-}
-
-/**
- * Adds the plans entry a plans deploy learned: where the portal reaches the plans backend and what it can do. Public
- * values only. Entries of other services are kept as they are.
- */
-export function withPlansEntry(
-  existing: ServiceManifest | undefined,
-  info: {
-    projectId: string;
-    projectName: string;
-    apiBaseUrl: string;
-    billing: string;
-    catalogRevision: number;
-    capabilities: Record<string, boolean>;
-    now?: Date;
-  },
-): ServiceManifest {
-  const base: ServiceManifest =
-    existing ??
-    parseManifest({
-      schemaVersion: SUPPORTED_MANIFEST_SCHEMA,
-      project: { name: info.projectName },
-    });
-  return {
-    ...base,
-    schemaVersion: SUPPORTED_MANIFEST_SCHEMA,
-    generatedAt: (info.now ?? new Date()).toISOString(),
-    preview: undefined,
-    project: { ...base.project, id: info.projectId, name: info.projectName },
-    services: {
-      ...base.services,
-      plans: {
-        ...base.services.plans,
-        provider: "apitogo",
-        status: "ready",
-        apiBaseUrl: info.apiBaseUrl.replace(/\/+$/, ""),
-        billing: info.billing,
-        catalogRevision: info.catalogRevision,
-        capabilities: info.capabilities,
-      },
-    },
-  };
-}
-
-/** Replaces `services.json` atomically. Public values only: this file ships inside the portal. */
-export async function writeManifest(
-  state: Pick<StatePaths, "dir">,
-  manifest: ServiceManifest,
-): Promise<void> {
-  const file = manifestPathFor(state);
-  await mkdir(path.dirname(file), { recursive: true });
-  const temporary = `${file}.${process.pid}.tmp`;
-  try {
-    await writeFile(
-      temporary,
-      `${JSON.stringify(manifest, null, 2)}\n`,
-      "utf8",
-    );
-    await rename(temporary, file);
-  } catch (error) {
-    await rm(temporary, { force: true });
-    throw error;
-  }
-}
-
-/**
- * Drops the entries of services that were torn down. The file is deleted when no service is left, because a
- * manifest with no services says nothing and would only look like a deployed project.
- */
-export async function removeServicesFromManifest(
-  state: Pick<StatePaths, "dir">,
-  names: readonly ManifestServiceName[],
-): Promise<void> {
-  const existing = await readManifest(state);
-  if (!existing) return;
-  const services = Object.fromEntries(
-    Object.entries(existing.services).filter(
-      ([name]) => !(names as readonly string[]).includes(name),
-    ),
-  );
-  if (Object.keys(services).length === 0) {
-    await rm(manifestPathFor(state), { force: true });
-    return;
-  }
-  await writeManifest(state, { ...existing, services });
-}
+import { mkdir, readFile, rename, rm, writeFile } from "node:fs/promises";
+import path from "node:path";
+import { z } from "zod";
+import { ConfigError, type ConfigIssue } from "./errors.js";
+import { manifestPathFor, type StatePaths } from "./paths.js";
+import type { ResolvedConfigV2 } from "./resolve.js";
+
+/** Highest `schemaVersion` this build of the portal understands. */
+export const SUPPORTED_MANIFEST_SCHEMA = 1;
+
+/** Object of booleans with camelCase names. A name that is absent means false (decision 19). */
+const Capabilities = z.record(z.string(), z.boolean()).default({});
+
+const Status = z.string().optional();
+
+/**
+ * The service manifest, `services.json` (Reference, section 4.1). Every service owns its entry; a service that is
+ * missing from the manifest is disabled or not yet deployed. Unknown fields are kept so a newer deploy does not
+ * break an older reader.
+ */
+const ServiceManifestSchema = z.looseObject({
+  schemaVersion: z.number().int(),
+  generatedAt: z.string().optional(),
+  /** Set only on the stub written for local runs; never present in a deployed manifest. */
+  preview: z.boolean().optional(),
+  project: z.looseObject({ id: z.string().optional(), name: z.string() }),
+  services: z
+    .looseObject({
+      portal: z
+        .looseObject({
+          url: z.string().optional(),
+          docs: z
+            .looseObject({ provider: z.string(), url: z.string().optional() })
+            .optional(),
+          console: z
+            .looseObject({ links: z.record(z.string(), z.string()).optional() })
+            .optional(),
+        })
+        .optional(),
+      identity: z
+        .looseObject({
+          provider: z.string().default("apitogo"),
+          status: Status,
+          issuer: z.string().optional(),
+          clientId: z.string().optional(),
+          scopes: z.array(z.string()).optional(),
+          audience: z.string().optional(),
+          capabilities: Capabilities,
+        })
+        .optional(),
+      gateway: z
+        .looseObject({
+          provider: z.string().optional(),
+          status: Status,
+          baseUrl: z.string().optional(),
+          openapiUrl: z.string().optional(),
+          openapiHash: z.string().optional(),
+          audience: z.string().optional(),
+          keyHeaderName: z.string().optional(),
+          capabilities: Capabilities,
+        })
+        .optional(),
+      plans: z
+        .looseObject({
+          provider: z.string().optional(),
+          status: Status,
+          apiBaseUrl: z.string().optional(),
+          keysApiBaseUrl: z.string().optional(),
+          billing: z.string().optional(),
+          audience: z.string().optional(),
+          scopes: z.array(z.string()).optional(),
+          catalogRevision: z.number().int().optional(),
+          capabilities: Capabilities,
+        })
+        .optional(),
+    })
+    .default({}),
+});
+
+export type ServiceManifest = z.infer<typeof ServiceManifestSchema>;
+export type ManifestServiceName = "identity" | "gateway" | "plans" | "portal";
+
+const issue = (
+  code: string,
+  path: string,
+  message: string,
+  hint?: string,
+): ConfigIssue => ({ code, path, message, hint });
+
+/** Validates parsed `services.json` content. Throws a ConfigError with stable codes. */
+export function parseManifest(
+  raw: unknown,
+  file = "services.json",
+): ServiceManifest {
+  const version =
+    typeof raw === "object" && raw !== null && "schemaVersion" in raw
+      ? raw.schemaVersion
+      : undefined;
+  if (typeof version === "number" && version > SUPPORTED_MANIFEST_SCHEMA) {
+    throw new ConfigError(file, [
+      issue(
+        "PORTAL_MANIFEST_SCHEMA",
+        "schemaVersion",
+        `services.json has schemaVersion ${version} but this CLI supports ${SUPPORTED_MANIFEST_SCHEMA}.`,
+        "Upgrade @lukoweb/apitogo.",
+      ),
+    ]);
+  }
+  const result = ServiceManifestSchema.safeParse(raw);
+  if (!result.success) {
+    throw new ConfigError(
+      file,
+      result.error.issues.map((problem) =>
+        issue(
+          "PORTAL_MANIFEST_INVALID",
+          problem.path.join("."),
+          problem.message,
+          "Run `apitogo deploy` to write a fresh services.json.",
+        ),
+      ),
+    );
+  }
+  return result.data;
+}
+
+/** Reads `services.json` from the state directory. Returns undefined when the file does not exist. */
+export async function readManifest(
+  state: Pick<StatePaths, "dir">,
+): Promise<ServiceManifest | undefined> {
+  const file = manifestPathFor(state);
+  let text: string;
+  try {
+    text = await readFile(file, "utf8");
+  } catch (error) {
+    if ((error as NodeJS.ErrnoException).code === "ENOENT") return undefined;
+    throw error;
+  }
+  try {
+    return parseManifest(JSON.parse(text), file);
+  } catch (error) {
+    if (error instanceof SyntaxError) {
+      throw new ConfigError(file, [
+        issue(
+          "PORTAL_MANIFEST_INVALID",
+          "",
+          `is not valid JSON (${error.message}).`,
+          "Run `apitogo deploy` to write a fresh services.json.",
+        ),
+      ]);
+    }
+    throw error;
+  }
+}
+
+type Entry = { status?: string; capabilities: Record<string, boolean> };
+
+/** A service is usable when it has an entry and is not still provisioning. A missing status counts as ready. */
+export function serviceReady(entry: { status?: string } | undefined): boolean {
+  return entry !== undefined && (entry.status ?? "ready") === "ready";
+}
+
+/** True only when the service exists, is ready and declares the capability. Absent means false. */
+export function hasCapability(entry: Entry | undefined, name: string): boolean {
+  return serviceReady(entry) && entry?.capabilities[name] === true;
+}
+
+/**
+ * Services the configured portal depends on. A production build needs a manifest entry for each of them
+ * (PORTAL_MANIFEST_MISSING); a docs-only portal with no gateway needs none.
+ */
+export function requiredServices(
+  resolved: ResolvedConfigV2,
+): ManifestServiceName[] {
+  const portal = resolved.portal;
+  if (!portal?.enabled) return [];
+  const needs: ManifestServiceName[] = [];
+  const consoleOn = portal.console.enabled;
+  const gatewayOn = resolved.gateway?.enabled === true;
+  const identityOn = resolved.identity?.enabled === true;
+  if (identityOn && (consoleOn || portal.requireAuth)) needs.push("identity");
+  if (gatewayOn && (consoleOn || portal.docs.enabled)) needs.push("gateway");
+  if (resolved.plans?.enabled === true && consoleOn) needs.push("plans");
+  return needs;
+}
+
+/** Problems that stop a production build: a required service without a manifest entry. */
+export function missingManifestServices(
+  resolved: ResolvedConfigV2,
+  manifest: ServiceManifest | undefined,
+): ConfigIssue[] {
+  return requiredServices(resolved)
+    .filter((name) => manifest?.services[name] === undefined)
+    .map((name) =>
+      issue(
+        "PORTAL_MANIFEST_MISSING",
+        `services.${name}`,
+        `the portal needs the ${name} service, but services.json has no entry for it.`,
+        `Run \`apitogo deploy --only ${name}\` first.`,
+      ),
+    );
+}
+
+/** Where a managed origin listens when it runs on this machine: the port the platform's hosting also uses. */
+export const PREVIEW_MANAGED_ORIGIN_URL = "http://localhost:8080";
+
+/**
+ * The address the API page of a preview calls before the gateway is deployed: the API itself. A proxy origin is
+ * reachable at its own URL; a managed origin is the user's code, run on this machine (`npm start` in its folder).
+ */
+function previewGatewayUrl(resolved: ResolvedConfigV2): string | undefined {
+  const gateway = resolved.gateway;
+  if (gateway?.enabled !== true) return undefined;
+  return gateway.origin.mode === "proxy"
+    ? gateway.origin.url
+    : PREVIEW_MANAGED_ORIGIN_URL;
+}
+
+/**
+ * The stand-in manifest for local runs before identity and plans exist. It is labelled `preview: true` and is
+ * refused by production builds. Sign-in gets no invented issuer; the API page calls the API directly, since the
+ * gateway has no address yet.
+ */
+export function stubManifest(resolved: ResolvedConfigV2): ServiceManifest {
+  const portal = resolved.portal;
+  const consoleOn = portal?.enabled === true && portal.console.enabled;
+  const gatewayUrl = previewGatewayUrl(resolved);
+  return parseManifest({
+    schemaVersion: SUPPORTED_MANIFEST_SCHEMA,
+    preview: true,
+    project: { id: resolved.project.id, name: resolved.project.name },
+    services: {
+      ...(gatewayUrl
+        ? { gateway: { status: "ready", baseUrl: gatewayUrl } }
+        : {}),
+      ...(consoleOn && resolved.identity?.enabled
+        ? {
+            identity: {
+              provider: "apitogo",
+              status: "ready",
+              capabilities: { nativeSignup: true },
+            },
+          }
+        : {}),
+      ...(consoleOn && resolved.plans?.enabled
+        ? {
+            plans: {
+              status: "ready",
+              capabilities: { catalog: true },
+            },
+          }
+        : {}),
+    },
+  });
+}
+
+/**
+ * Adds what a portal deploy learned (project, public URL, docs provider) to the manifest. Entries of other services
+ * are kept as they are, so deploying the portal never erases what identity or plans wrote.
+ */
+export function withPortalEntry(
+  existing: ServiceManifest | undefined,
+  info: {
+    projectId: string;
+    projectName: string;
+    url: string;
+    docs: { provider: string; url?: string };
+    now?: Date;
+  },
+): ServiceManifest {
+  const base: ServiceManifest =
+    existing ??
+    parseManifest({
+      schemaVersion: SUPPORTED_MANIFEST_SCHEMA,
+      project: { name: info.projectName },
+    });
+  const previousPortal = base.services.portal;
+  return {
+    ...base,
+    schemaVersion: SUPPORTED_MANIFEST_SCHEMA,
+    generatedAt: (info.now ?? new Date()).toISOString(),
+    preview: undefined,
+    project: { ...base.project, id: info.projectId, name: info.projectName },
+    services: {
+      ...base.services,
+      portal: {
+        ...previousPortal,
+        url: info.url.replace(/\/+$/, ""),
+        docs: info.docs,
+      },
+    },
+  };
+}
+
+/**
+ * Adds the gateway entry a gateway deploy learned. Only public values: the base URL and what the platform says the
+ * gateway can do. Entries of other services are kept as they are.
+ */
+export function withGatewayEntry(
+  existing: ServiceManifest | undefined,
+  info: {
+    projectId: string;
+    projectName: string;
+    provider: string;
+    baseUrl: string;
+    capabilities: Record<string, boolean>;
+    openapiUrl?: string;
+    openapiHash?: string;
+    keyHeaderName?: string;
+    now?: Date;
+  },
+): ServiceManifest {
+  const base: ServiceManifest =
+    existing ??
+    parseManifest({
+      schemaVersion: SUPPORTED_MANIFEST_SCHEMA,
+      project: { name: info.projectName },
+    });
+  const baseUrl = info.baseUrl.replace(/\/+$/, "");
+  return {
+    ...base,
+    schemaVersion: SUPPORTED_MANIFEST_SCHEMA,
+    generatedAt: (info.now ?? new Date()).toISOString(),
+    preview: undefined,
+    project: { ...base.project, id: info.projectId, name: info.projectName },
+    services: {
+      ...base.services,
+      gateway: {
+        ...base.services.gateway,
+        provider: info.provider,
+        status: "ready",
+        baseUrl,
+        audience: baseUrl,
+        capabilities: info.capabilities,
+        ...(info.openapiUrl ? { openapiUrl: info.openapiUrl } : {}),
+        ...(info.openapiHash ? { openapiHash: info.openapiHash } : {}),
+        ...(info.keyHeaderName ? { keyHeaderName: info.keyHeaderName } : {}),
+      },
+    },
+  };
+}
+
+/**
+ * Adds the identity entry an identity deploy learned: the issuer address, the portal's sign-in client and the audience
+ * of its tokens. Public values only. Entries of other services are kept as they are.
+ */
+export function withIdentityEntry(
+  existing: ServiceManifest | undefined,
+  info: {
+    projectId: string;
+    projectName: string;
+    /** `apitogo` for the platform's own identity, `oidc` for the customer's provider (nothing is made for it). */
+    provider?: "apitogo" | "oidc";
+    issuer: string;
+    clientId: string;
+    audience?: string;
+    nativeSignup: boolean;
+    now?: Date;
+  },
+): ServiceManifest {
+  const base: ServiceManifest =
+    existing ??
+    parseManifest({
+      schemaVersion: SUPPORTED_MANIFEST_SCHEMA,
+      project: { name: info.projectName },
+    });
+  return {
+    ...base,
+    schemaVersion: SUPPORTED_MANIFEST_SCHEMA,
+    generatedAt: (info.now ?? new Date()).toISOString(),
+    preview: undefined,
+    project: { ...base.project, id: info.projectId, name: info.projectName },
+    services: {
+      ...base.services,
+      identity: {
+        ...base.services.identity,
+        provider: info.provider ?? "apitogo",
+        status: "ready",
+        issuer: info.issuer.replace(/\/+$/, ""),
+        clientId: info.clientId,
+        scopes: ["openid", "profile", "email"],
+        ...(info.audience ? { audience: info.audience } : {}),
+        capabilities: { nativeSignup: info.nativeSignup },
+      },
+    },
+  };
+}
+
+/**
+ * Adds the plans entry a plans deploy learned: where the portal reaches the plans backend and what it can do. Public
+ * values only. Entries of other services are kept as they are.
+ */
+export function withPlansEntry(
+  existing: ServiceManifest | undefined,
+  info: {
+    projectId: string;
+    projectName: string;
+    apiBaseUrl: string;
+    billing: string;
+    catalogRevision: number;
+    capabilities: Record<string, boolean>;
+    now?: Date;
+  },
+): ServiceManifest {
+  const base: ServiceManifest =
+    existing ??
+    parseManifest({
+      schemaVersion: SUPPORTED_MANIFEST_SCHEMA,
+      project: { name: info.projectName },
+    });
+  return {
+    ...base,
+    schemaVersion: SUPPORTED_MANIFEST_SCHEMA,
+    generatedAt: (info.now ?? new Date()).toISOString(),
+    preview: undefined,
+    project: { ...base.project, id: info.projectId, name: info.projectName },
+    services: {
+      ...base.services,
+      plans: {
+        ...base.services.plans,
+        provider: "apitogo",
+        status: "ready",
+        apiBaseUrl: info.apiBaseUrl.replace(/\/+$/, ""),
+        billing: info.billing,
+        catalogRevision: info.catalogRevision,
+        capabilities: info.capabilities,
+      },
+    },
+  };
+}
+
+/** Replaces `services.json` atomically. Public values only: this file ships inside the portal. */
+export async function writeManifest(
+  state: Pick<StatePaths, "dir">,
+  manifest: ServiceManifest,
+): Promise<void> {
+  const file = manifestPathFor(state);
+  await mkdir(path.dirname(file), { recursive: true });
+  const temporary = `${file}.${process.pid}.tmp`;
+  try {
+    await writeFile(
+      temporary,
+      `${JSON.stringify(manifest, null, 2)}\n`,
+      "utf8",
+    );
+    await rename(temporary, file);
+  } catch (error) {
+    await rm(temporary, { force: true });
+    throw error;
+  }
+}
+
+/**
+ * Drops the entries of services that were torn down. The file is deleted when no service is left, because a
+ * manifest with no services says nothing and would only look like a deployed project.
+ */
+export async function removeServicesFromManifest(
+  state: Pick<StatePaths, "dir">,
+  names: readonly ManifestServiceName[],
+): Promise<void> {
+  const existing = await readManifest(state);
+  if (!existing) return;
+  const services = Object.fromEntries(
+    Object.entries(existing.services).filter(
+      ([name]) => !(names as readonly string[]).includes(name),
+    ),
+  );
+  if (Object.keys(services).length === 0) {
+    await rm(manifestPathFor(state), { force: true });
+    return;
+  }
+  await writeManifest(state, { ...existing, services });
+}