@amerged/ohmyhost-mcp 0.1.31 → 0.1.33

package/src/packages/contracts/src/framework-admission.ts

@@ -1,8 +1,25 @@
-import { isAdmittedNextVersion, PINNED_BUN_VERSION } from "./framework-build-script.mjs";
+import {
+  compareStableVersions,
+  FRAMEWORK_VERSION_POLICY,
+  frameworkVersionMinimum,
+  frameworkVersionVerdict,
+  parseStableVersion,
+  PINNED_BUN_VERSION,
+  type FrameworkVersionPackage,
+  type FrameworkVersionPolicy,
+} from "./framework-build-script.mjs";
 import { managedCustomerAuthDatabaseMessage } from "./customer-auth-admission.js";
 export { managedCustomerAuthAdmissionIssue } from "./customer-auth-admission.js";
+export type { FrameworkVersionPackage } from "./framework-build-script.mjs";
 
 export type PackageManagerName = "bun" | "npm" | "pnpm" | "yarn";
+export type LockfileName =
+  | "bun.lock"
+  | "bun.lockb"
+  | "package-lock.json"
+  | "pnpm-lock.yaml"
+  | "yarn.lock";
+export type FrameworkConfigBasename = "next.config" | "open-next.config" | "vite.config";
 
 export type FrameworkAdmissionReason =
   | "ambiguous_config"
@@ -13,12 +30,28 @@ export type FrameworkAdmissionReason =
   | "package_manager_lockfile_mismatch"
   | "package_manager_version_unsupported";
 
+const ADMISSION_DIAGNOSTIC_CODES = Object.freeze({
+  ambiguous_config: "framework_config_ambiguous",
+  ambiguous_lockfile: "lockfile_ambiguous",
+  invalid_package_manager: "package_manager_invalid",
+  missing_lockfile: "lockfile_missing",
+  missing_package_manager: "package_manager_missing",
+  package_manager_lockfile_mismatch: "package_manager_lockfile_mismatch",
+  package_manager_version_unsupported: "package_manager_version_unsupported",
+} as const satisfies Record<FrameworkAdmissionReason, string>);
+
 export class FrameworkAdmissionError extends Error {
   public readonly code = "framework_admission_failed";
+  /** The catalog diagnostic of the refused file, relative to the application root. */
+  public readonly diagnostic: FrameworkConversionDiagnostic;
 
-  public constructor(public readonly reason: FrameworkAdmissionReason) {
+  public constructor(
+    public readonly reason: FrameworkAdmissionReason,
+    path: string,
+  ) {
     super("Framework source is not admitted");
     this.name = "FrameworkAdmissionError";
+    this.diagnostic = requiredDiagnostic({ code: ADMISSION_DIAGNOSTIC_CODES[reason], path });
   }
 }
 
@@ -30,18 +63,13 @@ export interface PackageManagerInput {
 export interface PackageManagerDescriptor {
   readonly manager: PackageManagerName;
   readonly version: string;
-  readonly lockfile:
-    | "bun.lock"
-    | "bun.lockb"
-    | "package-lock.json"
-    | "pnpm-lock.yaml"
-    | "yarn.lock";
+  readonly lockfile: LockfileName;
   readonly installCommand: string;
   readonly buildCommand: string;
 }
 
 interface PackageManagerContract {
-  readonly lockfiles: readonly PackageManagerDescriptor["lockfile"][];
+  readonly lockfiles: readonly LockfileName[];
   readonly installCommand: string;
   readonly buildCommand: string;
 }
@@ -70,31 +98,37 @@ const PACKAGE_MANAGER_CONTRACTS: Readonly<Record<PackageManagerName, PackageMana
     }),
   });
 
-const ALL_LOCKFILES = Object.freeze(
+const ALL_LOCKFILES: readonly string[] = Object.freeze(
   Object.values(PACKAGE_MANAGER_CONTRACTS).flatMap(({ lockfiles }) => lockfiles),
 );
-const EXACT_VERSION = /^(0|[1-9][0-9]*)\.(0|[1-9][0-9]*)\.(0|[1-9][0-9]*)$/u;
+const PACKAGE_MANIFEST = "package.json";
 const PACKAGE_MANAGER_DECLARATION =
   /^(bun|npm|pnpm|yarn)@((?:0|[1-9][0-9]*)\.(?:0|[1-9][0-9]*)\.(?:0|[1-9][0-9]*))$/u;
 
 export function resolvePackageManager(input: PackageManagerInput): PackageManagerDescriptor {
   const presentLockfiles = ALL_LOCKFILES.filter((lockfile) => input.files.includes(lockfile));
-  if (presentLockfiles.length === 0) throw new FrameworkAdmissionError("missing_lockfile");
-  if (presentLockfiles.length !== 1) throw new FrameworkAdmissionError("ambiguous_lockfile");
+  if (presentLockfiles.length === 0) {
+    throw new FrameworkAdmissionError("missing_lockfile", PACKAGE_MANIFEST);
+  }
+  if (presentLockfiles.length !== 1) {
+    throw new FrameworkAdmissionError("ambiguous_lockfile", PACKAGE_MANIFEST);
+  }
   if (input.packageManager === undefined) {
-    throw new FrameworkAdmissionError("missing_package_manager");
+    throw new FrameworkAdmissionError("missing_package_manager", PACKAGE_MANIFEST);
   }
   const declaration = PACKAGE_MANAGER_DECLARATION.exec(input.packageManager);
-  if (declaration === null) throw new FrameworkAdmissionError("invalid_package_manager");
+  if (declaration === null) {
+    throw new FrameworkAdmissionError("invalid_package_manager", PACKAGE_MANIFEST);
+  }
   const manager = declaration[1] as PackageManagerName;
   const version = declaration[2] as string;
   const contract = PACKAGE_MANAGER_CONTRACTS[manager];
-  const lockfile = presentLockfiles[0] as PackageManagerDescriptor["lockfile"];
+  const lockfile = presentLockfiles[0] as LockfileName;
   if (!contract.lockfiles.includes(lockfile)) {
-    throw new FrameworkAdmissionError("package_manager_lockfile_mismatch");
+    throw new FrameworkAdmissionError("package_manager_lockfile_mismatch", lockfile);
   }
   if (manager === "bun" && version !== PINNED_BUN_VERSION) {
-    throw new FrameworkAdmissionError("package_manager_version_unsupported");
+    throw new FrameworkAdmissionError("package_manager_version_unsupported", PACKAGE_MANIFEST);
   }
   return Object.freeze({
     manager,
@@ -105,236 +139,646 @@ export function resolvePackageManager(input: PackageManagerInput): PackageManage
   });
 }
 
-export function resolveFrameworkConfig(basename: string, files: readonly string[]): string | null {
+export function resolveFrameworkConfig(
+  basename: FrameworkConfigBasename,
+  files: readonly string[],
+): string | null {
   const supported = [`${basename}.js`, `${basename}.mjs`, `${basename}.ts`] as const;
   const matches = supported.filter((candidate) => files.includes(candidate));
-  if (matches.length > 1) throw new FrameworkAdmissionError("ambiguous_config");
+  if (matches.length > 1) {
+    throw new FrameworkAdmissionError("ambiguous_config", matches[0] as string);
+  }
   return matches[0] ?? null;
 }
 
-export type AdmittedFramework = "nextjs" | "tanstack-start" | "vite";
-export type FrameworkVersionClassification = "experimental" | "unsupported" | "verified";
-export type FrameworkVersionReason =
-  | "inside_admitted_window"
-  | "invalid_version"
-  | "outside_admitted_window"
-  | "range_inside_admitted_window"
-  | "verified_fixture";
+export type FrameworkVersionStatus = "admitted" | "pending" | "unsupported";
 
+/** One framework package judged by its lockfile resolution or, without one, its declaration. */
 export interface FrameworkVersionAdmission {
-  readonly classification: FrameworkVersionClassification;
-  readonly reason: FrameworkVersionReason;
+  readonly package: FrameworkVersionPackage;
+  readonly status: FrameworkVersionStatus;
+  readonly declared: string;
+  readonly resolved: string | null;
+  /** The lowest admitted release for the line of the judged version; it names the required change. */
+  readonly minimum: string;
 }
 
-const VERIFIED_VERSIONS: Readonly<Record<AdmittedFramework, ReadonlySet<string>>> = Object.freeze({
-  vite: new Set(["5.4.21", "8.0.16", "8.2.2"]),
-  "tanstack-start": new Set(["1.168.26", "1.168.49"]),
-  nextjs: new Set(["15.5.26", "16.3.8"]),
-});
+type VersionTuple = readonly [major: number, minor: number, patch: number];
+
+const STABLE_VERSION_SOURCE =
+  "(?:0|[1-9][0-9]{0,5})\\.(?:0|[1-9][0-9]{0,5})\\.(?:0|[1-9][0-9]{0,5})";
+const VERSION_RANGE = new RegExp(`^([~^])(${STABLE_VERSION_SOURCE})$`, "u");
 
+/**
+ * A non-null lockfile resolution decides with the shared verdict. Without one, an exact declaration
+ * decides. A ^ range (below the next major) or ~ range (below the next minor) is admitted when every
+ * version it allows passes, unsupported when none can, and otherwise pending: planning admits it and
+ * the build's installed-version check decides. Every other declaration form is unsupported.
+ */
 export function classifyFrameworkVersion(
-  framework: AdmittedFramework,
-  version: string,
+  packageName: FrameworkVersionPackage,
+  declared: string,
+  resolved: string | null = null,
+  policy: FrameworkVersionPolicy = FRAMEWORK_VERSION_POLICY,
 ): FrameworkVersionAdmission {
-  const parsed = parseVersionSpec(version);
-  if (parsed === null) return versionAdmission("unsupported", "invalid_version");
-  if (!insideAdmittedWindow(framework, parsed.version)) {
-    return versionAdmission("unsupported", "outside_admitted_window");
-  }
-  if (!parsed.exact) {
-    return versionAdmission("experimental", "range_inside_admitted_window");
+  const judged = resolved ?? declared;
+  const range = resolved === null ? VERSION_RANGE.exec(declared) : null;
+  let status: FrameworkVersionStatus;
+  if (range === null) {
+    status =
+      frameworkVersionVerdict(packageName, judged, policy) === "admitted"
+        ? "admitted"
+        : "unsupported";
+  } else {
+    status = rangeStatus(packageName, range[1] === "^", range[2] as string, policy);
   }
-  return VERIFIED_VERSIONS[framework].has(version)
-    ? versionAdmission("verified", "verified_fixture")
-    : versionAdmission("experimental", "inside_admitted_window");
+  return Object.freeze({
+    package: packageName,
+    status,
+    declared,
+    resolved,
+    minimum: frameworkVersionMinimum(packageName, judged, policy),
+  });
 }
 
-type VersionTuple = readonly [major: number, minor: number, patch: number];
+function rangeStatus(
+  packageName: FrameworkVersionPackage,
+  caret: boolean,
+  base: string,
+  policy: FrameworkVersionPolicy,
+): FrameworkVersionStatus {
+  const lower = policyVersion(base);
+  const upper: VersionTuple = caret ? [lower[0] + 1, 0, 0] : [lower[0], lower[1] + 1, 0];
+  if (
+    frameworkVersionVerdict(packageName, base, policy) === "admitted" &&
+    !policy[packageName].denied.some(([introduced, fixed]) => {
+      const from = parseStableVersion(introduced);
+      const to = fixed === null ? null : parseStableVersion(fixed);
+      return (
+        from !== null &&
+        compareStableVersions(from, upper) < 0 &&
+        (to === null || compareStableVersions(to, lower) > 0)
+      );
+    })
+  )
+    return "admitted";
+  // The lowest release inside the range that can pass: past the floor and every fixed denied range.
+  const minimum = policyVersion(frameworkVersionMinimum(packageName, base, policy));
+  const candidate = compareStableVersions(minimum, lower) > 0 ? minimum : lower;
+  return compareStableVersions(candidate, upper) < 0 &&
+    frameworkVersionVerdict(packageName, candidate.join("."), policy) === "admitted"
+    ? "pending"
+    : "unsupported";
+}
 
-function parseVersionSpec(
-  version: string,
-): Readonly<{ exact: boolean; version: VersionTuple }> | null {
-  const exact = EXACT_VERSION.exec(version);
-  const match =
-    exact ?? (/^[~^](.*)$/u.exec(version)?.[1] ? EXACT_VERSION.exec(version.slice(1)) : null);
-  if (match === null) return null;
-  const tuple = [Number(match[1]), Number(match[2]), Number(match[3])] as const;
-  return tuple.every(Number.isSafeInteger)
-    ? Object.freeze({ exact: exact !== null, version: tuple })
-    : null;
+function policyVersion(version: string): VersionTuple {
+  const parsed = parseStableVersion(version);
+  if (parsed === null) throw new TypeError("Framework version policy is invalid");
+  return parsed;
 }
 
-function insideAdmittedWindow(framework: AdmittedFramework, version: VersionTuple): boolean {
-  switch (framework) {
-    case "vite":
-      return compareVersions(version, [5, 4, 0]) >= 0 && compareVersions(version, [8, 2, 2]) <= 0;
-    case "tanstack-start":
-      return (
-        compareVersions(version, [1, 168, 26]) >= 0 && compareVersions(version, [1, 168, 49]) <= 0
-      );
-    case "nextjs":
-      return isAdmittedNextVersion(version.join("."));
-  }
+const RESOLVED_VERSION_SOURCE = `${STABLE_VERSION_SOURCE}(?:-[0-9A-Za-z.-]{1,32})?`;
+const RESOLVED_VERSION_FIELD = anchoredPattern(RESOLVED_VERSION_SOURCE);
+const DECLARED_VERSION_FIELD = anchoredPattern(`[~^]?${RESOLVED_VERSION_SOURCE}`);
+const STABLE_VERSION_FIELD = anchoredPattern(STABLE_VERSION_SOURCE);
+
+/** A version the catalog names as resolved: X.Y.Z or X.Y.Z-<up to 32 of [0-9A-Za-z.-]>. */
+export function isResolvedFrameworkVersion(value: unknown): value is string {
+  return typeof value === "string" && RESOLVED_VERSION_FIELD.test(value);
 }
 
-function compareVersions(left: VersionTuple, right: VersionTuple): number {
-  const majorDifference = left[0] - right[0];
-  if (majorDifference !== 0) return majorDifference;
-  const minorDifference = left[1] - right[1];
-  return minorDifference !== 0 ? minorDifference : left[2] - right[2];
+/**
+ * The typed refusal of an unsupported admission, naming the file that decided it: the lockfile for
+ * a resolved version, package.json for a declaration. A declaration outside the exact, ^ and ~ forms
+ * asks for one of them. Admitted and pending admissions are not refused.
+ */
+export function frameworkVersionDiagnostic(
+  admission: FrameworkVersionAdmission,
+  lockfile: LockfileName | null,
+): FrameworkConversionDiagnostic | null {
+  if (admission.status !== "unsupported") return null;
+  if (admission.resolved !== null) {
+    if (lockfile === null) throw new TypeError("Framework version lockfile is required");
+    return requiredDiagnostic({
+      code: "framework_version_unsupported",
+      path: lockfile,
+      package: admission.package,
+      version: admission.resolved,
+      minimum: admission.minimum,
+    });
+  }
+  return DECLARED_VERSION_FIELD.test(admission.declared)
+    ? requiredDiagnostic({
+        code: "framework_version_unsupported",
+        path: PACKAGE_MANIFEST,
+        package: admission.package,
+        version: admission.declared,
+        minimum: admission.minimum,
+      })
+    : requiredDiagnostic({
+        code: "framework_version_declaration_unsupported",
+        path: PACKAGE_MANIFEST,
+        package: admission.package,
+      });
 }
 
-function versionAdmission(
-  classification: FrameworkVersionClassification,
-  reason: FrameworkVersionReason,
-): FrameworkVersionAdmission {
-  return Object.freeze({ classification, reason });
+/**
+ * The file a diagnostic names. Every class but repository_config is relative to the application
+ * and may carry its application-root prefix; ohmyhost.yaml always sits at the repository root.
+ */
+export type FrameworkConversionPathClass =
+  | "framework_config"
+  | "lockfile"
+  | "manifest"
+  | "module"
+  | "repository_config";
+
+/** A field value grammar: a closed set of values or an anchored pattern. */
+type FieldGrammar = readonly string[] | RegExp;
+
+interface DerivedText {
+  /** `path` selects by path class; any other name selects by that field's value. */
+  readonly from: string;
+  readonly text: Readonly<Record<string, string>>;
 }
 
-export type FrameworkConversionDiagnosticCode =
-  | "managed_auth_database_required"
-  | "database_binding_private"
-  | "database_driver_unsupported"
-  | "source_syntax_invalid"
-  | "worker_module_default_export_required"
-  | "scheduled_handler_required"
-  | "framework_base_path_unsupported"
-  | "tanstack_prerender_required"
-  | "tanstack_vite_plugins_required"
-  | "next_cache_components_unsupported";
-
-export interface FrameworkConversionDiagnostic {
-  readonly code: FrameworkConversionDiagnosticCode;
-  readonly path: string;
+interface DetailDefinition {
+  readonly paths: readonly FrameworkConversionPathClass[];
+  readonly fields?: Readonly<Record<string, FieldGrammar>>;
+  readonly derived?: Readonly<Record<string, DerivedText>>;
+  /** The sentence; `{{name}}` places the path, a field or a derived text. */
+  readonly template: string;
 }
 
+const FRAMEWORK_VERSION_PACKAGES = Object.freeze([
+  "next",
+  "vite",
+  "@tanstack/react-start",
+] as const satisfies readonly FrameworkVersionPackage[]);
+const FRAMEWORK_DEPENDENCY_PACKAGES = Object.freeze([
+  "next",
+  "react",
+  "react-dom",
+  "vite",
+  "@tanstack/react-start",
+  "@tanstack/react-router",
+  "@vitejs/plugin-react",
+  "@cloudflare/vite-plugin",
+] as const);
+const REACT_PACKAGES = Object.freeze(["react", "react-dom"] as const);
+const BUILD_FRAMEWORKS = Object.freeze(["nextjs", "vite-static", "tanstack-start"] as const);
+
 const PUSH_AND_PLAN = "Commit and push the change, then plan the new commit.";
+const VITE_BUILD_SCRIPT =
+  '"vite build", optionally joined with && to one "tsc", "tsc -b", "tsc --build" or "tsc --noEmit" stage';
 
-// Detail texts are the customer-facing sentence for one diagnostic; parseFrameworkConversionDetail
-// recognizes exactly these sentences so a client can map a detail back to its typed diagnostic.
-const FRAMEWORK_CONVERSION_DETAILS: Readonly<
-  Record<
-    FrameworkConversionDiagnosticCode,
-    Readonly<{ render(path: string): string; pattern: RegExp }>
-  >
-> = Object.freeze({
-  managed_auth_database_required: Object.freeze({
-    render: managedCustomerAuthDatabaseMessage,
-    pattern:
-      /^"([^"]+)" selects the managed Better Auth bridge, which requires the managed PostgreSQL database\. Set database\.enabled: true with an admitted migrations path, or set auth\.provider: none and keep the application-owned authentication configuration\. Commit and push the change, then plan the new commit\.$/u,
-  }),
-  database_binding_private: Object.freeze({
-    render: (path: string) =>
-      `"${path}" reads a database connection string (DATABASE_URL, HYPERDRIVE, connectionString or a postgres:// URL); none reaches a customer Worker. Call the database with createPrivateDatabaseClient from "@ohmyhost/customer-runtime/database". ${PUSH_AND_PLAN}`,
-    pattern:
-      /^"([^"]+)" reads a database connection string \(DATABASE_URL, HYPERDRIVE, connectionString or a postgres:\/\/ URL\); none reaches a customer Worker\. Call the database with createPrivateDatabaseClient from "@ohmyhost\/customer-runtime\/database"\. Commit and push the change, then plan the new commit\.$/u,
-  }),
-  database_driver_unsupported: Object.freeze({
-    render: (path: string) =>
-      `"${path}" imports a database socket driver (pg, postgres, pg-native or mysql2); customer Workers cannot open sockets. Call the database with createPrivateDatabaseClient from "@ohmyhost/customer-runtime/database". ${PUSH_AND_PLAN}`,
-    pattern:
-      /^"([^"]+)" imports a database socket driver \(pg, postgres, pg-native or mysql2\); customer Workers cannot open sockets\. Call the database with createPrivateDatabaseClient from "@ohmyhost\/customer-runtime\/database"\. Commit and push the change, then plan the new commit\.$/u,
-  }),
-  source_syntax_invalid: Object.freeze({
-    render: (path: string) =>
-      `Invalid JavaScript or TypeScript in "${path}". Fix the file, commit and push the change, then plan the new commit.`,
-    pattern:
-      /^Invalid JavaScript or TypeScript in "([^"]+)"\. Fix the file, commit and push the change, then plan the new commit\.$/u,
-  }),
-  worker_module_default_export_required: Object.freeze({
-    render: (path: string) =>
-      `Worker module "${path}" has no default export. Export default { fetch, scheduled } with the handlers ohmyho.st invokes; named exports are never called. ${PUSH_AND_PLAN}`,
-    pattern:
-      /^Worker module "([^"]+)" has no default export\. Export default \{ fetch, scheduled \} with the handlers ohmyho\.st invokes; named exports are never called\. Commit and push the change, then plan the new commit\.$/u,
-  }),
-  scheduled_handler_required: Object.freeze({
-    render: (path: string) =>
-      `functions.crons is declared but "${path}" exports no scheduled handler. Add scheduled(controller, env, ctx) to its default export, commit and push the change, then plan the new commit.`,
-    pattern:
-      /^functions\.crons is declared but "([^"]+)" exports no scheduled handler\. Add scheduled\(controller, env, ctx\) to its default export, commit and push the change, then plan the new commit\.$/u,
-  }),
-  framework_base_path_unsupported: Object.freeze({
-    render: (path: string) =>
-      `"${path}" sets a Vite base. ohmyho.st serves the app at the root origin: remove base or set base: "/". ${PUSH_AND_PLAN}`,
-    pattern:
-      /^"([^"]+)" sets a Vite base\. ohmyho\.st serves the app at the root origin: remove base or set base: "\/"\. Commit and push the change, then plan the new commit\.$/u,
-  }),
-  tanstack_prerender_required: Object.freeze({
-    render: (path: string) =>
-      `"${path}" does not call tanstackStart({ prerender: { enabled: true } }), which the static TanStack Start runtime needs; enable prerender, or set runtime.mode: edge with the Cloudflare Vite plugin. ${PUSH_AND_PLAN}`,
-    pattern:
-      /^"([^"]+)" does not call tanstackStart\(\{ prerender: \{ enabled: true \} \}\), which the static TanStack Start runtime needs; enable prerender, or set runtime\.mode: edge with the Cloudflare Vite plugin\. Commit and push the change, then plan the new commit\.$/u,
-  }),
-  tanstack_vite_plugins_required: Object.freeze({
-    render: (path: string) =>
-      `"${path}" does not follow the TanStack Start plugin contract: import tanstackStart from "@tanstack/react-start/plugin/vite"; on runtime edge also import cloudflare from "@cloudflare/vite-plugin" and call cloudflare({ viteEnvironment: { name: "ssr" } }) before tanstackStart(); on runtime static do not import the Cloudflare plugin. ${PUSH_AND_PLAN}`,
-    pattern:
-      /^"([^"]+)" does not follow the TanStack Start plugin contract: import tanstackStart from "@tanstack\/react-start\/plugin\/vite"; on runtime edge also import cloudflare from "@cloudflare\/vite-plugin" and call cloudflare\(\{ viteEnvironment: \{ name: "ssr" \} \}\) before tanstackStart\(\); on runtime static do not import the Cloudflare plugin\. Commit and push the change, then plan the new commit\.$/u,
-  }),
-  next_cache_components_unsupported: Object.freeze({
-    render: (path: string) =>
-      `"${path}" sets cacheComponents: true, which ohmyho.st does not support; remove it or set it to false. ${PUSH_AND_PLAN}`,
-    pattern:
-      /^"([^"]+)" sets cacheComponents: true, which ohmyho\.st does not support; remove it or set it to false\. Commit and push the change, then plan the new commit\.$/u,
-  }),
-});
+// Each sentence names the file, the rule and the exact change. Render and parse both derive from
+// the template, so a client maps a detail back to exactly one typed diagnostic.
+const FRAMEWORK_CONVERSION_DETAILS = Object.freeze({
+  managed_auth_database_required: {
+    paths: ["repository_config"],
+    template: managedCustomerAuthDatabaseMessage("{{path}}"),
+  },
+  database_binding_private: {
+    paths: ["module"],
+    template: `"{{path}}" reads a database connection string (DATABASE_URL, HYPERDRIVE, connectionString or a postgres:// URL); none reaches a customer Worker. Call the database with createPrivateDatabaseClient from "@ohmyhost/customer-runtime/database". ${PUSH_AND_PLAN}`,
+  },
+  database_driver_unsupported: {
+    paths: ["module"],
+    template: `"{{path}}" imports a database socket driver (pg, postgres, pg-native or mysql2); customer Workers cannot open sockets. Call the database with createPrivateDatabaseClient from "@ohmyhost/customer-runtime/database". ${PUSH_AND_PLAN}`,
+  },
+  source_syntax_invalid: {
+    paths: ["module"],
+    template:
+      'Invalid JavaScript or TypeScript in "{{path}}". Fix the file, commit and push the change, then plan the new commit.',
+  },
+  worker_module_default_export_required: {
+    paths: ["module"],
+    template: `Worker module "{{path}}" has no default export. Export default { fetch, scheduled } with the handlers ohmyho.st invokes; named exports are never called. ${PUSH_AND_PLAN}`,
+  },
+  scheduled_handler_required: {
+    paths: ["module"],
+    template:
+      'functions.crons is declared but "{{path}}" exports no scheduled handler. Add scheduled(controller, env, ctx) to its default export, commit and push the change, then plan the new commit.',
+  },
+  framework_base_path_unsupported: {
+    paths: ["framework_config"],
+    template: `"{{path}}" sets a Vite base. ohmyho.st serves the app at the root origin: remove base or set base: "/". ${PUSH_AND_PLAN}`,
+  },
+  tanstack_prerender_required: {
+    paths: ["framework_config"],
+    template: `"{{path}}" does not call tanstackStart({ prerender: { enabled: true } }), which the static TanStack Start runtime needs; enable prerender, or set runtime.mode: edge with the Cloudflare Vite plugin. ${PUSH_AND_PLAN}`,
+  },
+  tanstack_vite_plugins_required: {
+    paths: ["framework_config"],
+    template: `"{{path}}" does not follow the TanStack Start plugin contract: import tanstackStart from "@tanstack/react-start/plugin/vite"; on runtime edge also import cloudflare from "@cloudflare/vite-plugin" and call cloudflare({ viteEnvironment: { name: "ssr" } }) before tanstackStart(); on runtime static do not import the Cloudflare plugin. ${PUSH_AND_PLAN}`,
+  },
+  next_tailwind_turbopack_only: {
+    paths: ["framework_config"],
+    template: `"{{path}}" loads Tailwind CSS through the Turbopack rule "@tailwindcss/turbopack", which the Webpack build on ohmyho.st ignores, and the application root has no PostCSS configuration that Webpack reads, so the site would deploy without its Tailwind classes. Add postcss.config.mjs to the application root with export default { plugins: { "@tailwindcss/postcss": {} } } and remove the Turbopack rule. Use the package manager to add @tailwindcss/postcss to devDependencies at the same version as tailwindcss and to remove @tailwindcss/turbopack, so the lockfile records both. ${PUSH_AND_PLAN}`,
+  },
+  framework_version_unsupported: {
+    paths: ["manifest", "lockfile"],
+    fields: {
+      package: FRAMEWORK_VERSION_PACKAGES,
+      version: DECLARED_VERSION_FIELD,
+      minimum: STABLE_VERSION_FIELD,
+    },
+    derived: { verb: { from: "path", text: { manifest: "declares", lockfile: "resolves" } } },
+    template:
+      '"{{path}}" {{verb}} {{package}} {{version}}, which ohmyho.st does not admit; use {{package}} {{minimum}} or a later stable release, update package.json and the lockfile, commit and push the change, then plan the new commit.',
+  },
+  framework_version_declaration_unsupported: {
+    paths: ["manifest"],
+    fields: { package: FRAMEWORK_VERSION_PACKAGES },
+    template:
+      '"{{path}}" declares {{package}} in a form ohmyho.st cannot check against its security minimum; declare an exact X.Y.Z version or a ^X.Y.Z or ~X.Y.Z range, update the lockfile, commit and push the change, then plan the new commit.',
+  },
+  framework_dependency_required: {
+    paths: ["manifest"],
+    fields: { package: FRAMEWORK_DEPENDENCY_PACKAGES },
+    template:
+      '"{{path}}" does not declare {{package}} in dependencies, which this framework and runtime need. Add it with the package manager so the lockfile records it, commit and push the change, then plan the new commit.',
+  },
+  react_version_exact_required: {
+    paths: ["manifest"],
+    fields: { package: REACT_PACKAGES },
+    template:
+      '"{{path}}" must declare {{package}} in dependencies at an exact version such as 19.1.0, without ^ or ~, for Next.js. Pin the version the lockfile installs, commit and push the change, then plan the new commit.',
+  },
+  build_script_unsupported: {
+    paths: ["manifest"],
+    fields: { framework: BUILD_FRAMEWORKS },
+    derived: {
+      script: {
+        from: "framework",
+        text: {
+          nextjs:
+            'exactly "next build" or "next build --webpack"; ohmyho.st adds the OpenNext build itself',
+          "vite-static": VITE_BUILD_SCRIPT,
+          "tanstack-start": VITE_BUILD_SCRIPT,
+        },
+      },
+    },
+    template:
+      '"{{path}}" scripts.build is missing or not admitted for the {{framework}} adapter: it must be {{script}}. Move other steps into their own scripts, commit and push the change, then plan the new commit.',
+  },
+  better_auth_version_required: {
+    paths: ["manifest"],
+    template:
+      '"{{path}}" must declare better-auth at exactly 1.7.1 in dependencies because ohmyhost.yaml sets auth.provider: better-auth. Pin that version or set auth.provider: none, commit and push the change, then plan the new commit.',
+  },
+  package_manifest_invalid: {
+    paths: ["manifest"],
+    template:
+      '"{{path}}" is missing or is not one JSON object. Add package.json in the applicationRoot that ohmyhost.yaml names, or fix its syntax so the whole file parses as one object; commit and push the change, then plan the new commit.',
+  },
+  framework_unsupported: {
+    paths: ["manifest"],
+    template: `"{{path}}" declares none of next, vite or @tanstack/react-start. Add the app's framework to dependencies, or set runtime.mode: functions in ohmyhost.yaml and add src/ohmyhost/worker.ts. ${PUSH_AND_PLAN}`,
+  },
+  framework_ambiguous: {
+    paths: ["manifest"],
+    template:
+      '"{{path}}" declares next together with vite or @tanstack/react-start, so ohmyho.st cannot choose one framework. Remove the packages of the framework this application does not use, commit and push the change, then plan the new commit.',
+  },
+  lockfile_missing: {
+    paths: ["manifest"],
+    template:
+      '"{{path}}" has no lockfile beside it. Install with the packageManager it names so package-lock.json, pnpm-lock.yaml, yarn.lock or bun.lock is written, commit and push the change, then plan the new commit.',
+  },
+  lockfile_ambiguous: {
+    paths: ["manifest"],
+    template:
+      '"{{path}}" has more than one lockfile beside it. Keep only the lockfile of the packageManager it names and delete the others, commit and push the change, then plan the new commit.',
+  },
+  package_manager_missing: {
+    paths: ["manifest"],
+    template:
+      '"{{path}}" has no packageManager field. Set it to name@X.Y.Z for the npm, pnpm, yarn or bun version that wrote the lockfile, commit and push the change, then plan the new commit.',
+  },
+  package_manager_invalid: {
+    paths: ["manifest"],
+    template:
+      '"{{path}}" sets packageManager to a value ohmyho.st cannot use. Write npm, pnpm, yarn or bun, then @ and an exact X.Y.Z version without a +sha suffix, matching the lockfile; commit and push the change, then plan the new commit.',
+  },
+  package_manager_lockfile_mismatch: {
+    paths: ["lockfile"],
+    template:
+      '"{{path}}" was not written by the packageManager that package.json names. Set packageManager to the manager of this lockfile, or replace the lockfile with one from the named manager; commit and push the change, then plan the new commit.',
+  },
+  package_manager_version_unsupported: {
+    paths: ["manifest"],
+    template: `"{{path}}" pins a Bun version other than ${PINNED_BUN_VERSION}, the only Bun ohmyho.st builds with. Set packageManager to bun@${PINNED_BUN_VERSION}, reinstall to update the lockfile, commit and push the change, then plan the new commit.`,
+  },
+  repository_configuration_invalid: {
+    paths: ["repository_config"],
+    template:
+      '"{{path}}" does not match the ohmyho.st configuration schema. Run ohmyhost init --dry-run --json locally to see the exact field and fix, commit and push the change, then plan the new commit.',
+  },
+  runtime_mode_unsupported: {
+    paths: ["repository_config"],
+    fields: { framework: BUILD_FRAMEWORKS },
+    derived: {
+      mode: {
+        from: "framework",
+        text: {
+          nextjs: "runtime.mode: edge",
+          "vite-static":
+            "runtime.mode: edge with src/ohmyhost/companion.ts when database, auth, mail, storage or functions.crons is set, and static otherwise",
+          "tanstack-start": "runtime.mode: edge, or static without functions.crons and storage",
+        },
+      },
+    },
+    template: `"{{path}}" sets a runtime.mode that the {{framework}} adapter cannot run with this configuration; use {{mode}}. ${PUSH_AND_PLAN}`,
+  },
+  build_output_unsupported: {
+    paths: ["repository_config"],
+    fields: { framework: BUILD_FRAMEWORKS },
+    derived: {
+      output: {
+        from: "framework",
+        text: {
+          nextjs: ".open-next/assets",
+          "vite-static": "dist",
+          "tanstack-start": "dist/client",
+        },
+      },
+    },
+    template: `"{{path}}" sets a build.output that the {{framework}} adapter does not produce; set build.output: {{output}}. ${PUSH_AND_PLAN}`,
+  },
+  build_command_mismatch: {
+    paths: ["repository_config"],
+    template:
+      '"{{path}}" build.install or build.command differs from the commands of the packageManager in package.json (for npm: npm ci --ignore-scripts and npm run build). ohmyhost init --dry-run --json prints the exact values; set them, commit and push the change, then plan the new commit.',
+  },
+  build_option_unsupported: {
+    paths: ["repository_config"],
+    template:
+      '"{{path}}" sets a build option this runtime ignores: build.ssg_cache_max_mib applies only to Next.js, and runtime.mode: functions takes only build.install. Remove the option, commit and push the change, then plan the new commit.',
+  },
+  application_root_missing: {
+    paths: ["repository_config"],
+    template:
+      '"{{path}}" sets applicationRoot to a directory that is missing or empty in this commit. Set it to the directory that holds the app\'s package.json, or "." for the repository root; commit and push the change, then plan the new commit.',
+  },
+  framework_config_required: {
+    paths: ["framework_config"],
+    template:
+      'This application has no "{{path}}". Add one framework config with that name and a .js, .mjs or .ts extension that exports its config as default, commit and push the change, then plan the new commit.',
+  },
+  framework_config_ambiguous: {
+    paths: ["framework_config"],
+    template:
+      '"{{path}}" exists beside another variant with the same name and a .js, .mjs or .ts extension. Keep exactly one and delete the others, commit and push the change, then plan the new commit.',
+  },
+  framework_config_too_large: {
+    paths: ["framework_config"],
+    template:
+      '"{{path}}" is larger than the 256 KiB ohmyho.st inspects. Keep the config small and move large data into imported modules, commit and push the change, then plan the new commit.',
+  },
+  framework_config_default_export_required: {
+    paths: ["framework_config"],
+    template:
+      '"{{path}}" does not export its config as default. Use export default (next.config.js may assign module.exports instead), commit and push the change, then plan the new commit.',
+  },
+  next_output_unsupported: {
+    paths: ["framework_config"],
+    template:
+      '"{{path}}" sets output: "export" or output: "standalone", which the Next.js edge runtime on ohmyho.st cannot serve. Remove the output setting, commit and push the change, then plan the new commit.',
+  },
+  next_base_path_unsupported: {
+    paths: ["framework_config"],
+    template: `"{{path}}" sets basePath or assetPrefix. ohmyho.st serves the app at the root origin: remove both or set them to "". ${PUSH_AND_PLAN}`,
+  },
+  companion_entry_required: {
+    paths: ["module"],
+    template:
+      '"{{path}}" is missing. A Vite app with runtime.mode: edge or with database, auth, mail, storage or functions.crons needs this Worker module with export default { fetch }. Add it, or use runtime.mode: static without those settings; commit and push the change, then plan the new commit.',
+  },
+  worker_module_required: {
+    paths: ["module"],
+    template:
+      '"{{path}}" is missing. runtime.mode: functions and functions.crons on Next.js or TanStack Start need this Worker module; export default { fetch, scheduled } with the handlers ohmyho.st invokes. Add it, commit and push the change, then plan the new commit.',
+  },
+  worker_module_fetch_handler_required: {
+    paths: ["module"],
+    template: `Worker module "{{path}}" exports no fetch handler; runtime.mode: functions serves every request and the health check through it. Add a fetch handler that receives request, env and ctx to its default export. ${PUSH_AND_PLAN}`,
+  },
+} as const satisfies Readonly<Record<string, DetailDefinition>>);
 
-/**
- * An adapter rule that `init` does not check. It stays a TypeError, so every existing caller that
- * treats an adapter refusal as a TypeError keeps working, and carries the typed diagnostic whose
- * detail names the file and its fix.
- */
-export class FrameworkConversionDiagnosticError extends TypeError {
-  public readonly diagnostic: FrameworkConversionDiagnostic;
+type DetailDefinitions = typeof FRAMEWORK_CONVERSION_DETAILS;
+export type FrameworkConversionDiagnosticCode = keyof DetailDefinitions;
+type FieldValue<Grammar> = Grammar extends readonly (infer Value extends string)[] ? Value : string;
+type DiagnosticFields<Definition> = Definition extends { readonly fields: infer Fields }
+  ? { readonly [Field in keyof Fields]: FieldValue<Fields[Field]> }
+  : unknown;
 
-  public constructor(diagnostic: unknown) {
-    const parsed = parseFrameworkConversionDiagnostic(diagnostic);
-    if (parsed === null) throw new TypeError("Framework conversion diagnostic is invalid");
-    super(FRAMEWORK_CONVERSION_DETAILS[parsed.code].render(parsed.path));
-    this.name = "FrameworkConversionDiagnosticError";
-    this.diagnostic = parsed;
+/** A typed refusal: its code, the file it names and the bounded fields its sentence needs. */
+export type FrameworkConversionDiagnostic = {
+  [Code in FrameworkConversionDiagnosticCode]: Readonly<{ code: Code; path: string }> &
+    DiagnosticFields<DetailDefinitions[Code]>;
+}[FrameworkConversionDiagnosticCode];
+
+const DETAIL_DEFINITIONS: Readonly<Record<FrameworkConversionDiagnosticCode, DetailDefinition>> =
+  FRAMEWORK_CONVERSION_DETAILS;
+const PLACEHOLDER = /\{\{([a-z]+)\}\}/gu;
+const PATH_PATTERN = "[A-Za-z0-9_@()[\\]./${}-]{1,240}";
+const SAFE_PATH = new RegExp(`^${PATH_PATTERN}$`, "u");
+const MODULE_PATH = /^[A-Za-z0-9_@()[\]./${}-]+\.(?:[cm]?[jt]sx?)$/u;
+const FRAMEWORK_CONFIG_NAME = /^(?:next|open-next|vite)\.config\.(?:js|mjs|ts)$/u;
+// The public problem detail bound; every rendered sentence stays far below it.
+const MAXIMUM_DETAIL_LENGTH = 2_000;
+const DETAIL_PATTERNS = Object.freeze(
+  Object.entries(DETAIL_DEFINITIONS).map(([code, definition]) =>
+    Object.freeze({
+      code: code as FrameworkConversionDiagnosticCode,
+      pattern: detailPattern(definition),
+    }),
+  ),
+);
+
+function anchoredPattern(source: string): RegExp {
+  return new RegExp(`^(?:${source})$`, "u");
+}
+
+function escapePattern(text: string): string {
+  return text.replace(/[\\^$.*+?()[\]{}|]/gu, "\\$&");
+}
+
+function detailPattern(definition: DetailDefinition): RegExp {
+  const placed = new Set<string>();
+  let pattern = "^";
+  let offset = 0;
+  for (const match of definition.template.matchAll(PLACEHOLDER)) {
+    const name = match[1] as string;
+    pattern += escapePattern(definition.template.slice(offset, match.index));
+    pattern += placed.has(name)
+      ? `\\k<${name}>`
+      : `(?<${name}>${placeholderPattern(definition, name)})`;
+    placed.add(name);
+    offset = match.index + match[0].length;
   }
+  return new RegExp(`${pattern}${escapePattern(definition.template.slice(offset))}$`, "u");
+}
+
+function placeholderPattern(definition: DetailDefinition, name: string): string {
+  if (name === "path") return PATH_PATTERN;
+  const grammar = definition.fields?.[name];
+  if (grammar instanceof RegExp) return grammar.source.slice(1, -1);
+  const values = grammar ?? Object.values(definition.derived?.[name]?.text ?? {});
+  if (values.length === 0) throw new TypeError("Framework conversion detail template is invalid");
+  return `(?:${[...new Set(values)].map(escapePattern).join("|")})`;
+}
+
+function pathClassOf(
+  definition: DetailDefinition,
+  path: string,
+): FrameworkConversionPathClass | null {
+  if (path === "ohmyhost.yaml" && definition.paths.includes("repository_config"))
+    return "repository_config";
+  if (
+    !SAFE_PATH.test(path) ||
+    path.split("/").some((segment) => segment === "" || segment === "." || segment === "..")
+  )
+    return null;
+  const leaf = path.slice(path.lastIndexOf("/") + 1);
+  return (
+    definition.paths.find(
+      (pathClass) =>
+        (pathClass === "module" && MODULE_PATH.test(path)) ||
+        (pathClass === "manifest" && leaf === PACKAGE_MANIFEST) ||
+        (pathClass === "lockfile" && ALL_LOCKFILES.includes(leaf)) ||
+        (pathClass === "framework_config" && FRAMEWORK_CONFIG_NAME.test(leaf)),
+    ) ?? null
+  );
+}
+
+function fieldMatches(grammar: FieldGrammar, value: unknown): boolean {
+  if (typeof value !== "string") return false;
+  return grammar instanceof RegExp ? grammar.test(value) : grammar.includes(value);
 }
 
 function isFrameworkConversionDiagnosticCode(
   value: unknown,
 ): value is FrameworkConversionDiagnosticCode {
-  return typeof value === "string" && Object.hasOwn(FRAMEWORK_CONVERSION_DETAILS, value);
+  return typeof value === "string" && Object.hasOwn(DETAIL_DEFINITIONS, value);
 }
 
+/** Accepts exactly a catalog code, a path of that code's classes and its bounded fields. */
 export function parseFrameworkConversionDiagnostic(
   value: unknown,
 ): FrameworkConversionDiagnostic | null {
   if (typeof value !== "object" || value === null || Array.isArray(value)) return null;
-  const record = value as Record<string, unknown>;
-  const path = record["path"];
-  const code = record["code"];
+  const record = value as Readonly<Record<string, unknown>>;
+  const code = Object.hasOwn(record, "code") ? record["code"] : undefined;
+  const path = Object.hasOwn(record, "path") ? record["path"] : undefined;
+  if (!isFrameworkConversionDiagnosticCode(code) || typeof path !== "string") return null;
+  const definition = DETAIL_DEFINITIONS[code];
+  const fields = Object.entries(definition.fields ?? {}).map(
+    ([name, grammar]) =>
+      [name, grammar, Object.hasOwn(record, name) ? record[name] : undefined] as const,
+  );
   if (
-    Object.keys(record).length !== 2 ||
-    !isFrameworkConversionDiagnosticCode(code) ||
-    typeof path !== "string" ||
-    path.length > 240 ||
-    (code === "managed_auth_database_required"
-      ? path !== "ohmyhost.yaml"
-      : !/^[A-Za-z0-9_@()[\]./-]+\.(?:[cm]?[jt]sx?)$/u.test(path)) ||
-    path.split("/").some((segment) => segment === "" || segment === "." || segment === "..")
+    Object.keys(record).length !== fields.length + 2 ||
+    pathClassOf(definition, path) === null ||
+    fields.some(([, grammar, field]) => !fieldMatches(grammar, field))
   )
     return null;
-  return Object.freeze({ code, path });
+  return Object.freeze(
+    Object.fromEntries([
+      ["code", code],
+      ["path", path],
+      ...fields.map(([name, , field]) => [name, field]),
+    ]),
+  ) as FrameworkConversionDiagnostic;
+}
+
+function requiredDiagnostic(value: unknown): FrameworkConversionDiagnostic {
+  const diagnostic = parseFrameworkConversionDiagnostic(value);
+  if (diagnostic === null) throw new TypeError("Framework conversion diagnostic is invalid");
+  return diagnostic;
+}
+
+function renderDetail(diagnostic: FrameworkConversionDiagnostic): string {
+  const definition = DETAIL_DEFINITIONS[diagnostic.code];
+  const values: Readonly<Record<string, unknown>> = diagnostic;
+  const pathClass = pathClassOf(definition, diagnostic.path);
+  return definition.template.replace(PLACEHOLDER, (_placeholder, name: string) => {
+    const derived = definition.derived?.[name];
+    const value =
+      derived === undefined
+        ? values[name]
+        : derived.text[String(derived.from === "path" ? pathClass : values[derived.from])];
+    if (typeof value !== "string")
+      throw new TypeError("Framework conversion diagnostic is invalid");
+    return value;
+  });
+}
+
+/**
+ * A customer source refusal: its message is the catalog detail of the typed diagnostic, which names
+ * the file and its fix. It stays a TypeError, so callers that treat an adapter refusal as a
+ * TypeError keep working.
+ */
+export class FrameworkConversionDiagnosticError extends TypeError {
+  public readonly diagnostic: FrameworkConversionDiagnostic;
+
+  public constructor(diagnostic: unknown) {
+    const parsed = requiredDiagnostic(diagnostic);
+    super(renderDetail(parsed));
+    this.name = "FrameworkConversionDiagnosticError";
+    this.diagnostic = parsed;
+  }
 }
 
 export function frameworkConversionDetail(value: unknown): string | null {
   const diagnostic = parseFrameworkConversionDiagnostic(value);
-  return diagnostic === null
-    ? null
-    : FRAMEWORK_CONVERSION_DETAILS[diagnostic.code].render(diagnostic.path);
+  return diagnostic === null ? null : renderDetail(diagnostic);
 }
 
-export function parseFrameworkConversionDetail(value: unknown): string | null {
-  if (typeof value !== "string") return null;
-  for (const [code, detail] of Object.entries(FRAMEWORK_CONVERSION_DETAILS)) {
-    const match = detail.pattern.exec(value);
-    if (match !== null) return frameworkConversionDetail({ code, path: match[1] });
+/** The typed diagnostic whose rendering is exactly this detail, or null for any other text. */
+export function frameworkConversionDiagnosticFromDetail(
+  value: unknown,
+): FrameworkConversionDiagnostic | null {
+  if (typeof value !== "string" || value.length > MAXIMUM_DETAIL_LENGTH) return null;
+  for (const { code, pattern } of DETAIL_PATTERNS) {
+    const groups = pattern.exec(value)?.groups;
+    if (groups === undefined) continue;
+    const diagnostic = parseFrameworkConversionDiagnostic({
+      code,
+      path: groups["path"],
+      ...Object.fromEntries(
+        Object.keys(DETAIL_DEFINITIONS[code].fields ?? {}).map((name) => [name, groups[name]]),
+      ),
+    });
+    if (diagnostic !== null && renderDetail(diagnostic) === value) return diagnostic;
   }
   return null;
 }
+
+export function parseFrameworkConversionDetail(value: unknown): string | null {
+  const diagnostic = frameworkConversionDiagnosticFromDetail(value);
+  return diagnostic === null ? null : renderDetail(diagnostic);
+}
+
+/**
+ * Places an application-relative diagnostic under its application root for the repository-wide
+ * answer; ohmyhost.yaml stays at the repository root. Null when the rooted path is not admitted.
+ */
+export function rootFrameworkConversionDiagnostic(
+  value: unknown,
+  applicationRoot: string,
+): FrameworkConversionDiagnostic | null {
+  const diagnostic = parseFrameworkConversionDiagnostic(value);
+  if (
+    diagnostic === null ||
+    applicationRoot === "." ||
+    DETAIL_DEFINITIONS[diagnostic.code].paths.includes("repository_config")
+  )
+    return diagnostic;
+  return parseFrameworkConversionDiagnostic({
+    ...diagnostic,
+    path: `${applicationRoot}/${diagnostic.path}`,
+  });
+}