@sakupa/mcp 0.7.3 → 0.7.5

package/dist/bin.js

@@ -128,7 +128,7 @@ var FORBIDDEN_PATH_SEGMENTS = [
 var ALLOWED_HIDDEN_PATHS = [".well-known/"];
 
 // ../core/dist/domain/version.js
-var SAKUPA_MCP_VERSION = "0.7.3";
+var SAKUPA_MCP_VERSION = "0.7.5";
 
 // ../core/dist/domain/errors.js
 var HTTP_STATUS = {
@@ -444,6 +444,9 @@ function safeDecode(bytes) {
   }
 }
 
+// ../core/dist/domain/credentials.js
+var CREDENTIAL_PATTERN = /^sk_[A-Za-z0-9_-]{43}$/;
+
 // ../core/dist/domain/hashing.js
 async function sha256Hex(bytes) {
   const digest = await globalThis.crypto.subtle.digest("SHA-256", bytes.buffer.slice(bytes.byteOffset, bytes.byteOffset + bytes.byteLength));
@@ -458,10 +461,6 @@ var CREDENTIAL_HEADER = "x-sakupa-credential";
 var IDEMPOTENCY_HEADER = "x-sakupa-idempotency-key";
 var MCP_VERSION_HEADER = "x-sakupa-mcp-version";
 
-// ../core/dist/services/sites.js
-var utf8Decoder = new TextDecoder("utf-8", { fatal: false });
-var utf8Encoder = new TextEncoder();
-
 // ../core/dist/services/subscriptions.js
 var WEBHOOK_PROCESSING_LEASE_MS = 5 * 60 * 1e3;
 
@@ -1128,20 +1127,42 @@ var SITE_FILE = "site.json";
 function siteFilePath(projectDir) {
   return join2(projectDir, SITE_DIR, SITE_FILE);
 }
-function readSiteFile(projectDir) {
+function loadSiteFile(projectDir) {
   const path = siteFilePath(projectDir);
+  if (!existsSync(path)) return { kind: "absent" };
   let raw;
   try {
     raw = readFileSync(path, "utf8");
-  } catch {
-    return null;
+  } catch (err) {
+    return {
+      kind: "corrupted",
+      problem: `the file exists but could not be read (${err instanceof Error ? err.message : String(err)})`
+    };
   }
+  let parsed;
   try {
-    const parsed = JSON.parse(raw);
-    if (typeof parsed !== "object" || parsed === null) return null;
-    if (typeof parsed.siteId !== "string" || parsed.siteId.length === 0) return null;
-    if (typeof parsed.credential !== "string" || parsed.credential.length === 0) return null;
+    parsed = JSON.parse(raw);
+  } catch {
+    return { kind: "corrupted", problem: "the file exists but is not valid JSON" };
+  }
+  if (typeof parsed !== "object" || parsed === null) {
+    return { kind: "corrupted", problem: "the file does not contain a JSON object" };
+  }
+  if (typeof parsed.siteId !== "string" || parsed.siteId.length === 0) {
+    return { kind: "corrupted", problem: "the siteId field is missing or empty" };
+  }
+  if (typeof parsed.credential !== "string" || parsed.credential.length === 0) {
+    return { kind: "corrupted", problem: "the credential field is missing or empty" };
+  }
+  if (!CREDENTIAL_PATTERN.test(parsed.credential)) {
     return {
+      kind: "corrupted",
+      problem: "the credential does not match the shape Sakupa issues (sk_ followed by exactly 43 URL-safe base64 characters) \u2014 it looks locally altered or damaged"
+    };
+  }
+  return {
+    kind: "ok",
+    file: {
       siteId: parsed.siteId,
       credential: parsed.credential,
       createdAt: typeof parsed.createdAt === "string" ? parsed.createdAt : "",
@@ -1149,12 +1170,26 @@ function readSiteFile(projectDir) {
       ...typeof parsed.shortId === "string" ? { shortId: parsed.shortId } : {},
       ...typeof parsed.url === "string" ? { url: parsed.url } : {},
       ...typeof parsed.boundDomain === "string" ? { boundDomain: parsed.boundDomain } : {}
-    };
-  } catch {
-    return null;
-  }
+    }
+  };
 }
-function writeSiteFile(projectDir, file) {
+function siteFileRecoveryGuidance(projectDir) {
+  return `The site itself is intact on the server; only the local binding file (${siteFilePath(projectDir)}) is the problem. Restore the file (from a backup or by undoing the local edit). Do NOT delete it to work around the error: the credential is unrecoverable by design, so abandoning it permanently orphans the existing site. Publishing this project as a brand-NEW site requires the user to manually delete the .sakupa directory first \u2014 the tool will never overwrite it.`;
+}
+function writeSiteFile(projectDir, file, opts = {}) {
+  if (opts.allowReplace !== true) {
+    const existing = loadSiteFile(projectDir);
+    if (existing.kind === "corrupted") {
+      throw new Error(
+        `Refusing to overwrite ${siteFilePath(projectDir)}: ${existing.problem}. ` + siteFileRecoveryGuidance(projectDir)
+      );
+    }
+    if (existing.kind === "ok" && existing.file.siteId !== file.siteId) {
+      throw new Error(
+        `Refusing to overwrite ${siteFilePath(projectDir)}: it already binds this project to site ${existing.file.siteId}. ` + siteFileRecoveryGuidance(projectDir)
+      );
+    }
+  }
   const dir = join2(projectDir, SITE_DIR);
   mkdirSync(dir, { recursive: true });
   const path = join2(dir, SITE_FILE);
@@ -1232,14 +1267,20 @@ function structuredToolResult(envelope) {
 
 // src/tools/context.ts
 function requireSiteFile(ctx) {
-  const file = readSiteFile(ctx.projectDir);
-  if (!file) {
+  const state = loadSiteFile(ctx.projectDir);
+  if (state.kind === "corrupted") {
+    throw new SakupaError(
+      "invalid_request",
+      `.sakupa/site.json in ${ctx.projectDir} is damaged: ${state.problem}. ` + siteFileRecoveryGuidance(ctx.projectDir)
+    );
+  }
+  if (state.kind === "absent") {
     throw new SakupaError(
       "not_found",
       `No .sakupa/site.json found in ${ctx.projectDir}. This project has no Sakupa site binding yet \u2014 run deploy_site first to publish it (the management credential will be stored locally in .sakupa/site.json). If this was a paid custom-domain site whose project file was lost, use recover_domain_site instead.`
     );
   }
-  return file;
+  return state.file;
 }
 function toolError(e) {
   const errorCode = isSakupaError(e) ? e.code : "internal";
@@ -1258,7 +1299,7 @@ function toolError(e) {
       ([key, value]) => safeDetailKeys.has(key) && (typeof value === "string" || typeof value === "number" || typeof value === "boolean")
     )
   ) : void 0;
-  const safeSummary = errorCode === "not_found" ? "\u6240\u9700\u7684\u672C\u5730\u9879\u76EE\u7ED1\u5B9A\u6216\u8D44\u6E90\u4E0D\u53EF\u7528\uFF1B\u5982\u679C\u672C\u5730\u6CA1\u6709 .sakupa/site.json\uFF0C\u8BF7\u5148\u8FD0\u884C deploy_site first\u3002" : errorCode === "unauthorized" ? "\u5F53\u524D\u64CD\u4F5C\u672A\u901A\u8FC7\u7AD9\u70B9\u6743\u9650\u6821\u9A8C\u3002" : errorCode === "invalid_request" || errorCode === "validation_failed" ? "\u8BF7\u6C42\u53C2\u6570\u6216\u672C\u5730\u9879\u76EE\u68C0\u67E5\u672A\u901A\u8FC7\u3002" : errorCode === "state_conflict" ? "\u8D44\u6E90\u72B6\u6001\u5DF2\u7ECF\u53D8\u5316\uFF0C\u8BF7\u91CD\u65B0\u67E5\u8BE2\u72B6\u6001\u540E\u518D\u51B3\u5B9A\u4E0B\u4E00\u6B65\u3002" : errorCode === "confirmation_required" ? "\u8D44\u6E90\u6216\u8D26\u5355\u72B6\u6001\u5DF2\u53D8\u5316\uFF0C\u65E7\u786E\u8BA4\u5DF2\u5931\u6548\uFF1B\u8BF7\u91CD\u65B0\u9884\u89C8\u540E\u518D\u786E\u8BA4\u3002" : errorCode === "payment_required" ? "\u8BE5\u64CD\u4F5C\u9700\u8981\u6709\u6548\u8BA2\u9605\uFF1B\u8BF7\u5148\u67E5\u8BE2\u8D26\u5355\u72B6\u6001\u3002" : errorCode === "rate_limited" ? "\u8BF7\u6C42\u9891\u7387\u5DF2\u8FBE\u5230\u670D\u52A1\u7AEF\u4E0A\u9650\uFF0C\u8BF7\u6309\u8FD4\u56DE\u7684\u7B49\u5F85\u65F6\u95F4\u540E\u91CD\u8BD5\u3002" : retryable ? "\u5916\u90E8\u670D\u52A1\u6682\u65F6\u4E0D\u53EF\u7528\u6216\u8BF7\u6C42\u8FC7\u4E8E\u9891\u7E41\uFF0C\u8BF7\u7A0D\u540E\u91CD\u8BD5\u3002" : "\u64CD\u4F5C\u5931\u8D25\uFF1B\u672A\u8FD4\u56DE\u670D\u52A1\u7AEF\u5185\u90E8\u8BE6\u60C5\u3002";
+  const safeSummary = errorCode === "not_found" ? "The required local project binding or resource is unavailable; if this project has no .sakupa/site.json yet, run deploy_site first." : errorCode === "unauthorized" ? "The server rejected the site credential: the one in .sakupa/site.json no longer matches the server-side verifier. The site itself is intact on the server \u2014 only the local binding file is the problem. Repair the file (restore a backup or undo the local edit). Do NOT delete the .sakupa directory to work around this: the credential is unrecoverable by design, so abandoning it permanently orphans the existing site." : errorCode === "invalid_request" || errorCode === "validation_failed" ? "The request arguments or local project checks did not pass." : errorCode === "state_conflict" ? "The resource state has changed; re-query the current status before deciding the next step." : errorCode === "confirmation_required" ? "The site or billing state changed, so the previous confirmation is stale; run the preview again and confirm against the fresh snapshot." : errorCode === "payment_required" ? "This operation requires an active subscription; check billing_status first." : errorCode === "rate_limited" ? "The server rate limit was reached; retry after the returned wait time." : retryable ? "An upstream service is temporarily unavailable or busy; retry shortly." : "The operation failed; no server-internal details are exposed.";
   const result = structuredToolResult({
     schemaVersion: 1,
     outcome: "failed",
@@ -1460,7 +1501,18 @@ Next action: ${analysis.suggestedNextAction}`,
         const files = analysis.files;
         const outputAbs = resolve2(ctx.projectDir, analysis.recommendedOutputDir ?? ".");
         const manifest = await buildHashedManifest(files, outputAbs);
-        const existing = readSiteFile(ctx.projectDir);
+        const siteFileState = loadSiteFile(ctx.projectDir);
+        if (siteFileState.kind === "corrupted") {
+          return text(
+            "site_file_corrupted",
+            `This project's .sakupa/site.json is damaged: ${siteFileState.problem}.
+
+` + siteFileRecoveryGuidance(ctx.projectDir) + "\n\nNothing was deployed and no new site was created.",
+            { problem: siteFileState.problem },
+            "blocked"
+          );
+        }
+        const existing = siteFileState.kind === "ok" ? siteFileState.file : null;
         if (!existing && args.publicConfirmed !== true) {
           return text(
             "public_deployment_confirmation_required",
@@ -1540,6 +1592,16 @@ ${JSON.stringify(finalized2.warnings, null, 2)}` : ""),
         try {
           update = await updateOnce(false);
         } catch (e) {
+          if (isSakupaError(e) && e.code === "unauthorized") {
+            return text(
+              "credential_mismatch",
+              `The server rejected the credential in .sakupa/site.json for site ${existing.siteId} \u2014 the local file no longer matches the server-side verifier (most often a local edit or merge damage).
+
+` + siteFileRecoveryGuidance(ctx.projectDir) + "\n\nNothing was deployed and no new site was created.",
+              { siteId: existing.siteId },
+              "blocked"
+            );
+          }
           if (!isIncrementalReuseFailure(e)) throw e;
           update = await updateOnce(true);
         }
@@ -1784,13 +1846,13 @@ Full status:`, res);
             schemaVersion: 1,
             outcome: "waiting_user",
             resultCode: "site_billing_portal_ready",
-            summary: `\u5DF2\u521B\u5EFA\u6B64\u7AD9\u70B9\u7684 Stripe \u5BA2\u6237\u95E8\u6237\u77ED\u65F6\u94FE\u63A5\uFF1A${res2.portalUrl}\u3002\u4EFB\u4F55\u53D8\u66F4\u4ECD\u987B\u5728 Stripe \u9875\u9762\u5B8C\u6210\u3002`,
+            summary: `Short-lived Stripe customer portal link created for this site: ${res2.portalUrl}. Any change still happens only on the Stripe-hosted page.`,
             data: { scope: args.scope, portalUrl: res2.portalUrl },
             userAction: {
               type: "open_url",
               provider: "stripe",
               url: res2.portalUrl,
-              expectedOutcome: "\u7528\u6237\u5728 Stripe \u6258\u7BA1\u9875\u9762\u7BA1\u7406\u4ED8\u6B3E\u65B9\u5F0F\u3001\u53D1\u7968\u6216\u53D6\u6D88\u7EED\u8BA2"
+              expectedOutcome: "The user manages payment methods, invoices, or cancels renewal on the Stripe-hosted page"
             },
             nextActions: [{ tool: "billing_status", allowed: true }]
           });
@@ -1800,7 +1862,7 @@ Full status:`, res);
           schemaVersion: 1,
           outcome: "waiting_user",
           resultCode: "public_billing_recovery_portal_ready",
-          summary: `Stripe \u516C\u5171\u90AE\u7BB1 OTP \u767B\u5F55\u9875\uFF1A${res.portalUrl}\u3002\u5B83\u4F7F\u7528 one-time passcode\uFF0Cdoes not recover the Sakupa key\uFF0C\u4E5F\u4E0D\u6388\u4E88\u7AD9\u70B9\u6743\u9650\uFF1B\u540C\u90AE\u7BB1\u5B58\u5728\u591A\u4E2A Customer \u65F6\uFF0CStripe \u53EF\u80FD\u53EA\u6253\u5F00 most recently created \u7684\u53EF\u7528\u8BB0\u5F55\u3002`,
+          summary: `Stripe public email-OTP login page: ${res.portalUrl}. It uses a one-time passcode, does not recover the Sakupa key, and grants no site authority; when one email has several Customers, Stripe may open only the most recently created usable record.`,
           data: {
             scope: args.scope,
             portalUrl: res.portalUrl,
@@ -1811,7 +1873,7 @@ Full status:`, res);
             type: "open_url",
             provider: "stripe",
             url: res.portalUrl,
-            expectedOutcome: "\u7528\u6237\u7531 Stripe \u9A8C\u8BC1\u8D26\u5355\u90AE\u7BB1\u540E\u67E5\u770B\u5E76\u53D6\u6D88\u95E8\u6237\u4E2D\u663E\u793A\u7684\u8BA2\u9605"
+            expectedOutcome: "The user verifies the billing email with Stripe, then reviews and cancels the subscription shown in the portal"
           },
           nextActions: []
         });
@@ -1875,7 +1937,7 @@ After the DNS record resolves, re-run recover_domain_site with verificationId: "
             schemaVersion: 1,
             outcome: res2.status === "expired" ? "expired" : res2.readyToComplete ? "completed" : "pending_provider",
             resultCode: res2.status === "expired" ? "domain_recovery_expired" : res2.readyToComplete ? "domain_recovery_ready" : "domain_recovery_pending_dns",
-            summary: `DNS \u6062\u590D\u9A8C\u8BC1\u72B6\u6001\uFF1A${res2.status}`,
+            summary: `DNS recovery verification status: ${res2.status}`,
             data: { recovery: res2 },
             nextActions: [
               {
@@ -1890,13 +1952,17 @@ After the DNS record resolves, re-run recover_domain_site with verificationId: "
         const res = await ctx.client.completeRecovery(args.verificationId, {
           ...args.preserveExistingCredentials !== void 0 ? { preserveExistingCredentials: args.preserveExistingCredentials } : {}
         });
-        writeSiteFile(ctx.projectDir, {
-          siteId: res.siteId,
-          ...res.boundHostnames[0] !== void 0 ? { boundDomain: res.boundHostnames[0] } : {},
-          credential: res.credential,
-          createdAt: (/* @__PURE__ */ new Date()).toISOString(),
-          apiBaseUrl: ctx.apiBaseUrl
-        });
+        writeSiteFile(
+          ctx.projectDir,
+          {
+            siteId: res.siteId,
+            ...res.boundHostnames[0] !== void 0 ? { boundDomain: res.boundHostnames[0] } : {},
+            credential: res.credential,
+            createdAt: (/* @__PURE__ */ new Date()).toISOString(),
+            apiBaseUrl: ctx.apiBaseUrl
+          },
+          { allowReplace: true }
+        );
         return text(
           "domain_recovery_completed",
           `Recovery complete.
@@ -1973,7 +2039,8 @@ ${res.archiveUrl}`,
     },
     async (args) => {
       try {
-        const site = readSiteFile(ctx.projectDir);
+        const siteState = loadSiteFile(ctx.projectDir);
+        const site = siteState.kind === "ok" ? siteState.file : null;
         const diagnostics = {
           toolName: args.toolName,
           ...args.errorCode !== void 0 ? { errorCode: args.errorCode } : {},
@@ -2033,7 +2100,7 @@ function registerBillingTools(server, ctx) {
           schemaVersion: 1,
           outcome: "completed",
           resultCode: "billing_catalog_returned",
-          summary: `\u5DF2\u8FD4\u56DE ${catalog.plans.length} \u4E2A\u6708\u4ED8\u65B9\u6848\uFF1BStripe \u6258\u7BA1\u9875\u9762\u662F\u4ED8\u8D39\u4E0E\u6539\u6863\u7684\u6700\u7EC8\u786E\u8BA4\u5165\u53E3\u3002`,
+          summary: `Returned ${catalog.plans.length} monthly plans; the Stripe-hosted page is the final confirmation surface for payment and plan changes.`,
           data: { catalog },
           nextActions: [{ tool: "subscribe_site", allowed: true }]
         });
@@ -2066,13 +2133,13 @@ function registerBillingTools(server, ctx) {
           outcome: "waiting_user",
           resultCode: "stripe_plan_change_confirmation_required",
           operationId: args.operationId,
-          summary: `\u5DF2\u751F\u6210\u4ECE ${result.currentPlan} \u5230 ${result.targetPlan} \u7684 Stripe \u786E\u8BA4\u94FE\u63A5\uFF1B\u8BA2\u9605\u5C1A\u672A\u53D8\u66F4\u3002`,
+          summary: `Stripe confirmation link created for ${result.currentPlan} -> ${result.targetPlan}; the subscription has NOT changed yet.`,
           data: { result },
           userAction: {
             type: "open_url",
             provider: "stripe",
             url: result.portalUrl,
-            expectedOutcome: "\u7528\u6237\u5728 Stripe \u6258\u7BA1\u9875\u9762\u786E\u8BA4\u540E\uFF0C\u7531 webhook \u66F4\u65B0 Sakupa \u8BA2\u9605\u72B6\u6001"
+            expectedOutcome: "After the user confirms on the Stripe-hosted page, the webhook updates the Sakupa subscription state"
           },
           nextActions: [{ tool: "billing_status", allowed: true }]
         });
@@ -2137,7 +2204,7 @@ function registerLifecycleTools(server, ctx) {
             outcome: "waiting_user",
             resultCode: "delete_site_confirmation_required",
             operationId: args.operationId,
-            summary: "\u5DF2\u8FD4\u56DE\u4E0E\u5F53\u524D\u7AD9\u70B9\u53CA\u8D26\u5355\u72B6\u6001\u7ED1\u5B9A\u7684\u5220\u9664\u540E\u679C\uFF1B\u786E\u8BA4\u540E\u5185\u5BB9\u548C\u6C38\u4E45\u5730\u5740\u4E0D\u53EF\u6062\u590D\u3002",
+            summary: "Deletion consequences returned, bound to the current site and billing state; after confirmation the content and the permanent URL are unrecoverable.",
             data: { preview },
             nextActions: [
               { tool: "delete_site", allowed: true, reasonCode: "exact_confirmation_required" }
@@ -2155,7 +2222,7 @@ function registerLifecycleTools(server, ctx) {
           outcome: result.servingDeletionPending ? "pending_provider" : "completed",
           resultCode: "site_deleted",
           operationId: args.operationId,
-          summary: "\u7AD9\u70B9\u5DF2\u5220\u9664\uFF0C\u672C\u5730\u7BA1\u7406\u51ED\u8BC1\u6587\u4EF6\u5DF2\u79FB\u9664\u3002",
+          summary: "Site deleted; the local management credential file was removed.",
           data: { result },
           nextActions: []
         });
@@ -2189,7 +2256,7 @@ function registerLifecycleTools(server, ctx) {
             outcome: "waiting_user",
             resultCode: "unbind_domain_confirmation_required",
             operationId: args.operationId,
-            summary: "\u5DF2\u8FD4\u56DE\u7CBE\u786E\u7ED1\u5B9A\u5FEB\u7167\uFF1B\u89E3\u7ED1\u53EA\u79FB\u9664\u81EA\u5B9A\u4E49\u57DF\u540D\uFF0C\u8BA2\u9605\u3001\u5185\u5BB9\u548C\u6C38\u4E45\u5730\u5740\u4FDD\u6301\u4E0D\u53D8\u3002",
+            summary: "Exact binding snapshot returned; unbinding removes ONLY the custom domain \u2014 the subscription, content, and permanent URL stay unchanged.",
             data: { preview },
             nextActions: [
               { tool: "unbind_domain", allowed: true, reasonCode: "exact_confirmation_required" }
@@ -2208,7 +2275,7 @@ function registerLifecycleTools(server, ctx) {
           outcome: result.servingDeletionPending ? "pending_provider" : "completed",
           resultCode: "domain_unbound",
           operationId: args.operationId,
-          summary: "\u81EA\u5B9A\u4E49\u57DF\u540D\u5DF2\u89E3\u7ED1\uFF1B\u8BA2\u9605\u3001\u5DF2\u90E8\u7F72\u5185\u5BB9\u548C\u6C38\u4E45 Sakupa \u5730\u5740\u672A\u53D8\u3002",
+          summary: "Custom domain unbound; the subscription, deployed content, and permanent Sakupa URL are unchanged.",
           data: { result },
           nextActions: [{ tool: "site_status", allowed: true }]
         });

package/dist/index.js

@@ -123,7 +123,7 @@ var FORBIDDEN_PATH_SEGMENTS = [
 var ALLOWED_HIDDEN_PATHS = [".well-known/"];
 
 // ../core/dist/domain/version.js
-var SAKUPA_MCP_VERSION = "0.7.3";
+var SAKUPA_MCP_VERSION = "0.7.5";
 
 // ../core/dist/domain/errors.js
 var HTTP_STATUS = {
@@ -439,6 +439,9 @@ function safeDecode(bytes) {
   }
 }
 
+// ../core/dist/domain/credentials.js
+var CREDENTIAL_PATTERN = /^sk_[A-Za-z0-9_-]{43}$/;
+
 // ../core/dist/domain/hashing.js
 async function sha256Hex(bytes) {
   const digest = await globalThis.crypto.subtle.digest("SHA-256", bytes.buffer.slice(bytes.byteOffset, bytes.byteOffset + bytes.byteLength));
@@ -453,10 +456,6 @@ var CREDENTIAL_HEADER = "x-sakupa-credential";
 var IDEMPOTENCY_HEADER = "x-sakupa-idempotency-key";
 var MCP_VERSION_HEADER = "x-sakupa-mcp-version";
 
-// ../core/dist/services/sites.js
-var utf8Decoder = new TextDecoder("utf-8", { fatal: false });
-var utf8Encoder = new TextEncoder();
-
 // ../core/dist/services/subscriptions.js
 var WEBHOOK_PROCESSING_LEASE_MS = 5 * 60 * 1e3;
 
@@ -764,20 +763,42 @@ var SITE_FILE = "site.json";
 function siteFilePath(projectDir) {
   return join(projectDir, SITE_DIR, SITE_FILE);
 }
-function readSiteFile(projectDir) {
+function loadSiteFile(projectDir) {
   const path = siteFilePath(projectDir);
+  if (!existsSync(path)) return { kind: "absent" };
   let raw;
   try {
     raw = readFileSync(path, "utf8");
-  } catch {
-    return null;
+  } catch (err) {
+    return {
+      kind: "corrupted",
+      problem: `the file exists but could not be read (${err instanceof Error ? err.message : String(err)})`
+    };
   }
+  let parsed;
   try {
-    const parsed = JSON.parse(raw);
-    if (typeof parsed !== "object" || parsed === null) return null;
-    if (typeof parsed.siteId !== "string" || parsed.siteId.length === 0) return null;
-    if (typeof parsed.credential !== "string" || parsed.credential.length === 0) return null;
+    parsed = JSON.parse(raw);
+  } catch {
+    return { kind: "corrupted", problem: "the file exists but is not valid JSON" };
+  }
+  if (typeof parsed !== "object" || parsed === null) {
+    return { kind: "corrupted", problem: "the file does not contain a JSON object" };
+  }
+  if (typeof parsed.siteId !== "string" || parsed.siteId.length === 0) {
+    return { kind: "corrupted", problem: "the siteId field is missing or empty" };
+  }
+  if (typeof parsed.credential !== "string" || parsed.credential.length === 0) {
+    return { kind: "corrupted", problem: "the credential field is missing or empty" };
+  }
+  if (!CREDENTIAL_PATTERN.test(parsed.credential)) {
     return {
+      kind: "corrupted",
+      problem: "the credential does not match the shape Sakupa issues (sk_ followed by exactly 43 URL-safe base64 characters) \u2014 it looks locally altered or damaged"
+    };
+  }
+  return {
+    kind: "ok",
+    file: {
       siteId: parsed.siteId,
       credential: parsed.credential,
       createdAt: typeof parsed.createdAt === "string" ? parsed.createdAt : "",
@@ -785,12 +806,26 @@ function readSiteFile(projectDir) {
       ...typeof parsed.shortId === "string" ? { shortId: parsed.shortId } : {},
       ...typeof parsed.url === "string" ? { url: parsed.url } : {},
       ...typeof parsed.boundDomain === "string" ? { boundDomain: parsed.boundDomain } : {}
-    };
-  } catch {
-    return null;
-  }
+    }
+  };
 }
-function writeSiteFile(projectDir, file) {
+function siteFileRecoveryGuidance(projectDir) {
+  return `The site itself is intact on the server; only the local binding file (${siteFilePath(projectDir)}) is the problem. Restore the file (from a backup or by undoing the local edit). Do NOT delete it to work around the error: the credential is unrecoverable by design, so abandoning it permanently orphans the existing site. Publishing this project as a brand-NEW site requires the user to manually delete the .sakupa directory first \u2014 the tool will never overwrite it.`;
+}
+function writeSiteFile(projectDir, file, opts = {}) {
+  if (opts.allowReplace !== true) {
+    const existing = loadSiteFile(projectDir);
+    if (existing.kind === "corrupted") {
+      throw new Error(
+        `Refusing to overwrite ${siteFilePath(projectDir)}: ${existing.problem}. ` + siteFileRecoveryGuidance(projectDir)
+      );
+    }
+    if (existing.kind === "ok" && existing.file.siteId !== file.siteId) {
+      throw new Error(
+        `Refusing to overwrite ${siteFilePath(projectDir)}: it already binds this project to site ${existing.file.siteId}. ` + siteFileRecoveryGuidance(projectDir)
+      );
+    }
+  }
   const dir = join(projectDir, SITE_DIR);
   mkdirSync(dir, { recursive: true });
   const path = join(dir, SITE_FILE);
@@ -1290,14 +1325,20 @@ function structuredToolResult(envelope) {
 
 // src/tools/context.ts
 function requireSiteFile(ctx) {
-  const file = readSiteFile(ctx.projectDir);
-  if (!file) {
+  const state = loadSiteFile(ctx.projectDir);
+  if (state.kind === "corrupted") {
+    throw new SakupaError(
+      "invalid_request",
+      `.sakupa/site.json in ${ctx.projectDir} is damaged: ${state.problem}. ` + siteFileRecoveryGuidance(ctx.projectDir)
+    );
+  }
+  if (state.kind === "absent") {
     throw new SakupaError(
       "not_found",
       `No .sakupa/site.json found in ${ctx.projectDir}. This project has no Sakupa site binding yet \u2014 run deploy_site first to publish it (the management credential will be stored locally in .sakupa/site.json). If this was a paid custom-domain site whose project file was lost, use recover_domain_site instead.`
     );
   }
-  return file;
+  return state.file;
 }
 function toolError(e) {
   const errorCode = isSakupaError(e) ? e.code : "internal";
@@ -1316,7 +1357,7 @@ function toolError(e) {
       ([key, value]) => safeDetailKeys.has(key) && (typeof value === "string" || typeof value === "number" || typeof value === "boolean")
     )
   ) : void 0;
-  const safeSummary = errorCode === "not_found" ? "\u6240\u9700\u7684\u672C\u5730\u9879\u76EE\u7ED1\u5B9A\u6216\u8D44\u6E90\u4E0D\u53EF\u7528\uFF1B\u5982\u679C\u672C\u5730\u6CA1\u6709 .sakupa/site.json\uFF0C\u8BF7\u5148\u8FD0\u884C deploy_site first\u3002" : errorCode === "unauthorized" ? "\u5F53\u524D\u64CD\u4F5C\u672A\u901A\u8FC7\u7AD9\u70B9\u6743\u9650\u6821\u9A8C\u3002" : errorCode === "invalid_request" || errorCode === "validation_failed" ? "\u8BF7\u6C42\u53C2\u6570\u6216\u672C\u5730\u9879\u76EE\u68C0\u67E5\u672A\u901A\u8FC7\u3002" : errorCode === "state_conflict" ? "\u8D44\u6E90\u72B6\u6001\u5DF2\u7ECF\u53D8\u5316\uFF0C\u8BF7\u91CD\u65B0\u67E5\u8BE2\u72B6\u6001\u540E\u518D\u51B3\u5B9A\u4E0B\u4E00\u6B65\u3002" : errorCode === "confirmation_required" ? "\u8D44\u6E90\u6216\u8D26\u5355\u72B6\u6001\u5DF2\u53D8\u5316\uFF0C\u65E7\u786E\u8BA4\u5DF2\u5931\u6548\uFF1B\u8BF7\u91CD\u65B0\u9884\u89C8\u540E\u518D\u786E\u8BA4\u3002" : errorCode === "payment_required" ? "\u8BE5\u64CD\u4F5C\u9700\u8981\u6709\u6548\u8BA2\u9605\uFF1B\u8BF7\u5148\u67E5\u8BE2\u8D26\u5355\u72B6\u6001\u3002" : errorCode === "rate_limited" ? "\u8BF7\u6C42\u9891\u7387\u5DF2\u8FBE\u5230\u670D\u52A1\u7AEF\u4E0A\u9650\uFF0C\u8BF7\u6309\u8FD4\u56DE\u7684\u7B49\u5F85\u65F6\u95F4\u540E\u91CD\u8BD5\u3002" : retryable ? "\u5916\u90E8\u670D\u52A1\u6682\u65F6\u4E0D\u53EF\u7528\u6216\u8BF7\u6C42\u8FC7\u4E8E\u9891\u7E41\uFF0C\u8BF7\u7A0D\u540E\u91CD\u8BD5\u3002" : "\u64CD\u4F5C\u5931\u8D25\uFF1B\u672A\u8FD4\u56DE\u670D\u52A1\u7AEF\u5185\u90E8\u8BE6\u60C5\u3002";
+  const safeSummary = errorCode === "not_found" ? "The required local project binding or resource is unavailable; if this project has no .sakupa/site.json yet, run deploy_site first." : errorCode === "unauthorized" ? "The server rejected the site credential: the one in .sakupa/site.json no longer matches the server-side verifier. The site itself is intact on the server \u2014 only the local binding file is the problem. Repair the file (restore a backup or undo the local edit). Do NOT delete the .sakupa directory to work around this: the credential is unrecoverable by design, so abandoning it permanently orphans the existing site." : errorCode === "invalid_request" || errorCode === "validation_failed" ? "The request arguments or local project checks did not pass." : errorCode === "state_conflict" ? "The resource state has changed; re-query the current status before deciding the next step." : errorCode === "confirmation_required" ? "The site or billing state changed, so the previous confirmation is stale; run the preview again and confirm against the fresh snapshot." : errorCode === "payment_required" ? "This operation requires an active subscription; check billing_status first." : errorCode === "rate_limited" ? "The server rate limit was reached; retry after the returned wait time." : retryable ? "An upstream service is temporarily unavailable or busy; retry shortly." : "The operation failed; no server-internal details are exposed.";
   const result = structuredToolResult({
     schemaVersion: 1,
     outcome: "failed",
@@ -1522,7 +1563,18 @@ Next action: ${analysis.suggestedNextAction}`,
         const files = analysis.files;
         const outputAbs = resolve2(ctx.projectDir, analysis.recommendedOutputDir ?? ".");
         const manifest = await buildHashedManifest(files, outputAbs);
-        const existing = readSiteFile(ctx.projectDir);
+        const siteFileState = loadSiteFile(ctx.projectDir);
+        if (siteFileState.kind === "corrupted") {
+          return text(
+            "site_file_corrupted",
+            `This project's .sakupa/site.json is damaged: ${siteFileState.problem}.
+
+` + siteFileRecoveryGuidance(ctx.projectDir) + "\n\nNothing was deployed and no new site was created.",
+            { problem: siteFileState.problem },
+            "blocked"
+          );
+        }
+        const existing = siteFileState.kind === "ok" ? siteFileState.file : null;
         if (!existing && args.publicConfirmed !== true) {
           return text(
             "public_deployment_confirmation_required",
@@ -1602,6 +1654,16 @@ ${JSON.stringify(finalized2.warnings, null, 2)}` : ""),
         try {
           update = await updateOnce(false);
         } catch (e) {
+          if (isSakupaError(e) && e.code === "unauthorized") {
+            return text(
+              "credential_mismatch",
+              `The server rejected the credential in .sakupa/site.json for site ${existing.siteId} \u2014 the local file no longer matches the server-side verifier (most often a local edit or merge damage).
+
+` + siteFileRecoveryGuidance(ctx.projectDir) + "\n\nNothing was deployed and no new site was created.",
+              { siteId: existing.siteId },
+              "blocked"
+            );
+          }
           if (!isIncrementalReuseFailure(e)) throw e;
           update = await updateOnce(true);
         }
@@ -1846,13 +1908,13 @@ Full status:`, res);
             schemaVersion: 1,
             outcome: "waiting_user",
             resultCode: "site_billing_portal_ready",
-            summary: `\u5DF2\u521B\u5EFA\u6B64\u7AD9\u70B9\u7684 Stripe \u5BA2\u6237\u95E8\u6237\u77ED\u65F6\u94FE\u63A5\uFF1A${res2.portalUrl}\u3002\u4EFB\u4F55\u53D8\u66F4\u4ECD\u987B\u5728 Stripe \u9875\u9762\u5B8C\u6210\u3002`,
+            summary: `Short-lived Stripe customer portal link created for this site: ${res2.portalUrl}. Any change still happens only on the Stripe-hosted page.`,
             data: { scope: args.scope, portalUrl: res2.portalUrl },
             userAction: {
               type: "open_url",
               provider: "stripe",
               url: res2.portalUrl,
-              expectedOutcome: "\u7528\u6237\u5728 Stripe \u6258\u7BA1\u9875\u9762\u7BA1\u7406\u4ED8\u6B3E\u65B9\u5F0F\u3001\u53D1\u7968\u6216\u53D6\u6D88\u7EED\u8BA2"
+              expectedOutcome: "The user manages payment methods, invoices, or cancels renewal on the Stripe-hosted page"
             },
             nextActions: [{ tool: "billing_status", allowed: true }]
           });
@@ -1862,7 +1924,7 @@ Full status:`, res);
           schemaVersion: 1,
           outcome: "waiting_user",
           resultCode: "public_billing_recovery_portal_ready",
-          summary: `Stripe \u516C\u5171\u90AE\u7BB1 OTP \u767B\u5F55\u9875\uFF1A${res.portalUrl}\u3002\u5B83\u4F7F\u7528 one-time passcode\uFF0Cdoes not recover the Sakupa key\uFF0C\u4E5F\u4E0D\u6388\u4E88\u7AD9\u70B9\u6743\u9650\uFF1B\u540C\u90AE\u7BB1\u5B58\u5728\u591A\u4E2A Customer \u65F6\uFF0CStripe \u53EF\u80FD\u53EA\u6253\u5F00 most recently created \u7684\u53EF\u7528\u8BB0\u5F55\u3002`,
+          summary: `Stripe public email-OTP login page: ${res.portalUrl}. It uses a one-time passcode, does not recover the Sakupa key, and grants no site authority; when one email has several Customers, Stripe may open only the most recently created usable record.`,
           data: {
             scope: args.scope,
             portalUrl: res.portalUrl,
@@ -1873,7 +1935,7 @@ Full status:`, res);
             type: "open_url",
             provider: "stripe",
             url: res.portalUrl,
-            expectedOutcome: "\u7528\u6237\u7531 Stripe \u9A8C\u8BC1\u8D26\u5355\u90AE\u7BB1\u540E\u67E5\u770B\u5E76\u53D6\u6D88\u95E8\u6237\u4E2D\u663E\u793A\u7684\u8BA2\u9605"
+            expectedOutcome: "The user verifies the billing email with Stripe, then reviews and cancels the subscription shown in the portal"
           },
           nextActions: []
         });
@@ -1937,7 +1999,7 @@ After the DNS record resolves, re-run recover_domain_site with verificationId: "
             schemaVersion: 1,
             outcome: res2.status === "expired" ? "expired" : res2.readyToComplete ? "completed" : "pending_provider",
             resultCode: res2.status === "expired" ? "domain_recovery_expired" : res2.readyToComplete ? "domain_recovery_ready" : "domain_recovery_pending_dns",
-            summary: `DNS \u6062\u590D\u9A8C\u8BC1\u72B6\u6001\uFF1A${res2.status}`,
+            summary: `DNS recovery verification status: ${res2.status}`,
             data: { recovery: res2 },
             nextActions: [
               {
@@ -1952,13 +2014,17 @@ After the DNS record resolves, re-run recover_domain_site with verificationId: "
         const res = await ctx.client.completeRecovery(args.verificationId, {
           ...args.preserveExistingCredentials !== void 0 ? { preserveExistingCredentials: args.preserveExistingCredentials } : {}
         });
-        writeSiteFile(ctx.projectDir, {
-          siteId: res.siteId,
-          ...res.boundHostnames[0] !== void 0 ? { boundDomain: res.boundHostnames[0] } : {},
-          credential: res.credential,
-          createdAt: (/* @__PURE__ */ new Date()).toISOString(),
-          apiBaseUrl: ctx.apiBaseUrl
-        });
+        writeSiteFile(
+          ctx.projectDir,
+          {
+            siteId: res.siteId,
+            ...res.boundHostnames[0] !== void 0 ? { boundDomain: res.boundHostnames[0] } : {},
+            credential: res.credential,
+            createdAt: (/* @__PURE__ */ new Date()).toISOString(),
+            apiBaseUrl: ctx.apiBaseUrl
+          },
+          { allowReplace: true }
+        );
         return text(
           "domain_recovery_completed",
           `Recovery complete.
@@ -2035,7 +2101,8 @@ ${res.archiveUrl}`,
     },
     async (args) => {
       try {
-        const site = readSiteFile(ctx.projectDir);
+        const siteState = loadSiteFile(ctx.projectDir);
+        const site = siteState.kind === "ok" ? siteState.file : null;
         const diagnostics = {
           toolName: args.toolName,
           ...args.errorCode !== void 0 ? { errorCode: args.errorCode } : {},
@@ -2130,7 +2197,7 @@ function registerLifecycleTools(server, ctx) {
             outcome: "waiting_user",
             resultCode: "delete_site_confirmation_required",
             operationId: args.operationId,
-            summary: "\u5DF2\u8FD4\u56DE\u4E0E\u5F53\u524D\u7AD9\u70B9\u53CA\u8D26\u5355\u72B6\u6001\u7ED1\u5B9A\u7684\u5220\u9664\u540E\u679C\uFF1B\u786E\u8BA4\u540E\u5185\u5BB9\u548C\u6C38\u4E45\u5730\u5740\u4E0D\u53EF\u6062\u590D\u3002",
+            summary: "Deletion consequences returned, bound to the current site and billing state; after confirmation the content and the permanent URL are unrecoverable.",
             data: { preview },
             nextActions: [
               { tool: "delete_site", allowed: true, reasonCode: "exact_confirmation_required" }
@@ -2148,7 +2215,7 @@ function registerLifecycleTools(server, ctx) {
           outcome: result.servingDeletionPending ? "pending_provider" : "completed",
           resultCode: "site_deleted",
           operationId: args.operationId,
-          summary: "\u7AD9\u70B9\u5DF2\u5220\u9664\uFF0C\u672C\u5730\u7BA1\u7406\u51ED\u8BC1\u6587\u4EF6\u5DF2\u79FB\u9664\u3002",
+          summary: "Site deleted; the local management credential file was removed.",
           data: { result },
           nextActions: []
         });
@@ -2182,7 +2249,7 @@ function registerLifecycleTools(server, ctx) {
             outcome: "waiting_user",
             resultCode: "unbind_domain_confirmation_required",
             operationId: args.operationId,
-            summary: "\u5DF2\u8FD4\u56DE\u7CBE\u786E\u7ED1\u5B9A\u5FEB\u7167\uFF1B\u89E3\u7ED1\u53EA\u79FB\u9664\u81EA\u5B9A\u4E49\u57DF\u540D\uFF0C\u8BA2\u9605\u3001\u5185\u5BB9\u548C\u6C38\u4E45\u5730\u5740\u4FDD\u6301\u4E0D\u53D8\u3002",
+            summary: "Exact binding snapshot returned; unbinding removes ONLY the custom domain \u2014 the subscription, content, and permanent URL stay unchanged.",
             data: { preview },
             nextActions: [
               { tool: "unbind_domain", allowed: true, reasonCode: "exact_confirmation_required" }
@@ -2201,7 +2268,7 @@ function registerLifecycleTools(server, ctx) {
           outcome: result.servingDeletionPending ? "pending_provider" : "completed",
           resultCode: "domain_unbound",
           operationId: args.operationId,
-          summary: "\u81EA\u5B9A\u4E49\u57DF\u540D\u5DF2\u89E3\u7ED1\uFF1B\u8BA2\u9605\u3001\u5DF2\u90E8\u7F72\u5185\u5BB9\u548C\u6C38\u4E45 Sakupa \u5730\u5740\u672A\u53D8\u3002",
+          summary: "Custom domain unbound; the subscription, deployed content, and permanent Sakupa URL are unchanged.",
           data: { result },
           nextActions: [{ tool: "site_status", allowed: true }]
         });
@@ -2234,7 +2301,7 @@ function registerBillingTools(server, ctx) {
           schemaVersion: 1,
           outcome: "completed",
           resultCode: "billing_catalog_returned",
-          summary: `\u5DF2\u8FD4\u56DE ${catalog.plans.length} \u4E2A\u6708\u4ED8\u65B9\u6848\uFF1BStripe \u6258\u7BA1\u9875\u9762\u662F\u4ED8\u8D39\u4E0E\u6539\u6863\u7684\u6700\u7EC8\u786E\u8BA4\u5165\u53E3\u3002`,
+          summary: `Returned ${catalog.plans.length} monthly plans; the Stripe-hosted page is the final confirmation surface for payment and plan changes.`,
           data: { catalog },
           nextActions: [{ tool: "subscribe_site", allowed: true }]
         });
@@ -2267,13 +2334,13 @@ function registerBillingTools(server, ctx) {
           outcome: "waiting_user",
           resultCode: "stripe_plan_change_confirmation_required",
           operationId: args.operationId,
-          summary: `\u5DF2\u751F\u6210\u4ECE ${result.currentPlan} \u5230 ${result.targetPlan} \u7684 Stripe \u786E\u8BA4\u94FE\u63A5\uFF1B\u8BA2\u9605\u5C1A\u672A\u53D8\u66F4\u3002`,
+          summary: `Stripe confirmation link created for ${result.currentPlan} -> ${result.targetPlan}; the subscription has NOT changed yet.`,
           data: { result },
           userAction: {
             type: "open_url",
             provider: "stripe",
             url: result.portalUrl,
-            expectedOutcome: "\u7528\u6237\u5728 Stripe \u6258\u7BA1\u9875\u9762\u786E\u8BA4\u540E\uFF0C\u7531 webhook \u66F4\u65B0 Sakupa \u8BA2\u9605\u72B6\u6001"
+            expectedOutcome: "After the user confirms on the Stripe-hosted page, the webhook updates the Sakupa subscription state"
           },
           nextActions: [{ tool: "billing_status", allowed: true }]
         });
@@ -2358,7 +2425,7 @@ export {
   createSakupaMcpServer,
   deleteSiteFile,
   loadMcpRuntimeConfig,
-  readSiteFile,
+  loadSiteFile,
   registerLifecycleTools,
   registerTools,
   requireSiteFile,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sakupa/mcp",
-  "version": "0.7.3",
+  "version": "0.7.5",
   "description": "Sakupa MCP server: publish AI-made static sites from your AI tool. AI-made pages, live in seconds.",
   "type": "module",
   "main": "dist/index.js",