@cosmicdrift/kumiko-guards 0.374.0 → 0.377.0

package/src/guard-tailwind-scan-surface.ts

@@ -2,10 +2,9 @@
 /**
  * Guard: `className` string-literal tokens under kumiko-framework's
  * `packages/bundled-features/src/**` must already be reachable through the
- * real Tailwind `@source` scan surface (`packages/renderer-web/src` +
- * `packages/renderer/src` + `samples/**\/src`, see
- * `packages/renderer-web/src/styles.css`). bundled-features itself is NOT
- * part of that scan surface (infra#654, follow-up to
+ * real Tailwind `@source` scan surface (`packages/renderer/src` +
+ * `samples/**\/src`, see `packages/renderer/src/web/styles.css`).
+ * bundled-features itself is NOT part of that scan surface (infra#654, follow-up to
  * kumiko-framework#2498/#2496): expanding `@source` there was verified to
  * work in the monorepo build but makes the standalone npm-consumer case
  * (no monorepo-relative scan path — #359) falsely green. A class used only
@@ -33,7 +32,7 @@
  *   bun guards/guard-tailwind-scan-surface.ts --write-baseline # (re)write the baseline
  *   bun guards/guard-tailwind-scan-surface.ts --no-baseline    # skip the comparison
  */
-import { existsSync, readFileSync, realpathSync } from "node:fs";
+import { existsSync, readFileSync, realpathSync, statSync } from "node:fs";
 import * as path from "node:path";
 import { Glob } from "bun";
 import { type SourceFile, SyntaxKind } from "ts-morph";
@@ -64,7 +63,6 @@ const SCAN: ScanSpec = {
   kinds: ["framework"],
   frameworkWithin: [
     "packages/bundled-features/src/**/*.tsx",
-    "packages/renderer-web/src/**",
     "packages/renderer/src/**",
     "samples/**/src/**",
   ],
@@ -75,7 +73,7 @@ const IGNORE_TAG = "kumiko-lint-ignore tailwind-scan-surface";
 // The allow-set mirrors what Tailwind's own scanner sees over the real
 // @source surface: every string/template-literal text in the file, not
 // just JSX className attributes — cn(...) calls, variant maps and shared
-// class constants in renderer-web/renderer/samples legitimately emit
+// class constants in renderer/samples legitimately emit
 // classes too. No EXCLUDE filter here on purpose: the @source globs
 // themselves scan __tests__/*.test.tsx just the same, so excluding them
 // from the allow-set would manufacture false positives.
@@ -148,7 +146,7 @@ function scan(
         if (token.length === 0 || allowed.has(token)) continue;
         findings.push({ file, line, token });
         console.warn(
-          `  [tailwind-scan-surface WARN] ${file}:${line}  class "${token}" is outside the Tailwind scan surface (renderer-web/src, renderer/src, samples/**/src)`,
+          `  [tailwind-scan-surface WARN] ${file}:${line}  class "${token}" is outside the Tailwind scan surface (renderer/src, samples/**/src)`,
         );
       }
     }
@@ -173,8 +171,8 @@ const tailwindScanSurfaceBaseline = (baselineRoot: string) =>
 // Second, independent rule: a consuming app repo (studio,
 // publicstatus, …) imports Framework AND Enterprise packages by npm name
 // (@cosmicdrift/* resp. @cosmicdriftgamestudio/*). Every one of them that
-// ships .tsx with `className` under its own scan surface (renderer-web +
-// renderer + samples/**/src) needs its own `@source` entry in the app's
+// ships .tsx with `className` under its own scan surface (renderer/src +
+// samples/**/src) needs its own `@source` entry in the app's
 // styles.css — nothing else scans it. Missed cases so far: kumiko-designer
 // in studio (studio#289), kumiko-ai-agent in publicstatus (publicstatus#442)
 // — both fixed by hand, both silent (no build/lint error) until noticed
@@ -244,11 +242,26 @@ function classNameExampleIn(pkgDir: string): string | undefined {
 }
 
 // Resolves `@import "spec";` specifiers in a CSS file to the imported file's
-// absolute path — a bare/package specifier (`@cosmicdrift/kumiko-renderer-
+// absolute path — a bare/package specifier (`@cosmicdrift/kumiko-renderer/
 // web/styles.css`) resolves through the SAME node_modules hop search as a
 // package dependency (it IS one); a relative specifier (`./x.css`) resolves
 // against the importing file's own directory. Unresolvable imports (e.g.
 // Tailwind's own `"tailwindcss"`) are dropped, not thrown on.
+// A subpath like "@scope/name/web/styles.css" only exists as a file through
+// the package's `exports` map ("./web/styles.css" -> "./src/web/styles.css").
+function resolveThroughPackageExports(appRoot: string, spec: string): string | undefined {
+  const [scope, name, ...rest] = spec.split("/");
+  if (scope === undefined || name === undefined || rest.length === 0) return undefined;
+  const pkgDir = resolvePackageDir(appRoot, `${scope}/${name}`);
+  if (pkgDir === undefined) return undefined;
+  const exportsField = readJsonSafe(path.join(pkgDir, "package.json"))?.["exports"];
+  if (typeof exportsField !== "object" || exportsField === null) return undefined;
+  const target = Object.entries(exportsField).find(([key]) => key === `./${rest.join("/")}`)?.[1];
+  if (typeof target !== "string") return undefined;
+  const abs = path.join(pkgDir, target);
+  return existsSync(abs) ? abs : undefined;
+}
+
 function resolveCssImports(cssAbsPath: string, css: string, appRoot: string): string[] {
   const specifiers = [...css.matchAll(/@import\s+["']([^"']+)["']/g)].map((m) => m[1]);
   const resolved: string[] = [];
@@ -262,7 +275,8 @@ function resolveCssImports(cssAbsPath: string, css: string, appRoot: string): st
     // Package-style specifier including its subpath (e.g. "@scope/name/
     // styles.css") — resolvePackageDir's node_modules hop search works
     // unchanged since it only checks existence, file or directory alike.
-    const candidate = resolvePackageDir(appRoot, spec);
+    const candidate =
+      resolvePackageDir(appRoot, spec) ?? resolveThroughPackageExports(appRoot, spec);
     if (candidate !== undefined) resolved.push(candidate);
   }
   return resolved;
@@ -297,8 +311,22 @@ function realpathOrSelf(p: string): string {
   }
 }
 
+// The deprecated renderer-web stylesheet only `@import`s the renderer's, so the
+// chain has to be followed past the first hop.
+function resolveCssImportsTransitively(cssAbsPath: string, css: string, appRoot: string): string[] {
+  const seen = new Set<string>();
+  const queue = resolveCssImports(cssAbsPath, css, appRoot);
+  for (let imported = queue.shift(); imported !== undefined; imported = queue.shift()) {
+    if (seen.has(imported)) continue;
+    seen.add(imported);
+    if (!existsSync(imported) || statSync(imported).isDirectory()) continue;
+    queue.push(...resolveCssImports(imported, readFileSync(imported, "utf-8"), appRoot));
+  }
+  return [...seen];
+}
+
 // A package is covered if an `@source` entry — in the app's own styles.css
-// OR in a CSS file it `@import`s (e.g. renderer-web's, which ships its own
+// OR in a CSS file it `@import`s (e.g. the renderer's web stylesheet, which ships its own
 // @source lines for the framework's scan surface) — resolves, in THIS
 // install layout, to a directory on the same branch as the package's own
 // directory (either one nested inside the other: the entry could scan the
@@ -314,7 +342,7 @@ function isCoveredByImportChain(
   pkgDir: string,
 ): boolean {
   const realPkgDir = realpathOrSelf(pkgDir);
-  for (const imported of resolveCssImports(stylesAbs, css, appRoot)) {
+  for (const imported of resolveCssImportsTransitively(stylesAbs, css, appRoot)) {
     for (const staticDir of sourceStaticDirsFromCss(imported)) {
       const realStaticDir = realpathOrSelf(staticDir);
       if (
@@ -329,6 +357,12 @@ function isCoveredByImportChain(
   return false;
 }
 
+function isRendererWebStylesheetImport(css: string): boolean {
+  return (
+    css.includes("kumiko-renderer/web/styles.css") || css.includes("kumiko-renderer-web/styles.css")
+  );
+}
+
 export function scanSourceCoverage(roots: readonly RepoRoot[]): SourceCoverageFinding[] {
   const findings: SourceCoverageFinding[] = [];
   for (const root of roots) {
@@ -336,14 +370,14 @@ export function scanSourceCoverage(roots: readonly RepoRoot[]): SourceCoverageFi
     const stylesAbs = path.join(root.absPath, APP_STYLES_REL);
     if (!existsSync(stylesAbs)) continue;
     const css = readFileSync(stylesAbs, "utf-8");
-    // Only apps on the renderer-web @source convention are in scope — an
+    // Only apps on the renderer web @source convention are in scope — an
     // app without that @import never had a scan surface to extend.
-    if (!css.includes("kumiko-renderer-web/styles.css")) continue;
+    if (!isRendererWebStylesheetImport(css)) continue;
     const pkg = readJsonSafe(path.join(root.absPath, "package.json"));
     if (!pkg) continue;
     const file = path.relative(ROOT, stylesAbs);
     for (const name of dependencyNames(pkg)) {
-      if (css.includes(name)) continue; // already @source'd (or @import'd, e.g. renderer-web itself)
+      if (css.includes(name)) continue; // already @source'd (or @import'd, e.g. the renderer's web stylesheet itself)
       const dir = resolvePackageDir(root.absPath, name);
       if (dir === undefined) continue;
       const example = classNameExampleIn(dir);
@@ -531,7 +565,7 @@ function checkBaseline(findings: readonly Finding[], baselineRoot: string): Guar
   const resolveLine = (file: string): number => findings.find((f) => f.file === file)?.line ?? 1;
   return tailwindScanSurfaceBaseline(baselineRoot).check(
     baselineCounts(findings),
-    "Class outside the @source scan surface (renderer-web/src, renderer/src, samples/**/src) — reuse a class already emitted there, or move the styling into renderer-web.",
+    "Class outside the @source scan surface (renderer/src, samples/**/src) — reuse a class already emitted there, or move the styling into renderer/src/web.",
     {
       formatDriftRemediation:
         "Run `bun guards/guard-tailwind-scan-surface.ts --write-baseline` once.",
@@ -569,8 +603,8 @@ export function createGuard(options: { readonly baselineRoot?: string } = {}): A
     name: "Tailwind-Scan-Surface Guard",
     scan: SCAN,
     hint:
-      "Tailwind class in bundled-features outside the @source scan surface (renderer-web/src, renderer/src, samples/**/src) " +
-      `— reuse a class already emitted there, or move the styling into renderer-web. Justified exception: // ${IGNORE_TAG} <reason>. ` +
+      "Tailwind class in bundled-features outside the @source scan surface (renderer/src, samples/**/src) " +
+      `— reuse a class already emitted there, or move the styling into renderer/src/web. Justified exception: // ${IGNORE_TAG} <reason>. ` +
       "Package without @source coverage in an app: add an @source entry for both install layouts. " +
       "@source with a node_modules/<pkg>/<segment> path: check whether <pkg> even publishes that segment (package.json files).",
     run: (files, roots = resolveRepoRoots()) => analyse(files, true, roots, baselineRoot),

package/src/guard-unsafe-append-event.ts

@@ -0,0 +1,125 @@
+#!/usr/bin/env bun
+/**
+ * Guard: reports `ctx.unsafeAppendEvent` (also `ctx["unsafeAppendEvent"]` and destructuring) outside `migrations/`, `upcasters/` and tests.
+ *
+ * `appendEvent` is the typed default, `tryAppendEvent` the optimistic variant. The untyped
+ * `unsafeAppendEvent` skips payload typing and is meant for migrations and upcasters, where the
+ * event type is not knowable at compile time.
+ *
+ * Existing call sites are frozen per file in `.kumiko-unsafe-append-event-baseline.json`; a count
+ * over the baseline fails, at or under passes. Without the file (consumer repos) the guard only
+ * warns.
+ *
+ * Usage:
+ *   bun packages/guards/src/guard-unsafe-append-event.ts                  # compare to baseline
+ *   bun packages/guards/src/guard-unsafe-append-event.ts --write-baseline # freeze current
+ */
+
+import * as path from "node:path";
+
+import { Node, type SourceFile, SyntaxKind } from "ts-morph";
+import {
+  ALL_REPO_KINDS,
+  type AstGuard,
+  baselineRatchet,
+  buildSharedProject,
+  filesForGuard,
+  isLocalFinding,
+  relFromRepoRoot,
+  runStandalone,
+  type ScanSpec,
+} from "./_lib/guard-kit";
+import { resolveRepoRoots } from "./_lib/roots";
+
+const SCAN: ScanSpec = {
+  kinds: ALL_REPO_KINDS,
+  scope: "source",
+  extensions: ["ts"],
+  frameworkWithin: ["packages/*/src/**", "samples/**"],
+};
+
+const SYMBOL = "unsafeAppendEvent";
+const ALLOWED_PATH = /(^|\/)(migrations|upcasters|__tests__)\/|\.test\.ts$|\.d\.ts$/;
+
+function unsafeAppendEventLines(sf: SourceFile): number[] {
+  const propertyAccesses = sf
+    .getDescendantsOfKind(SyntaxKind.PropertyAccessExpression)
+    .filter((access) => access.getNameNode().getText() === SYMBOL);
+  const elementAccesses = sf
+    .getDescendantsOfKind(SyntaxKind.ElementAccessExpression)
+    .filter((access) => {
+      const argument = access.getArgumentExpression();
+      return (
+        argument !== undefined &&
+        (Node.isStringLiteral(argument) || Node.isNoSubstitutionTemplateLiteral(argument)) &&
+        argument.getLiteralText() === SYMBOL
+      );
+    });
+  const destructurings = sf
+    .getDescendantsOfKind(SyntaxKind.BindingElement)
+    .filter(
+      (element) => (element.getPropertyNameNode() ?? element.getNameNode()).getText() === SYMBOL,
+    );
+  return [...propertyAccesses, ...elementAccesses, ...destructurings].map((node) =>
+    node.getStartLineNumber(),
+  );
+}
+
+type Finding = { readonly file: string; readonly line: number };
+
+function scan(files: readonly SourceFile[], roots = resolveRepoRoots()): Finding[] {
+  const findings: Finding[] = [];
+  for (const sf of files) {
+    const file = relFromRepoRoot(sf.getFilePath(), roots);
+    if (ALLOWED_PATH.test(file)) continue;
+    for (const line of unsafeAppendEventLines(sf)) findings.push({ file, line });
+  }
+  return findings;
+}
+
+function countsPerFile(findings: readonly Finding[]): Record<string, number> {
+  const counts: Record<string, number> = {};
+  for (const f of findings.filter(isLocalFinding)) counts[f.file] = (counts[f.file] ?? 0) + 1;
+  return counts;
+}
+
+const GUARD_NAME = "Unsafe-Append-Event Guard";
+const DEFAULT_BASELINE_FILE = path.join(process.cwd(), ".kumiko-unsafe-append-event-baseline.json");
+
+const REMEDIATION =
+  "unsafeAppendEvent drops payload typing. Use ctx.appendEvent (default) or ctx.tryAppendEvent (conflict as result); the untyped variant belongs in migrations/ and upcasters/.";
+
+const REWRITE_COMMAND = `kumiko-guards guards --write-baseline --guard="${GUARD_NAME}"`;
+
+export function createUnsafeAppendEventGuard(baselineFile: string): AstGuard {
+  const baseline = baselineRatchet({
+    file: baselineFile,
+    formatVersion: 1,
+    unit: "unsafeAppendEvent call(s)",
+  });
+  return {
+    name: GUARD_NAME,
+    scan: SCAN,
+    hint: `${REMEDIATION} After a deliberate change: \`${REWRITE_COMMAND}\`.`,
+    run(files, roots = resolveRepoRoots()) {
+      const findings = scan(files, roots);
+      const violations = baseline.check(countsPerFile(findings), REMEDIATION, {
+        formatDriftRemediation: `Run \`${REWRITE_COMMAND}\` once.`,
+        resolveLine: (file) => findings.find((f) => f.file === file)?.line ?? 1,
+      });
+      return { violations };
+    },
+    writeBaseline: (files, roots) => baseline.write(countsPerFile(scan(files, roots))),
+  };
+}
+
+export const guard = createUnsafeAppendEventGuard(DEFAULT_BASELINE_FILE);
+
+if (import.meta.main) {
+  if (process.argv.slice(2).includes("--write-baseline")) {
+    const project = buildSharedProject([guard]);
+    guard.writeBaseline?.(filesForGuard(project, guard));
+    process.exit(0);
+  }
+  runStandalone(guard);
+}

package/src/pre-push.sh

@@ -24,13 +24,6 @@
 # Extension point: a tracked, executable scripts/pre-push-extra.sh runs
 # before the main check in every branch above, with KUMIKO_PUSH_REPO_ROOT
 # and KUMIKO_PUSH_PARENT_DIR available inline (never exported).
-#
-# Override: set PRE_PUSH_SKIP=1 to bypass (use sparingly).
-
-if [ "${PRE_PUSH_SKIP:-0}" = "1" ]; then
-  echo "[pre-push] PRE_PUSH_SKIP=1 — hook skipped"
-  exit 0
-fi
 
 # Git exports GIT_DIR & co. to hooks; nothing this hook starts may inherit them,
 # or a test's fixture git calls write into this repo.
@@ -142,7 +135,9 @@ fi
 # canonical sibling path instead of this worktree — checking the wrong
 # code. Run the worktree-local check only when scripts/check-wt.sh is
 # tracked and executable (untracked/symlink stubs must not hijack push).
-if [ "$(git rev-parse --path-format=absolute --git-dir)" != "$GIT_COMMON_DIR" ] \
+# A check-wt.sh that wraps this hook sets KUMIKO_CHECK_WT=1 so it is not re-entered.
+if [ "${KUMIKO_CHECK_WT:-0}" != "1" ] \
+   && [ "$(git rev-parse --path-format=absolute --git-dir)" != "$GIT_COMMON_DIR" ] \
    && git -C "$REPO_ROOT" ls-files --error-unmatch scripts/check-wt.sh >/dev/null 2>&1 \
    && [ -x "$REPO_ROOT/scripts/check-wt.sh" ]; then
   echo "[pre-push] worktree detected — worktree check (see scripts/check-wt.sh)…"
@@ -178,7 +173,7 @@ if [ "$(git rev-parse --path-format=absolute --git-dir)" != "$GIT_COMMON_DIR" ]
   echo "[pre-push] worktree without scripts/check-wt.sh — running this worktree's package.json scripts (typecheck, lint, test, test:dom) and guards (guards, checks, comment-lang)…"
   if ! has_package_script test; then
     echo "[pre-push] FATAL: worktree without a package.json \"test\" script — nothing to run, refusing push." >&2
-    echo "Add a \"test\" script to package.json, or set PRE_PUSH_SKIP=1 to bypass (use sparingly)." >&2
+    echo "Add a \"test\" script to package.json." >&2
     exit 1
   fi
   FAILED=""
@@ -218,7 +213,7 @@ else
   # "Script not found" — check it up front with a clear, actionable message.
   if ! has_package_script test; then
     echo "[pre-push] FATAL: standalone clone without a package.json \"test\" script — nothing to run, refusing push." >&2
-    echo "Add a \"test\" script to package.json, or set PRE_PUSH_SKIP=1 to bypass (use sparingly)." >&2
+    echo "Add a \"test\" script to package.json." >&2
     exit 1
   fi
   cd "$REPO_ROOT" && bun run test

package/src/repo-manifest/app-ports/index.ts

@@ -0,0 +1,13 @@
+export { listAppPorts } from "@cosmicdrift/kumiko-framework/config";
+export {
+  findPortCollisions,
+  type PortClaim,
+  type PortCollision,
+  type ScannedApp,
+  scanWorkspaceApps,
+} from "./port-registry.ts";
+export {
+  parseStaticAppConfig,
+  readStaticAppConfig,
+  type StaticAppConfig,
+} from "./static-app-config.ts";

package/src/repo-manifest/app-ports/port-registry.ts

@@ -0,0 +1,45 @@
+// Port registry across the apps of a workspace: every app declares its ports
+// in kumiko.config.ts, and two apps (or two roles of one app) must never claim
+// the same port, otherwise their local dev and E2E runs block each other.
+import { existsSync, readdirSync } from "node:fs";
+import { join } from "node:path";
+import {
+  APP_CONFIG_FILE,
+  type AppPortRole,
+  listAppPorts,
+} from "@cosmicdrift/kumiko-framework/config";
+import { readStaticAppConfig, type StaticAppConfig } from "./static-app-config.ts";
+
+export type ScannedApp = { readonly app: string; readonly config: StaticAppConfig };
+
+export type PortClaim = { readonly app: string; readonly role: AppPortRole };
+
+export type PortCollision = { readonly port: number; readonly claims: readonly PortClaim[] };
+
+/** Direct children of `root` with a kumiko.config.ts; worktrees and dot-dirs are skipped. */
+export function scanWorkspaceApps(root: string): readonly ScannedApp[] {
+  return readdirSync(root, { withFileTypes: true })
+    .filter(
+      (entry) =>
+        entry.isDirectory() && !entry.name.startsWith(".") && entry.name !== "node_modules",
+    )
+    .filter((entry) => existsSync(join(root, entry.name, APP_CONFIG_FILE)))
+    .map((entry) => ({ app: entry.name, config: readStaticAppConfig(join(root, entry.name)) }))
+    .sort((a, b) => a.app.localeCompare(b.app));
+}
+
+export function findPortCollisions(apps: readonly ScannedApp[]): readonly PortCollision[] {
+  const claimsByPort = new Map<number, PortClaim[]>();
+  for (const { app, config } of apps) {
+    if (config.kind !== "defined") continue;
+    for (const { role, port } of listAppPorts(config.ports)) {
+      const claims = claimsByPort.get(port) ?? [];
+      claims.push({ app, role });
+      claimsByPort.set(port, claims);
+    }
+  }
+  return [...claimsByPort.entries()]
+    .filter(([, claims]) => claims.length > 1)
+    .map(([port, claims]) => ({ port, claims }))
+    .sort((a, b) => a.port - b.port);
+}

package/src/repo-manifest/app-ports/static-app-config.ts

@@ -0,0 +1,121 @@
+// Reads the ports out of kumiko.config.ts without importing it: importing
+// would execute every feature module of the app, and the port registry scans
+// sibling apps whose dependencies may not even be installed.
+import { existsSync, readFileSync } from "node:fs";
+import { join } from "node:path";
+import {
+  APP_CONFIG_FILE,
+  type AppInfraPorts,
+  type AppPorts,
+  findAppPortProblems,
+} from "@cosmicdrift/kumiko-framework/config";
+import { type Node, type ObjectLiteralExpression, Project, SyntaxKind } from "ts-morph";
+
+export type StaticAppConfig =
+  | { readonly kind: "missing" }
+  /** A config without defineAppConfig: the app has not adopted the standard yet. */
+  | { readonly kind: "legacy" }
+  | { readonly kind: "invalid"; readonly message: string }
+  | { readonly kind: "defined"; readonly ports: AppPorts };
+
+const INFRA_KEYS = [
+  "postgres",
+  "redis",
+  "meilisearch",
+  "s3",
+] as const satisfies readonly (keyof AppInfraPorts)[];
+
+type InfraKey = (typeof INFRA_KEYS)[number];
+
+function isInfraKey(name: string): name is InfraKey {
+  return INFRA_KEYS.some((key) => key === name);
+}
+
+class StaticConfigError extends Error {}
+
+function propertyName(node: Node): string | undefined {
+  if (node.isKind(SyntaxKind.PropertyAssignment)) return node.getName().replace(/^["']|["']$/g, "");
+  return undefined;
+}
+
+function objectProperty(object: ObjectLiteralExpression, name: string): Node | undefined {
+  for (const property of object.getProperties()) {
+    if (
+      property.isKind(SyntaxKind.SpreadAssignment) ||
+      property.isKind(SyntaxKind.ShorthandPropertyAssignment)
+    ) {
+      throw new StaticConfigError(
+        `${name}: spread and shorthand properties cannot be read statically`,
+      );
+    }
+    if (propertyName(property) === name && property.isKind(SyntaxKind.PropertyAssignment)) {
+      return property.getInitializerOrThrow();
+    }
+  }
+  return undefined;
+}
+
+function numericLiteral(node: Node | undefined, path: string): number {
+  if (node === undefined) throw new StaticConfigError(`${path} is missing`);
+  if (!node.isKind(SyntaxKind.NumericLiteral)) {
+    throw new StaticConfigError(
+      `${path} must be a number literal so tooling can read it, got "${node.getText()}"`,
+    );
+  }
+  return node.getLiteralValue();
+}
+
+function objectLiteral(node: Node | undefined, path: string): ObjectLiteralExpression {
+  if (node === undefined) throw new StaticConfigError(`${path} is missing`);
+  if (!node.isKind(SyntaxKind.ObjectLiteralExpression)) {
+    throw new StaticConfigError(`${path} must be an object literal, got "${node.getText()}"`);
+  }
+  return node;
+}
+
+function readInfraPorts(node: Node | undefined): AppInfraPorts | undefined {
+  if (node === undefined) return undefined;
+  const object = objectLiteral(node, "ports.infra");
+  const infra: Partial<Record<InfraKey, number>> = {};
+  for (const property of object.getProperties()) {
+    const name = propertyName(property);
+    if (name === undefined || !isInfraKey(name)) {
+      throw new StaticConfigError(
+        `ports.infra: unknown entry "${property.getText()}", expected ${INFRA_KEYS.join(", ")}`,
+      );
+    }
+    infra[name] = numericLiteral(objectProperty(object, name), `ports.infra.${name}`);
+  }
+  return infra;
+}
+
+export function parseStaticAppConfig(source: string): StaticAppConfig {
+  const project = new Project({ useInMemoryFileSystem: true, skipFileDependencyResolution: true });
+  const file = project.createSourceFile(APP_CONFIG_FILE, source);
+  const call = file
+    .getDescendantsOfKind(SyntaxKind.CallExpression)
+    .find((candidate) => candidate.getExpression().getText() === "defineAppConfig");
+  if (call === undefined) return { kind: "legacy" };
+  try {
+    const config = objectLiteral(call.getArguments()[0], "defineAppConfig argument");
+    const ports = objectLiteral(objectProperty(config, "ports"), "ports");
+    const infra = readInfraPorts(objectProperty(ports, "infra"));
+    const parsed: AppPorts = {
+      dev: numericLiteral(objectProperty(ports, "dev"), "ports.dev"),
+      e2e: numericLiteral(objectProperty(ports, "e2e"), "ports.e2e"),
+      ...(infra === undefined ? {} : { infra }),
+    };
+    const problems = findAppPortProblems(parsed);
+    if (problems.length > 0) return { kind: "invalid", message: problems.join("; ") };
+    return { kind: "defined", ports: parsed };
+  } catch (error) {
+    if (error instanceof StaticConfigError) return { kind: "invalid", message: error.message };
+    throw error;
+  }
+}
+
+export function readStaticAppConfig(appRoot: string): StaticAppConfig {
+  const path = join(appRoot, APP_CONFIG_FILE);
+  if (!existsSync(path)) return { kind: "missing" };
+  return parseStaticAppConfig(readFileSync(path, "utf-8"));
+}