@lukoweb/apitogo 0.2.22 → 0.2.24

package/src/config/v2/services.ts

@@ -1,663 +1,663 @@
-import { access, mkdir, rename, rm, stat, writeFile } from "node:fs/promises";
-import path from "node:path";
-import { ApitogoError } from "../../lib/util/invariant.js";
-import { docsFromPaths, starterPage } from "./init.js";
-import { detectExistingDocs } from "./layout.js";
-import { loadConfigV2 } from "./load.js";
-import { parseConfigV2 } from "./parse.js";
-import { type ResolvedConfigV2, resolveConfigV2 } from "./resolve.js";
-import { checkDependencies } from "./rules.js";
-import type { ConfigV2 } from "./schema.js";
-
-export const SERVICES = ["portal", "gateway", "identity", "plans"] as const;
-export type ServiceName = (typeof SERVICES)[number];
-
-export class ServiceEditError extends ApitogoError {
-  constructor(message: string, developerHint?: string) {
-    super(message, { developerHint, title: "Cannot change the services" });
-    this.name = "ServiceEditError";
-  }
-}
-
-export function isServiceName(value: string): value is ServiceName {
-  return (SERVICES as readonly string[]).includes(value);
-}
-
-/** Options for `apitogo add`, one group per service (Reference, section 1.3). Everything is optional here. */
-export type AddOptions = {
-  dir: string;
-  /** Add the section with `enabled: false`. */
-  disabled?: boolean;
-  /** Include every docs folder found instead of asking. */
-  acceptAllDocs?: boolean;
-  portal?: {
-    name?: string;
-    docs?: string[] | false;
-    docsProvider?: "apitogo" | "external";
-    docsUrl?: string;
-    noConsole?: boolean;
-    requireAuth?: boolean;
-    search?: "pagefind" | "inkeep" | "none";
-  };
-  gateway?: {
-    provider?: string;
-    origin?: "managed" | "proxy";
-    url?: string;
-    source?: string;
-    runtime?: "nodejs" | "python" | "dotnet";
-    runtimeVersion?: string;
-    exclude?: string[];
-    spec?: string[];
-    createSpec?: boolean;
-    auth?: "identity" | "oidc";
-    oidcMetadataUrl?: string;
-    issuers?: string[];
-    audiences?: string[];
-    rateLimit?: string;
-    quota?: string;
-    cors?: string[];
-  };
-  identity?: {
-    native?: boolean;
-    provider?: "apitogo" | "oidc";
-    issuer?: string;
-    clientId?: string;
-    connection?: string;
-    authority?: string;
-    connectionClientId?: string;
-  };
-  plans?: {
-    file?: string;
-    template?: "free" | "tiered" | "none";
-    billing?: "stripe" | "none";
-  };
-};
-
-export type PlannedFile = { path: string; content: string };
-
-export type ServiceEdit = {
-  service: ServiceName;
-  action: "add" | "remove";
-  dir: string;
-  configPath: string;
-  /** The config that will be written. */
-  config: ConfigV2;
-  /** Files created by an add; files that already exist are listed in `keep` and never overwritten. */
-  files: PlannedFile[];
-  keep: string[];
-  /** Human-readable follow-ups: secrets to set, files left behind after a remove. */
-  notes: string[];
-};
-
-const exists = (target: string) =>
-  access(target).then(
-    () => true,
-    () => false,
-  );
-
-const rel = (dir: string, target: string) =>
-  path.relative(dir, target).split(path.sep).join("/") || ".";
-
-const STARTER_SPEC = (name: string) => `openapi: 3.1.0
-info:
-  title: ${JSON.stringify(name)}
-  version: 1.0.0
-paths:
-  /health:
-    get:
-      operationId: getHealth
-      summary: Health check
-      responses:
-        "200":
-          description: The service is up.
-`;
-
-const PLAN_TEMPLATES: Record<"free" | "tiered" | "none", unknown[]> = {
-  none: [],
-  free: [
-    {
-      sku: "free",
-      displayName: "Free",
-      default: true,
-      limits: {
-        // The platform's Free tier allows at most 3 calls per 60 seconds per plan; a higher number is refused.
-        rateLimit: { calls: 3, periodSeconds: 60 },
-        quota: { calls: 1000, periodDays: 30 },
-      },
-    },
-  ],
-  tiered: [
-    {
-      sku: "free",
-      displayName: "Free",
-      default: true,
-      limits: {
-        // The platform's Free tier allows at most 3 calls per 60 seconds per plan; a higher number is refused.
-        rateLimit: { calls: 3, periodSeconds: 60 },
-        quota: { calls: 1000, periodDays: 30 },
-      },
-    },
-    {
-      sku: "pro",
-      displayName: "Pro",
-      priceAmount: 49,
-      priceCurrency: "usd",
-      billingInterval: "month",
-      limits: {
-        rateLimit: { calls: 100, periodSeconds: 60 },
-        quota: { calls: 100000, periodDays: 30 },
-      },
-    },
-    {
-      sku: "enterprise",
-      displayName: "Enterprise",
-      pricingModel: "custom",
-      priceLabel: "Contact us",
-    },
-  ],
-};
-
-function pair(value: string, flag: string, unit: string): [number, number] {
-  const match = /^(\d+)\/(\d+)$/.exec(value);
-  if (!match) {
-    throw new ServiceEditError(
-      `${flag} must look like <calls>/<${unit}>, for example 100/60.`,
-    );
-  }
-  return [Number(match[1]), Number(match[2])];
-}
-
-/** The path of a file inside the project, relative to the config, refusing anything outside it. */
-function insideProject(dir: string, requested: string, what: string): string {
-  const absolute = path.resolve(dir, requested);
-  const relative = path.relative(dir, absolute);
-  if (
-    relative === "" ||
-    relative.startsWith("..") ||
-    path.isAbsolute(relative)
-  ) {
-    throw new ServiceEditError(
-      `${what} "${requested}" is outside the project directory.`,
-    );
-  }
-  return relative.split(path.sep).join("/");
-}
-
-type Context = {
-  dir: string;
-  config: ConfigV2;
-  resolved: ResolvedConfigV2;
-  options: AddOptions;
-  files: PlannedFile[];
-  keep: string[];
-  notes: string[];
-};
-
-async function addFile(context: Context, target: string, content: string) {
-  if (await exists(target)) context.keep.push(target);
-  else context.files.push({ path: target, content });
-}
-
-async function buildPortal(
-  context: Context,
-): Promise<NonNullable<ConfigV2["portal"]>> {
-  const { options, dir, resolved } = context;
-  const o = options.portal ?? {};
-  const external = o.docsProvider === "external";
-  if (!external && o.docsUrl) {
-    throw new ServiceEditError("--docs-url needs --docs-provider external.");
-  }
-  if (external && !o.docsUrl) {
-    throw new ServiceEditError(
-      "--docs-provider external needs --docs-url <https url>.",
-    );
-  }
-  const name = o.name?.trim() || resolved.project.name;
-
-  let content: string[] = [];
-  if (!external) {
-    if (Array.isArray(o.docs) && o.docs.length > 0) {
-      content = await docsFromPaths(dir, o.docs);
-    } else if (o.docs !== false) {
-      const candidates = await detectExistingDocs(dir);
-      if (
-        candidates.length === 1 ||
-        (candidates.length > 1 && options.acceptAllDocs)
-      ) {
-        content = candidates.map((candidate) => candidate.glob);
-      } else if (candidates.length > 1) {
-        throw new ServiceEditError(
-          `Several places with documentation were found (${candidates.map((c) => c.path).join(", ")}).`,
-          "Pass --docs <path> for each one to include, --no-docs to include none, or --yes to include all.",
-        );
-      }
-    }
-    if (content.length === 0) {
-      await addFile(
-        context,
-        path.join(resolved.root, "portal", "pages", "index.mdx"),
-        starterPage(name),
-      );
-    }
-  }
-
-  return {
-    ...(options.disabled ? { enabled: false } : {}),
-    name,
-    ...(external
-      ? { docs: { provider: "external" as const, url: o.docsUrl } }
-      : content.length > 0
-        ? { docs: { content } }
-        : {}),
-    ...(o.noConsole ? { console: { enabled: false } } : {}),
-    ...(o.requireAuth ? { requireAuth: true } : {}),
-    ...(o.search && !external ? { search: o.search } : {}),
-  };
-}
-
-async function buildGateway(
-  context: Context,
-): Promise<NonNullable<ConfigV2["gateway"]>> {
-  const { options, dir, resolved } = context;
-  const o = options.gateway ?? {};
-  const mode =
-    o.origin ??
-    (o.url ? "proxy" : o.source || o.runtime ? "managed" : undefined);
-  if (!mode) {
-    throw new ServiceEditError(
-      "The gateway needs an origin: say how it reaches your API.",
-      "Pass --origin proxy --url <https url> for an API you host, or --origin managed --source <folder> --runtime <nodejs|python|dotnet> --runtime-version <version> to have it run your code.",
-    );
-  }
-  let origin: NonNullable<ConfigV2["gateway"]>["origin"];
-  if (mode === "proxy") {
-    if (!o.url)
-      throw new ServiceEditError("--origin proxy needs --url <https url>.");
-    origin = { mode, url: o.url };
-  } else {
-    if (!o.source || !o.runtime || !o.runtimeVersion) {
-      throw new ServiceEditError(
-        "--origin managed needs --source, --runtime and --runtime-version.",
-        "For example: --source server --runtime nodejs --runtime-version NODE_22_LTS.",
-      );
-    }
-    origin = {
-      mode,
-      source: insideProject(dir, o.source, "Source folder"),
-      runtime: o.runtime,
-      runtimeVersion: o.runtimeVersion,
-      ...(o.exclude?.length ? { exclude: o.exclude } : {}),
-    };
-  }
-
-  let specs: string[];
-  if (o.spec?.length) {
-    specs = [];
-    for (const requested of o.spec) {
-      const relative = insideProject(dir, requested, "OpenAPI file");
-      if (
-        !(await stat(path.join(dir, relative)).then(
-          (s) => s.isFile(),
-          () => false,
-        ))
-      ) {
-        throw new ServiceEditError(
-          `OpenAPI file "${requested}" does not exist in ${dir}.`,
-        );
-      }
-      specs.push(relative);
-    }
-  } else if (o.createSpec) {
-    const target = path.join(resolved.apisDir, "openapi.yaml");
-    await addFile(context, target, STARTER_SPEC(resolved.project.name));
-    specs = [rel(dir, target)];
-  } else {
-    throw new ServiceEditError(
-      "The gateway needs an OpenAPI file and none was given.",
-      "Pass --spec <path> for an existing file, or --create-spec to start from a small one.",
-    );
-  }
-
-  const auth = o.auth
-    ? o.auth === "identity"
-      ? { mode: "identity" as const }
-      : {
-          mode: "oidc" as const,
-          ...(o.oidcMetadataUrl ? { metadataUrl: o.oidcMetadataUrl } : {}),
-          ...(o.issuers?.length ? { issuers: o.issuers } : {}),
-          ...(o.audiences?.length ? { audiences: o.audiences } : {}),
-        }
-    : undefined;
-
-  const rateLimit = o.rateLimit
-    ? pair(o.rateLimit, "--rate-limit", "seconds")
-    : undefined;
-  const quota = o.quota ? pair(o.quota, "--quota", "days") : undefined;
-  const policies = {
-    ...(rateLimit
-      ? { rateLimit: { calls: rateLimit[0], periodSeconds: rateLimit[1] } }
-      : {}),
-    ...(quota ? { quota: { calls: quota[0], periodDays: quota[1] } } : {}),
-    ...(o.cors?.length ? { cors: o.cors } : {}),
-  };
-
-  return {
-    ...(options.disabled ? { enabled: false } : {}),
-    ...(o.provider ? { provider: o.provider } : {}),
-    origin,
-    specs,
-    ...(auth ? { auth } : {}),
-    ...(Object.keys(policies).length > 0 ? { policies } : {}),
-  };
-}
-
-function buildIdentity(context: Context): NonNullable<ConfigV2["identity"]> {
-  const { options } = context;
-  const o = options.identity ?? {};
-  const provider = o.provider ?? "apitogo";
-  if (provider === "oidc") {
-    if (!o.issuer)
-      throw new ServiceEditError("--provider oidc needs --issuer <https url>.");
-    if (o.connection || o.native === false) {
-      throw new ServiceEditError(
-        "--no-native and --connection only apply to the apitogo identity provider.",
-      );
-    }
-    return {
-      ...(options.disabled ? { enabled: false } : {}),
-      provider,
-      issuer: o.issuer,
-      ...(o.clientId ? { clientId: o.clientId } : {}),
-    };
-  }
-  if (o.issuer || o.clientId) {
-    throw new ServiceEditError(
-      "--issuer and --client-id need --provider oidc.",
-    );
-  }
-  const connections = o.connection
-    ? (() => {
-        if (!o.authority || !o.connectionClientId) {
-          throw new ServiceEditError(
-            "--connection needs --authority <https url> and --connection-client-id <id>.",
-          );
-        }
-        const secret = `${o.connection.toUpperCase().replace(/[^A-Z0-9]/g, "_")}_CLIENT_SECRET`;
-        context.notes.push(
-          `Set the connection's client secret: apitogo secrets set ${secret}`,
-        );
-        return [
-          {
-            id: o.connection,
-            type: "oidc" as const,
-            authority: o.authority,
-            clientId: o.connectionClientId,
-            clientSecret: `secret:${secret}`,
-          },
-        ];
-      })()
-    : undefined;
-  return {
-    ...(options.disabled ? { enabled: false } : {}),
-    ...(provider !== "apitogo" ? { provider } : {}),
-    ...(o.native === false ? { native: false } : {}),
-    ...(connections ? { connections } : {}),
-  };
-}
-
-async function buildPlans(
-  context: Context,
-): Promise<NonNullable<ConfigV2["plans"]>> {
-  const { options, dir, resolved } = context;
-  const o = options.plans ?? {};
-  const template = o.template ?? "free";
-  const billing = o.billing ?? "stripe";
-  if (template === "tiered" && billing === "none") {
-    throw new ServiceEditError(
-      "The tiered template has paid plans, which need a billing provider.",
-      "Use --billing stripe, or --template free.",
-    );
-  }
-  const file = o.file ? insideProject(dir, o.file, "Plans file") : undefined;
-  const target = file
-    ? path.join(dir, file)
-    : (resolved.plans?.file ?? path.join(resolved.root, "plans.json"));
-  await addFile(
-    context,
-    target,
-    `${JSON.stringify({ version: 1, plans: PLAN_TEMPLATES[template] }, null, 2)}\n`,
-  );
-  if (billing === "stripe") {
-    context.notes.push(
-      "Set the billing key: apitogo secrets set STRIPE_API_KEY",
-    );
-  }
-  return {
-    ...(options.disabled ? { enabled: false } : {}),
-    ...(file ? { file } : {}),
-    ...(billing === "stripe"
-      ? {
-          billing: {
-            provider: "stripe" as const,
-            apiKey: "secret:STRIPE_API_KEY",
-          },
-        }
-      : { billing: { provider: "none" as const } }),
-  };
-}
-
-function reparse(configPath: string, raw: ConfigV2): ConfigV2 {
-  // The strict parser is the one source of truth for what a valid config is.
-  return parseConfigV2(JSON.parse(JSON.stringify(raw)), configPath);
-}
-
-function dependencyProblems(config: ConfigV2, configPath: string) {
-  return checkDependencies(config, resolveConfigV2(config, configPath));
-}
-
-/**
- * Decides what `add <service>` would write without touching the disk. The strict schema and the dependency rules
- * (Reference, section 2.1) run on the new config first, so a refused add changes nothing.
- */
-export async function planAddService(
-  service: ServiceName,
-  options: AddOptions,
-): Promise<ServiceEdit> {
-  const dir = path.resolve(options.dir);
-  const { config, resolved } = loadConfigV2(dir);
-  if (config[service] !== undefined) {
-    throw new ServiceEditError(
-      `${service} is already in ${path.basename(resolved.configPath)}.`,
-      `Edit the file, or run \`apitogo remove ${service}\` first. Its files are kept.`,
-    );
-  }
-
-  const context: Context = {
-    dir,
-    config,
-    resolved,
-    options,
-    files: [],
-    keep: [],
-    notes: [],
-  };
-  const section =
-    service === "portal"
-      ? await buildPortal(context)
-      : service === "gateway"
-        ? await buildGateway(context)
-        : service === "identity"
-          ? buildIdentity(context)
-          : await buildPlans(context);
-
-  const next = reparse(resolved.configPath, { ...config, [service]: section });
-  if (!options.disabled) {
-    const before = new Set(
-      dependencyProblems(config, resolved.configPath).map(
-        (i) => i.code + i.path,
-      ),
-    );
-    const added = dependencyProblems(next, resolved.configPath).filter(
-      (issue) => !before.has(issue.code + issue.path),
-    );
-    if (added.length > 0) {
-      throw new ServiceEditError(
-        added.map((issue) => issue.message).join(" "),
-        added
-          .map((issue) => issue.hint)
-          .filter(Boolean)
-          .join(" ") || "Add the missing service first.",
-      );
-    }
-  }
-
-  return {
-    service,
-    action: "add",
-    dir,
-    configPath: resolved.configPath,
-    config: next,
-    files: context.files,
-    keep: context.keep,
-    notes: context.notes,
-  };
-}
-
-/**
- * Decides what `remove <service>` would do: the section goes, every file stays. Refuses when another enabled
- * service would be left without something it needs.
- */
-export async function planRemoveService(
-  service: ServiceName,
-  options: { dir: string },
-): Promise<ServiceEdit> {
-  const dir = path.resolve(options.dir);
-  const { config, resolved } = loadConfigV2(dir);
-  if (config[service] === undefined) {
-    throw new ServiceEditError(
-      `${service} is not in ${path.basename(resolved.configPath)}.`,
-    );
-  }
-  const { [service]: removed, ...rest } = config;
-  const next = reparse(resolved.configPath, rest as ConfigV2);
-
-  const before = new Set(
-    dependencyProblems(config, resolved.configPath).map((i) => i.code + i.path),
-  );
-  const caused = dependencyProblems(next, resolved.configPath).filter(
-    (issue) => !before.has(issue.code + issue.path),
-  );
-  if (caused.length > 0) {
-    throw new ServiceEditError(
-      `${service} cannot be removed while something depends on it: ${caused.map((issue) => issue.message).join(" ")}`,
-      "Remove or change the dependent service first.",
-    );
-  }
-
-  const left: string[] = [];
-  const r = resolved;
-  if (service === "portal" && r.portal) left.push(rel(dir, r.portal.dir));
-  if (service === "plans" && r.plans) left.push(rel(dir, r.plans.file));
-  if (service === "gateway" && r.gateway)
-    left.push(...r.gateway.specs.map((s) => rel(dir, s)));
-  void removed;
-
-  return {
-    service,
-    action: "remove",
-    dir,
-    configPath: resolved.configPath,
-    config: next,
-    files: [],
-    keep: [],
-    notes: left.length > 0 ? [`Files are kept: ${left.join(", ")}.`] : [],
-  };
-}
-
-/** Replaces the config file atomically: a failure leaves the old file in place. */
-async function writeConfig(
-  configPath: string,
-  config: ConfigV2,
-): Promise<void> {
-  const temporary = `${configPath}.${process.pid}.tmp`;
-  try {
-    await writeFile(temporary, `${JSON.stringify(config, null, 2)}\n`, "utf8");
-    await rename(temporary, configPath);
-  } catch (error) {
-    await rm(temporary, { force: true });
-    throw error;
-  }
-}
-
-/** Writes new files (never over existing ones), then replaces the config atomically. A failure leaves the old config. */
-export async function applyServiceEdit(
-  edit: ServiceEdit,
-): Promise<{ created: string[] }> {
-  const created: string[] = [];
-  for (const file of edit.files) {
-    await mkdir(path.dirname(file.path), { recursive: true });
-    try {
-      await writeFile(file.path, file.content, { flag: "wx" });
-      created.push(file.path);
-    } catch (error) {
-      if ((error as NodeJS.ErrnoException).code !== "EEXIST") throw error;
-    }
-  }
-  await writeConfig(edit.configPath, edit.config);
-  return { created };
-}
-
-/** The "will change" list shown before anything is written. */
-export function formatServiceEdit(edit: ServiceEdit): string[] {
-  const verb = edit.action === "add" ? "Adds" : "Removes";
-  return [
-    `${verb} the ${edit.service} section in ${path.basename(edit.configPath)}.`,
-    ...(edit.files.length > 0
-      ? [
-          "Will create:",
-          ...edit.files.map((file) => `  ${rel(edit.dir, file.path)}`),
-        ]
-      : []),
-    ...(edit.keep.length > 0
-      ? [
-          `Already there, left alone: ${edit.keep.map((file) => rel(edit.dir, file)).join(", ")}`,
-        ]
-      : []),
-    ...edit.notes,
-  ];
-}
-
-/**
- * Writes `project.id` into the config when it has none: `deploy` and `project create` link a folder to a platform
- * project (Reference, section 3.1). An id that is already there is never replaced.
- */
-export async function setProjectId(
-  dir: string,
-  projectId: string,
-): Promise<boolean> {
-  const { config, resolved } = loadConfigV2(dir);
-  if (config.project?.id) return false;
-  const next = reparse(resolved.configPath, {
-    ...config,
-    project: { ...config.project, id: projectId },
-  });
-  await writeConfig(resolved.configPath, next);
-  return true;
-}
-
-/** Removes `project.id` when it is the given id: the project is gone, so the link would only point at nothing. */
-export async function clearProjectId(
-  dir: string,
-  projectId: string,
-): Promise<boolean> {
-  const { config, resolved } = loadConfigV2(dir);
-  if (config.project?.id !== projectId) return false;
-  const { id: _id, ...project } = config.project;
-  const { project: _old, ...rest } = config;
-  const next = reparse(resolved.configPath, {
-    ...rest,
-    ...(Object.keys(project).length > 0 ? { project } : {}),
-  });
-  await writeConfig(resolved.configPath, next);
-  return true;
-}
+import { access, mkdir, rename, rm, stat, writeFile } from "node:fs/promises";
+import path from "node:path";
+import { ApitogoError } from "../../lib/util/invariant.js";
+import { docsFromPaths, starterPage } from "./init.js";
+import { detectExistingDocs } from "./layout.js";
+import { loadConfigV2 } from "./load.js";
+import { parseConfigV2 } from "./parse.js";
+import { type ResolvedConfigV2, resolveConfigV2 } from "./resolve.js";
+import { checkDependencies } from "./rules.js";
+import type { ConfigV2 } from "./schema.js";
+
+export const SERVICES = ["portal", "gateway", "identity", "plans"] as const;
+export type ServiceName = (typeof SERVICES)[number];
+
+export class ServiceEditError extends ApitogoError {
+  constructor(message: string, developerHint?: string) {
+    super(message, { developerHint, title: "Cannot change the services" });
+    this.name = "ServiceEditError";
+  }
+}
+
+export function isServiceName(value: string): value is ServiceName {
+  return (SERVICES as readonly string[]).includes(value);
+}
+
+/** Options for `apitogo add`, one group per service (Reference, section 1.3). Everything is optional here. */
+export type AddOptions = {
+  dir: string;
+  /** Add the section with `enabled: false`. */
+  disabled?: boolean;
+  /** Include every docs folder found instead of asking. */
+  acceptAllDocs?: boolean;
+  portal?: {
+    name?: string;
+    docs?: string[] | false;
+    docsProvider?: "apitogo" | "external";
+    docsUrl?: string;
+    noConsole?: boolean;
+    requireAuth?: boolean;
+    search?: "pagefind" | "inkeep" | "none";
+  };
+  gateway?: {
+    provider?: string;
+    origin?: "managed" | "proxy";
+    url?: string;
+    source?: string;
+    runtime?: "nodejs" | "python" | "dotnet";
+    runtimeVersion?: string;
+    exclude?: string[];
+    spec?: string[];
+    createSpec?: boolean;
+    auth?: "identity" | "oidc";
+    oidcMetadataUrl?: string;
+    issuers?: string[];
+    audiences?: string[];
+    rateLimit?: string;
+    quota?: string;
+    cors?: string[];
+  };
+  identity?: {
+    native?: boolean;
+    provider?: "apitogo" | "oidc";
+    issuer?: string;
+    clientId?: string;
+    connection?: string;
+    authority?: string;
+    connectionClientId?: string;
+  };
+  plans?: {
+    file?: string;
+    template?: "free" | "tiered" | "none";
+    billing?: "stripe" | "none";
+  };
+};
+
+export type PlannedFile = { path: string; content: string };
+
+export type ServiceEdit = {
+  service: ServiceName;
+  action: "add" | "remove";
+  dir: string;
+  configPath: string;
+  /** The config that will be written. */
+  config: ConfigV2;
+  /** Files created by an add; files that already exist are listed in `keep` and never overwritten. */
+  files: PlannedFile[];
+  keep: string[];
+  /** Human-readable follow-ups: secrets to set, files left behind after a remove. */
+  notes: string[];
+};
+
+const exists = (target: string) =>
+  access(target).then(
+    () => true,
+    () => false,
+  );
+
+const rel = (dir: string, target: string) =>
+  path.relative(dir, target).split(path.sep).join("/") || ".";
+
+const STARTER_SPEC = (name: string) => `openapi: 3.1.0
+info:
+  title: ${JSON.stringify(name)}
+  version: 1.0.0
+paths:
+  /health:
+    get:
+      operationId: getHealth
+      summary: Health check
+      responses:
+        "200":
+          description: The service is up.
+`;
+
+const PLAN_TEMPLATES: Record<"free" | "tiered" | "none", unknown[]> = {
+  none: [],
+  free: [
+    {
+      sku: "free",
+      displayName: "Free",
+      default: true,
+      limits: {
+        // The platform's Free tier allows at most 3 calls per 60 seconds per plan; a higher number is refused.
+        rateLimit: { calls: 3, periodSeconds: 60 },
+        quota: { calls: 1000, periodDays: 30 },
+      },
+    },
+  ],
+  tiered: [
+    {
+      sku: "free",
+      displayName: "Free",
+      default: true,
+      limits: {
+        // The platform's Free tier allows at most 3 calls per 60 seconds per plan; a higher number is refused.
+        rateLimit: { calls: 3, periodSeconds: 60 },
+        quota: { calls: 1000, periodDays: 30 },
+      },
+    },
+    {
+      sku: "pro",
+      displayName: "Pro",
+      priceAmount: 49,
+      priceCurrency: "usd",
+      billingInterval: "month",
+      limits: {
+        rateLimit: { calls: 100, periodSeconds: 60 },
+        quota: { calls: 100000, periodDays: 30 },
+      },
+    },
+    {
+      sku: "enterprise",
+      displayName: "Enterprise",
+      pricingModel: "custom",
+      priceLabel: "Contact us",
+    },
+  ],
+};
+
+function pair(value: string, flag: string, unit: string): [number, number] {
+  const match = /^(\d+)\/(\d+)$/.exec(value);
+  if (!match) {
+    throw new ServiceEditError(
+      `${flag} must look like <calls>/<${unit}>, for example 100/60.`,
+    );
+  }
+  return [Number(match[1]), Number(match[2])];
+}
+
+/** The path of a file inside the project, relative to the config, refusing anything outside it. */
+function insideProject(dir: string, requested: string, what: string): string {
+  const absolute = path.resolve(dir, requested);
+  const relative = path.relative(dir, absolute);
+  if (
+    relative === "" ||
+    relative.startsWith("..") ||
+    path.isAbsolute(relative)
+  ) {
+    throw new ServiceEditError(
+      `${what} "${requested}" is outside the project directory.`,
+    );
+  }
+  return relative.split(path.sep).join("/");
+}
+
+type Context = {
+  dir: string;
+  config: ConfigV2;
+  resolved: ResolvedConfigV2;
+  options: AddOptions;
+  files: PlannedFile[];
+  keep: string[];
+  notes: string[];
+};
+
+async function addFile(context: Context, target: string, content: string) {
+  if (await exists(target)) context.keep.push(target);
+  else context.files.push({ path: target, content });
+}
+
+async function buildPortal(
+  context: Context,
+): Promise<NonNullable<ConfigV2["portal"]>> {
+  const { options, dir, resolved } = context;
+  const o = options.portal ?? {};
+  const external = o.docsProvider === "external";
+  if (!external && o.docsUrl) {
+    throw new ServiceEditError("--docs-url needs --docs-provider external.");
+  }
+  if (external && !o.docsUrl) {
+    throw new ServiceEditError(
+      "--docs-provider external needs --docs-url <https url>.",
+    );
+  }
+  const name = o.name?.trim() || resolved.project.name;
+
+  let content: string[] = [];
+  if (!external) {
+    if (Array.isArray(o.docs) && o.docs.length > 0) {
+      content = await docsFromPaths(dir, o.docs);
+    } else if (o.docs !== false) {
+      const candidates = await detectExistingDocs(dir);
+      if (
+        candidates.length === 1 ||
+        (candidates.length > 1 && options.acceptAllDocs)
+      ) {
+        content = candidates.map((candidate) => candidate.glob);
+      } else if (candidates.length > 1) {
+        throw new ServiceEditError(
+          `Several places with documentation were found (${candidates.map((c) => c.path).join(", ")}).`,
+          "Pass --docs <path> for each one to include, --no-docs to include none, or --yes to include all.",
+        );
+      }
+    }
+    if (content.length === 0) {
+      await addFile(
+        context,
+        path.join(resolved.root, "portal", "pages", "index.mdx"),
+        starterPage(name),
+      );
+    }
+  }
+
+  return {
+    ...(options.disabled ? { enabled: false } : {}),
+    name,
+    ...(external
+      ? { docs: { provider: "external" as const, url: o.docsUrl } }
+      : content.length > 0
+        ? { docs: { content } }
+        : {}),
+    ...(o.noConsole ? { console: { enabled: false } } : {}),
+    ...(o.requireAuth ? { requireAuth: true } : {}),
+    ...(o.search && !external ? { search: o.search } : {}),
+  };
+}
+
+async function buildGateway(
+  context: Context,
+): Promise<NonNullable<ConfigV2["gateway"]>> {
+  const { options, dir, resolved } = context;
+  const o = options.gateway ?? {};
+  const mode =
+    o.origin ??
+    (o.url ? "proxy" : o.source || o.runtime ? "managed" : undefined);
+  if (!mode) {
+    throw new ServiceEditError(
+      "The gateway needs an origin: say how it reaches your API.",
+      "Pass --origin proxy --url <https url> for an API you host, or --origin managed --source <folder> --runtime <nodejs|python|dotnet> --runtime-version <version> to have it run your code.",
+    );
+  }
+  let origin: NonNullable<ConfigV2["gateway"]>["origin"];
+  if (mode === "proxy") {
+    if (!o.url)
+      throw new ServiceEditError("--origin proxy needs --url <https url>.");
+    origin = { mode, url: o.url };
+  } else {
+    if (!o.source || !o.runtime || !o.runtimeVersion) {
+      throw new ServiceEditError(
+        "--origin managed needs --source, --runtime and --runtime-version.",
+        "For example: --source server --runtime nodejs --runtime-version NODE_22_LTS.",
+      );
+    }
+    origin = {
+      mode,
+      source: insideProject(dir, o.source, "Source folder"),
+      runtime: o.runtime,
+      runtimeVersion: o.runtimeVersion,
+      ...(o.exclude?.length ? { exclude: o.exclude } : {}),
+    };
+  }
+
+  let specs: string[];
+  if (o.spec?.length) {
+    specs = [];
+    for (const requested of o.spec) {
+      const relative = insideProject(dir, requested, "OpenAPI file");
+      if (
+        !(await stat(path.join(dir, relative)).then(
+          (s) => s.isFile(),
+          () => false,
+        ))
+      ) {
+        throw new ServiceEditError(
+          `OpenAPI file "${requested}" does not exist in ${dir}.`,
+        );
+      }
+      specs.push(relative);
+    }
+  } else if (o.createSpec) {
+    const target = path.join(resolved.apisDir, "openapi.yaml");
+    await addFile(context, target, STARTER_SPEC(resolved.project.name));
+    specs = [rel(dir, target)];
+  } else {
+    throw new ServiceEditError(
+      "The gateway needs an OpenAPI file and none was given.",
+      "Pass --spec <path> for an existing file, or --create-spec to start from a small one.",
+    );
+  }
+
+  const auth = o.auth
+    ? o.auth === "identity"
+      ? { mode: "identity" as const }
+      : {
+          mode: "oidc" as const,
+          ...(o.oidcMetadataUrl ? { metadataUrl: o.oidcMetadataUrl } : {}),
+          ...(o.issuers?.length ? { issuers: o.issuers } : {}),
+          ...(o.audiences?.length ? { audiences: o.audiences } : {}),
+        }
+    : undefined;
+
+  const rateLimit = o.rateLimit
+    ? pair(o.rateLimit, "--rate-limit", "seconds")
+    : undefined;
+  const quota = o.quota ? pair(o.quota, "--quota", "days") : undefined;
+  const policies = {
+    ...(rateLimit
+      ? { rateLimit: { calls: rateLimit[0], periodSeconds: rateLimit[1] } }
+      : {}),
+    ...(quota ? { quota: { calls: quota[0], periodDays: quota[1] } } : {}),
+    ...(o.cors?.length ? { cors: o.cors } : {}),
+  };
+
+  return {
+    ...(options.disabled ? { enabled: false } : {}),
+    ...(o.provider ? { provider: o.provider } : {}),
+    origin,
+    specs,
+    ...(auth ? { auth } : {}),
+    ...(Object.keys(policies).length > 0 ? { policies } : {}),
+  };
+}
+
+function buildIdentity(context: Context): NonNullable<ConfigV2["identity"]> {
+  const { options } = context;
+  const o = options.identity ?? {};
+  const provider = o.provider ?? "apitogo";
+  if (provider === "oidc") {
+    if (!o.issuer)
+      throw new ServiceEditError("--provider oidc needs --issuer <https url>.");
+    if (o.connection || o.native === false) {
+      throw new ServiceEditError(
+        "--no-native and --connection only apply to the apitogo identity provider.",
+      );
+    }
+    return {
+      ...(options.disabled ? { enabled: false } : {}),
+      provider,
+      issuer: o.issuer,
+      ...(o.clientId ? { clientId: o.clientId } : {}),
+    };
+  }
+  if (o.issuer || o.clientId) {
+    throw new ServiceEditError(
+      "--issuer and --client-id need --provider oidc.",
+    );
+  }
+  const connections = o.connection
+    ? (() => {
+        if (!o.authority || !o.connectionClientId) {
+          throw new ServiceEditError(
+            "--connection needs --authority <https url> and --connection-client-id <id>.",
+          );
+        }
+        const secret = `${o.connection.toUpperCase().replace(/[^A-Z0-9]/g, "_")}_CLIENT_SECRET`;
+        context.notes.push(
+          `Set the connection's client secret: apitogo secrets set ${secret}`,
+        );
+        return [
+          {
+            id: o.connection,
+            type: "oidc" as const,
+            authority: o.authority,
+            clientId: o.connectionClientId,
+            clientSecret: `secret:${secret}`,
+          },
+        ];
+      })()
+    : undefined;
+  return {
+    ...(options.disabled ? { enabled: false } : {}),
+    ...(provider !== "apitogo" ? { provider } : {}),
+    ...(o.native === false ? { native: false } : {}),
+    ...(connections ? { connections } : {}),
+  };
+}
+
+async function buildPlans(
+  context: Context,
+): Promise<NonNullable<ConfigV2["plans"]>> {
+  const { options, dir, resolved } = context;
+  const o = options.plans ?? {};
+  const template = o.template ?? "free";
+  const billing = o.billing ?? "stripe";
+  if (template === "tiered" && billing === "none") {
+    throw new ServiceEditError(
+      "The tiered template has paid plans, which need a billing provider.",
+      "Use --billing stripe, or --template free.",
+    );
+  }
+  const file = o.file ? insideProject(dir, o.file, "Plans file") : undefined;
+  const target = file
+    ? path.join(dir, file)
+    : (resolved.plans?.file ?? path.join(resolved.root, "plans.json"));
+  await addFile(
+    context,
+    target,
+    `${JSON.stringify({ version: 1, plans: PLAN_TEMPLATES[template] }, null, 2)}\n`,
+  );
+  if (billing === "stripe") {
+    context.notes.push(
+      "Set the billing key: apitogo secrets set STRIPE_API_KEY",
+    );
+  }
+  return {
+    ...(options.disabled ? { enabled: false } : {}),
+    ...(file ? { file } : {}),
+    ...(billing === "stripe"
+      ? {
+          billing: {
+            provider: "stripe" as const,
+            apiKey: "secret:STRIPE_API_KEY",
+          },
+        }
+      : { billing: { provider: "none" as const } }),
+  };
+}
+
+function reparse(configPath: string, raw: ConfigV2): ConfigV2 {
+  // The strict parser is the one source of truth for what a valid config is.
+  return parseConfigV2(JSON.parse(JSON.stringify(raw)), configPath);
+}
+
+function dependencyProblems(config: ConfigV2, configPath: string) {
+  return checkDependencies(config, resolveConfigV2(config, configPath));
+}
+
+/**
+ * Decides what `add <service>` would write without touching the disk. The strict schema and the dependency rules
+ * (Reference, section 2.1) run on the new config first, so a refused add changes nothing.
+ */
+export async function planAddService(
+  service: ServiceName,
+  options: AddOptions,
+): Promise<ServiceEdit> {
+  const dir = path.resolve(options.dir);
+  const { config, resolved } = loadConfigV2(dir);
+  if (config[service] !== undefined) {
+    throw new ServiceEditError(
+      `${service} is already in ${path.basename(resolved.configPath)}.`,
+      `Edit the file, or run \`apitogo remove ${service}\` first. Its files are kept.`,
+    );
+  }
+
+  const context: Context = {
+    dir,
+    config,
+    resolved,
+    options,
+    files: [],
+    keep: [],
+    notes: [],
+  };
+  const section =
+    service === "portal"
+      ? await buildPortal(context)
+      : service === "gateway"
+        ? await buildGateway(context)
+        : service === "identity"
+          ? buildIdentity(context)
+          : await buildPlans(context);
+
+  const next = reparse(resolved.configPath, { ...config, [service]: section });
+  if (!options.disabled) {
+    const before = new Set(
+      dependencyProblems(config, resolved.configPath).map(
+        (i) => i.code + i.path,
+      ),
+    );
+    const added = dependencyProblems(next, resolved.configPath).filter(
+      (issue) => !before.has(issue.code + issue.path),
+    );
+    if (added.length > 0) {
+      throw new ServiceEditError(
+        added.map((issue) => issue.message).join(" "),
+        added
+          .map((issue) => issue.hint)
+          .filter(Boolean)
+          .join(" ") || "Add the missing service first.",
+      );
+    }
+  }
+
+  return {
+    service,
+    action: "add",
+    dir,
+    configPath: resolved.configPath,
+    config: next,
+    files: context.files,
+    keep: context.keep,
+    notes: context.notes,
+  };
+}
+
+/**
+ * Decides what `remove <service>` would do: the section goes, every file stays. Refuses when another enabled
+ * service would be left without something it needs.
+ */
+export async function planRemoveService(
+  service: ServiceName,
+  options: { dir: string },
+): Promise<ServiceEdit> {
+  const dir = path.resolve(options.dir);
+  const { config, resolved } = loadConfigV2(dir);
+  if (config[service] === undefined) {
+    throw new ServiceEditError(
+      `${service} is not in ${path.basename(resolved.configPath)}.`,
+    );
+  }
+  const { [service]: removed, ...rest } = config;
+  const next = reparse(resolved.configPath, rest as ConfigV2);
+
+  const before = new Set(
+    dependencyProblems(config, resolved.configPath).map((i) => i.code + i.path),
+  );
+  const caused = dependencyProblems(next, resolved.configPath).filter(
+    (issue) => !before.has(issue.code + issue.path),
+  );
+  if (caused.length > 0) {
+    throw new ServiceEditError(
+      `${service} cannot be removed while something depends on it: ${caused.map((issue) => issue.message).join(" ")}`,
+      "Remove or change the dependent service first.",
+    );
+  }
+
+  const left: string[] = [];
+  const r = resolved;
+  if (service === "portal" && r.portal) left.push(rel(dir, r.portal.dir));
+  if (service === "plans" && r.plans) left.push(rel(dir, r.plans.file));
+  if (service === "gateway" && r.gateway)
+    left.push(...r.gateway.specs.map((s) => rel(dir, s)));
+  void removed;
+
+  return {
+    service,
+    action: "remove",
+    dir,
+    configPath: resolved.configPath,
+    config: next,
+    files: [],
+    keep: [],
+    notes: left.length > 0 ? [`Files are kept: ${left.join(", ")}.`] : [],
+  };
+}
+
+/** Replaces the config file atomically: a failure leaves the old file in place. */
+async function writeConfig(
+  configPath: string,
+  config: ConfigV2,
+): Promise<void> {
+  const temporary = `${configPath}.${process.pid}.tmp`;
+  try {
+    await writeFile(temporary, `${JSON.stringify(config, null, 2)}\n`, "utf8");
+    await rename(temporary, configPath);
+  } catch (error) {
+    await rm(temporary, { force: true });
+    throw error;
+  }
+}
+
+/** Writes new files (never over existing ones), then replaces the config atomically. A failure leaves the old config. */
+export async function applyServiceEdit(
+  edit: ServiceEdit,
+): Promise<{ created: string[] }> {
+  const created: string[] = [];
+  for (const file of edit.files) {
+    await mkdir(path.dirname(file.path), { recursive: true });
+    try {
+      await writeFile(file.path, file.content, { flag: "wx" });
+      created.push(file.path);
+    } catch (error) {
+      if ((error as NodeJS.ErrnoException).code !== "EEXIST") throw error;
+    }
+  }
+  await writeConfig(edit.configPath, edit.config);
+  return { created };
+}
+
+/** The "will change" list shown before anything is written. */
+export function formatServiceEdit(edit: ServiceEdit): string[] {
+  const verb = edit.action === "add" ? "Adds" : "Removes";
+  return [
+    `${verb} the ${edit.service} section in ${path.basename(edit.configPath)}.`,
+    ...(edit.files.length > 0
+      ? [
+          "Will create:",
+          ...edit.files.map((file) => `  ${rel(edit.dir, file.path)}`),
+        ]
+      : []),
+    ...(edit.keep.length > 0
+      ? [
+          `Already there, left alone: ${edit.keep.map((file) => rel(edit.dir, file)).join(", ")}`,
+        ]
+      : []),
+    ...edit.notes,
+  ];
+}
+
+/**
+ * Writes `project.id` into the config when it has none: `deploy` and `project create` link a folder to a platform
+ * project (Reference, section 3.1). An id that is already there is never replaced.
+ */
+export async function setProjectId(
+  dir: string,
+  projectId: string,
+): Promise<boolean> {
+  const { config, resolved } = loadConfigV2(dir);
+  if (config.project?.id) return false;
+  const next = reparse(resolved.configPath, {
+    ...config,
+    project: { ...config.project, id: projectId },
+  });
+  await writeConfig(resolved.configPath, next);
+  return true;
+}
+
+/** Removes `project.id` when it is the given id: the project is gone, so the link would only point at nothing. */
+export async function clearProjectId(
+  dir: string,
+  projectId: string,
+): Promise<boolean> {
+  const { config, resolved } = loadConfigV2(dir);
+  if (config.project?.id !== projectId) return false;
+  const { id: _id, ...project } = config.project;
+  const { project: _old, ...rest } = config;
+  const next = reparse(resolved.configPath, {
+    ...rest,
+    ...(Object.keys(project).length > 0 ? { project } : {}),
+  });
+  await writeConfig(resolved.configPath, next);
+  return true;
+}