deepspace 0.20.0 → 0.22.0

package/dist/cli.js

@@ -8,8 +8,8 @@ import {
   renderUsage
 } from "citty";
 import { sync as spawnSync8 } from "cross-spawn";
-import { readFileSync as readFileSync28, existsSync as existsSync26 } from "fs";
-import { dirname as dirname12, join as join24 } from "path";
+import { readFileSync as readFileSync28, existsSync as existsSync27 } from "fs";
+import { dirname as dirname12, join as join25 } from "path";
 import { fileURLToPath as fileURLToPath3 } from "url";
 
 // src/cli/lib/spinner.ts
@@ -530,7 +530,7 @@ import { readFileSync as readFileSync2, existsSync, mkdirSync } from "fs";
 import { join } from "path";
 import { homedir } from "os";
 
-// src/cli/jwt.ts
+// src/shared/jwt.ts
 function decodeJwtPayload(token) {
   const payloadSegment = token.split(".")[1];
   if (!payloadSegment) {
@@ -913,8 +913,6 @@ import { parse as parseToml } from "smol-toml";
 // src/server/utils/registry-client.ts
 var APP_ID_RE = /^app_[0-9A-HJKMNP-TV-Z]{26}$/;
 var STRICT_APP_ID_RE = APP_ID_RE;
-
-// src/cli/lib/app-identity.ts
 var CROCKFORD = "0123456789ABCDEFGHJKMNPQRSTVWXYZ";
 function mintUlid(now = Date.now()) {
   let ts = "";
@@ -938,9 +936,8 @@ function mintUlid(now = Date.now()) {
   }
   return `${ts}${rs}`.slice(0, 26);
 }
-function mintAppId(now = Date.now()) {
-  return `app_${mintUlid(now)}`;
-}
+
+// src/cli/lib/app-identity.ts
 function readWranglerIdentityConfig(cwd) {
   const wranglerPath = join2(resolve2(cwd), "wrangler.toml");
   if (!existsSync3(wranglerPath)) return null;
@@ -996,6 +993,18 @@ ${line}
   }
   writeFileSync2(wranglerPath, src);
 }
+var APP_ID_PLACEHOLDER = "__APP_ID__";
+function stampAppIdInSources(cwd, appId, previousAppId) {
+  const constantsPath = join2(resolve2(cwd), "src", "constants.ts");
+  if (!existsSync3(constantsPath)) return false;
+  const needles = [APP_ID_PLACEHOLDER, ...previousAppId ? [previousAppId] : []];
+  const content = readFileSync5(constantsPath, "utf-8");
+  let next = content;
+  for (const needle of needles) next = next.replaceAll(needle, appId);
+  if (next === content) return false;
+  writeFileSync2(constantsPath, next);
+  return true;
+}
 
 // src/cli/commands/dev.ts
 import { resolve as resolve8, basename as basename2, join as join11 } from "path";
@@ -2677,11 +2686,15 @@ Free it with \`${killCmd}\`, or start on another port: \`deepspace dev start --p
     }
     const url = `http://${host === DEFAULT_DEV_HOST ? "localhost" : host}:${port}`;
     say("Starting dev server...\n");
-    const vite = spawn2("npx", ["vite", "--port", String(port), "--strictPort", "--host", host], {
-      cwd: appDir,
-      stdio: "inherit",
-      env: wranglerViteEnv(process.env, wranglerConfig, { DEEPSPACE_PORT: String(port) })
-    });
+    const vite = spawn2(
+      "npx",
+      ["vite", "--port", String(port), "--strictPort", "--host", host, "--clearScreen", "false"],
+      {
+        cwd: appDir,
+        stdio: "inherit",
+        env: wranglerViteEnv(process.env, wranglerConfig, { DEEPSPACE_PORT: String(port) })
+      }
+    );
     const readiness = new AbortController();
     if (args.json) {
       void waitForPortListening(port, host, READINESS_TIMEOUT_MS, readiness.signal).then((ready) => {
@@ -3195,7 +3208,7 @@ async function syncTestAccountStore() {
 // src/cli/commands/test.ts
 var DEPLOY_URL2 = process.env.DEEPSPACE_DEPLOY_URL ?? PLATFORM_URLS.deploy;
 var PLAYWRIGHT_OUTPUT_DIR = ".deepspace/test-results";
-function playwrightTestArgs(testFiles) {
+function playwrightTestArgs(testFiles, flags = {}) {
   return [
     "playwright",
     "test",
@@ -3203,6 +3216,9 @@ function playwrightTestArgs(testFiles) {
     "tests/playwright.config.ts",
     "--output",
     PLAYWRIGHT_OUTPUT_DIR,
+    ...flags.grep ? ["--grep", flags.grep] : [],
+    ...flags.project ? ["--project", flags.project] : [],
+    ...flags.headed ? ["--headed"] : [],
     ...testFiles
   ];
 }
@@ -3223,6 +3239,21 @@ var test_default = defineDeepspaceCommand({
       description: `Port for vite/webServer (default ${DEFAULT_PORT}, or $DEEPSPACE_PORT)`,
       required: false
     },
+    grep: {
+      type: "string",
+      description: "Only run Playwright tests matching this pattern (forwarded to --grep)",
+      required: false
+    },
+    project: {
+      type: "string",
+      description: "Playwright project to run (forwarded to --project)",
+      required: false
+    },
+    headed: {
+      type: "boolean",
+      description: "Run Playwright browsers headed (forwarded to --headed)",
+      default: false
+    },
     env: {
       type: "string",
       alias: "e",
@@ -3237,6 +3268,11 @@ var test_default = defineDeepspaceCommand({
     preflightNodeVersion("test run");
     const suite = args.suite ?? "default";
     const wranglerEnv = typeof args.env === "string" && args.env.trim() ? args.env.trim() : void 0;
+    const forwarded = {
+      grep: typeof args.grep === "string" && args.grep ? args.grep : void 0,
+      project: typeof args.project === "string" && args.project ? args.project : void 0,
+      headed: Boolean(args.headed)
+    };
     const start = resolve9(".");
     const appDir = findAppDir(start);
     if (!appDir) {
@@ -3293,32 +3329,36 @@ var test_default = defineDeepspaceCommand({
     let exitCode = 0;
     switch (suite) {
       case "smoke":
-        exitCode = runPlaywright(appDir, ["tests/smoke.spec.ts"], port, wranglerEnv);
+        exitCode = runPlaywright(appDir, ["tests/smoke.spec.ts"], port, wranglerEnv, forwarded);
         break;
       case "api":
-        exitCode = runPlaywright(appDir, ["tests/api.spec.ts"], port, wranglerEnv);
+        exitCode = runPlaywright(appDir, ["tests/api.spec.ts"], port, wranglerEnv, forwarded);
         break;
       case "e2e":
-        exitCode = runPlaywright(appDir, [], port, wranglerEnv);
+        exitCode = runPlaywright(appDir, [], port, wranglerEnv, forwarded);
         break;
       case "unit":
+        if (forwarded.grep || forwarded.project || forwarded.headed) {
+          console.error("note: --grep/--project/--headed apply to Playwright suites and are ignored by `unit`");
+        }
         exitCode = runVitest(appDir);
         break;
       case "all":
         exitCode = runVitest(appDir);
-        if (exitCode === 0) exitCode = runPlaywright(appDir, [], port, wranglerEnv);
+        if (exitCode === 0) exitCode = runPlaywright(appDir, [], port, wranglerEnv, forwarded);
         break;
       case "default":
         exitCode = runPlaywright(
           appDir,
           ["tests/smoke.spec.ts", "tests/api.spec.ts"],
           port,
-          wranglerEnv
+          wranglerEnv,
+          forwarded
         );
         break;
       default:
         if (suite.endsWith(".spec.ts")) {
-          exitCode = runPlaywright(appDir, [suite], port, wranglerEnv);
+          exitCode = runPlaywright(appDir, [suite], port, wranglerEnv, forwarded);
         } else {
           throw new Refusal(
             `Unknown test suite: ${suite}
@@ -3335,7 +3375,7 @@ Available: smoke, api, e2e, unit, all`,
     return { data: { suite, port, appDir, wranglerEnv: wranglerEnv ?? null } };
   }
 });
-function runPlaywright(appDir, testFiles, port, wranglerEnv) {
+function runPlaywright(appDir, testFiles, port, wranglerEnv, flags) {
   let wranglerConfig;
   try {
     wranglerConfig = prepareWranglerEnvConfig(appDir, wranglerEnv);
@@ -3344,7 +3384,7 @@ function runPlaywright(appDir, testFiles, port, wranglerEnv) {
     return 1;
   }
   try {
-    const result = spawnSync4("npx", playwrightTestArgs(testFiles), {
+    const result = spawnSync4("npx", playwrightTestArgs(testFiles, flags), {
       cwd: appDir,
       stdio: "inherit",
       env: wranglerViteEnv(process.env, wranglerConfig, {
@@ -3453,7 +3493,7 @@ var create = defineDeepspaceCommand({
     await ensureToken();
     const email = args.email;
     const password = args.password;
-    const name = args.name;
+    const name = args.name ?? email.split("@")[0];
     const label = args.label;
     let account;
     try {
@@ -3477,6 +3517,7 @@ var create = defineDeepspaceCommand({
       console.log(`Created test account:`);
       console.log(`  ID:       ${account.id}`);
       console.log(`  Email:    ${account.email}`);
+      console.log(`  Selector: ${name}`);
       console.log(`  Password: ${password}`);
       console.log(`  UserID:   ${account.userId}`);
       if (account.label) console.log(`  Label:    ${account.label}`);
@@ -3487,6 +3528,7 @@ Saved to ${TEST_ACCOUNTS_PATH}`);
       data: {
         id: account.id,
         email: account.email,
+        name,
         // The password is already echoed on the human path and stored 0600 in
         // ACCOUNTS_PATH — withholding it from --json would only force scripts
         // to parse the file themselves.
@@ -3504,6 +3546,18 @@ var list = defineDeepspaceCommand({
     name: "list",
     description: "List your test accounts"
   },
+  args: {
+    usable: {
+      type: "boolean",
+      description: "Only accounts with locally saved credentials (usable by the users() fixture)",
+      default: false
+    },
+    reveal: {
+      type: "boolean",
+      description: "Print locally saved passwords instead of masking them",
+      default: false
+    }
+  },
   async run({ args }) {
     await ensureToken();
     let remote;
@@ -3512,42 +3566,47 @@ var list = defineDeepspaceCommand({
     } catch (err) {
       throw new Refusal(`Failed: ${err.message}`, "test_accounts_list_failed");
     }
-    const local = loadAllTestAccounts();
-    const localByEmail = new Map(local.map((a) => [a.email, a]));
-    if (remote.length === 0) {
+    const localByEmail = new Map(loadAllTestAccounts().map((a) => [a.email, a]));
+    const accounts = remote.map((a) => {
+      const stored = localByEmail.get(a.email);
+      return {
+        id: a.id,
+        email: a.email,
+        userId: a.userId,
+        label: a.label,
+        createdAt: a.createdAt,
+        name: stored?.name ?? null,
+        password: stored?.password ?? null,
+        usableByFixture: Boolean(stored?.password)
+      };
+    }).filter((a) => !args.usable || a.usableByFixture);
+    if (accounts.length === 0) {
       if (!args.json) {
         console.log(
-          "No test accounts. Create one with: deepspace test accounts create --email <email> --password <password>"
+          remote.length > 0 ? `No test accounts with locally saved credentials (${remote.length} remote-only). Recreate them with: deepspace test accounts create --email <email> --password <password>` : "No test accounts. Create one with: deepspace test accounts create --email <email> --password <password>"
         );
       }
       return { data: { accounts: [], count: 0, limit: 10 } };
     }
     if (!args.json) {
-      console.log(`Test accounts (${remote.length}/10):
+      console.log(`Test accounts (${remote.length}/10${args.usable ? ", usable only" : ""}):
 `);
-      for (const a of remote) {
-        const stored = localByEmail.get(a.email);
+      for (const a of accounts) {
         const date = new Date(a.createdAt).toLocaleDateString();
         console.log(`  ${a.email}${a.label ? ` (${a.label})` : ""}`);
         console.log(`    ID: ${a.id}  UserID: ${a.userId}  Created: ${date}`);
-        if (stored?.password) {
-          console.log(`    Password: ${stored.password}`);
+        console.log(`    Selector: ${a.name ?? "(none)"}`);
+        if (a.usableByFixture) {
+          console.log(`    Password: ${args.reveal ? a.password : "(saved locally)"}`);
         } else {
-          console.log(`    Password: (not saved locally)`);
+          console.log(`    Password: (not saved locally \u2014 not usable by the users() fixture)`);
         }
       }
     }
     return {
       data: {
-        accounts: remote.map((a) => ({
-          id: a.id,
-          email: a.email,
-          userId: a.userId,
-          label: a.label,
-          createdAt: a.createdAt,
-          password: localByEmail.get(a.email)?.password ?? null
-        })),
-        count: remote.length,
+        accounts,
+        count: accounts.length,
         limit: 10
       }
     };
@@ -4417,6 +4476,7 @@ async function buildDeployBundle(options) {
   if (lintFindings && lintFindings.length > 0) {
     p6.log.warn(formatSchemaLintFindings(lintFindings).join("\n"));
   }
+  const buildStarted = Date.now();
   spinner2.start("Building...");
   let preparedWranglerConfig;
   try {
@@ -4439,7 +4499,7 @@ async function buildDeployBundle(options) {
   } finally {
     preparedWranglerConfig?.cleanup();
   }
-  spinner2.stop("Built");
+  spinner2.stop(`Built (${Math.round((Date.now() - buildStarted) / 1e3)}s)`);
   const deployConfigPath = join15(appDir, ".wrangler", "deploy", "config.json");
   if (!existsSync14(deployConfigPath)) {
     output.die(
@@ -4601,6 +4661,51 @@ import * as p7 from "@clack/prompts";
 import { existsSync as existsSync15 } from "fs";
 import { join as join16 } from "path";
 import { pathToFileURL as pathToFileURL2 } from "url";
+
+// src/shared/api-error.ts
+var SLUG_RE = /^[a-z0-9]+(?:[_.-][a-z0-9]+)*$/;
+var HUMAN_MESSAGES = {
+  owner_connect_not_ready: "This app isn't ready to accept payments yet \u2014 the app owner needs to finish payment setup.",
+  invalid_json: "The request body was not valid JSON.",
+  invalid_body: "The request body is invalid.",
+  invalid_product_id: "Invalid product id.",
+  duplicate_product_id: "Duplicate product id.",
+  unknown_product: "Unknown product.",
+  too_many_products: "Too many products declared.",
+  invalid_amount: "Invalid amount.",
+  invalid_name: "Invalid product name.",
+  invalid_description: "Invalid product description.",
+  unsupported_currency: "Unsupported currency.",
+  unknown_app: "Unknown app.",
+  not_app_owner: "Only the app owner (or a collaborator) can do this.",
+  invalid_return_url: "Invalid return URL.",
+  invalid_cancel_url: "Invalid cancel URL.",
+  unknown_plan: "Unknown subscription plan.",
+  unknown_price: "No price is configured for that billing interval.",
+  no_subscription: "No subscription found for this account."
+};
+function normalizeApiError(status3, body) {
+  const payload = body !== null && typeof body === "object" ? body : {};
+  const rawError = typeof payload.error === "string" ? payload.error : void 0;
+  const message = typeof payload.message === "string" ? payload.message : void 0;
+  const humanError = rawError !== void 0 && !SLUG_RE.test(rawError) ? rawError : void 0;
+  const code = rawError !== void 0 && SLUG_RE.test(rawError) ? rawError : typeof payload.code === "string" && SLUG_RE.test(payload.code) ? payload.code : void 0;
+  const details = {};
+  for (const [key, value] of Object.entries(payload)) {
+    if (key === "success" || key === "error" || key === "message" || key === "issues" || key === "code")
+      continue;
+    details[key] = value;
+  }
+  return {
+    error: message ?? humanError ?? (code !== void 0 ? HUMAN_MESSAGES[code] : void 0) ?? rawError ?? `Request failed (${status3})`,
+    ...code !== void 0 ? { code } : {},
+    status: status3,
+    ...Object.keys(details).length > 0 ? { details } : {},
+    ...Array.isArray(payload.issues) ? { issues: payload.issues } : {}
+  };
+}
+
+// src/cli/commands/deploy/commerce.ts
 var API_URL2 = process.env.DEEPSPACE_API_URL ?? PLATFORM_URLS.api;
 function errorMessage2(error) {
   return error instanceof Error ? error.message : String(error);
@@ -4674,7 +4779,7 @@ Stripe will keep charging them until you cancel. Cancel at the end of their curr
         });
         const body = await response.json().catch(() => ({}));
         if (!response.ok || !body.success) {
-          lastError = body.error ?? `HTTP ${response.status}`;
+          lastError = normalizeApiError(response.status, body).error;
           spinner2.stop(`Cancel failed for ${change.slug}: ${lastError}`);
           stopped = true;
           break;
@@ -4732,7 +4837,7 @@ async function syncSubscriptionPlans(appDir, appName, token, nonInteractive) {
     if (!response.ok || !body.ok) {
       spinner2.stop("Plan sync skipped");
       p7.log.warn(
-        `Plan sync failed: ${body.error ?? `HTTP ${response.status}`}${body.hint ? ` \u2014 ${body.hint}` : ""}`
+        `Plan sync failed: ${normalizeApiError(response.status, body).error}${body.hint ? ` \u2014 ${body.hint}` : ""}`
       );
       return;
     }
@@ -4790,7 +4895,7 @@ async function syncOneTimeProducts(appDir, appName, token) {
     }
     spinner2?.stop("Product sync skipped");
     p7.log.warn(
-      `Product sync failed: ${body.error ?? `HTTP ${response.status}`}${body.details ? ` \u2014 ${JSON.stringify(body.details)}` : ""}`
+      `Product sync failed: ${normalizeApiError(response.status, body).error}${body.details ? ` \u2014 ${JSON.stringify(body.details)}` : ""}`
     );
   } catch (error) {
     spinner2?.stop("Product sync skipped");
@@ -5522,7 +5627,7 @@ async function syncDeployRepository(options) {
       p9.log.info(`Workspace ${workspaceBranchId} is synced at ${tip.slice(0, 10)}.`);
     } else if (secretFiles.length > 0) {
       p9.log.warn(
-        `Skipping cloud-repo push \u2014 the branch tracks secret file(s): ${secretFiles.join(", ")}. Untrack with \`git rm --cached ${secretFiles[0]}\` (add to .gitignore), re-commit, then \`deepspace push\`. Deploy continues; this release's source isn't recoverable until then.`
+        `Skipping cloud-repo push \u2014 the branch tracks secret file(s): ${secretFiles.join(", ")}. Untrack with \`git rm --cached ${secretFiles[0]}\` (add to .gitignore), re-commit, then \`deepspace push\`. Without the push this deploy carries no source lineage: if the live release has one, the server refuses it as stale (--ignore-stale replaces it anyway), and this release's source isn't recoverable until the push works.`
       );
     } else {
       const pushResult = await pushWithTransientRetry(
@@ -5658,7 +5763,7 @@ function detachedHeadRefusal() {
 var CLOUDFLARE_DEPLOY_ERROR_HINT = "Deployment reached the DeepSpace deploy worker, but Cloudflare's deployment control-plane API failed. This is often caused by a Cloudflare Dashboard/API incident or Workers for Platforms entitlement outage. Already deployed apps should keep serving; wait for Cloudflare to recover and retry.";
 var DEPLOY_SERVICE_LIMIT_HINT = "The DeepSpace deploy service hit a resource limit processing this deploy (the deploy worker was terminated before it could answer). This is a DeepSpace-side failure, not a Cloudflare incident \u2014 your app was not changed. Retry; if it keeps happening, report the app id and asset count.";
 var REQUIRED_ASSET_TRANSPORT = "content-addressed-v1";
-var UPLOAD_CONCURRENCY = 4;
+var UPLOAD_CONCURRENCY = 16;
 async function deployBuiltBundle(options) {
   const {
     deployUrl,
@@ -5747,15 +5852,19 @@ async function deployBuiltBundle(options) {
     form.append("deployKey", repository.deployKey);
     return form;
   };
-  const postCommit = async () => postWithRetry(
-    `${deployUrl}/api/deploy/${appId}`,
-    () => ({
-      method: "POST",
-      headers: { Authorization: `Bearer ${token}` },
-      body: makeForm()
-    }),
-    { retryServerErrors: false }
-  );
+  let commitStarted = Date.now();
+  const postCommit = async () => {
+    commitStarted = Date.now();
+    return postWithRetry(
+      `${deployUrl}/api/deploy/${appId}`,
+      () => ({
+        method: "POST",
+        headers: { Authorization: `Bearer ${token}` },
+        body: makeForm()
+      }),
+      { retryServerErrors: false, attempts: 2, timeoutMs: 24e4 }
+    );
+  };
   let response;
   try {
     response = await postCommit();
@@ -5802,6 +5911,7 @@ async function deployBuiltBundle(options) {
       body.code
     );
   }
+  p10.log.info(`Platform commit: ${Math.round((Date.now() - commitStarted) / 1e3)}s`);
   if (body.onBehalfOfOwner) {
     p10.log.warn("This release is attributed to the app's owner, not to your account.");
   }
@@ -5920,8 +6030,12 @@ async function uploadDeployAssets(options) {
       spinner2.message(`Uploading assets \u2014 ${uploaded}/${total}...`);
     }
   };
+  const uploadStarted = Date.now();
   try {
     await Promise.all(Array.from({ length: Math.min(UPLOAD_CONCURRENCY, missing.length) }, worker));
+    p10.log.info(
+      `Uploaded ${total} file(s) in ${Math.round((Date.now() - uploadStarted) / 1e3)}s`
+    );
   } catch (error) {
     spinner2.stop("Deploy failed");
     if (error instanceof AssetUploadError) {
@@ -5967,13 +6081,14 @@ function errorMessage4(error) {
 }
 async function postWithRetry(url, makeInit, {
   attempts = 4,
-  retryServerErrors = true
+  retryServerErrors = true,
+  timeoutMs = 6e4
 } = {}) {
   let lastResponse;
   let lastError;
   for (let attempt = 1; attempt <= attempts; attempt++) {
     try {
-      const response = await fetch(url, makeInit());
+      const response = await fetch(url, { ...makeInit(), signal: AbortSignal.timeout(timeoutMs) });
       const transient = retryServerErrors && (response.status >= 500 || response.status === 408 || response.status === 429);
       if (!transient) return response;
       lastResponse = response;
@@ -6146,13 +6261,14 @@ var deploy_default = defineCommand3({
       );
     }
     const appName = nameResult.name;
-    let appId = readAppId(appDir, envName);
+    const appId = readAppId(appDir, envName);
     p12.log.info(envName ? `App: ${appName}  (env: ${envName})` : `App: ${appName}`);
     const { token, ownerId } = await authenticate(appDir, output);
     if (!appId) {
-      appId = mintAppId();
-      writeAppId(appDir, appId, { wranglerEnv: envName });
-      p12.log.info(`Minted app id ${appId} \u2014 commit wrangler.toml.`);
+      return output.die(
+        `No app id in wrangler.toml${envName ? ` for [env.${envName}]` : ""}. Run \`deepspace app init${envName ? ` --env ${envName}` : ""}\` to register this app, then re-deploy.`,
+        "app_not_initialized"
+      );
     }
     p12.log.info(`Id: ${appId}`);
     const secretsCache = await loadDeploySecrets({
@@ -6218,6 +6334,7 @@ var deploy_default = defineCommand3({
       spinner: spinner2
     });
     let serving = "unverifiable";
+    const edgeWaitStarted = Date.now();
     if (body.url) {
       spinner2.message("Waiting for the edge to serve this release...");
       serving = await waitForLiveRelease(body.url, body.releaseStamp, 9e4);
@@ -6247,7 +6364,9 @@ var deploy_default = defineCommand3({
         return;
       }
     }
-    spinner2.stop("Deployed!");
+    spinner2.stop(
+      `Deployed! (edge confirmed in ${Math.round((Date.now() - edgeWaitStarted) / 1e3)}s)`
+    );
     p12.log.success(`Live at: ${body.url}`);
     await syncCommerce(appDir, appId, token, output.nonInteractive);
     if (output.json) {
@@ -6508,7 +6627,10 @@ var undeploy_default = defineDeepspaceCommand({
           }
         );
       }
-      throw new Refusal(body.error ?? `Undeploy error (${res.status})`, "undeploy_failed");
+      throw new Refusal(
+        body.error ?? `Undeploy error (${res.status})`,
+        body.code ?? "undeploy_failed"
+      );
     }
     s?.stop("Removed");
     const hosts = body.releasedHosts ?? [];
@@ -9205,7 +9327,9 @@ async function runList(args) {
         for (const ep of endpoints) {
           const pad = ep.endpoint.padEnd(widest);
           const cost = formatCurrency(ep.billing.baseCost, ep.billing.currency);
-          console.log(`  ${pad}  ${ep.billing.model.padEnd(12)} ${cost}`);
+          const oauth = ep.requiresOAuth ? " [oauth]" : "";
+          console.log(`  ${pad}  ${ep.billing.model.padEnd(12)} ${cost}${oauth}`);
+          if (ep.description) console.log(`    ${ep.description}`);
         }
         console.log();
       }
@@ -9234,9 +9358,15 @@ async function runInfo(args) {
   }
   if (!args.json) {
     console.log(`${integration}/${endpoint}`);
+    if (info2.description) console.log(`  ${info2.description}`);
     console.log(
       `  billing: ${formatCurrency(info2.billing.baseCost, info2.billing.currency)} ${billingUnit(info2.billing.model)}`
     );
+    if (info2.requiresOAuth) {
+      console.log(
+        "  Requires OAuth: without a connected account, a call succeeds with data { requiresOAuth: true, authUrl } \u2014 open the authUrl, then retry."
+      );
+    }
     console.log();
     console.log("Input schema:");
     console.log(
@@ -9245,6 +9375,11 @@ async function runInfo(args) {
     console.log();
     console.log("Example body:");
     console.log(info2.example ? JSON.stringify(info2.example, null, 2) : "  (no example available)");
+    if (info2.outputSchema) {
+      console.log();
+      console.log("Output schema:");
+      console.log(JSON.stringify(info2.outputSchema, null, 2));
+    }
   }
   return { data: info2 };
 }
@@ -9325,17 +9460,19 @@ async function runInvoke(args) {
     }
     return { data: payload };
   }
-  const errMsg = payload.error ?? `Request failed (${res.status})`;
-  const lines = [`${integration}/${endpoint} (${res.status}, ${elapsed}ms): ${errMsg}`];
-  if (Array.isArray(payload.issues)) {
-    for (const issue of payload.issues) {
+  const norm = normalizeApiError(res.status, payload);
+  const lines = [`${integration}/${endpoint} (${res.status}, ${elapsed}ms): ${norm.error}`];
+  if (norm.issues) {
+    for (const issue of norm.issues) {
       const path = issue.path?.length ? issue.path.join(".") : "(root)";
       lines.push(`  - ${path}: ${issue.message}`);
     }
   }
-  const code = typeof payload.code === "string" ? payload.code : "integration_call_failed";
+  const code = norm.code ?? "integration_call_failed";
   const rest = { ...payload };
   delete rest.error;
+  delete rest.message;
+  delete rest.code;
   throw new Refusal(lines.join("\n"), code, {
     ...res.status === 401 ? { action: cliAction("deepspace", "auth", "login") } : {},
     extra: rest
@@ -10106,10 +10243,29 @@ var secrets_default = defineCommand10({
 });
 
 // src/cli/commands/init.ts
+import { existsSync as existsSync21 } from "fs";
+import { join as join20 } from "path";
+var DEPLOY_URL12 = process.env.DEEPSPACE_DEPLOY_URL ?? PLATFORM_URLS.deploy;
+function commitScaffoldIfUnborn(appDir, token) {
+  try {
+    if (!existsSync21(join20(appDir, ".git"))) return false;
+    if (runGit(appDir, ["rev-parse", "--verify", "HEAD"], { allowFail: true }).status === 0) {
+      return false;
+    }
+    ensureGitIdentity(appDir, token);
+    if (runGit(appDir, ["add", "-A"], { allowFail: true }).status !== 0) return false;
+    const commit = runGit(appDir, ["commit", "-m", "Initial DeepSpace scaffold", "--no-verify"], {
+      allowFail: true
+    });
+    return commit.status === 0;
+  } catch {
+    return false;
+  }
+}
 var init_default = defineDeepspaceCommand({
   meta: {
     name: "init",
-    description: "Mint this app\u2019s immutable DEEPSPACE_APP_ID into wrangler.toml"
+    description: "Register this app: mint its immutable DEEPSPACE_APP_ID into wrangler.toml"
   },
   args: {
     "new-id": {
@@ -10143,23 +10299,31 @@ var init_default = defineDeepspaceCommand({
         data: { status: "already_initialized", appId: existing, appDir, env: envName ?? null }
       };
     }
-    const appId = mintAppId();
+    const token = await ensureToken();
+    const { appId } = await apiFetch(DEPLOY_URL12, token, "/api/apps/mint", {
+      method: "POST"
+    });
     writeAppId(appDir, appId, { wranglerEnv: envName, force: Boolean(args["new-id"]) });
+    if (!envName) stampAppIdInSources(appDir, appId, existing);
+    const committedScaffold = commitScaffoldIfUnborn(appDir, token);
     if (!args.json) {
       if (existing) {
         console.log(`Forked: ${existing} \u2192 ${appId}${envName ? ` (env: ${envName})` : ""}`);
-        console.log("The next deploy registers this as a NEW app; the original is untouched.");
+        console.log("Registered as a NEW app under your account; the original is untouched.");
       } else {
-        console.log(`Minted ${appId}${envName ? ` (env: ${envName})` : ""} \u2014 commit wrangler.toml.`);
-        console.log("The first deploy registers it and claims the `name` subdomain.");
+        console.log(
+          `Registered ${appId}${envName ? ` (env: ${envName})` : ""} to your account` + (committedScaffold ? " \u2014 initial scaffold commit created." : " \u2014 commit wrangler.toml.")
+        );
+        console.log("The first deploy claims the `name` subdomain.");
       }
       console.log(`App dir: ${appDir}`);
     }
     return {
       data: {
-        status: existing ? "forked" : "minted",
+        status: existing ? "forked" : "registered",
         appId,
         ...existing ? { previousAppId: existing } : {},
+        committedScaffold,
         appDir,
         env: envName ?? null
       }
@@ -10170,7 +10334,7 @@ var init_default = defineDeepspaceCommand({
 // src/cli/commands/status.ts
 import { defineCommand as defineCommand11 } from "citty";
 import * as p17 from "@clack/prompts";
-import { existsSync as existsSync21, readFileSync as readFileSync24 } from "fs";
+import { existsSync as existsSync22, readFileSync as readFileSync24 } from "fs";
 function timeAgo(iso) {
   const ms = Date.now() - Date.parse(iso);
   if (!Number.isFinite(ms) || ms < 0) return iso;
@@ -10255,7 +10419,7 @@ var status_default = defineCommand11({
       json.services = urls;
       if (urlOverrides.length > 0) json.urlOverrides = urlOverrides;
     }
-    facts.loggedIn = existsSync21(SESSION_PATH);
+    facts.loggedIn = existsSync22(SESSION_PATH);
     let userId = null;
     if (!facts.loggedIn) {
       lines.push(["Session", "not logged in"]);
@@ -10944,18 +11108,18 @@ var pull_default = defineDeepspaceCommand({
 
 // src/cli/commands/clone.ts
 import * as p20 from "@clack/prompts";
-import { existsSync as existsSync22, readdirSync as readdirSync6, rmSync as rmSync5 } from "fs";
-import { resolve as resolve17, basename as basename5, join as join20 } from "path";
+import { existsSync as existsSync23, readdirSync as readdirSync6, rmSync as rmSync5 } from "fs";
+import { resolve as resolve17, basename as basename5, join as join21 } from "path";
 function cleanFailedCloneDir(dir) {
   let entries;
   try {
     entries = readdirSync6(dir);
   } catch {
-    return existsSync22(dir) ? ["<unreadable>"] : [];
+    return existsSync23(dir) ? ["<unreadable>"] : [];
   }
   if (entries.length === 1 && entries[0] === ".git") {
     try {
-      rmSync5(join20(dir, ".git"), { recursive: true, force: true });
+      rmSync5(join21(dir, ".git"), { recursive: true, force: true });
       return [];
     } catch {
       return entries;
@@ -10964,7 +11128,7 @@ function cleanFailedCloneDir(dir) {
   return entries;
 }
 function validateCloneTarget(dir) {
-  if (!existsSync22(dir)) return false;
+  if (!existsSync23(dir)) return false;
   let entries;
   try {
     entries = readdirSync6(dir);
@@ -11087,7 +11251,7 @@ async function actorLabels(token, appId) {
 }
 
 // src/cli/commands/releases.ts
-var DEPLOY_URL12 = process.env.DEEPSPACE_DEPLOY_URL ?? PLATFORM_URLS.deploy;
+var DEPLOY_URL13 = process.env.DEEPSPACE_DEPLOY_URL ?? PLATFORM_URLS.deploy;
 var releases_default = defineDeepspaceCommand({
   meta: {
     name: "releases",
@@ -11122,8 +11286,8 @@ var releases_default = defineDeepspaceCommand({
     const spinner2 = args.json ? null : createSpinner();
     spinner2?.start("Loading release history\u2026");
     const token = await ensureToken();
-    const appId = await resolveAppTarget(DEPLOY_URL12, token, appArg, { wranglerEnv: envArg });
-    const { releases } = await repoApi(DEPLOY_URL12, token, appId).listReleases(limit);
+    const appId = await resolveAppTarget(DEPLOY_URL13, token, appArg, { wranglerEnv: envArg });
+    const { releases } = await repoApi(DEPLOY_URL13, token, appId).listReleases(limit);
     spinner2?.stop(`Loaded ${releases.length} ${releases.length === 1 ? "release" : "releases"}.`);
     if (!args.json) {
       if (releases.length === 0) {
@@ -11156,7 +11320,7 @@ Retry in a moment, or re-run with --allow-do-deletion to accept the risk.`,
     "do_guard_unavailable"
   );
 }
-var DEPLOY_URL13 = process.env.DEEPSPACE_DEPLOY_URL ?? PLATFORM_URLS.deploy;
+var DEPLOY_URL14 = process.env.DEEPSPACE_DEPLOY_URL ?? PLATFORM_URLS.deploy;
 function pickPreviousRelease(releases) {
   if (releases.length === 0) {
     return { error: "No releases recorded yet \u2014 nothing to roll back to.", code: "no_releases" };
@@ -11218,8 +11382,8 @@ var rollback_default = defineDeepspaceCommand({
     const spinner2 = args.json ? null : createSpinner();
     spinner2?.start("Preparing rollback\u2026");
     const token = await ensureToken();
-    const appId = await resolveAppTarget(DEPLOY_URL13, token, appArg, { wranglerEnv: envArg });
-    const api4 = repoApi(DEPLOY_URL13, token, appId);
+    const appId = await resolveAppTarget(DEPLOY_URL14, token, appArg, { wranglerEnv: envArg });
+    const api4 = repoApi(DEPLOY_URL14, token, appId);
     let releaseId = args.release ? String(args.release).trim() : "";
     if (!releaseId) {
       const { releases } = await api4.listReleases(2);
@@ -11230,7 +11394,7 @@ var rollback_default = defineDeepspaceCommand({
     spinner2?.message(`Rolling back to ${releaseId}\u2026`);
     let result;
     try {
-      result = await apiFetch(DEPLOY_URL13, token, `/api/deploy/${appId}/rollback`, {
+      result = await apiFetch(DEPLOY_URL14, token, `/api/deploy/${appId}/rollback`, {
         method: "POST",
         body: JSON.stringify({
           releaseId,
@@ -11441,7 +11605,7 @@ function printOverlaps(overlaps, json) {
 // src/cli/commands/workspace/local.ts
 import * as p24 from "@clack/prompts";
 import {
-  existsSync as existsSync23,
+  existsSync as existsSync24,
   mkdirSync as mkdirSync7,
   readFileSync as readFileSync25,
   realpathSync as realpathSync6,
@@ -11449,7 +11613,7 @@ import {
   statSync as statSync3,
   writeFileSync as writeFileSync7
 } from "fs";
-import { dirname as dirname11, isAbsolute as isAbsolute5, join as join21, relative as relative2, sep as sep2 } from "path";
+import { dirname as dirname11, isAbsolute as isAbsolute5, join as join22, relative as relative2, sep as sep2 } from "path";
 var WORKSPACE_MARKER = "deepspace-workspace.json";
 function excludeWorktreeDir(appDir, dir) {
   try {
@@ -11470,7 +11634,7 @@ function worktreeMarkerPath(worktreeRoot) {
     const result = runGit(worktreeRoot, ["rev-parse", "--absolute-git-dir"], { allowFail: true });
     if (result.status !== 0) return null;
     const gitDir = result.stdout.toString("utf-8").trim();
-    return isAbsolute5(gitDir) ? join21(gitDir, WORKSPACE_MARKER) : null;
+    return isAbsolute5(gitDir) ? join22(gitDir, WORKSPACE_MARKER) : null;
   } catch {
     return null;
   }
@@ -11515,11 +11679,11 @@ function isManagedWorkspaceWorktree(worktreeRoot, workspaceId) {
 function defaultWorkspaceRoot(appDir, workspaceId) {
   const primary = listWorktrees(appDir)[0];
   if (!primary) throw new Error("Git did not report a primary worktree");
-  return join21(primary.path, ".deepspace", "ws", workspaceId.slice(3).toLowerCase());
+  return join22(primary.path, ".deepspace", "ws", workspaceId.slice(3).toLowerCase());
 }
 function appDirInWorktree(appDir, worktreeRoot) {
   const appRelative = relative2(realpathSync6(repoToplevel(appDir)), realpathSync6(appDir));
-  return appRelative ? join21(worktreeRoot, appRelative) : worktreeRoot;
+  return appRelative ? join22(worktreeRoot, appRelative) : worktreeRoot;
 }
 function primaryAppDir(appDir) {
   const primary = listWorktrees(appDir)[0];
@@ -11554,7 +11718,7 @@ function rematerializeWorkspaceWorktree(appDir, worktreeRoot, branch, workspaceI
 function inOwnLinkedWorktree(appDir, id) {
   if (workspaceIdFromBranch(currentBranch(appDir)) !== id) return false;
   try {
-    return statSync3(join21(repoToplevel(appDir), ".git")).isFile();
+    return statSync3(join22(repoToplevel(appDir), ".git")).isFile();
   } catch {
     return false;
   }
@@ -11679,7 +11843,7 @@ function cleanupWorkspaceLocal(appDir, id, trunkBranch, options = {}) {
         }
         runGit(mainDir, ["worktree", "prune"], { allowFail: true });
         out.worktreeDir = null;
-        const leftover = existsSync23(linked.path);
+        const leftover = existsSync24(linked.path);
         if (leftover) out.leftoverDir = linked.path;
         else out.worktreeRemoved = linked.path;
         deleteWsBranch(mainDir, branch, expectedBranchOid, out);
@@ -11977,7 +12141,7 @@ var newWorkspaceCommand = defineDeepspaceCommand({
 
 // src/cli/commands/workspace/attach.ts
 import * as p26 from "@clack/prompts";
-import { existsSync as existsSync24, readdirSync as readdirSync7, realpathSync as realpathSync7, rmSync as rmSync6 } from "fs";
+import { existsSync as existsSync25, readdirSync as readdirSync7, realpathSync as realpathSync7, rmSync as rmSync6 } from "fs";
 import { isAbsolute as isAbsolute7, resolve as resolve19 } from "path";
 function samePath(a, b) {
   const real = (p35) => {
@@ -11997,7 +12161,7 @@ function finishedWorkspaceMessage(id, view) {
   return `Workspace ${id} is ${workspace.status} \u2014 its ref is retained briefly (fetch ${workspace.ref} to inspect), but attach only works on active workspaces.`;
 }
 function cleanFailedFreshAttachDir(dir) {
-  if (!existsSync24(dir)) return [];
+  if (!existsSync25(dir)) return [];
   let entries;
   try {
     entries = readdirSync7(dir);
@@ -12079,7 +12243,7 @@ var attachWorkspaceCommand = defineDeepspaceCommand({
       const localTip = resolveCommit(appDir, `refs/heads/${branch}`);
       if (localTip) {
         let existing = resolveWorkspaceWorktree(listWorktrees(appDir), id);
-        if (existing && !existsSync24(existing)) {
+        if (existing && !existsSync25(existing)) {
           runGit(appDir, ["worktree", "prune"], { allowFail: true });
           existing = null;
         }
@@ -12197,7 +12361,7 @@ var attachWorkspaceCommand = defineDeepspaceCommand({
       process.cwd(),
       (typeof args.dir === "string" ? args.dir.trim() : "") || `ws-${id.slice(3).toLowerCase()}`
     );
-    if (existsSync24(dir)) {
+    if (existsSync25(dir)) {
       spinner2?.stop("Target exists.");
       throw new Refusal(`${dir} already exists \u2014 pass a different directory.`, "dir_exists");
     }
@@ -12535,12 +12699,12 @@ import * as p30 from "@clack/prompts";
 // src/cli/lib/validation.ts
 import { sync as spawnSync7 } from "cross-spawn";
 import { readFileSync as readFileSync26 } from "fs";
-import { join as join22 } from "path";
+import { join as join23 } from "path";
 var MAX_SUMMARY_CHARS = 4e3;
 var MAX_OUTPUT_BUFFER = 64 * 1024 * 1024;
 function configuredCommand(appDir) {
   try {
-    const pkg2 = JSON.parse(readFileSync26(join22(appDir, "package.json"), "utf-8"));
+    const pkg2 = JSON.parse(readFileSync26(join23(appDir, "package.json"), "utf-8"));
     if (pkg2.scripts?.validate) return `${detectPackageManager(appDir)} run --silent validate`;
   } catch {
   }
@@ -12581,7 +12745,7 @@ function conflictMarkerFiles(diffCheckOutput) {
 function pullAfterLandAction(primaryDir, intoBranch, landedOid) {
   if (currentBranch(primaryDir) !== intoBranch) return null;
   if (resolveCommit(primaryDir, "HEAD") === landedOid) return null;
-  return { cwd: primaryDir, argv: ["deepspace", "pull"] };
+  return executableAction({ cwd: primaryDir, argv: ["deepspace", "pull"] });
 }
 function landResumeArgv(args) {
   const argv = ["deepspace", "workspace", "land"];
@@ -12862,6 +13026,7 @@ var landWorkspaceCommand = defineDeepspaceCommand({
     }
     spinner2?.stop(`Landed ${id} into ${intoBranch} at ${landedOid.slice(0, 10)}.`);
     const primaryDir = primaryAppDir(appDir);
+    const action = pullAfterLandAction(primaryDir, intoBranch, landedOid);
     const cleanup = keepWorktree ? null : cleanupWorkspaceLocal(appDir, id, intoBranch, { expectedBranchOid: landedOid });
     const inOwnWorktree = !cleanup && inOwnLinkedWorktree(appDir, id);
     const retainedWorktree = cleanup?.worktreeRetained ?? (keepWorktree || inOwnWorktree ? appDir : null);
@@ -12895,7 +13060,6 @@ var landWorkspaceCommand = defineDeepspaceCommand({
         { actionRequired: true, action: action2, extra: data }
       );
     }
-    const action = pullAfterLandAction(primaryDir, intoBranch, landedOid);
     return { data, ...action ? { action } : {} };
   }
 });
@@ -13616,13 +13780,13 @@ function sameRefs(left, right) {
 
 // src/cli/commands/update.ts
 import * as p34 from "@clack/prompts";
-import { existsSync as existsSync25, readFileSync as readFileSync27, writeFileSync as writeFileSync8 } from "fs";
-import { join as join23, resolve as resolve20 } from "path";
+import { existsSync as existsSync26, readFileSync as readFileSync27, writeFileSync as writeFileSync8 } from "fs";
+import { join as join24, resolve as resolve20 } from "path";
 
 // package.json
 var package_default = {
   name: "deepspace",
-  version: "0.20.0",
+  version: "0.22.0",
   engines: {
     node: ">=22.15.0 <23 || >=24 <25 || >=26 <27"
   },
@@ -13655,6 +13819,10 @@ var package_default = {
       types: "./dist/testing.d.ts",
       import: "./dist/testing.js"
     },
+    "./testing/mcp": {
+      types: "./dist/testing-mcp.d.ts",
+      import: "./dist/testing-mcp.js"
+    },
     "./documentation": {
       types: "./dist/documentation.d.ts",
       import: "./dist/documentation.js"
@@ -13789,18 +13957,18 @@ function gapIsTooWide(from, to) {
   return from.major === 0 && from.minor < OLDEST_SUPPORTED_MINOR;
 }
 function readAppSdkVersion(appDir) {
-  const installed = join23(appDir, "node_modules", "deepspace", "package.json");
-  if (existsSync25(installed)) {
+  const installed = join24(appDir, "node_modules", "deepspace", "package.json");
+  if (existsSync26(installed)) {
     const parsed2 = JSON.parse(readFileSync27(installed, "utf8"));
     if (typeof parsed2.version === "string") return parsed2.version;
   }
-  const manifest = join23(appDir, "package.json");
-  if (!existsSync25(manifest)) return null;
+  const manifest = join24(appDir, "package.json");
+  if (!existsSync26(manifest)) return null;
   const parsed = JSON.parse(readFileSync27(manifest, "utf8"));
   return parsed.dependencies?.deepspace ?? null;
 }
 function pinSdkVersion(appDir, version) {
-  const path = join23(appDir, "package.json");
+  const path = join24(appDir, "package.json");
   const source = readFileSync27(path, "utf8");
   const manifest = JSON.parse(source);
   const dependencies = manifest.dependencies;
@@ -13827,16 +13995,16 @@ function buildPreviewSecretsUpgradeInstruction(appDir) {
     "vite.config.mts",
     "vite.config.js",
     "vite.config.mjs"
-  ].find((candidate) => existsSync25(join23(appDir, candidate)));
+  ].find((candidate) => existsSync26(join24(appDir, candidate)));
   if (!configName) return null;
-  const source = readFileSync27(join23(appDir, configName), "utf8");
+  const source = readFileSync27(join24(appDir, configName), "utf8");
   if (source.includes("deepspace-remove-build-preview-secrets")) return null;
   return `${configName}: add the build-preview secret cleanup from ${BUILD_PREVIEW_SECRETS_GUIDE}; app update left this app-owned file unchanged.`;
 }
 function usersSchemaVisibilityUpgradeInstruction(appDir) {
   const schemaName = "src/schemas/users-schema.ts";
-  const path = join23(appDir, schemaName);
-  if (!existsSync25(path)) return null;
+  const path = join24(appDir, schemaName);
+  if (!existsSync26(path)) return null;
   const source = readFileSync27(path, "utf8");
   if (!/\bmember\s*:\s*\{[^}]*\bread\s*:\s*true\b/s.test(source)) return null;
   return `${schemaName}: review the member user-row visibility change at ${USERS_SCHEMA_VISIBILITY_GUIDE}; app update left this app-owned schema unchanged.`;
@@ -13988,8 +14156,8 @@ var update_default = defineDeepspaceCommand({
 
 // src/cli/cli.ts
 var __dirname = dirname12(fileURLToPath3(import.meta.url));
-var pkg = JSON.parse(readFileSync28(join24(__dirname, "..", "package.json"), "utf-8"));
-if (process.platform === "linux" && !process.env.SSL_CERT_FILE && existsSync26("/etc/ssl/certs/ca-certificates.crt")) {
+var pkg = JSON.parse(readFileSync28(join25(__dirname, "..", "package.json"), "utf-8"));
+if (process.platform === "linux" && !process.env.SSL_CERT_FILE && existsSync27("/etc/ssl/certs/ca-certificates.crt")) {
   process.env.SSL_CERT_FILE = "/etc/ssl/certs/ca-certificates.crt";
 }
 var create2 = defineCommand14({