@lukoweb/apitogo 0.1.147 → 0.2.1

package/src/config/v2/manifest.ts

@@ -0,0 +1,293 @@
+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,
+      },
+    },
+  };
+}
+
+/** 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;
+  }
+}

package/src/config/v2/parse.ts

@@ -0,0 +1,214 @@
+import { z } from "zod";
+import { ConfigError, type ConfigIssue } from "./errors.js";
+import { CONFIG_VERSION, type ConfigV2, ConfigV2Schema } from "./schema.js";
+
+/** Keys that existed in an earlier design and were removed on purpose, with the reason to show the tenant. */
+const REMOVED_KEYS: Readonly<Record<string, string>> = {
+  "plans.provider":
+    "plans.provider was removed. Only plans.billing.provider (stripe or none) is selectable.",
+};
+
+type PathSegment = PropertyKey;
+
+function pathToString(path: readonly PathSegment[]): string {
+  return path.reduce<string>(
+    (acc, segment) =>
+      typeof segment === "number"
+        ? `${acc}[${segment}]`
+        : acc === ""
+          ? String(segment)
+          : `${acc}.${String(segment)}`,
+    "",
+  );
+}
+
+function unwrapOptional(schema: z.core.$ZodType): z.core.$ZodType {
+  let current = schema;
+  while (current instanceof z.ZodOptional) current = current.unwrap();
+  return current;
+}
+
+function step(
+  schema: z.core.$ZodType,
+  segment: PathSegment,
+): z.core.$ZodType | undefined {
+  const current = unwrapOptional(schema);
+  if (current instanceof z.ZodObject && typeof segment === "string") {
+    return current.shape[segment];
+  }
+  if (current instanceof z.ZodArray && typeof segment === "number") {
+    return current.element;
+  }
+  return undefined;
+}
+
+/** The keys the schema accepts at `path`, used for "did you mean" hints. Empty when the path cannot be resolved. */
+function knownKeysAt(path: readonly PathSegment[]): string[] {
+  let current: z.core.$ZodType | undefined = ConfigV2Schema;
+  for (const segment of path) {
+    if (!current) return [];
+    current = step(current, segment);
+  }
+  if (!current) return [];
+  const resolved = unwrapOptional(current);
+  return resolved instanceof z.ZodObject ? Object.keys(resolved.shape) : [];
+}
+
+function editDistance(a: string, b: string): number {
+  const row = Array.from({ length: b.length + 1 }, (_, i) => i);
+  for (let i = 1; i <= a.length; i++) {
+    let previous = row[0] ?? 0;
+    row[0] = i;
+    for (let j = 1; j <= b.length; j++) {
+      const current = row[j] ?? 0;
+      row[j] = Math.min(
+        (row[j] ?? 0) + 1,
+        (row[j - 1] ?? 0) + 1,
+        previous + (a[i - 1] === b[j - 1] ? 0 : 1),
+      );
+      previous = current;
+    }
+  }
+  return row[b.length] ?? 0;
+}
+
+function unknownKeyHint(
+  fullPath: string,
+  key: string,
+  known: readonly string[],
+): string | undefined {
+  const removed = REMOVED_KEYS[fullPath];
+  if (removed) return removed;
+
+  const closest = known
+    .map((candidate) => ({
+      candidate,
+      distance: editDistance(key.toLowerCase(), candidate.toLowerCase()),
+    }))
+    .filter(({ distance }) => distance <= 2)
+    .sort((a, b) => a.distance - b.distance)[0];
+  if (closest) return `Did you mean "${closest.candidate}"?`;
+  return known.length > 0 ? `Allowed keys: ${known.join(", ")}.` : undefined;
+}
+
+function mapIssue(issue: z.core.$ZodIssue): ConfigIssue[] {
+  const path = pathToString(issue.path);
+
+  switch (issue.code) {
+    case "unrecognized_keys":
+      return issue.keys.map((key) => {
+        const fullPath = pathToString([...issue.path, key]);
+        return {
+          code: "CONFIG_UNKNOWN_KEY",
+          path: fullPath,
+          message: `Unknown key "${key}".`,
+          hint: unknownKeyHint(fullPath, key, knownKeysAt(issue.path)),
+        };
+      });
+    case "invalid_value":
+      return [
+        {
+          code: "CONFIG_INVALID_VALUE",
+          path,
+          message: `must be one of: ${issue.values.map((v) => JSON.stringify(v)).join(", ")}.`,
+        },
+      ];
+    case "custom": {
+      const code =
+        typeof issue.params?.code === "string"
+          ? issue.params.code
+          : "CONFIG_INVALID_VALUE";
+      return [{ code, path, message: issue.message ?? "is invalid." }];
+    }
+    case "invalid_type":
+      return [
+        /received undefined/.test(issue.message)
+          ? { code: "CONFIG_MISSING_FIELD", path, message: "is required." }
+          : { code: "CONFIG_INVALID_VALUE", path, message: issue.message },
+      ];
+    default:
+      return [{ code: "CONFIG_INVALID_VALUE", path, message: issue.message }];
+  }
+}
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+
+/**
+ * Checks that must run before the schema because the schema cannot express them well: the version gate and the
+ * one legacy shape that deserves its own message. Returns the issues, the value to validate, and whether to stop.
+ */
+function preflight(raw: unknown): {
+  issues: ConfigIssue[];
+  value: unknown;
+  stop: boolean;
+} {
+  if (!isRecord(raw)) {
+    return {
+      issues: [
+        {
+          code: "CONFIG_INVALID_VALUE",
+          path: "",
+          message: "The config must be a JSON object.",
+        },
+      ],
+      value: raw,
+      stop: true,
+    };
+  }
+
+  if (raw.version !== CONFIG_VERSION) {
+    const found =
+      raw.version === undefined
+        ? '"version" is missing.'
+        : `"version" is ${JSON.stringify(raw.version)}.`;
+    return {
+      issues: [
+        {
+          code: "CONFIG_VERSION_UNSUPPORTED",
+          path: "version",
+          message: `${found} This CLI reads config version ${CONFIG_VERSION}.`,
+          hint: `Set "version": ${CONFIG_VERSION}. Earlier flat configs are not supported; see the Tenant Service Model for the new shape.`,
+        },
+      ],
+      value: raw,
+      stop: true,
+    };
+  }
+
+  const issues: ConfigIssue[] = [];
+  const value = structuredClone(raw);
+  const portal = value.portal;
+  if (isRecord(portal) && Array.isArray(portal.docs)) {
+    issues.push({
+      code: "PORTAL_CONFIG_INVALID",
+      path: "portal.docs",
+      message:
+        "portal.docs is now an object. Rename the globs array to portal.docs.content.",
+      hint: 'For example: "docs": { "content": ["docs/**/*.md"] }',
+    });
+    // Reported above; keep the schema from reporting the same value again as a type error.
+    delete portal.docs;
+  }
+
+  return { issues, value, stop: false };
+}
+
+/** Validates a parsed config. Throws a {@link ConfigError} listing every problem found. */
+export function parseConfigV2(
+  raw: unknown,
+  file = "apitogo.config.json",
+): ConfigV2 {
+  const pre = preflight(raw);
+  if (pre.stop) throw new ConfigError(file, pre.issues);
+
+  const result = ConfigV2Schema.safeParse(pre.value);
+  const issues = [
+    ...pre.issues,
+    ...(result.success ? [] : result.error.issues.flatMap(mapIssue)),
+  ];
+
+  if (issues.length > 0 || !result.success) throw new ConfigError(file, issues);
+  return result.data;
+}

package/src/config/v2/paths.ts

@@ -0,0 +1,54 @@
+import path from "node:path";
+import type { Layout } from "./schema.js";
+
+/** Names inside the generated-state directory (Tenant Service Model, section 4). All of it is regenerable. */
+export const STATE_FILE = "state.json";
+/** Service manifest written by `deploy` (Reference, section 4). Public values only. */
+export const MANIFEST_FILE = "services.json";
+export const GENERATED_DIR = "generated";
+export const BUILD_DIR = "build";
+
+/**
+ * Directory that holds the tenant-authored content for a layout: the config's own directory for `standalone`,
+ * an `apitogo/` folder next to it for `embedded`.
+ */
+export function layoutRoot(configDir: string, layout: Layout): string {
+  return layout === "embedded" ? path.join(configDir, "apitogo") : configDir;
+}
+
+/**
+ * Directory for generated and observed state. It carries its own `.gitignore` containing `*`, so the tenant's root
+ * `.gitignore` never needs to change.
+ */
+export function stateDirFor(configDir: string, layout: Layout): string {
+  return layout === "embedded"
+    ? path.join(configDir, "apitogo", ".state")
+    : path.join(configDir, ".apitogo");
+}
+
+/** Path of the service manifest inside a state directory. */
+export const manifestPathFor = (state: { dir: string }): string =>
+  path.join(state.dir, MANIFEST_FILE);
+
+export type StatePaths = {
+  dir: string;
+  /** Per-service ledger and artifact hashes. */
+  file: string;
+  /** Generated portal wrapper, resolved config snapshot, processed OpenAPI schemas. */
+  generatedDir: string;
+  /** Build output; replaces the old root `dist/`. */
+  buildDir: string;
+  /** The state directory's own ignore file. */
+  gitignore: string;
+};
+
+export function statePathsFor(configDir: string, layout: Layout): StatePaths {
+  const dir = stateDirFor(configDir, layout);
+  return {
+    dir,
+    file: path.join(dir, STATE_FILE),
+    generatedDir: path.join(dir, GENERATED_DIR),
+    buildDir: path.join(dir, BUILD_DIR),
+    gitignore: path.join(dir, ".gitignore"),
+  };
+}

package/src/config/v2/portal-profile.ts

@@ -0,0 +1,88 @@
+import type { ResolvedConfigV2 } from "./resolve.js";
+
+/**
+ * What the portal build has to do, derived from the resolved config. The generated wrapper (API-20) reads
+ * this and nothing else, so "docs only", "console only" and "both" are decided in one place.
+ */
+export type PortalProfile = {
+  /** False when `portal.enabled` is false or the config has no portal: nothing is built. */
+  enabled: boolean;
+  docs: {
+    enabled: boolean;
+    provider: "apitogo" | "external";
+    /** Absolute globs of pages APItoGo builds. Empty unless APItoGo hosts the docs. */
+    content: string[];
+    /** Where an external docs site lives; console links point at it. */
+    url?: string;
+  };
+  console: { enabled: boolean };
+  /** Build pipelines the portal needs. A pipeline that is false must not run, not just stay hidden. */
+  pipelines: {
+    /** Markdown and MDX pages, and the navigation made from them. */
+    markdown: boolean;
+    /** OpenAPI processing and the API reference pages. */
+    openapi: boolean;
+    /** Search index; only for docs APItoGo hosts. */
+    search: "pagefind" | "inkeep" | "none";
+  };
+  /** Built modules for the portal, in the module system's terms (`modules.docs`, `modules.userPanel`, ...). */
+  modules: { docs: boolean; userPanel: boolean };
+  /** What a portal whose docs live elsewhere still guarantees, so an external docs site can link to it. */
+  externalDocs?: {
+    url?: string;
+    /** The OpenAPI files the docs site can fetch. */
+    openapiExport: boolean;
+    /** The console answers cross-origin requests from the docs site. */
+    cors: boolean;
+    /** The portal manifest lists console links (sign-in, keys, usage, pricing) for the docs site to use. */
+    consoleLinksInManifest: boolean;
+    /** The console carries the project's theme and name, not APItoGo's. */
+    whiteLabelConsole: boolean;
+  };
+};
+
+const NOT_BUILT: PortalProfile = {
+  enabled: false,
+  docs: { enabled: false, provider: "apitogo", content: [] },
+  console: { enabled: false },
+  pipelines: { markdown: false, openapi: false, search: "none" },
+  modules: { docs: false, userPanel: false },
+};
+
+export function portalProfile(resolved: ResolvedConfigV2): PortalProfile {
+  const portal = resolved.portal;
+  if (!portal?.enabled) return NOT_BUILT;
+
+  const hostsDocs = portal.docs.enabled && portal.docs.provider === "apitogo";
+  const externalDocs =
+    portal.docs.enabled && portal.docs.provider === "external";
+  const gatewayOn = resolved.gateway?.enabled === true;
+
+  return {
+    enabled: true,
+    docs: {
+      enabled: portal.docs.enabled,
+      provider: portal.docs.provider,
+      content: hostsDocs ? portal.docs.content : [],
+      url: externalDocs ? portal.docs.url : undefined,
+    },
+    console: { enabled: portal.console.enabled },
+    pipelines: {
+      markdown: hostsDocs,
+      openapi: hostsDocs && gatewayOn,
+      search: hostsDocs ? portal.search : "none",
+    },
+    modules: { docs: hostsDocs, userPanel: portal.console.enabled },
+    ...(externalDocs
+      ? {
+          externalDocs: {
+            url: portal.docs.url,
+            openapiExport: gatewayOn,
+            cors: portal.console.enabled,
+            consoleLinksInManifest: portal.console.enabled,
+            whiteLabelConsole: portal.console.enabled,
+          },
+        }
+      : {}),
+  };
+}