@amerged/ohmyhost-mcp 0.1.22 → 0.1.24

package/src/apps/product-cli/{repository-init.ts → src/repository-init.ts}

@@ -7,9 +7,14 @@ import {
   type ApplicationRoot,
 } from "@ohmyhost/contracts/application-root";
 import { parseOhmyhostConfigYaml, type OhmyhostConfig } from "@ohmyhost/contracts";
+import {
+  isAdmittedFrameworkBuildScript,
+  PINNED_BUN_VERSION,
+} from "@ohmyhost/contracts/framework-build-script";
 import {
   classifyFrameworkVersion,
   FrameworkAdmissionError,
+  managedCustomerAuthAdmissionIssue,
   resolveFrameworkConfig,
   resolvePackageManager,
   type AdmittedFramework,
@@ -24,6 +29,7 @@ import {
 import {
   admitExpandOnlyMigrations,
   DatabaseMigrationAdmissionError,
+  type DatabaseMigrationAdmissionReason,
 } from "@ohmyhost/contracts/database-migration-admission";
 
 import cliPackage from "../package.json" with { type: "json" };
@@ -96,6 +102,8 @@ export interface RepositoryInitBlocker {
     | "database_driver_unsupported"
     | "build_script_missing"
     | "better_auth_version_unsupported"
+    | "managed_auth_mail_required"
+    | "managed_auth_database_required"
     | "framework_ambiguous"
     | "framework_unsupported"
     | "framework_version_unsupported"
@@ -184,6 +192,11 @@ export interface RepositoryInitResult {
     bindings: readonly string[];
     packages: RepositoryInitRuntimePackages;
   }> | null;
+  /** What server code of any framework installs and reads once a capability is enabled. */
+  readonly runtime: Readonly<{
+    bindings: readonly string[];
+    packages: RepositoryInitRuntimePackages;
+  }> | null;
 }
 
 export class RepositoryInitError extends Error {
@@ -447,6 +460,8 @@ export async function initializeRepository(
             ...runtimeContract(capabilities),
           })
         : null,
+    // Next.js and TanStack Start have neither a companion nor a Worker module, and read it here.
+    runtime: Object.values(capabilities).some(Boolean) ? runtimeContract(capabilities) : null,
   });
 }
 
@@ -480,7 +495,7 @@ async function cronBlockers(
       {
         code: "scheduled_functions_runtime_unsupported",
         message:
-          "Declared crons run on the edge runtime of a Vite API companion, Next.js or TanStack Start application, or on the functions runtime.",
+          "functions.crons needs runtime.mode edge (Next.js, TanStack Start, or Vite with src/ohmyhost/companion.ts) or functions (src/ohmyhost/worker.ts) in ohmyhost.yaml. Change runtime.mode, or remove functions.crons.",
       },
     ];
   }
@@ -585,20 +600,31 @@ function migrationFilenameBlockers(
   const invalid = files
     .filter((path) => path.startsWith(prefix))
     .map((path) => path.slice(prefix.length))
-    .some(
+    .find(
       (path) => !/^(?:[A-Za-z0-9][A-Za-z0-9._-]*\/)*\d{14}_[a-z0-9][a-z0-9_-]*\.sql$/u.test(path),
     );
-  return invalid
-    ? [
+  return invalid === undefined
+    ? []
+    : [
         {
           code: "migration_filename_noncanonical",
-          message:
-            "Rename every PostgreSQL migration to YYYYMMDDHHMMSS_name.sql before initialization.",
+          message: `Migration file '${invalid}' in ${root} is not named YYYYMMDDHHMMSS_name.sql (14 digits, an underscore, then lowercase letters, digits, _ or -). Every file in that directory must match, README and .gitkeep included: rename or move it, keeping the run order.`,
         },
-      ]
-    : [];
+      ];
 }
 
+/** What each rejection reason of the expand-only migration gate means, and how to satisfy it. */
+const MIGRATION_REJECTION: Readonly<Record<DatabaseMigrationAdmissionReason, string>> = {
+  destructive:
+    "It contains DROP, TRUNCATE, INSERT, UPDATE, DELETE, BEGIN/COMMIT/ROLLBACK, CREATE OR REPLACE, or ALTER TABLE other than ADD; move row changes to 'ohmyhost database write'.",
+  provider_specific:
+    "It mentions supabase, CREATE POLICY, ROW LEVEL SECURITY, the auth. or storage. schema, or the anon, authenticated or service_role role; comments count.",
+  unsupported:
+    "It has a statement other than CREATE TABLE, TYPE, DOMAIN, SEQUENCE, VIEW, MATERIALIZED VIEW, TRIGGER, INDEX or FUNCTION, ALTER TABLE ... ADD, COMMENT ON, CREATE SCHEMA IF NOT EXISTS auth|extensions|private or CREATE EXTENSION IF NOT EXISTS pgcrypto|btree_gist|unaccent; or a function not in LANGUAGE sql or plpgsql, SECURITY DEFINER without SET search_path, or the word ohmyhost, comments included.",
+  invalid:
+    "It is empty, not UTF-8 with LF line endings, has a BOM or NUL byte or an unterminated quote or comment, or exceeds 256 KiB (at most 128 files and 2 MiB in total).",
+};
+
 async function migrationSqlBlockers(
   applicationDirectory: string,
   files: readonly string[],
@@ -634,7 +660,7 @@ async function migrationSqlBlockers(
       if (!(error instanceof DatabaseMigrationAdmissionError)) throw error;
       blockers.push({
         code: "migration_sql_not_admitted",
-        message: `PostgreSQL migration '${migration.path}' is not admitted (${error.reason}).`,
+        message: `PostgreSQL migration '${migration.path}' is not admitted (${error.reason}): ${MIGRATION_REJECTION[error.reason]} Migrations are expand-only. Fix the file before its first deployment; never edit a migration a deployment already applied.`,
       });
     }
   }
@@ -647,7 +673,7 @@ async function migrationSqlBlockers(
     return [
       {
         code: "migration_sql_not_admitted",
-        message: `PostgreSQL migration set is not admitted (${error.reason}).`,
+        message: `The migration set is not admitted (${error.reason}): ${MIGRATION_REJECTION[error.reason]}`,
       },
     ];
   }
@@ -664,23 +690,24 @@ async function readExistingConfiguration(
   if (!information.isFile() || information.size > MAXIMUM_CONFIGURATION_BYTES) {
     throw new RepositoryInitError(
       "repository_configuration_invalid",
-      "Existing ohmyhost.yaml must be one bounded regular file.",
+      "ohmyhost.yaml must be one regular file of at most 64 KiB",
     );
   }
   const configuration = await readFile(configurationPath, "utf8");
   let parsed;
   try {
     parsed = parseOhmyhostConfigYaml(configuration);
-  } catch {
+  } catch (error) {
+    // The parser names the offending key; dropping it left the agent nothing to fix.
     throw new RepositoryInitError(
       "repository_configuration_invalid",
-      "Existing ohmyhost.yaml is invalid.",
+      error instanceof TypeError ? error.message : "ohmyhost.yaml is invalid",
     );
   }
   if (parsed.applicationRoot !== applicationRoot) {
     throw new RepositoryInitError(
       "repository_configuration_root_mismatch",
-      "Existing ohmyhost.yaml must select the detected application root.",
+      `ohmyhost.yaml sets applicationRoot to '${parsed.applicationRoot}', but init selected '${applicationRoot}'. Run 'ohmyhost init --root ${parsed.applicationRoot} --dry-run --json', or correct applicationRoot.`,
     );
   }
   return configuration;
@@ -858,10 +885,18 @@ function hasDirectSafeBuildCommand(
 ): boolean {
   const scripts = packageJson["scripts"];
   if (!isRecord(scripts) || typeof scripts["build"] !== "string") return false;
-  const command = scripts["build"];
-  if (command.includes("..") || /(?:^|\s)cd(?:\s|$)/u.test(command)) return false;
-  if (framework === "nextjs") return command === "next build" || command === "next build --webpack";
-  return command === "vite build" || command === "vite build && tsc --noEmit";
+  return (
+    (framework === "nextjs" || framework === "vite" || framework === "tanstack-start") &&
+    isAdmittedFrameworkBuildScript(framework, scripts["build"])
+  );
+}
+
+/** The package.json build-script blocker, quoting at most 200 characters of the rejected script. */
+function buildScriptMessage(framework: RepositoryFramework, command: string): string {
+  const quoted = command.slice(0, 200);
+  if (framework === "nextjs")
+    return `package.json scripts.build must be exactly "next build" or "next build --webpack", not "${quoted}". Move other steps into their own scripts, then commit and push.`;
+  return `package.json scripts.build must be "vite build", optionally joined with && to exactly one "tsc", "tsc -b", "tsc --build" or "tsc --noEmit" stage before or after it, not "${quoted}". Move other steps into their own scripts, then commit and push.`;
 }
 
 async function assertRepositoryRoot(root: string): Promise<void> {
@@ -1049,6 +1084,13 @@ function frameworkConfigurations(files: readonly string[]): FrameworkConfigurati
   });
 }
 
+/** The package.json dependency that carries each admitted framework's version. */
+const FRAMEWORK_PACKAGE: Readonly<Record<AdmittedFramework, string>> = {
+  nextjs: "next",
+  "tanstack-start": "@tanstack/react-start",
+  vite: "vite",
+};
+
 function frameworkCompatibility(
   packageJson: Record<string, unknown>,
   framework: RepositoryFramework,
@@ -1056,13 +1098,13 @@ function frameworkCompatibility(
   const targets: readonly Readonly<{ framework: AdmittedFramework; packageName: string }>[] =
     framework === "tanstack-start"
       ? [
-          { framework: "tanstack-start", packageName: "@tanstack/react-start" },
-          { framework: "vite", packageName: "vite" },
+          { framework: "tanstack-start", packageName: FRAMEWORK_PACKAGE["tanstack-start"] },
+          { framework: "vite", packageName: FRAMEWORK_PACKAGE.vite },
         ]
       : framework === "nextjs"
-        ? [{ framework: "nextjs", packageName: "next" }]
+        ? [{ framework: "nextjs", packageName: FRAMEWORK_PACKAGE.nextjs }]
         : framework === "vite"
-          ? [{ framework: "vite", packageName: "vite" }]
+          ? [{ framework: "vite", packageName: FRAMEWORK_PACKAGE.vite }]
           : [];
   const frameworks = targets.map(({ framework: targetFramework, packageName }) => {
     const version = dependencyVersion(packageJson, packageName) ?? "";
@@ -1132,7 +1174,7 @@ function repositoryBlockers(
     blockers.push({
       code: "framework_ambiguous",
       message:
-        "TanStack Start must explicitly enable static prerendering or the complete Cloudflare edge contract.",
+        'TanStack Start needs one vite.config.js, .mjs or .ts that selects a mode. Static: tanstackStart({ prerender: { enabled: true } }) from "@tanstack/react-start/plugin/vite" and no "@cloudflare/vite-plugin". Server: cloudflare({ viteEnvironment: { name: "ssr" } }) from "@cloudflare/vite-plugin" listed before tanstackStart() in plugins, with @cloudflare/vite-plugin, @tanstack/react-router, @tanstack/react-start, react, react-dom, @vitejs/plugin-react and vite in package.json.',
     });
   }
   const relevantAmbiguousConfigs = frameworkConfigs.ambiguous.filter((config) =>
@@ -1156,7 +1198,9 @@ function repositoryBlockers(
     blockers.push({
       code: "package_manager_unpinned",
       message:
-        "Declare one exact npm, pnpm, Yarn, or Bun packageManager version and commit its matching lockfile.",
+        packageManagerAdmission.reason === "package_manager_version_unsupported"
+          ? `This build image runs Bun ${PINNED_BUN_VERSION}; pin packageManager to bun@${PINNED_BUN_VERSION} and commit its matching lockfile. Repeating the unchanged version cannot work.`
+          : "Declare one exact npm, pnpm, Yarn, or Bun packageManager version and commit its matching lockfile.",
     });
   } else if (
     existingConfiguration !== null &&
@@ -1166,17 +1210,21 @@ function repositoryBlockers(
   ) {
     blockers.push({
       code: "build_command_unsupported",
-      message: "Use the admitted package manager's secure install and direct build commands.",
+      message: `ohmyhost.yaml build.install must be exactly "${packageManagerAdmission.installCommand}"${
+        "command" in existingConfiguration.build
+          ? ` and build.command "${packageManagerAdmission.buildCommand}"`
+          : ""
+      } for the packageManager in package.json. Set them, then commit and push.`,
     });
   }
   if (compatibility.classification === "unsupported" && compatibility.frameworks.length > 0) {
     const unsupported = compatibility.frameworks
       .filter((entry) => entry.classification === "unsupported")
-      .map((entry) => `${entry.framework}@${entry.version || "missing"}`)
+      .map((entry) => `${FRAMEWORK_PACKAGE[entry.framework]}@${entry.version || "missing"}`)
       .join(", ");
     blockers.push({
       code: "framework_version_unsupported",
-      message: `Framework version is outside the admitted POC window: ${unsupported}.`,
+      message: `${unsupported} is outside the versions ohmyho.st builds: next 15.5.x or 16.0.0–16.3.4, vite 5.4.0–8.2.2, @tanstack/react-start 1.168.26–1.168.49, as an exact version or a ^ or ~ range whose base version is inside. Pin a version in that range in package.json, update the lockfile, commit and push.`,
     });
   }
   const scripts = packageJson["scripts"];
@@ -1192,10 +1240,12 @@ function repositoryBlockers(
   } else if (!hasDirectSafeBuildCommand(packageJson, framework)) {
     blockers.push({
       code: "build_command_unsupported",
-      message: "Use a direct framework build command without traversal or directory changes.",
+      message: buildScriptMessage(framework, scripts["build"]),
     });
   }
   const betterAuthVersion = dependencyVersion(packageJson, "better-auth");
+  const managedMailIssue = managedCustomerAuthAdmissionIssue(existingConfiguration);
+  if (managedMailIssue !== null) blockers.push(managedMailIssue);
   if (
     existingConfiguration?.auth?.provider === "better-auth" &&
     betterAuthVersion !== null &&
@@ -1229,7 +1279,7 @@ function repositoryBlockers(
       blockers.push({
         code: "next_adapter_unconfigured",
         message:
-          "Declare direct next build, exact Next/React versions, and one supported Next config; ohmyhost supplies the OpenNext build overlay.",
+          'Next.js needs scripts.build exactly "next build" or "next build --webpack", react and react-dom at exact versions such as "19.1.0" (no ^ or ~), next within 15.5.x or 16.0.0–16.3.4, and exactly one next.config.js, .mjs or .ts, with at most one open-next.config file. ohmyho.st adds the OpenNext build itself; do not make it the build script.',
       });
     }
   }

package/src/apps/product-cli/{runtime-contract.ts → src/runtime-contract.ts}

@@ -1,4 +1,8 @@
 import { parseFeedbackSubmissionDetail } from "@ohmyhost/contracts/feedback";
+import {
+  parseProjectDataChangePlan as readProjectDataChangePlan,
+  type ProjectDataChangePlan,
+} from "@ohmyhost/contracts/project-data-changes";
 import { parseFrameworkConversionDetail } from "@ohmyhost/contracts/framework-admission";
 import {
   parseOperationDeploymentProgress,
@@ -8,7 +12,6 @@ import type {
   GithubConnectionAuthorization,
   GithubOrganizationConnection,
   GithubOrganizationConnectionStatus,
-  ProblemDetails,
   OrganizationCredits,
   ProjectCreditBudget,
 } from "@ohmyhost/sdk-ts";
@@ -22,314 +25,8 @@ import {
 } from "@ohmyhost/contracts/operation-failure";
 export type { PublicOperationFailure } from "@ohmyhost/contracts/operation-failure";
 
-/** Exported for the documentation build, which publishes one page per code. */
-export const PROBLEM_POLICY = {
-  cloudflare_zone_not_bound: {
-    status: 409,
-    retryable: false,
-    action:
-      "Configure the project domain first with 'ohmyhost domain paid plan' then 'ohmyhost domain paid apply', or configure its sender domain with 'ohmyhost mail setup'. Then request Cloudflare authorization for that domain's zone.",
-  },
-  github_connection_required: {
-    status: 409,
-    retryable: false,
-    action:
-      "This workspace has no GitHub connection yet. Run 'ohmyhost github connect --organization ULID --idempotency-key KEY --json' for it, complete its browser link, then repeat the original source link. If the project belongs to another account, use that account's login instead; error.acting_as names the login this ran as.",
-  },
-  github_connection_revoked: {
-    status: 409,
-    retryable: false,
-    action:
-      "Run 'ohmyhost github connect --organization ULID --idempotency-key KEY --json' to restore this workspace's GitHub connection, then repeat the original source link.",
-  },
-  repository_not_installed: {
-    status: 403,
-    retryable: false,
-    action:
-      "Read 'ohmyhost github status --organization ULID --json', open connection.settings_url and add this repository to the installation. Then repeat the original source link and key.",
-  },
-  database_write_pending: {
-    status: 409,
-    retryable: false,
-    action: "Poll the original database-write operation before transfer or deletion.",
-  },
-  cloudflare_authorization_closed: {
-    status: 409,
-    retryable: false,
-    action:
-      "Read Cloudflare DNS status. Reuse a valid grant for the requested zone; otherwise request fresh authorization with a new idempotency key. Do not replay the callback.",
-  },
-  billing_recharge_conflict: {
-    status: 409,
-    retryable: false,
-    action:
-      "Read billing recharge get and the current revision. Preserve the original key after uncertainty; do not start a checkout or automatically re-enable charges.",
-  },
-  billing_purchase_conflict: {
-    status: 409,
-    retryable: false,
-    action:
-      "Read the original checkout and use billing portal to manage the existing subscription. Do not create another purchase after uncertainty.",
-  },
-  compute_performance_paid_required: {
-    status: 403,
-    retryable: false,
-    action: "Check Paid service and usable credits or grace, or choose standard compute.",
-  },
-  compute_performance_unavailable: {
-    status: 503,
-    retryable: false,
-    action:
-      "Choose standard compute or report inactive performance pricing through feedback. Do not repeatedly resubmit.",
-  },
-  compute_change_pending: {
-    status: 409,
-    retryable: false,
-    action:
-      "Poll the existing operation after 60 seconds. Do not submit another size change, deletion or transfer while it runs.",
-  },
-  compute_change_conflict: {
-    status: 409,
-    retryable: false,
-    action:
-      "Read the original operation and current database compute. Preserve data and report unresolved conflicts through feedback with the operation ID.",
-  },
-  database_access_limit: {
-    status: 409,
-    retryable: false,
-    action:
-      "List the project's database credentials and revoke one you no longer need, then request access again.",
-  },
-  project_notes_conflict: {
-    status: 409,
-    retryable: false,
-    action:
-      "Read project context, merge the current notes and retry with its version and a new idempotency key.",
-  },
-  invalid_request: { status: 400, retryable: false, action: "Check the request and retry." },
-  unauthenticated: {
-    status: 401,
-    retryable: false,
-    action:
-      "Check OHMYHOST_TOKEN and the selected environment. Replace invalid tokens, or unset OHMYHOST_TOKEN and run 'ohmyhost login'.",
-  },
-  forbidden: { status: 403, retryable: false, action: "Check organization access." },
-  organization_required: {
-    status: 409,
-    retryable: false,
-    action:
-      "Run 'ohmyhost organization list --json' and select one with 'ohmyhost organization use --organization ULID --json', or create the first workspace.",
-  },
-  resource_not_found: {
-    status: 404,
-    retryable: false,
-    action:
-      "Check the resource identifier and the account: a project is visible only to its own organization, and error.acting_as names the login this ran as. Use the login of the account that owns it.",
-  },
-  idempotency_key_reused: {
-    status: 409,
-    retryable: false,
-    action: "Use a new idempotency key for a different request.",
-  },
-  project_handle_unavailable: {
-    status: 503,
-    retryable: true,
-    action: "Retry project creation with the same idempotency key.",
-  },
-  project_handle_taken: {
-    status: 409,
-    retryable: false,
-    action:
-      "Run 'ohmyhost project handle check' for a free address, then rename to one of the alternatives it returns.",
-  },
-  project_handle_invalid: {
-    status: 409,
-    retryable: false,
-    action:
-      "Choose one to five lowercase words of letters and digits, three to fifty-nine characters, avoiding reserved words.",
-  },
-  project_handle_unchanged: {
-    status: 409,
-    retryable: false,
-    action: "The project already answers on this address; no rename is needed.",
-  },
-  project_rename_blocked: {
-    status: 409,
-    retryable: true,
-    action:
-      "Wait for the running operation to finish, read the project again, then rename with the new ETag.",
-  },
-  project_identity_unavailable: {
-    status: 503,
-    retryable: true,
-    action: "Retry project creation with the same idempotency key.",
-  },
-  deployment_plan_expired: {
-    status: 409,
-    retryable: false,
-    action: "Run 'ohmyhost plan' again, then deploy the new plan.",
-  },
-  deployment_plan_incompatible: {
-    status: 409,
-    retryable: false,
-    action: "Run 'ohmyhost plan' again with the current source revision.",
-  },
-  confirmation_expired: {
-    status: 409,
-    retryable: false,
-    action: "Plan the destructive action again before confirming it.",
-  },
-  confirmation_invalid: {
-    status: 409,
-    retryable: false,
-    action: "Use the confirmation token from a fresh matching plan.",
-  },
-  etag_mismatch: {
-    status: 409,
-    retryable: false,
-    action: "Refresh the resource, plan the action again, and retry.",
-  },
-  promotion_source_stale: {
-    status: 409,
-    retryable: false,
-    action: "Read the current dev deployment, then plan promotion again.",
-  },
-  promotion_target_stale: {
-    status: 409,
-    retryable: false,
-    action: "Read the current prod status, then plan promotion again.",
-  },
-  promotion_invalid_target: {
-    status: 409,
-    retryable: false,
-    action: "Select the current succeeded dev deployment and target prod.",
-  },
-  mail_capacity_unavailable: {
-    status: 503,
-    retryable: true,
-    action:
-      "Report this request ID through feedback. The stored mail setup continues automatically once ohmyho.st has capacity; follow mail status and keep the original idempotency key.",
-  },
-  mail_domain_conflict: {
-    status: 409,
-    retryable: false,
-    action: "Read and use the sender domain already configured for this project.",
-  },
-  mail_domain_required: {
-    status: 409,
-    retryable: false,
-    action:
-      "This app declares mail.enabled. Configure the project's own sender domain with 'ohmyhost mail setup' using its Prod environment ID, or set mail.enabled to false if the app sends no mail, then plan again.",
-  },
-  storage_jurisdiction_conflict: {
-    status: 409,
-    retryable: false,
-    action:
-      "Set storage.jurisdiction in ohmyhost.yaml to the project's hosting region shown by project status, then plan again.",
-  },
-  shared_data_requires_promotion: {
-    status: 409,
-    retryable: false,
-    action:
-      "Plan and deploy this commit to Dev, then run 'ohmyhost deployment promote plan' to reach Prod.",
-  },
-  production_deployment_required: {
-    status: 409,
-    retryable: false,
-    action:
-      "Deploy to Prod first: run 'ohmyhost plan --environment prod' and deploy that plan, or promote the current Dev deployment with 'ohmyhost deployment promote plan'. Then plan the domain again.",
-  },
-  framework_conversion_required: {
-    status: 409,
-    retryable: false,
-    action:
-      "Run 'ohmyhost init', apply the matching ohmyhost framework skill, then plan the new commit.",
-  },
-  repository_configuration_missing: {
-    status: 409,
-    retryable: false,
-    action:
-      "Place ohmyhost.yaml at the Git repository root and set applicationRoot to the application directory (for example website). Commit and push the change, then plan the new commit.",
-  },
-  migration_filename_noncanonical: {
-    status: 409,
-    retryable: false,
-    action:
-      "Rename every migration to YYYYMMDDHHMMSS_name.sql, commit the change, then plan again.",
-  },
-  environment_secret_mutation_blocked: {
-    status: 409,
-    retryable: true,
-    action: "Wait for the active deployment or rollback to finish, then retry unchanged.",
-  },
-  workers_runtime_incompatible: {
-    status: 409,
-    retryable: false,
-    action: "Remove or replace the reported module, commit the change, then create a new plan.",
-  },
-  payload_too_large: { status: 413, retryable: false, action: "Reduce the request size." },
-  project_export_not_ready: {
-    status: 409,
-    retryable: false,
-    action: "Finish database provisioning, then request the export again. No backup was accepted.",
-  },
-  powered_by_flag_required: {
-    status: 409,
-    retryable: false,
-    action:
-      "Keep the flag on, remove the custom domain with 'ohmyhost domain paid delete', or buy Paid, then switch the flag off.",
-  },
-  rate_limited: { status: 429, retryable: true, action: "Retry after the server delay." },
-  insufficient_organization_credits: {
-    status: 402,
-    retryable: false,
-    action:
-      "Add organization credits or wait for reservations to settle, then retry the same request.",
-  },
-  project_budget_exceeded: {
-    status: 402,
-    retryable: false,
-    action: "Raise the project's stop budget or select continue, then retry the same request.",
-  },
-  paid_plan_required: {
-    status: 402,
-    retryable: false,
-    action:
-      "Ask the organization Owner to activate Paid through billing checkout, then retry. Top-ups and signup credits do not activate Paid. For a website domain alone, a Free workspace may instead show the powered-by flag on the project.",
-  },
-  interactive_login_required: {
-    status: 403,
-    retryable: false,
-    action:
-      "Unset OHMYHOST_TOKEN and run ohmyhost login before managing tokens. Existing token files remain unchanged.",
-  },
-  api_key_creation_uncertain: {
-    status: 503,
-    retryable: true,
-    action:
-      "Repeat the original token name and Idempotency-Key to observe its result; do not blindly create another key.",
-  },
-  api_key_permissions_unavailable: {
-    status: 503,
-    retryable: false,
-    action:
-      "Report the platform user-key permission configuration through feedback. Repeated login or creation will not fix it.",
-  },
-  reconciliation_exhausted: {
-    status: 409,
-    retryable: false,
-    action:
-      "Stop retries and submit feedback with this operation ID. A platform recovery review is required.",
-  },
-  service_unavailable: { status: 503, retryable: true, action: "Retry later." },
-} as const satisfies Readonly<
-  Record<
-    ProblemDetails["code"],
-    { readonly status: number; readonly retryable: boolean; readonly action: string }
-  >
->;
-
-type ProblemCode = keyof typeof PROBLEM_POLICY;
+import { PROBLEM_POLICY, type ProblemCode } from "@ohmyhost/contracts/problem-policy";
+export { PROBLEM_POLICY } from "@ohmyhost/contracts/problem-policy";
 
 export class ResponseContractError extends Error {
   public constructor() {
@@ -338,8 +35,17 @@ export class ResponseContractError extends Error {
   }
 }
 
+export function parseProjectDataChangePlan(value: unknown): ProjectDataChangePlan {
+  try {
+    return readProjectDataChangePlan(value);
+  } catch {
+    throw new ResponseContractError();
+  }
+}
+
 export interface SafeProblem {
   readonly requestId: string;
+  readonly message?: string;
   /** The error's documentation page, when the server names one on docs.ohmyho.st. */
   readonly docsUrl?: string;
   readonly retryAfterSeconds?: number;
@@ -1604,6 +1310,7 @@ export const parseSafeProblem = (value: unknown): SafeProblem => {
   const docsUrl = String(input["type"]);
   return {
     requestId: input["request_id"],
+    ...(input["detail"] === undefined ? {} : { message: String(input["detail"]) }),
     ...(docsUrl.startsWith("https://docs.ohmyho.st/errors/") ? { docsUrl } : {}),
     code: code as ProblemCode,
     retryable: policy.retryable,