@amerged/ohmyhost-mcp 0.1.15 → 0.1.17

package/src/apps/mcp/local-server.ts

@@ -53,6 +53,20 @@ export interface LocalMcpProductClient {
   }): Promise<CloudflareDnsAuthorization>;
   getCloudflareDnsStatus(projectId: string): Promise<CloudflareDnsAuthorizationStatus>;
   createDevAccessTicket(projectId: string): Promise<DevAccessTicket>;
+  ensureDevShareLink(projectId: string): Promise<import("@ohmyhost/sdk-ts").DevAccessState>;
+  setDevAccessMode(input: {
+    projectId: string;
+    mode: "protected" | "public";
+    idempotencyKey: string;
+  }): Promise<import("@ohmyhost/sdk-ts").DevAccessState>;
+  rotateDevShareLink(input: {
+    projectId: string;
+    idempotencyKey: string;
+  }): Promise<import("@ohmyhost/sdk-ts").DevAccessState>;
+  revokeDevShareLink(input: {
+    projectId: string;
+    idempotencyKey: string;
+  }): Promise<import("@ohmyhost/sdk-ts").DevAccessState>;
   changeDatabaseCompute(input: {
     projectId: string;
     environment: "dev" | "prod";
@@ -264,6 +278,7 @@ interface ProjectCreateInput {
   readonly organizationId: string;
   readonly name: string;
   readonly dataMode?: "shared" | "isolated";
+  readonly devAccessMode?: "protected" | "public";
   readonly region?: "us" | "eu";
   readonly idempotencyKey: string;
 }
@@ -278,6 +293,7 @@ interface SourceLinkInput {
 interface DeploymentPlanInput {
   readonly projectId: string;
   readonly commitSha: string;
+  readonly environment: "dev" | "prod";
 }
 
 interface DeploymentCreateInput {
@@ -461,7 +477,7 @@ export function createLocalOhmyhostMcpServer(dependencies: LocalOhmyhostMcpDepen
     server,
     dependencies,
     "domain_paid_plan",
-    "Plan a customer-owned production hostname and return the manual CNAME/validation instructions. This does not activate or change DNS. Free projects use their platform domain without customer DNS authorization.",
+    "Plan a customer-owned production hostname and return the manual CNAME/validation instructions. This does not activate or change DNS. Free projects use their platform domain without customer DNS authorization. production_deployment_required means Prod has no active deployment: deploy to Prod or promote the current Dev deployment, then plan again.",
     z.object({ project_id: identifier, hostname: domainName }),
     (client, input) =>
       client.planPaidDomain({ projectId: input.project_id, hostname: input.hostname }),
@@ -470,7 +486,7 @@ export function createLocalOhmyhostMcpServer(dependencies: LocalOhmyhostMcpDepen
     server,
     dependencies,
     "domain_paid_apply",
-    "Activate the explicitly requested customer hostname. Requires Paid; the backend may reuse only its scoped customer OAuth grant. After domain_cloudflare_status is authorized, replay the original hostname/key to reconcile its exact DNS records. Otherwise return the manual DNS records to the human. Preserve the original hostname/key after uncertainty; no arbitrary DNS or provider credentials are accepted.",
+    "Activate the explicitly requested customer hostname. Requires Paid; the backend may reuse only its scoped customer OAuth grant. After domain_cloudflare_status is authorized, replay the original hostname/key to reconcile its exact DNS records. Otherwise return the manual DNS records to the human. Preserve the original hostname/key after uncertainty; no arbitrary DNS or provider credentials are accepted. production_deployment_required changed nothing: deploy to Prod or promote Dev first, then repeat the same hostname/key.",
     z.object({
       project_id: identifier,
       hostname: domainName,
@@ -1001,11 +1017,12 @@ export function createLocalOhmyhostMcpServer(dependencies: LocalOhmyhostMcpDepen
     server,
     dependencies,
     "project_create",
-    "Create an ohmyho.st project. Recommend isolated Dev/Prod data, but respect the customer's choice and added database consumption. shared is the default and uses one database/file namespace; isolated separates database/Auth records and files. Choose before provisioning; changing the established mode requires a data migration. region defaults to us; eu places the project's database, files and builds in the EU at the same prices. The region cannot be changed later, and ohmyhost.yaml storage.jurisdiction must equal it.",
+    "Create an ohmyho.st project. Ask whether Dev should be protected (default) or public before creation; public means anyone with the Dev URL can open it, including when Dev and Prod share data. Recommend isolated Dev/Prod data, but respect the customer's choice and added database consumption. shared is the default and uses one database/file namespace; isolated separates database/Auth records and files. Choose before provisioning; changing the established mode requires a data migration. region defaults to us; eu places the project's database, files and builds in the EU at the same prices. The region cannot be changed later, and ohmyhost.yaml storage.jurisdiction must equal it.",
     z.object({
       organization_id: identifier,
       name: z.string().min(1).max(128),
       data_mode: z.enum(["shared", "isolated"]).optional(),
+      dev_access_mode: z.enum(["protected", "public"]).optional(),
       region: z.enum(["us", "eu"]).optional(),
       idempotency_key: idempotencyKey,
     }),
@@ -1014,6 +1031,7 @@ export function createLocalOhmyhostMcpServer(dependencies: LocalOhmyhostMcpDepen
         organizationId: input.organization_id,
         name: input.name,
         ...(input.data_mode === undefined ? {} : { dataMode: input.data_mode }),
+        ...(input.dev_access_mode === undefined ? {} : { devAccessMode: input.dev_access_mode }),
         ...(input.region === undefined ? {} : { region: input.region }),
         idempotencyKey: input.idempotency_key,
       }),
@@ -1031,15 +1049,68 @@ export function createLocalOhmyhostMcpServer(dependencies: LocalOhmyhostMcpDepen
     server,
     dependencies,
     "project_status",
-    "Get source, both Dev/Prod environment IDs, deployment URLs, latest operation and cleanup status. Dev URLs are protected: use project_dev_access_create before browser verification. Select environments by name when configuring secrets; never infer a Prod ID from the default Dev environment.",
+    "Get source, both Dev/Prod environment IDs, deployment URLs, Dev access mode, latest operation and cleanup status. Protected Dev needs project_dev_share_link_get for a persistent share link. Select environments by name when configuring secrets; never infer a Prod ID from the default Dev environment.",
     z.object({ project_id: identifier }),
     (client, input) => client.getProjectStatus(input.project_id),
   );
+  registerProductTool(
+    server,
+    dependencies,
+    "project_dev_share_link_get",
+    "Owner only: get or create the persistent protected Dev link. The same link works for multiple visitors and has no automatic expiry. Keep it out of notes and logs.",
+    z.object({ project_id: identifier }),
+    (client, input) => client.ensureDevShareLink(input.project_id),
+    mutationAnnotations(),
+  );
+  registerProductTool(
+    server,
+    dependencies,
+    "project_dev_access_mode_set",
+    "Owner only: choose public Dev (no platform token) or protected Dev (share link required). A switch takes effect on the next request; switching back creates a new link.",
+    z.object({
+      project_id: identifier,
+      mode: z.enum(["protected", "public"]),
+      idempotency_key: idempotencyKey,
+    }),
+    (client, input) =>
+      client.setDevAccessMode({
+        projectId: input.project_id,
+        mode: input.mode,
+        idempotencyKey: input.idempotency_key,
+      }),
+    destructiveAnnotations(),
+  );
+  registerProductTool(
+    server,
+    dependencies,
+    "project_dev_share_link_rotate",
+    "Owner only: replace the persistent Dev link and immediately revoke old links and sessions. Repeat the same key after uncertainty.",
+    z.object({ project_id: identifier, idempotency_key: idempotencyKey }),
+    (client, input) =>
+      client.rotateDevShareLink({
+        projectId: input.project_id,
+        idempotencyKey: input.idempotency_key,
+      }),
+    destructiveAnnotations(),
+  );
+  registerProductTool(
+    server,
+    dependencies,
+    "project_dev_share_link_revoke",
+    "Owner only: revoke the persistent Dev link and active sessions immediately; Dev stays protected until a new link is obtained.",
+    z.object({ project_id: identifier, idempotency_key: idempotencyKey }),
+    (client, input) =>
+      client.revokeDevShareLink({
+        projectId: input.project_id,
+        idempotencyKey: input.idempotency_key,
+      }),
+    destructiveAnnotations(),
+  );
   registerProductTool(
     server,
     dependencies,
     "project_dev_access_create",
-    "Create an owner-only ten-minute single-use access link for the protected Dev app. Anonymous Dev HTTP 404 is expected; it does not prove deployment failure. Open redeem_url once in the intended browser or isolated cookie jar, then use the clean origin with its session cookie. Keep the link and cookie private, out of reports, logs and project notes. A new ticket invalidates earlier Dev access and unused owner tickets; do not blindly retry an uncertain request. This grants no customer application login or Prod access.",
+    "Create an owner-only one-hour single-use access link for the protected Dev app. Anonymous Dev HTTP 404 is expected; it does not prove deployment failure. Open redeem_url once in the intended browser or isolated cookie jar, then use the clean origin with its session cookie. Keep the link and cookie private, out of reports, logs and project notes. A new ticket invalidates earlier one-time ticket sessions and unused owner tickets but not the persistent share link; do not blindly retry an uncertain request. This grants no customer application login or Prod access.",
     z.object({ project_id: identifier }),
     (client, input) => client.createDevAccessTicket(input.project_id),
     { ...mutationAnnotations(), idempotentHint: false },
@@ -1097,10 +1168,18 @@ export function createLocalOhmyhostMcpServer(dependencies: LocalOhmyhostMcpDepen
     server,
     dependencies,
     "deployment_plan",
-    "Plan an immutable deployment. Preserve the customer's existing authentication integration, such as Better Auth or WorkOS, and use the same generic Next.js/Vite/TanStack runtime contract. ohmyho.st login is separate. Read the app Skill's auth guidance and report actual plan blockers, required secret names/callback configuration and unverified runtime compatibility. Never assume a working platform login proves application login or silently replace its auth provider.",
-    z.object({ project_id: identifier, commit_sha: commitSha }),
+    "Plan an immutable deployment. Preserve the customer's existing authentication integration, such as Better Auth or WorkOS, and use the same generic Next.js/Vite/TanStack runtime contract. ohmyho.st login is separate. Read the app Skill's auth guidance and report actual plan blockers, required secret names/callback configuration and unverified runtime compatibility. Hosting, including Better Auth, needs no mail domain unless the app declares mail.enabled. Never assume a working platform login proves application login or silently replace its auth provider. The plan builds into Dev unless environment is prod; prod builds straight into Prod without a Dev deployment (a project with shared data and a database must deploy to Dev and promote instead). The plan stays valid for 24 hours.",
+    z.object({
+      project_id: identifier,
+      commit_sha: commitSha,
+      environment: z.enum(["dev", "prod"]).optional(),
+    }),
     (client, input) =>
-      client.planDeployment({ projectId: input.project_id, commitSha: input.commit_sha }),
+      client.planDeployment({
+        projectId: input.project_id,
+        commitSha: input.commit_sha,
+        environment: input.environment ?? "dev",
+      }),
   );
   registerProductTool(
     server,
@@ -1219,7 +1298,7 @@ export function createLocalOhmyhostMcpServer(dependencies: LocalOhmyhostMcpDepen
     server,
     dependencies,
     "mail_setup",
-    "Configure the customer's one production mail domain using the project Prod environment ID. The Dev and Prod application URLs do not create separate mail domains. Ask whether they want sending and receiving. Configure sending first; receiving requires mail_webhook_set, application signature verification and mail_webhook_verify. Preserve existing mailbox MX records. No Resend account or key is needed.",
+    "Configure the customer's one production mail domain using the project Prod environment ID, only when the customer wants mail or the app declares mail.enabled; hosting needs no mail domain and none is registered automatically. The Dev and Prod application URLs do not create separate mail domains. Ask whether they want sending and receiving. Configure sending first; receiving requires mail_webhook_set, application signature verification and mail_webhook_verify. Preserve existing mailbox MX records. No Resend account or key is needed.",
     z.object({
       project_id: identifier,
       environment_id: identifier,
@@ -1397,6 +1476,28 @@ export function createLocalOhmyhostMcpServer(dependencies: LocalOhmyhostMcpDepen
       });
     },
   );
+  registerProductTool(
+    server,
+    dependencies,
+    "mail_domain_delete",
+    "Retire the project's mail domain while the project stays active; use its Prod environment ID. Sending and receiving stop at once, then its provider domain and key are removed. DNS is not changed: remove the returned dns_records from the domain's DNS. Only when the customer no longer wants mail. Requires explicit confirmation; repeat the same key after uncertainty.",
+    z.object({
+      project_id: identifier,
+      environment_id: identifier,
+      idempotency_key: idempotencyKey,
+      confirm: z.literal(true),
+    }),
+    async (client, input) => {
+      if (!client.managedMail) throw new Error("Mail unavailable");
+      return client.managedMail({
+        action: "domain_delete",
+        projectId: input.project_id,
+        environmentId: input.environment_id,
+        idempotencyKey: input.idempotency_key,
+      });
+    },
+    destructiveAnnotations(),
+  );
   registerProductTool(
     server,
     dependencies,

package/src/apps/product-cli/cli.ts

@@ -67,6 +67,7 @@ import {
   parseOrganizationCredits,
   parseProjectCreditBudget,
   parseDevAccessTicket,
+  parseDevAccessState,
   parseGuardedActionPlan,
   parseEnvironmentSecret,
   parseEnvironmentSecretDeletion,
@@ -254,6 +255,7 @@ interface CliErrorDocument {
     readonly message?: string;
     readonly retry_after_seconds?: number;
     readonly request_id?: string;
+    readonly docs_url?: string;
   };
 }
 
@@ -303,13 +305,20 @@ const HELP_USAGE = Object.freeze({
   "feedback submit":
     "ohmyhost feedback submit --organization ULID --kind bug|issue|feature_request --title TITLE --description REDACTED_REPORT [--project ULID] [--environment ULID] [--operation ULID] [--error-code CODE] [--client-version VERSION] --idempotency-key KEY --json",
   "project create":
-    "ohmyhost project create --organization ULID --name NAME [--data-mode shared|isolated] [--region us|eu] --idempotency-key KEY --json (the region is chosen once: us is the default, eu places the database, files and builds in the EU; it cannot be changed later)",
+    "ohmyhost project create --organization ULID --name NAME [--data-mode shared|isolated] [--dev-access-mode protected|public] [--region us|eu] --idempotency-key KEY --json (the region is chosen once: us is the default, eu places the database, files and builds in the EU; it cannot be changed later)",
   "project list": "ohmyhost project list [--cursor ULID] [--limit LIMIT] --json",
   "project context": "ohmyhost project context --project ULID --json",
   "project notes set":
     "ohmyhost project notes set --project ULID --version NUMBER --markdown TEXT --idempotency-key KEY --json (no credentials or signed URLs)",
   "project status": "ohmyhost project status --project ULID --json",
   "project dev-access create": "ohmyhost project dev-access create --project ULID --json",
+  "project dev-share link": "ohmyhost project dev-share link --project ULID --json",
+  "project dev-share rotate":
+    "ohmyhost project dev-share rotate --project ULID --idempotency-key KEY --yes --json",
+  "project dev-share revoke":
+    "ohmyhost project dev-share revoke --project ULID --idempotency-key KEY --yes --json",
+  "project dev-access mode":
+    "ohmyhost project dev-access mode --project ULID --mode protected|public --idempotency-key KEY --yes --json",
   "project handle check":
     "ohmyhost project handle check --handle HANDLE --json (is this address free? answers with a reason and free alternatives; the address becomes HANDLE.check.omh.st)",
   "project handle set":
@@ -347,9 +356,9 @@ const HELP_USAGE = Object.freeze({
   "domain paid status": "ohmyhost domain paid status --project ULID --json",
   "domain paid delete":
     "ohmyhost domain paid delete --project ULID --hostname HOST --idempotency-key KEY --yes --json",
-  plan: "ohmyhost plan --project ULID --commit SHA --json",
+  plan: "ohmyhost plan --project ULID --commit SHA [--environment dev|prod] --json",
   deploy:
-    "ohmyhost deploy --project ULID --plan-id ULID --idempotency-key KEY --yes [--wait] --json",
+    "ohmyhost deploy --project ULID (--plan-id ULID | --commit SHA [--environment dev|prod]) --idempotency-key KEY --yes [--wait] --json",
   logs: "ohmyhost logs OPERATION_ULID --follow --json",
   "deployment logs": "ohmyhost deployment logs --project ULID --deployment ULID --follow --json",
   "rollback plan": "ohmyhost rollback plan --project ULID --deployment DEPLOYMENT_ULID --json",
@@ -387,6 +396,8 @@ const HELP_USAGE = Object.freeze({
   "mail domain set":
     "ohmyhost mail domain set --project ULID --environment ULID --domain DOMAIN --sending true --receiving false --idempotency-key KEY --json",
   "mail domain status": "ohmyhost mail domain status --project ULID --environment ULID --json",
+  "mail domain delete":
+    "ohmyhost mail domain delete --project ULID --environment ULID --idempotency-key KEY --yes --json",
 } satisfies Readonly<Record<CustomerCommandLabel, string>>);
 
 const HELP_COMMANDS = Object.freeze(
@@ -740,6 +751,37 @@ export class ProductCli {
       if (command.kind === "project-status") return await this.getProjectStatus(command, signal);
       if (command.kind === "project-dev-access-create")
         return await this.createDevAccessTicket(command, signal);
+      if (
+        command.kind === "project-dev-share-link" ||
+        command.kind === "project-dev-share-rotate" ||
+        command.kind === "project-dev-share-revoke" ||
+        command.kind === "project-dev-access-mode-set"
+      ) {
+        const api = await this.authenticatedApi(command.credentialStore, signal);
+        const state = parseDevAccessState(
+          command.kind === "project-dev-share-link"
+            ? await api.ensureDevShareLink(command.projectId)
+            : command.kind === "project-dev-share-rotate"
+              ? await api.rotateDevShareLink(command.projectId, command.idempotencyKey)
+              : command.kind === "project-dev-share-revoke"
+                ? await api.revokeDevShareLink(command.projectId, command.idempotencyKey)
+                : await api.setDevAccessMode(
+                    command.projectId,
+                    command.mode,
+                    command.idempotencyKey,
+                  ),
+        );
+        return success(
+          command.kind === "project-dev-share-link"
+            ? "project dev-share link"
+            : command.kind === "project-dev-share-rotate"
+              ? "project dev-share rotate"
+              : command.kind === "project-dev-share-revoke"
+                ? "project dev-share revoke"
+                : "project dev-access mode",
+          { status: "succeeded", state },
+        );
+      }
       if (command.kind === "database-write") {
         const file = await open(command.statementFile, "r"),
           buffer = Buffer.alloc(65_537);
@@ -1169,6 +1211,7 @@ export class ProductCli {
         organizationId: command.organizationId,
         name: command.name,
         ...(command.dataMode === undefined ? {} : { dataMode: command.dataMode }),
+        ...(command.devAccessMode === undefined ? {} : { devAccessMode: command.devAccessMode }),
         ...(command.region === undefined ? {} : { region: command.region }),
         idempotencyKey: command.idempotencyKey,
       }),
@@ -1451,7 +1494,10 @@ export class ProductCli {
   ): Promise<CliResult> {
     const api = await this.authenticatedApi(command.credentialStore, signal);
     const autoDeploy = await api.getAutoDeploy(command.projectId);
-    return success("source auto-deploy status", { status: "ready", auto_deploy: autoDeploy });
+    return success("source auto-deploy status", {
+      status: autoDeploy.generation === 0 ? "not_configured" : "ready",
+      auto_deploy: autoDeploy,
+    });
   }
 
   private async authorizeCloudflareDns(
@@ -1507,7 +1553,16 @@ export class ProductCli {
   ): Promise<CliResult> {
     const api = await this.authenticatedApi(command.credentialStore, signal);
     const plan = parseDeploymentPlan(await api.planDeployment(command));
-    return success("plan", { status: "planned", plan });
+    // Say which environment this plan changes and how the change reaches the live site.
+    const notes =
+      plan["environment"] === "prod"
+        ? [
+            `This plan builds straight into Prod (${String(plan["route"])}); Prod traffic switches once it is activated.`,
+          ]
+        : [
+            `This plan updates Dev only (${String(plan["route"])}). To go live, deploy with --environment prod or promote the Dev deployment with '${this.dependencies.commandPrefix} deployment promote plan --project ULID --deployment DEV_DEPLOYMENT_ULID --json'.`,
+          ];
+    return success("plan", { status: "planned", plan, notes });
   }
 
   private async deploy(
@@ -1515,20 +1570,37 @@ export class ProductCli {
     signal: AbortSignal,
   ): Promise<CliResult> {
     const api = await this.authenticatedApi(command.credentialStore, signal);
-    let operation = parseOperation(await api.createDeployment(command));
+    // With --commit the deploy plans first, so an approved deploy needs no separate plan step.
+    const plan =
+      command.commitSha === null
+        ? null
+        : parseDeploymentPlan(
+            await api.planDeployment({
+              projectId: command.projectId,
+              commitSha: command.commitSha,
+              environment: command.environment,
+            }),
+          );
+    let operation = parseOperation(
+      await api.createDeployment({
+        projectId: command.projectId,
+        planId: plan === null ? String(command.planId) : String(plan["id"]),
+        idempotencyKey: command.idempotencyKey,
+      }),
+    );
     if (command.wait) operation = await this.waitForOperation(api, operation, signal);
-    // A healthy Dev deployment answers 404 on its own origin until a ticket is redeemed. Without
-    // this sentence the first thing a customer sees after a successful deploy looks like a failure.
+    // Dev access follows the project-selected mode; the clean URL alone is insufficient when protected.
     const notes =
       operation.state === "succeeded"
         ? [
-            `A Dev URL answers 404 until you redeem an access ticket: run '${this.dependencies.commandPrefix} project dev-access create --project ULID --json' and open its redeem_url once.`,
+            `Check project status for dev_access_mode. For protected Dev, run '${this.dependencies.commandPrefix} project dev-share link --project ULID --json' and open or share its persistent share_url; public Dev opens directly.`,
           ]
         : [];
     return success("deploy", {
       status: command.wait ? "completed" : "accepted",
       operation,
-      ...(notes.length > 0 ? { notes } : {}),
+      ...(plan === null ? {} : { plan }),
+      ...(notes.length > 0 && plan?.["environment"] !== "prod" ? { notes } : {}),
     });
   }
 
@@ -2044,6 +2116,7 @@ const classifyFailure = (command: CommandLabel, error: unknown, signal: AbortSig
         undefined,
         problem.retryAfterSeconds,
         problem.requestId,
+        problem.docsUrl,
       );
     } catch {
       return failure(
@@ -2094,6 +2167,7 @@ const failure = (
   operation?: ReturnType<typeof parseOperation>,
   retryAfterSeconds?: number,
   requestId?: string,
+  docsUrl?: string,
 ): CliResult => {
   const document: CliErrorDocument = {
     version: 1,
@@ -2106,6 +2180,7 @@ const failure = (
       suggested_action: suggestedAction,
       ...(retryAfterSeconds === undefined ? {} : { retry_after_seconds: retryAfterSeconds }),
       ...(requestId === undefined ? {} : { request_id: requestId }),
+      ...(docsUrl === undefined ? {} : { docs_url: docsUrl }),
       ...(operation?.error === undefined ? {} : { message: operation.error.message }),
     },
   };
@@ -2144,6 +2219,10 @@ const parsedCommandName = (command: ProductCliCommand): CommandLabel => {
   if (command.kind === "project-notes-set") return "project notes set";
   if (command.kind === "project-status") return "project status";
   if (command.kind === "project-dev-access-create") return "project dev-access create";
+  if (command.kind === "project-dev-share-link") return "project dev-share link";
+  if (command.kind === "project-dev-share-rotate") return "project dev-share rotate";
+  if (command.kind === "project-dev-share-revoke") return "project dev-share revoke";
+  if (command.kind === "project-dev-access-mode-set") return "project dev-access mode";
   if (command.kind === "project-handle-check") return "project handle check";
   if (command.kind === "project-handle-set") return "project handle set";
   if (command.kind === "database-write") return "database write";