@amerged/ohmyhost-mcp 0.1.10

package/src/packages/contracts/database-compute.ts

@@ -0,0 +1,72 @@
+export interface DatabaseCompute {
+  readonly project_id: string;
+  readonly environment: "dev" | "prod";
+  readonly data_mode: "shared" | "isolated";
+  readonly observed_at: string;
+  readonly database: null | {
+    readonly min_cu: number;
+    readonly max_cu: number;
+    readonly min_memory_gb: number;
+    readonly max_memory_gb: number;
+    readonly suspend_timeout_seconds: number;
+    readonly state: "init" | "active" | "idle";
+    readonly pending_state: "init" | "active" | "idle" | null;
+    readonly disabled: boolean;
+    readonly region: string;
+  };
+}
+export function assertDatabaseCompute(value: unknown): asserts value is DatabaseCompute {
+  if (
+    !record(value) ||
+    !exact(value, ["data_mode", "database", "environment", "observed_at", "project_id"]) ||
+    typeof value["project_id"] !== "string" ||
+    !/^[0-7][0-9A-HJKMNP-TV-Z]{25}$/u.test(value["project_id"]) ||
+    !["dev", "prod"].includes(String(value["environment"])) ||
+    !["shared", "isolated"].includes(String(value["data_mode"])) ||
+    typeof value["observed_at"] !== "string" ||
+    !Number.isFinite(Date.parse(value["observed_at"])) ||
+    new Date(value["observed_at"]).toISOString() !== value["observed_at"]
+  )
+    throw new TypeError("Invalid database compute report");
+  const db = value["database"];
+  if (db === null) return;
+  if (
+    !record(db) ||
+    !exact(db, [
+      "disabled",
+      "max_cu",
+      "max_memory_gb",
+      "min_cu",
+      "min_memory_gb",
+      "pending_state",
+      "region",
+      "state",
+      "suspend_timeout_seconds",
+    ]) ||
+    typeof db["min_cu"] !== "number" ||
+    typeof db["max_cu"] !== "number" ||
+    !Number.isFinite(db["min_cu"]) ||
+    !Number.isFinite(db["max_cu"]) ||
+    db["min_cu"] < 0.25 ||
+    db["max_cu"] < db["min_cu"] ||
+    db["max_cu"] > Number.MAX_SAFE_INTEGER / 4096 ||
+    db["min_memory_gb"] !== db["min_cu"] * 4 ||
+    db["max_memory_gb"] !== db["max_cu"] * 4 ||
+    !Number.isSafeInteger(db["suspend_timeout_seconds"]) ||
+    Number(db["suspend_timeout_seconds"]) < -1 ||
+    Number(db["suspend_timeout_seconds"]) > 604800 ||
+    !["init", "active", "idle"].includes(String(db["state"])) ||
+    (db["pending_state"] !== null &&
+      !["init", "active", "idle"].includes(String(db["pending_state"]))) ||
+    typeof db["disabled"] !== "boolean" ||
+    typeof db["region"] !== "string" ||
+    !/^aws-[a-z0-9]+(?:-[a-z0-9]+)*-[0-9]+$/u.test(db["region"])
+  )
+    throw new TypeError("Invalid database compute configuration");
+}
+function record(v: unknown): v is Record<string, unknown> {
+  return typeof v === "object" && v !== null && !Array.isArray(v);
+}
+function exact(v: Record<string, unknown>, keys: readonly string[]) {
+  return Object.keys(v).sort().join(",") === keys.join(",");
+}

package/src/packages/contracts/database-migration-admission.ts

@@ -0,0 +1,235 @@
+const MAX_MIGRATION_COUNT = 128;
+const MAX_MIGRATION_BYTES = 256 * 1024;
+const MAX_MIGRATION_TOTAL_BYTES = 2 * 1024 * 1024;
+const MIGRATION_PATH = /^(?:[A-Za-z0-9][A-Za-z0-9._-]*\/)*\d{14}_[a-z0-9][a-z0-9_-]*\.sql$/u;
+
+export type DatabaseMigrationAdmissionReason =
+  | "destructive"
+  | "invalid"
+  | "provider_specific"
+  | "unsupported";
+
+export class DatabaseMigrationAdmissionError extends Error {
+  public readonly code = "database_migration_not_admitted";
+
+  public constructor(public readonly reason: DatabaseMigrationAdmissionReason) {
+    super("Database migration is not admitted");
+    this.name = "DatabaseMigrationAdmissionError";
+  }
+}
+
+export interface DatabaseMigrationInput {
+  readonly path: string;
+  readonly body: Uint8Array;
+}
+
+export interface DatabaseMigrationAdmission {
+  readonly files: readonly Readonly<{ path: string; statementCount: number }>[];
+  readonly statementCount: number;
+}
+
+export function admitExpandOnlyMigrations(
+  migrations: readonly DatabaseMigrationInput[],
+): DatabaseMigrationAdmission {
+  if (
+    !Array.isArray(migrations) ||
+    migrations.length === 0 ||
+    migrations.length > MAX_MIGRATION_COUNT
+  ) {
+    throw new DatabaseMigrationAdmissionError("invalid");
+  }
+  let previousPath = "";
+  let totalBytes = 0;
+  let statementCount = 0;
+  const files = migrations.map((migration) => {
+    if (
+      typeof migration !== "object" ||
+      migration === null ||
+      !MIGRATION_PATH.test(migration.path) ||
+      migration.path <= previousPath ||
+      !(migration.body instanceof Uint8Array) ||
+      migration.body.byteLength === 0 ||
+      migration.body.byteLength > MAX_MIGRATION_BYTES
+    ) {
+      throw new DatabaseMigrationAdmissionError("invalid");
+    }
+    previousPath = migration.path;
+    totalBytes += migration.body.byteLength;
+    if (totalBytes > MAX_MIGRATION_TOTAL_BYTES || migration.body.includes(0)) {
+      throw new DatabaseMigrationAdmissionError("invalid");
+    }
+    let sql: string;
+    try {
+      sql = new TextDecoder("utf-8", { fatal: true }).decode(migration.body);
+    } catch {
+      throw new DatabaseMigrationAdmissionError("invalid");
+    }
+    if (sql.length === 0 || sql.includes("\r") || sql.charCodeAt(0) === 0xfeff) {
+      throw new DatabaseMigrationAdmissionError("invalid");
+    }
+    if (/\bohmyhost\b/iu.test(sql)) throw new DatabaseMigrationAdmissionError("unsupported");
+    rejectProviderSpecificSql(sql);
+    const statements = splitSqlStatements(sql);
+    if (statements.length === 0) throw new DatabaseMigrationAdmissionError("invalid");
+    for (const statement of statements) admitStatement(statement);
+    statementCount += statements.length;
+    return Object.freeze({ path: migration.path, statementCount: statements.length });
+  });
+  return Object.freeze({ files: Object.freeze(files), statementCount });
+}
+
+function rejectProviderSpecificSql(sql: string): void {
+  const normalized = sql.toLowerCase();
+  const withoutPortableAuth = normalized.replace(
+    /\bauth\s*\.\s*"(?:account|ratelimit|session|user|verification)"/gu,
+    "",
+  );
+  if (
+    /\bauth\s*\./u.test(withoutPortableAuth) ||
+    /\bstorage\s*\./u.test(normalized) ||
+    /\b(?:to|from)\s+(?:anon|authenticated|service_role)\b/u.test(normalized) ||
+    /\bcreate\s+policy\b/u.test(normalized) ||
+    /\brow\s+level\s+security\b/u.test(normalized) ||
+    /\bsupabase\b/u.test(normalized)
+  ) {
+    throw new DatabaseMigrationAdmissionError("provider_specific");
+  }
+}
+
+function splitSqlStatements(sql: string): readonly string[] {
+  const statements: string[] = [];
+  let start = 0;
+  let index = 0;
+  while (index < sql.length) {
+    const character = sql[index];
+    const next = sql[index + 1];
+    if (character === "-" && next === "-") {
+      index = skipLineComment(sql, index + 2);
+      continue;
+    }
+    if (character === "/" && next === "*") {
+      index = skipBlockComment(sql, index + 2);
+      continue;
+    }
+    if (character === "'") {
+      index = skipQuoted(sql, index + 1, "'");
+      continue;
+    }
+    if (character === '"') {
+      index = skipQuoted(sql, index + 1, '"');
+      continue;
+    }
+    if (character === "$") {
+      const delimiter = dollarDelimiter(sql, index);
+      if (delimiter !== null) {
+        const end = sql.indexOf(delimiter, index + delimiter.length);
+        if (end < 0) throw new DatabaseMigrationAdmissionError("invalid");
+        index = end + delimiter.length;
+        continue;
+      }
+    }
+    if (character === ";") {
+      const statement = sql.slice(start, index).trim();
+      if (statement.length > 0) statements.push(statement);
+      start = index + 1;
+    }
+    index += 1;
+  }
+  const tail = sql.slice(start).trim();
+  if (tail.length > 0) statements.push(tail);
+  return Object.freeze(statements);
+}
+
+function skipLineComment(sql: string, index: number): number {
+  const newline = sql.indexOf("\n", index);
+  return newline < 0 ? sql.length : newline + 1;
+}
+
+function skipBlockComment(sql: string, index: number): number {
+  let depth = 1;
+  while (index < sql.length) {
+    if (sql[index] === "/" && sql[index + 1] === "*") {
+      depth += 1;
+      index += 2;
+      continue;
+    }
+    if (sql[index] === "*" && sql[index + 1] === "/") {
+      depth -= 1;
+      index += 2;
+      if (depth === 0) return index;
+      continue;
+    }
+    index += 1;
+  }
+  throw new DatabaseMigrationAdmissionError("invalid");
+}
+
+function skipQuoted(sql: string, index: number, quote: "'" | '"'): number {
+  while (index < sql.length) {
+    if (sql[index] !== quote) {
+      index += 1;
+      continue;
+    }
+    if (sql[index + 1] === quote) {
+      index += 2;
+      continue;
+    }
+    return index + 1;
+  }
+  throw new DatabaseMigrationAdmissionError("invalid");
+}
+
+function dollarDelimiter(sql: string, index: number): string | null {
+  const match = /^\$(?:[A-Za-z_][A-Za-z0-9_]*)?\$/u.exec(sql.slice(index));
+  return match?.[0] ?? null;
+}
+
+function admitStatement(statement: string): void {
+  const normalized = normalizeStatement(statement);
+  if (normalized === "set check_function_bodies = false") return;
+  if (/^create\s+function\b/u.test(normalized)) {
+    if (
+      !/\blanguage\s+(?:sql|plpgsql)\b/u.test(normalized) ||
+      (/\bsecurity\s+definer\b/u.test(normalized) &&
+        !/\bset\s+search_path\s*(?:=\s*|to\s+)/u.test(normalized))
+    ) {
+      throw new DatabaseMigrationAdmissionError("unsupported");
+    }
+    return;
+  }
+  if (
+    /^create\s+schema\s+if\s+not\s+exists\s+(?:auth|extensions|private)$/u.test(normalized) ||
+    /^create\s+extension\s+if\s+not\s+exists\s+(?:pgcrypto|btree_gist|unaccent)(?:\s+with\s+schema\s+extensions)?$/u.test(
+      normalized,
+    ) ||
+    /^create\s+(?:table|type|domain|sequence|view|materialized\s+view|(?:constraint\s+)?trigger)\b/u.test(
+      normalized,
+    ) ||
+    /^create\s+(?:unique\s+)?index\b/u.test(normalized) ||
+    /^alter\s+table\s+(?:only\s+)?[a-z0-9_."]+\s+add\s+(?:(?:column|constraint)\s+)?(?:if\s+not\s+exists\s+)?[a-z0-9_"]+/u.test(
+      normalized,
+    ) ||
+    /^comment\s+on\b/u.test(normalized)
+  ) {
+    if (/^create\s+or\s+replace\b/u.test(normalized)) {
+      throw new DatabaseMigrationAdmissionError("destructive");
+    }
+    return;
+  }
+  if (/^(?:drop|truncate|delete|update|insert|begin|commit|rollback)\b/u.test(normalized)) {
+    throw new DatabaseMigrationAdmissionError("destructive");
+  }
+  if (/^alter\s+table\b/u.test(normalized) || /^create\s+or\s+replace\b/u.test(normalized)) {
+    throw new DatabaseMigrationAdmissionError("destructive");
+  }
+  throw new DatabaseMigrationAdmissionError("unsupported");
+}
+
+function normalizeStatement(statement: string): string {
+  return statement
+    .replace(/--[^\n]*(?:\n|$)/gu, " ")
+    .replace(/\/\*[\s\S]*?\*\//gu, " ")
+    .trim()
+    .replace(/\s+/gu, " ")
+    .toLowerCase();
+}

package/src/packages/contracts/feedback.ts

@@ -0,0 +1,96 @@
+export interface FeedbackSubmission {
+  readonly organization_id: string;
+  readonly project_id?: string;
+  readonly environment_id?: string;
+  readonly operation_id?: string;
+  readonly kind: "bug" | "issue" | "feature_request";
+  readonly title: string;
+  /** Redacted expected/actual behavior and minimal reproduction; never raw logs or secrets. */
+  readonly description: string;
+  readonly error_code?: string;
+  readonly client_version?: string;
+}
+
+export interface FeedbackReceipt {
+  readonly id: string;
+  readonly organization_id: string;
+  readonly submitted_at: string;
+}
+
+const identifier = /^[0-7][0-9A-HJKMNP-TV-Z]{25}$/u;
+const fields = new Set([
+  "organization_id",
+  "project_id",
+  "environment_id",
+  "operation_id",
+  "kind",
+  "title",
+  "description",
+  "error_code",
+  "client_version",
+]);
+
+export function parseFeedbackSubmission(value: unknown): FeedbackSubmission {
+  if (typeof value !== "object" || value === null || Array.isArray(value))
+    throw new TypeError("Invalid feedback");
+  const v = value as Record<string, unknown>;
+  if (
+    Object.keys(v).some((key) => !fields.has(key)) ||
+    typeof v["organization_id"] !== "string" ||
+    !identifier.test(v["organization_id"]) ||
+    typeof v["kind"] !== "string" ||
+    !["bug", "issue", "feature_request"].includes(v["kind"]) ||
+    !validText(v["title"], 160, false) ||
+    !validText(v["description"], 8000, true)
+  )
+    throw new TypeError("Invalid feedback");
+  for (const key of ["project_id", "environment_id", "operation_id"]) {
+    if (key in v && (typeof v[key] !== "string" || !identifier.test(v[key])))
+      throw new TypeError("Invalid feedback scope");
+  }
+  if (("environment_id" in v || "operation_id" in v) && !("project_id" in v))
+    throw new TypeError("Project scope is required");
+  for (const key of ["error_code", "client_version"]) {
+    if (
+      key in v &&
+      (typeof v[key] !== "string" || !/^[A-Za-z0-9][A-Za-z0-9._:/+-]{0,127}$/u.test(v[key]))
+    )
+      throw new TypeError("Invalid feedback metadata");
+  }
+  return v as unknown as FeedbackSubmission;
+}
+
+export function parseFeedbackReceipt(value: unknown): FeedbackReceipt {
+  if (typeof value !== "object" || value === null || Array.isArray(value))
+    throw new TypeError("Feedback was not acknowledged");
+  const v = value as Record<string, unknown>;
+  if (
+    Object.keys(v).sort().join(",") !== "id,organization_id,submitted_at" ||
+    typeof v["id"] !== "string" ||
+    !identifier.test(v["id"]) ||
+    typeof v["organization_id"] !== "string" ||
+    !identifier.test(v["organization_id"]) ||
+    typeof v["submitted_at"] !== "string" ||
+    !/^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}\.\d{3}Z$/u.test(v["submitted_at"]) ||
+    !Number.isFinite(Date.parse(v["submitted_at"])) ||
+    new Date(v["submitted_at"]).toISOString() !== v["submitted_at"]
+  )
+    throw new TypeError("Feedback was not acknowledged");
+  return v as unknown as FeedbackReceipt;
+}
+
+function validText(value: unknown, max: number, multiline: boolean): boolean {
+  return (
+    typeof value === "string" &&
+    value === value.trim() &&
+    Array.from(value).length >= 1 &&
+    Array.from(value).length <= max &&
+    !Array.from(value).some((character) => {
+      const code = character.charCodeAt(0);
+      return (
+        (code < 32 && !(multiline && (code === 9 || code === 10 || code === 13))) ||
+        (code >= 127 && code <= 159)
+      );
+    })
+  );
+}

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

@@ -0,0 +1,280 @@
+export type PackageManagerName = "bun" | "npm" | "pnpm" | "yarn";
+
+export type FrameworkAdmissionReason =
+  | "ambiguous_config"
+  | "ambiguous_lockfile"
+  | "invalid_package_manager"
+  | "missing_lockfile"
+  | "missing_package_manager"
+  | "package_manager_lockfile_mismatch";
+
+export class FrameworkAdmissionError extends Error {
+  public readonly code = "framework_admission_failed";
+
+  public constructor(public readonly reason: FrameworkAdmissionReason) {
+    super("Framework source is not admitted");
+    this.name = "FrameworkAdmissionError";
+  }
+}
+
+export interface PackageManagerInput {
+  readonly packageManager: string | undefined;
+  readonly files: readonly string[];
+}
+
+export interface PackageManagerDescriptor {
+  readonly manager: PackageManagerName;
+  readonly version: string;
+  readonly lockfile:
+    | "bun.lock"
+    | "bun.lockb"
+    | "package-lock.json"
+    | "pnpm-lock.yaml"
+    | "yarn.lock";
+  readonly installCommand: string;
+  readonly buildCommand: string;
+}
+
+interface PackageManagerContract {
+  readonly lockfiles: readonly PackageManagerDescriptor["lockfile"][];
+  readonly installCommand: string;
+  readonly buildCommand: string;
+}
+
+const PACKAGE_MANAGER_CONTRACTS: Readonly<Record<PackageManagerName, PackageManagerContract>> =
+  Object.freeze({
+    bun: Object.freeze({
+      lockfiles: Object.freeze(["bun.lock", "bun.lockb"] as const),
+      installCommand: "bun install --frozen-lockfile --ignore-scripts",
+      buildCommand: "bun run build",
+    }),
+    npm: Object.freeze({
+      lockfiles: Object.freeze(["package-lock.json"] as const),
+      installCommand: "npm ci --ignore-scripts",
+      buildCommand: "npm run build",
+    }),
+    pnpm: Object.freeze({
+      lockfiles: Object.freeze(["pnpm-lock.yaml"] as const),
+      installCommand: "pnpm install --frozen-lockfile --ignore-scripts",
+      buildCommand: "pnpm run build",
+    }),
+    yarn: Object.freeze({
+      lockfiles: Object.freeze(["yarn.lock"] as const),
+      installCommand: "yarn install --immutable --mode=skip-build",
+      buildCommand: "yarn run build",
+    }),
+  });
+
+const ALL_LOCKFILES = 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_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 (input.packageManager === undefined) {
+    throw new FrameworkAdmissionError("missing_package_manager");
+  }
+  const declaration = PACKAGE_MANAGER_DECLARATION.exec(input.packageManager);
+  if (declaration === null) throw new FrameworkAdmissionError("invalid_package_manager");
+  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"];
+  if (!contract.lockfiles.includes(lockfile)) {
+    throw new FrameworkAdmissionError("package_manager_lockfile_mismatch");
+  }
+  return Object.freeze({
+    manager,
+    version,
+    lockfile,
+    installCommand: contract.installCommand,
+    buildCommand: contract.buildCommand,
+  });
+}
+
+export function resolveFrameworkConfig(basename: string, 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");
+  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 interface FrameworkVersionAdmission {
+  readonly classification: FrameworkVersionClassification;
+  readonly reason: FrameworkVersionReason;
+}
+
+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.23", "16.3.2"]),
+});
+
+export function classifyFrameworkVersion(
+  framework: AdmittedFramework,
+  version: string,
+): 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");
+  }
+  return VERIFIED_VERSIONS[framework].has(version)
+    ? versionAdmission("verified", "verified_fixture")
+    : versionAdmission("experimental", "inside_admitted_window");
+}
+
+type VersionTuple = readonly [major: number, minor: number, patch: number];
+
+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 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 (
+        (version[0] === 15 && version[1] === 5) ||
+        (compareVersions(version, [16, 0, 0]) >= 0 && compareVersions(version, [16, 3, 4]) <= 0)
+      );
+  }
+}
+
+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];
+}
+
+function versionAdmission(
+  classification: FrameworkVersionClassification,
+  reason: FrameworkVersionReason,
+): FrameworkVersionAdmission {
+  return Object.freeze({ classification, reason });
+}
+
+export type FrameworkConversionDiagnosticCode =
+  | "database_binding_private"
+  | "database_driver_unsupported"
+  | "source_syntax_invalid"
+  | "worker_module_default_export_required"
+  | "scheduled_handler_required";
+
+export interface FrameworkConversionDiagnostic {
+  readonly code: FrameworkConversionDiagnosticCode;
+  readonly path: string;
+}
+
+// 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({
+  database_binding_private: Object.freeze({
+    render: (path: string) =>
+      `"${path}" reads a managed database connection string. Hyperdrive, DATABASE_URL and postgres:// URLs never reach a customer Worker; call the database with createPrivateDatabaseClient from "@ohmyhost/customer-runtime/database". Commit the change, then plan again.`,
+    pattern:
+      /^"([^"]+)" reads a managed database connection string\. Hyperdrive, DATABASE_URL and postgres:\/\/ URLs never reach a customer Worker; call the database with createPrivateDatabaseClient from "@ohmyhost\/customer-runtime\/database"\. Commit the change, then plan again\.$/u,
+  }),
+  database_driver_unsupported: Object.freeze({
+    render: (path: string) =>
+      `"${path}" imports a PostgreSQL socket driver. Outbound connect() is disabled for customer Workers, so it can never open a connection; call the database with createPrivateDatabaseClient from "@ohmyhost/customer-runtime/database". Commit the change, then plan again.`,
+    pattern:
+      /^"([^"]+)" imports a PostgreSQL socket driver\. Outbound connect\(\) is disabled for customer Workers, so it can never open a connection; call the database with createPrivateDatabaseClient from "@ohmyhost\/customer-runtime\/database"\. Commit the change, then plan again\.$/u,
+  }),
+  source_syntax_invalid: Object.freeze({
+    render: (path: string) =>
+      `Invalid JavaScript or TypeScript in "${path}". Fix the file, commit the change, then plan again.`,
+    pattern:
+      /^Invalid JavaScript or TypeScript in "([^"]+)"\. Fix the file, commit the change, then plan again\.$/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. Commit the change, then plan again.`,
+    pattern:
+      /^Worker module "([^"]+)" has no default export\. Export default \{ fetch, scheduled \} with the handlers ohmyho\.st invokes; named exports are never called\. Commit the change, then plan again\.$/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 the change, then plan again.`,
+    pattern:
+      /^functions\.crons is declared but "([^"]+)" exports no scheduled handler\. Add scheduled\(controller, env, ctx\) to its default export, commit the change, then plan again\.$/u,
+  }),
+});
+
+function isFrameworkConversionDiagnosticCode(
+  value: unknown,
+): value is FrameworkConversionDiagnosticCode {
+  return typeof value === "string" && Object.hasOwn(FRAMEWORK_CONVERSION_DETAILS, value);
+}
+
+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"];
+  if (
+    Object.keys(record).length !== 2 ||
+    !isFrameworkConversionDiagnosticCode(code) ||
+    typeof path !== "string" ||
+    path.length > 240 ||
+    !/^[A-Za-z0-9_@()[\]./-]+\.(?:[cm]?[jt]sx?)$/u.test(path) ||
+    path.split("/").some((segment) => segment === "" || segment === "." || segment === "..")
+  )
+    return null;
+  return Object.freeze({ code, path });
+}
+
+export function frameworkConversionDetail(value: unknown): string | null {
+  const diagnostic = parseFrameworkConversionDiagnostic(value);
+  return diagnostic === null
+    ? null
+    : FRAMEWORK_CONVERSION_DETAILS[diagnostic.code].render(diagnostic.path);
+}
+
+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] });
+  }
+  return null;
+}