deepspace 0.8.1 → 0.9.0

package/dist/cli.js

@@ -221,6 +221,62 @@ function wrapCommandErrors(cmd) {
   return cmd;
 }
 
+// src/cli/lib/command-suggestions.ts
+function editDistance(a, b) {
+  const left = a.toLowerCase();
+  const right = b.toLowerCase();
+  const dp = Array.from({ length: left.length + 1 }, (_, i) => [
+    i,
+    ...new Array(right.length).fill(0)
+  ]);
+  for (let j = 1; j <= right.length; j++) dp[0][j] = j;
+  for (let i = 1; i <= left.length; i++) {
+    for (let j = 1; j <= right.length; j++) {
+      dp[i][j] = Math.min(
+        dp[i - 1][j] + 1,
+        dp[i][j - 1] + 1,
+        dp[i - 1][j - 1] + (left[i - 1] === right[j - 1] ? 0 : 1)
+      );
+    }
+  }
+  return dp[left.length][right.length];
+}
+function commandPaths(table, prefix = []) {
+  const paths = [];
+  for (const [name, command] of Object.entries(table)) {
+    const path = [...prefix, name];
+    paths.push(path);
+    if (command.subCommands) paths.push(...commandPaths(command.subCommands, path));
+  }
+  return paths;
+}
+function closestCommandPath(input, table) {
+  const ranked = commandPaths(table).map((path) => ({ path, distance: editDistance(input, path.at(-1) ?? "") })).sort(
+    (a, b) => a.distance - b.distance || a.path.length - b.path.length || a.path.join(" ").localeCompare(b.path.join(" "))
+  );
+  return ranked[0]?.path ?? null;
+}
+function findUnknownCommand(argv, rootCommands) {
+  let table = rootCommands;
+  const accepted = [];
+  for (const token of argv) {
+    if (!table || token.startsWith("-")) return null;
+    const command = table[token];
+    if (!command) {
+      const relativeSuggestion = closestCommandPath(token, table);
+      if (!relativeSuggestion) return null;
+      return {
+        attemptedPath: ["deepspace", ...accepted, token],
+        helpPath: ["deepspace", ...accepted],
+        suggestion: ["deepspace", ...accepted, ...relativeSuggestion]
+      };
+    }
+    accepted.push(token);
+    table = command.subCommands;
+  }
+  return null;
+}
+
 // src/cli/env.ts
 function resolveDeepSpaceEnvironment(value) {
   if (value === void 0 || value === "production") return "production";
@@ -653,7 +709,7 @@ async function provisionProfile(jwt) {
   }
 }
 function sleep(ms) {
-  return new Promise((resolve18) => setTimeout(resolve18, ms));
+  return new Promise((resolve19) => setTimeout(resolve19, ms));
 }
 function base64url(bytes) {
   return bytes.toString("base64").replace(/\+/g, "-").replace(/\//g, "_").replace(/=+$/, "");
@@ -730,8 +786,9 @@ import { join as join3, resolve } from "path";
 import { parse as parseToml } from "smol-toml";
 
 // src/server/utils/registry-client.ts
-var APP_ID_RE = /^(app_[0-9A-HJKMNP-TV-Z]{26}|[a-z0-9][a-z0-9_-]{0,63})$/;
-var STRICT_APP_ID_RE = /^app_[0-9A-HJKMNP-TV-Z]{26}$/;
+var APP_ID_RE = /^app_[0-9A-HJKMNP-TV-Z]{26}$/;
+var STRICT_APP_ID_RE = APP_ID_RE;
+var LEGACY_APP_ID_RE = /^[a-z0-9][a-z0-9_-]{0,63}$/;
 
 // src/cli/lib/app-identity.ts
 var CROCKFORD = "0123456789ABCDEFGHJKMNPQRSTVWXYZ";
@@ -760,44 +817,59 @@ function mintUlid(now = Date.now()) {
 function mintAppId(now = Date.now()) {
   return `app_${mintUlid(now)}`;
 }
-async function resolveExistingAppId(deployUrl, token, appName) {
-  const headers = { Authorization: `Bearer ${token}` };
-  try {
-    const res = await fetch(`${deployUrl}/api/apps`, { headers });
-    if (res.ok) {
-      const body = await res.json();
-      const match = body.apps?.find((a) => a.name === appName);
-      if (match?.appId) return { kind: "adopted", appId: match.appId, owned: true };
-    }
-  } catch {
-  }
-  try {
-    const res = await fetch(
-      `${deployUrl}/api/apps/${encodeURIComponent(appName)}/analytics?period=1h`,
-      { headers }
-    );
-    if (res.ok) return { kind: "adopted", appId: appName, owned: false };
-    if (res.status === 403) return { kind: "taken" };
-  } catch {
-  }
-  return { kind: "none" };
-}
-function readAppId(cwd = process.cwd(), wranglerEnv) {
+function readWranglerConfig(cwd) {
   const wranglerPath = join3(resolve(cwd), "wrangler.toml");
   if (!existsSync3(wranglerPath)) return null;
-  let cfg;
   try {
-    cfg = parseToml(readFileSync4(wranglerPath, "utf-8"));
+    return parseToml(readFileSync4(wranglerPath, "utf-8"));
   } catch (err) {
     throw new InputError(
       `Could not parse ${wranglerPath}: ${err instanceof Error ? err.message : String(err)}`,
       "invalid_config"
     );
   }
+}
+function readAppId(cwd = process.cwd(), wranglerEnv) {
+  const cfg = readWranglerConfig(cwd);
+  if (!cfg) return null;
   const vars = wranglerEnv ? cfg.env?.[wranglerEnv]?.vars : cfg.vars;
   const id = vars?.DEEPSPACE_APP_ID;
   return typeof id === "string" && APP_ID_RE.test(id) ? id : null;
 }
+function readLegacyAppId(cwd = process.cwd(), wranglerEnv) {
+  const cfg = readWranglerConfig(cwd);
+  if (!cfg) return null;
+  const slot = wranglerEnv ? cfg.env?.[wranglerEnv] : cfg;
+  if (!slot) return null;
+  const declaredId = slot.vars?.DEEPSPACE_APP_ID;
+  if (declaredId !== void 0) {
+    if (typeof declaredId === "string" && LEGACY_APP_ID_RE.test(declaredId)) return declaredId;
+    throw new InputError(
+      "DEEPSPACE_APP_ID is present but invalid; correct it before migrating.",
+      "invalid_app_id"
+    );
+  }
+  const appName = typeof slot.vars?.APP_NAME === "string" ? slot.vars.APP_NAME : null;
+  const workerName = typeof slot.name === "string" ? slot.name : null;
+  if (!appName) return null;
+  if (!workerName) {
+    throw new InputError(
+      "Legacy migration requires both Worker name and APP_NAME to be present and identical.",
+      "ambiguous_legacy_app_id"
+    );
+  }
+  if (appName !== workerName) {
+    throw new InputError(
+      `Legacy APP_NAME "${appName}" does not match Worker name "${workerName}"; migration cannot choose safely.`,
+      "ambiguous_legacy_app_id"
+    );
+  }
+  const legacyAppId = appName;
+  if (!legacyAppId || !LEGACY_APP_ID_RE.test(legacyAppId) || APP_ID_RE.test(legacyAppId)) {
+    return null;
+  }
+  return legacyAppId;
+}
 function writeAppId(cwd, appId, opts = {}) {
   const wranglerPath = join3(resolve(cwd), "wrangler.toml");
   if (!existsSync3(wranglerPath)) {
@@ -836,7 +908,7 @@ ${line}
 }
 
 // src/cli/commands/dev.ts
-import { resolve as resolve6, basename as basename2, join as join12 } from "path";
+import { resolve as resolve7, basename as basename2, join as join12 } from "path";
 import spawn from "cross-spawn";
 
 // src/cli/lib/app-context.ts
@@ -1230,7 +1302,7 @@ function upsertWorktreeLaunchConfig(mainRepoRoot, worktreeName, appDir, opts) {
     let port = opts.port;
     if (opts.probePort) {
       const taken = new Set(
-        config.configurations.map((c) => Number(c?.port)).filter((p34) => Number.isInteger(p34) && p34 > 0)
+        config.configurations.map((c) => Number(c?.port)).filter((p35) => Number.isInteger(p35) && p35 > 0)
       );
       for (let i = 0; i < WORKTREE_PORT_RANGE && taken.has(port); i++) {
         port = WORKTREE_PORT_MIN + (port - WORKTREE_PORT_MIN + 1) % WORKTREE_PORT_RANGE;
@@ -1341,6 +1413,8 @@ var RESERVED_BINDING_NAMES = /* @__PURE__ */ new Set([
   "ASSETS",
   "PLATFORM_WORKER",
   "API_WORKER",
+  "DEEPSPACE_APP_ID",
+  "DEEPSPACE_RESOURCE_ID",
   "APP_NAME",
   "OWNER_USER_ID",
   "AUTH_JWT_PUBLIC_KEY",
@@ -1358,7 +1432,9 @@ function validateBindingManifest(manifest) {
   const seenNames = /* @__PURE__ */ new Set();
   for (const entry of manifest) {
     if (!entry || typeof entry !== "object") {
-      errors.push({ reason: `Entry must be an object (got ${entry === null ? "null" : typeof entry})` });
+      errors.push({
+        reason: `Entry must be an object (got ${entry === null ? "null" : typeof entry})`
+      });
       continue;
     }
     const e = entry;
@@ -1407,7 +1483,8 @@ function requiredFieldError(b) {
     case "r2_bucket":
       return b.bucket_name ? null : `r2_bucket binding "${b.name}" missing bucket_name (or "auto")`;
     case "kv_namespace": {
-      if (!b.namespace_id) return `kv_namespace binding "${b.name}" missing namespace_id (or "auto")`;
+      if (!b.namespace_id)
+        return `kv_namespace binding "${b.name}" missing namespace_id (or "auto")`;
       if (b.namespace_id === AUTO_PROVISION_SENTINEL && !b.title) {
         return `kv_namespace binding "${b.name}" with namespace_id="auto" requires "title"`;
       }
@@ -1909,7 +1986,7 @@ function prepareWranglerEnvConfig(appDir, envName, opts = {}) {
   if (!opts.sharedDevVarsCache) return { wranglerEnv: envName, cleanup() {
   } };
   warnIfLegacyEnvDevVarsExists(appDir, envName, opts.warn);
-  const config = readWranglerConfig(appDir);
+  const config = readWranglerConfig2(appDir);
   const resolved = resolveAppNameForEnv(config, envName);
   if (!resolved.ok) throw new Error(resolved.reason);
   const flattened = flattenWranglerEnvConfig(config, envName);
@@ -1973,7 +2050,7 @@ var WranglerConfigError = class extends Error {
     this.name = "WranglerConfigError";
   }
 };
-function readWranglerConfig(appDir) {
+function readWranglerConfig2(appDir) {
   const path = join7(appDir, "wrangler.toml");
   const raw = readFileSync8(path, "utf-8");
   try {
@@ -2170,8 +2247,8 @@ ${custom}
 }
 
 // src/cli/lib/install-status.ts
-import { existsSync as existsSync9, readFileSync as readFileSync11 } from "fs";
-import { dirname as dirname4, join as join9 } from "path";
+import { existsSync as existsSync9, readFileSync as readFileSync11, realpathSync as realpathSync2 } from "fs";
+import { dirname as dirname4, join as join9, resolve as resolve5 } from "path";
 
 // src/cli/lib/package-manager.ts
 import { existsSync as existsSync8, readFileSync as readFileSync10 } from "fs";
@@ -2217,18 +2294,18 @@ function ensureInstallReady(appDir) {
   const logPath = join9(sentinelDir, "install.log");
   if (existsSync9(errPath)) {
     const detail = readFileSync11(errPath, "utf-8").trimEnd();
-    const log28 = existsSync9(logPath) ? ` Full log: ${logPath}.` : "";
+    const log29 = existsSync9(logPath) ? ` Full log: ${logPath}.` : "";
     throw new Refusal(
-      `Dependency install failed: ${detail}.${log28} Run \`npm install\` (or \`bun install\`) manually, then retry.`,
+      `Dependency install failed: ${detail}.${log29} Run \`npm install\` (or \`bun install\`) manually, then retry.`,
       "install_failed",
       { action: { cwd: appDir, argv: [detectPackageManager(appDir), "install"] } }
     );
   }
   if (existsSync9(startedPath) && !existsSync9(donePath)) {
     if (!installWorkerAlive(sentinelDir)) {
-      const log28 = existsSync9(logPath) ? ` See what happened: ${logPath}.` : "";
+      const log29 = existsSync9(logPath) ? ` See what happened: ${logPath}.` : "";
       throw new Refusal(
-        `The dependency install is no longer running and never finished.${log28} Run \`npm install\` (or \`bun install\`) manually, then retry.`,
+        `The dependency install is no longer running and never finished.${log29} Run \`npm install\` (or \`bun install\`) manually, then retry.`,
         "install_failed",
         { action: { cwd: appDir, argv: [detectPackageManager(appDir), "install"] } }
       );
@@ -2248,14 +2325,27 @@ function ensureInstallReady(appDir) {
   );
 }
 function resolvesDeepspace(fromDir) {
-  let dir = fromDir;
+  let dir = canonicalPath2(fromDir);
+  let checkoutRoot = null;
+  try {
+    checkoutRoot = canonicalPath2(repoToplevel(dir));
+  } catch {
+  }
   for (; ; ) {
     if (existsSync9(join9(dir, "node_modules", "deepspace", "package.json"))) return true;
+    if (dir === checkoutRoot) return false;
     const parent = dirname4(dir);
     if (parent === dir) return false;
     dir = parent;
   }
 }
+function canonicalPath2(path) {
+  try {
+    return realpathSync2(path);
+  } catch {
+    return resolve5(path);
+  }
+}
 function installWorkerAlive(sentinelDir) {
   const pidPath = join9(sentinelDir, "install.pid");
   if (!existsSync9(pidPath)) return false;
@@ -2273,7 +2363,7 @@ function installWorkerAlive(sentinelDir) {
 import { execFileSync } from "child_process";
 import { existsSync as existsSync10 } from "fs";
 import * as nodeModule from "module";
-import { resolve as resolve5 } from "path";
+import { resolve as resolve6 } from "path";
 function preflightNodeVersion(command, hasRegisterHooks = typeof nodeModule.registerHooks === "function") {
   if (hasRegisterHooks) return;
   throw new Refusal(
@@ -2284,7 +2374,7 @@ function preflightNodeVersion(command, hasRegisterHooks = typeof nodeModule.regi
 var DLL_NOT_FOUND = -1073741515;
 function preflightWindowsWorkerd(appDir) {
   if (process.platform !== "win32") return;
-  const workerdExe = resolve5(
+  const workerdExe = resolve6(
     appDir,
     "node_modules",
     "@cloudflare",
@@ -2364,7 +2454,7 @@ function lintSchema(schema) {
     const offendingRoles = Object.entries(schema.permissions).filter(([, perms]) => perms.read === true).map(([role]) => role);
     if (offendingRoles.length > 0) {
       const usesAware = Object.values(schema.permissions).some(
-        (p34) => typeof p34.read === "string" && VISIBILITY_AWARE.includes(p34.read)
+        (p35) => typeof p35.read === "string" && VISIBILITY_AWARE.includes(p35.read)
       );
       if (!usesAware) {
         warnings.push(
@@ -2445,10 +2535,10 @@ function formatSchemaLintFindings(findings) {
 import { createServer } from "net";
 var DEFAULT_PORT = 5173;
 function checkPortAvailable(port, host = "0.0.0.0") {
-  return new Promise((resolve18) => {
+  return new Promise((resolve19) => {
     const srv = createServer();
-    srv.once("error", () => resolve18(false));
-    srv.once("listening", () => srv.close(() => resolve18(true)));
+    srv.once("error", () => resolve19(false));
+    srv.once("listening", () => srv.close(() => resolve19(true)));
     srv.listen(port, host);
   });
 }
@@ -2503,7 +2593,7 @@ var dev_default = defineDeepspaceCommand({
     };
     preflightNodeVersion("dev start");
     const wranglerEnv = typeof args.env === "string" && args.env.trim() ? args.env.trim() : void 0;
-    const start = resolve6(args.dir ?? ".");
+    const start = resolve7(args.dir ?? ".");
     const appDir = findAppDir(start);
     if (!appDir) {
       throw new Refusal(noAppDirMessage(start, findChildApps(start)), "no_app_dir");
@@ -2914,7 +3004,7 @@ function isAlive(pid) {
 }
 
 // src/cli/commands/test.ts
-import { resolve as resolve7 } from "path";
+import { resolve as resolve8 } from "path";
 import { sync as spawnSync4 } from "cross-spawn";
 
 // src/cli/lib/playwright.ts
@@ -2974,7 +3064,7 @@ 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 start = resolve7(".");
+    const start = resolve8(".");
     const appDir = findAppDir(start);
     if (!appDir) {
       throw new Refusal(noAppDirMessage(start, findChildApps(start)), "no_app_dir");
@@ -3113,7 +3203,7 @@ function runVitest(appDir) {
 
 // src/cli/commands/screenshot.ts
 import { sync as spawnSync5 } from "cross-spawn";
-import { resolve as resolve8 } from "path";
+import { resolve as resolve9 } from "path";
 var screenshot_default = defineDeepspaceCommand({
   meta: {
     name: "screenshot",
@@ -3142,7 +3232,7 @@ var screenshot_default = defineDeepspaceCommand({
     }
   },
   async run({ args }) {
-    const appDir = resolve8(".");
+    const appDir = resolve9(".");
     ensurePlaywright(appDir);
     const url = String(args.url);
     const output = String(args.output);
@@ -3499,13 +3589,13 @@ var test_accounts_default = defineCommand2({
 // src/cli/commands/deploy.ts
 import * as p12 from "@clack/prompts";
 import { defineCommand as defineCommand3 } from "citty";
-import { resolve as resolve11 } from "path";
+import { resolve as resolve12 } from "path";
 
 // src/cli/commands/deploy/build.ts
 import * as p6 from "@clack/prompts";
 import { execSync as execSync2 } from "child_process";
 import { existsSync as existsSync13, readFileSync as readFileSync14, readdirSync as readdirSync4 } from "fs";
-import { dirname as dirname5, join as join14, resolve as resolve9 } from "path";
+import { dirname as dirname5, join as join14, resolve as resolve10 } from "path";
 var RESERVED_RUN_WORKER_FIRST = /* @__PURE__ */ new Set([
   "/api/*",
   "/ws/*",
@@ -3549,7 +3639,7 @@ async function buildDeployBundle(options) {
     );
   }
   const deployConfig = JSON.parse(readFileSync14(deployConfigPath, "utf-8"));
-  const outputWranglerPath = resolve9(dirname5(deployConfigPath), deployConfig.configPath);
+  const outputWranglerPath = resolve10(dirname5(deployConfigPath), deployConfig.configPath);
   if (!existsSync13(outputWranglerPath)) {
     output.die(`Output wrangler.json not found at ${outputWranglerPath}`, "build_output_missing");
   }
@@ -3563,7 +3653,7 @@ async function buildDeployBundle(options) {
   }
   const workerDir = dirname5(outputWranglerPath);
   const workerBundlePath = join14(workerDir, outputConfig.main);
-  const clientDir = outputConfig.assets?.directory ? resolve9(workerDir, outputConfig.assets.directory) : null;
+  const clientDir = outputConfig.assets?.directory ? resolve10(workerDir, outputConfig.assets.directory) : null;
   if (!existsSync13(workerBundlePath)) {
     output.die(`Worker bundle not found at ${workerBundlePath}`, "build_output_missing");
   }
@@ -4100,7 +4190,7 @@ function repoApi(deployUrl, token, appId) {
 // src/cli/lib/vc-remote.ts
 import { existsSync as existsSync15 } from "fs";
 import { tmpdir } from "os";
-import { isAbsolute as isAbsolute3, relative, resolve as resolve10 } from "path";
+import { isAbsolute as isAbsolute3, relative, resolve as resolve11 } from "path";
 var SPACE_REMOTE = "space";
 function deployBaseUrl() {
   return process.env.DEEPSPACE_DEPLOY_URL ?? PLATFORM_URLS.deploy;
@@ -4117,6 +4207,16 @@ function gitAuthEnv(token, base = deployBaseUrl()) {
     [`GIT_CONFIG_VALUE_${index}`]: `Authorization: Bearer ${token}`
   };
 }
+function gitSourceImportEnv(token, revision, base = deployBaseUrl()) {
+  const env = gitAuthEnv(token, base);
+  const index = Number(env.GIT_CONFIG_COUNT);
+  return {
+    ...env,
+    GIT_CONFIG_COUNT: String(index + 1),
+    [`GIT_CONFIG_KEY_${index}`]: `http.${base.replace(/\/+$/, "")}.extraHeader`,
+    [`GIT_CONFIG_VALUE_${index}`]: `X-DeepSpace-Source-Revision: ${revision}`
+  };
+}
 function runGitRemote(cwd, token, args, opts = {}) {
   return runGit(cwd, args, { ...opts, env: { ...gitAuthEnv(token), ...opts.env ?? {} } });
 }
@@ -4124,7 +4224,7 @@ function entryIsTransient(cwd) {
   const entry = process.argv[1];
   if (!entry) return true;
   if (/[\\/]_npx[\\/]/.test(entry) || entry.startsWith(tmpdir())) return true;
-  const rel = relative(resolve10(cwd), resolve10(entry));
+  const rel = relative(resolve11(cwd), resolve11(entry));
   return rel === "" || !rel.startsWith("..") && !isAbsolute3(rel);
 }
 function helperEntryUsable(command) {
@@ -4244,6 +4344,12 @@ function classifyPushTransportFailure(error) {
       error: `A first push to this new app hit your plan's active-app quota. Use \`deepspace app list\` to choose an app to undeploy, or upgrade your plan, then retry.`
     };
   }
+  if (/(?:HTTP |error: )422\b/i.test(message)) {
+    return {
+      code: "source_managed_by_github",
+      error: "This app uses GitHub source. Push with normal Git/GitHub, then run `deepspace deploy`."
+    };
+  }
   if (/(?:HTTP |error: )429\b/i.test(message)) {
     return {
       code: "rate_limited",
@@ -4322,22 +4428,138 @@ function resolveWorkspaceWorktree(worktrees, workspaceId) {
   return worktrees.find((worktree) => worktree.branch === branch)?.path ?? null;
 }
 
+// src/cli/lib/source-control.ts
+function githubRepositoryFromUrl(url) {
+  const trimmed = url.trim();
+  let path = null;
+  const scp = /^(?:[^@\s]+@)?github\.com:([^\s]+)$/i.exec(trimmed);
+  if (scp) {
+    path = scp[1];
+  } else {
+    try {
+      const parsed = new URL(trimmed);
+      if (parsed.hostname.toLowerCase() !== "github.com") return null;
+      path = parsed.pathname.replace(/^\/+/, "");
+    } catch {
+      return null;
+    }
+  }
+  const repository = path.replace(/\/+$/, "").replace(/\.git$/i, "");
+  if (!/^[A-Za-z0-9][A-Za-z0-9-]{0,38}\/[A-Za-z0-9][A-Za-z0-9._-]{0,99}$/.test(repository)) {
+    return null;
+  }
+  return repository.toLowerCase();
+}
+function listGitHubRemotes(cwd) {
+  const names = runGit(cwd, ["remote"], { allowFail: true }).stdout.toString("utf-8").split("\n").map((name) => name.trim()).filter(Boolean);
+  const remotes = [];
+  for (const name of names) {
+    const result = runGit(cwd, ["remote", "get-url", name], { allowFail: true });
+    if (result.status !== 0) continue;
+    const url = result.stdout.toString("utf-8").trim();
+    const repository = githubRepositoryFromUrl(url);
+    if (repository) remotes.push({ name, repository, url });
+  }
+  return remotes;
+}
+function selectGitHubRemote(cwd, options = {}) {
+  const remotes = listGitHubRemotes(cwd);
+  if (options.name) return remotes.find((remote) => remote.name === options.name) ?? null;
+  const repository = options.repository?.toLowerCase();
+  const matching = repository ? remotes.filter((remote) => remote.repository === repository) : remotes;
+  return matching.find((remote) => remote.name === "origin") ?? (matching.length === 1 ? matching[0] : null);
+}
+function remotePublicRefs(cwd, remote) {
+  const output = runGit(cwd, ["ls-remote", "--refs", remote]).stdout.toString("utf-8");
+  return output.split("\n").map((line) => line.trim()).filter(Boolean).map((line) => {
+    const [oid, name] = line.split(/\s+/, 2);
+    return { oid, name };
+  }).filter(
+    (ref) => /^[0-9a-f]{40}$/.test(ref.oid) && (ref.name.startsWith("refs/heads/") || ref.name.startsWith("refs/tags/"))
+  );
+}
+function remoteBranchOid(cwd, remote, branch) {
+  return remotePublicRefs(cwd, remote).find((ref) => ref.name === `refs/heads/${branch}`)?.oid ?? null;
+}
+function localTransferRefs(cwd, prefix, target) {
+  const output = runGit(cwd, [
+    "for-each-ref",
+    "--format=%(refname) %(objectname)",
+    prefix
+  ]).stdout.toString("utf-8");
+  return output.split("\n").map((line) => line.trim()).filter(Boolean).map((line) => {
+    const [name, oid] = line.split(/\s+/, 2);
+    return { name: `${target}/${name.slice(`${prefix}/`.length)}`, oid };
+  }).filter((ref) => /^[0-9a-f]{40}$/.test(ref.oid));
+}
+
+// src/cli/lib/source-api.ts
+async function getAppSource(deployUrl, token, appId) {
+  try {
+    const state = await apiFetch(
+      deployUrl,
+      token,
+      `/api/apps/${encodeURIComponent(appId)}/source`
+    );
+    return { ...state, registered: true };
+  } catch (error) {
+    if (error instanceof ApiError && error.code === "app_not_found") {
+      return { appId, source: null, revision: 0, registered: false };
+    }
+    throw error;
+  }
+}
+function setAppSource(deployUrl, token, appId, input) {
+  return apiFetch(
+    deployUrl,
+    token,
+    `/api/apps/${encodeURIComponent(appId)}/source`,
+    { method: "POST", body: JSON.stringify(input) }
+  );
+}
+
 // src/cli/commands/deploy/repository.ts
 async function syncDeployRepository(options) {
-  const { deployUrl, appDir, appId, token, push, ignoreStale, output } = options;
+  const { deployUrl, appDir, appId, token, push, ignoreStale, output, sourceState } = options;
   let commitOid = null;
   let recoverable = false;
   const deployKey = mintIdempotencyKey();
-  if (!push) {
+  let source = sourceState.source;
+  let sourceRevision = sourceState.revision;
+  const baseReleaseId = null;
+  if (!push && source?.provider !== "github") {
     try {
       assertSyncableRepo(appDir);
       commitOid = resolveCommit(appDir, "HEAD");
     } catch {
     }
-    return { commitOid, recoverable, deployKey };
+    return { commitOid, recoverable, deployKey, source, sourceRevision, baseReleaseId };
   }
   try {
     assertSyncableRepo(appDir);
+    if (source?.provider === "github") {
+      const github = syncGitHubDeploy({
+        deployUrl,
+        appDir,
+        appId,
+        token,
+        source,
+        ignoreStale,
+        output
+      });
+      return await github.then((result) => ({
+        ...result,
+        deployKey,
+        source,
+        sourceRevision
+      }));
+    }
+    if (!source && listGitHubRemotes(appDir).length > 0) {
+      output.die(
+        "This app has a GitHub remote but no claimed source. Choose once with `deepspace app source github` (manual GitHub ownership) or `deepspace app source deepspace` (packaged DeepSpace source), then deploy again.",
+        "source_unclaimed"
+      );
+    }
     ensureSpaceRemote(appDir, appId);
     const branch = currentBranch(appDir);
     const workspaceBranchId = workspaceIdFromBranch(branch);
@@ -4351,7 +4573,9 @@ async function syncDeployRepository(options) {
       throw new Error(refusal.error);
     }
     const tip = resolveCommit(appDir, `refs/heads/${branch}`);
-    if (!tip) return { commitOid, recoverable, deployKey };
+    if (!tip) {
+      return { commitOid, recoverable, deployKey, source, sourceRevision, baseReleaseId };
+    }
     const secretFiles = workspaceBranchId ? [] : trackedSecretFiles(appDir, tip);
     if (workspaceBranchId) {
       const { view } = await repoApi(deployUrl, token, appId).getWorkspace(workspaceBranchId);
@@ -4427,11 +4651,81 @@ async function syncDeployRepository(options) {
       }
     }
     commitOid = tip;
+    if (!source) {
+      const claimed = await getAppSource(deployUrl, token, appId);
+      source = claimed.source;
+      sourceRevision = claimed.revision;
+    }
   } catch (error) {
     const failure = deployRepositoryFailure(error);
     output.die(failure.error, failure.code);
   }
-  return { commitOid, recoverable, deployKey };
+  return { commitOid, recoverable, deployKey, source, sourceRevision, baseReleaseId };
+}
+async function syncGitHubDeploy(options) {
+  const { deployUrl, appDir, appId, token, source, ignoreStale, output } = options;
+  if (!isWorkTreeClean(appDir)) {
+    const refusal = dirtyWorktreeRefusal(currentBranch(appDir));
+    output.die(refusal.error, refusal.code);
+  }
+  const branch = currentBranch(appDir);
+  if (!branch) {
+    const refusal = detachedHeadRefusal();
+    output.die(refusal.error, refusal.code);
+    throw new Error(refusal.error);
+  }
+  const tip = resolveCommit(appDir, "HEAD");
+  if (!tip) {
+    output.die("The repository has no commit to deploy.", "no_commits");
+    throw new Error("The repository has no commit to deploy.");
+  }
+  const remote = selectGitHubRemote(appDir, { repository: source.repository });
+  if (!remote) {
+    output.die(
+      `No local GitHub remote points at ${source.repository}. Add one, then deploy again.`,
+      "github_remote_required"
+    );
+    throw new Error(`No local GitHub remote points at ${source.repository}.`);
+  }
+  const secretFiles = trackedSecretFiles(appDir, tip);
+  if (secretFiles.length > 0) {
+    output.die(
+      `Refusing to deploy a GitHub commit that tracks secret file(s): ${secretFiles.join(", ")}. Remove them from Git history, push the repaired branch, then deploy.`,
+      "secret_in_history"
+    );
+  }
+  if (remoteBranchOid(appDir, remote.name, branch) !== tip) {
+    output.die(
+      `GitHub ${source.repository} does not have ${branch} at ${tip.slice(0, 10)}. DeepSpace never pushes GitHub source; publish it manually, then deploy again.`,
+      "github_push_required",
+      {
+        actionRequired: true,
+        action: { cwd: appDir, argv: ["git", "push", remote.name, branch] }
+      }
+    );
+  }
+  const latest = await repoApi(deployUrl, token, appId).latestRelease().then((result) => result.release);
+  if (latest?.commitOid && latest.commitOid !== tip) {
+    const known = resolveCommit(appDir, latest.commitOid) !== null;
+    const containsLive = known && isAncestor(appDir, latest.commitOid, tip);
+    if ((!known || !containsLive) && !ignoreStale) {
+      output.die(
+        known ? `This GitHub branch does not contain live release #${latest.seq} (${latest.commitOid.slice(0, 10)}). Integrate the published GitHub history, then redeploy.` : `The live release commit ${latest.commitOid.slice(0, 10)} is not in this checkout. Fetch ${source.repository}, integrate it, then redeploy.`,
+        "stale_base",
+        {
+          actionRequired: true,
+          action: { cwd: appDir, argv: ["git", "fetch", remote.name] }
+        }
+      );
+    }
+    if (!containsLive) {
+      p9.log.warn(
+        "Deploying GitHub history that does not contain the live release (--ignore-stale)."
+      );
+    }
+  }
+  p9.log.info(`Verified GitHub ${source.repository}:${branch} at ${tip.slice(0, 10)} (no push).`);
+  return { commitOid: tip, recoverable: true, baseReleaseId: latest?.id ?? null };
 }
 function classifyRemoteState(appDir, token, branch, localTip) {
   let remoteTip = null;
@@ -4473,7 +4767,7 @@ async function pushWithTransientRetry(push) {
     } catch (error) {
       const message = errorMessage3(error);
       if (/(?:HTTP |error: )(?:429|503)\b/i.test(message) && attempt < backoffMs.length) {
-        await new Promise((resolve18) => setTimeout(resolve18, backoffMs[attempt]));
+        await new Promise((resolve19) => setTimeout(resolve19, backoffMs[attempt]));
         continue;
       }
       throw error;
@@ -4601,6 +4895,14 @@ async function deployBuiltBundle(options) {
     if (shouldSendLineage(repository.commitOid, repository.recoverable)) {
       form.append("commitOid", repository.commitOid);
     }
+    if (repository.source) {
+      form.append("sourceProvider", repository.source.provider);
+      form.append("sourceRevision", String(repository.sourceRevision));
+      if (repository.source.provider === "github") {
+        form.append("sourceRepository", repository.source.repository);
+      }
+    }
+    if (repository.baseReleaseId) form.append("baseReleaseId", repository.baseReleaseId);
     if (ignoreStale) form.append("ignoreStale", "true");
     form.append("deployKey", repository.deployKey);
     return form;
@@ -4627,7 +4929,7 @@ async function deployBuiltBundle(options) {
   }
   let body = await response.json().catch(() => ({}));
   for (let attempt = 0; response.status === 503 && body.code === "release_finalization_pending" && attempt < 3; attempt++) {
-    await new Promise((resolve18) => setTimeout(resolve18, 250 * 2 ** attempt));
+    await new Promise((resolve19) => setTimeout(resolve19, 250 * 2 ** attempt));
     response = await postCommit();
     body = await response.json().catch(() => ({}));
   }
@@ -4736,7 +5038,7 @@ async function postWithRetry(url, makeInit, {
       lastError = error;
     }
     if (attempt < attempts) {
-      await new Promise((resolve18) => setTimeout(resolve18, Math.min(8e3, 500 * 2 ** (attempt - 1))));
+      await new Promise((resolve19) => setTimeout(resolve19, Math.min(8e3, 500 * 2 ** (attempt - 1))));
     }
   }
   if (lastResponse) return lastResponse;
@@ -4885,15 +5187,10 @@ var deploy_default = defineCommand3({
       description: "Deploy even though hand-edited .dev.vars secrets are absent from the store (they will NOT be deployed, and any a previous deploy set are dropped).",
       default: false
     },
-    adopt: {
-      type: "boolean",
-      description: "Confirm adopting an existing app you can deploy but do not own (collaborator/admin on-behalf) when wrangler.toml has no DEEPSPACE_APP_ID. Without this flag an interactive prompt asks.",
-      default: false
-    },
     // Citty maps --no-push to the negation of an argument named `push`.
     push: {
       type: "boolean",
-      description: "Sync the branch to the app's cloud repo before deploying (--no-push to skip; the release then may point at source the platform cannot recover).",
+      description: "Sync DeepSpace source before deploying. The legacy --no-push escape hatch skips recoverable source lineage; GitHub apps are verified and never pushed automatically.",
       default: true
     },
     "ignore-stale": {
@@ -4910,7 +5207,7 @@ var deploy_default = defineCommand3({
   async run({ args }) {
     const output = createDeployOutput(args.json === true);
     preflightNodeVersion("deploy");
-    const appDir = resolve11(args.dir ?? ".");
+    const appDir = resolve12(args.dir ?? ".");
     const selectorRefusal = blankSelectorRefusal(args);
     if (selectorRefusal) output.die(selectorRefusal.error, selectorRefusal.code);
     const envName = typeof args.env === "string" && args.env.trim() ? args.env.trim() : void 0;
@@ -4927,7 +5224,7 @@ var deploy_default = defineCommand3({
     }
     p12.intro("Deploying DeepSpace app");
     output.showIntro();
-    const wranglerConfig = readWranglerConfig(appDir);
+    const wranglerConfig = readWranglerConfig2(appDir);
     const nameResult = resolveAppNameForEnv(wranglerConfig, envName);
     if (!nameResult.ok) return output.die(nameResult.reason, "invalid_app_name");
     const declaredName = envName ? wranglerConfig.env?.[envName]?.name : wranglerConfig.name;
@@ -4940,35 +5237,21 @@ var deploy_default = defineCommand3({
     }
     const appName = nameResult.name;
     let appId = readAppId(appDir, envName);
-    p12.log.info(envName ? `App: ${appName}  (env: ${envName})` : `App: ${appName}`);
-    const { token, ownerId } = await authenticate(appDir, output);
     if (!appId) {
-      const existing = await resolveExistingAppId(DEPLOY_URL3, token, appName);
-      if (existing.kind === "taken") {
+      const legacyAppId = readLegacyAppId(appDir, envName);
+      if (legacyAppId) {
         output.die(
-          `"${appName}" is taken by an app you don't have deploy access to. Ask the owner to add you as a collaborator (\`deepspace app collaborators add\`), or pick a different \`name\` in wrangler.toml.`,
-          "name_taken"
+          `This checkout still uses legacy app identity ${legacyAppId}. Run \`deepspace app migrate --dry-run\`, then complete \`deepspace app migrate\` before deploying.`,
+          "legacy_app_migration_required"
         );
       }
-      if (existing.kind === "adopted" && !existing.owned && !args.adopt) {
-        if (output.nonInteractive) {
-          output.die(
-            `"${appName}" is an existing app owned by another account that you can deploy on-behalf (collaborator/admin). Confirmation needs --adopt here \u2014 re-run with --adopt to deploy it, or pick a different \`name\` in wrangler.toml if you meant a new app.`,
-            "confirmation_required"
-          );
-        }
-        const confirmed = await p12.confirm({
-          message: `"${appName}" is an existing app owned by another account that you can deploy on-behalf (you are a collaborator or admin). Deploy it? (Meant a new app? Pick a different \`name\` in wrangler.toml.)`
-        });
-        if (p12.isCancel(confirmed) || !confirmed) {
-          output.die("Deploy cancelled.", "cancelled");
-        }
-      }
-      appId = existing.kind === "adopted" ? existing.appId : mintAppId();
+    }
+    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(
-        existing.kind === "adopted" ? `Adopted existing app id ${appId} for ${appName} \u2014 commit wrangler.toml.` : `Minted app id ${appId} \u2014 commit wrangler.toml.`
-      );
+      p12.log.info(`Minted app id ${appId} \u2014 commit wrangler.toml.`);
     }
     p12.log.info(`Id: ${appId}`);
     const secretsCache = await loadDeploySecrets({
@@ -4980,6 +5263,7 @@ var deploy_default = defineCommand3({
       token,
       output
     });
+    const sourceState = await getAppSource(DEPLOY_URL3, token, appId);
     const repository = await syncDeployRepository({
       deployUrl: DEPLOY_URL3,
       appDir,
@@ -4987,7 +5271,8 @@ var deploy_default = defineCommand3({
       token,
       push: args.push !== false,
       ignoreStale: Boolean(args["ignore-stale"]),
-      output
+      output,
+      sourceState
     });
     const spinner2 = createSpinner();
     const bundle = await buildDeployBundle({
@@ -5101,7 +5386,7 @@ async function waitForAssetsReady(url, timeoutMs) {
       if (!body.includes("Assets have not yet deployed") && !body.includes("No app configured")) {
         streak++;
         if (streak >= 3) return true;
-        await new Promise((resolve18) => setTimeout(resolve18, 1500));
+        await new Promise((resolve19) => setTimeout(resolve19, 1500));
         continue;
       }
       streak = 0;
@@ -5109,7 +5394,7 @@ async function waitForAssetsReady(url, timeoutMs) {
       streak = 0;
     }
     const waitMs = Math.min(8e3, 1e3 * 2 ** (attempt - 1));
-    await new Promise((resolve18) => setTimeout(resolve18, waitMs));
+    await new Promise((resolve19) => setTimeout(resolve19, waitMs));
   }
   return false;
 }
@@ -5741,8 +6026,8 @@ var usage_default = defineDeepspaceCommand({
 });
 
 // src/cli/commands/add.ts
-import { existsSync as existsSync18, readFileSync as readFileSync17, realpathSync as realpathSync2 } from "fs";
-import { dirname as dirname7, join as join17, resolve as resolve13 } from "path";
+import { existsSync as existsSync18, readFileSync as readFileSync17, realpathSync as realpathSync3 } from "fs";
+import { dirname as dirname7, join as join17, resolve as resolve14 } from "path";
 import { pathToFileURL as pathToFileURL3 } from "url";
 
 // src/cli/commands/feature-installer.ts
@@ -5762,7 +6047,7 @@ import {
 } from "fs";
 import { spawnSync as spawnSync6 } from "child_process";
 import { tmpdir as tmpdir2 } from "os";
-import { dirname as dirname6, isAbsolute as isAbsolute4, join as join16, resolve as resolve12 } from "path";
+import { dirname as dirname6, isAbsolute as isAbsolute4, join as join16, resolve as resolve13 } from "path";
 import { fileURLToPath } from "url";
 var NAV_MARKER = "// \u2500\u2500 Features add nav items below this line \u2500\u2500";
 function featurePackageRoot(moduleUrl = import.meta.url) {
@@ -5810,7 +6095,7 @@ function featureCatalog(packageRoot = featurePackageRoot()) {
     description: config.description ?? null
   }));
 }
-function editDistance(a, b) {
+function editDistance2(a, b) {
   const row = Array.from({ length: b.length + 1 }, (_, index) => index);
   for (let i = 1; i <= a.length; i++) {
     let previous = row[0];
@@ -5827,7 +6112,7 @@ function suggestFeature(featureId, packageRoot = featurePackageRoot()) {
   let closest = null;
   let closestDistance = Number.POSITIVE_INFINITY;
   for (const feature of listFeatureConfigs(packageRoot)) {
-    const distance = editDistance(featureId, feature.id);
+    const distance = editDistance2(featureId, feature.id);
     if (distance < closestDistance) {
       closest = feature.id;
       closestDistance = distance;
@@ -5837,7 +6122,7 @@ function suggestFeature(featureId, packageRoot = featurePackageRoot()) {
   return closest !== null && closestDistance <= threshold ? closest : null;
 }
 function resolveTargetDir(raw) {
-  return isAbsolute4(raw) ? raw : resolve12(raw);
+  return isAbsolute4(raw) ? raw : resolve13(raw);
 }
 function resolveFeatureDestPath(fileDest, route) {
   const pages = "src/pages/";
@@ -6482,7 +6767,7 @@ async function targetInstaller(appDir) {
       "feature_installer_missing"
     );
   }
-  if (realpathSync2(installedRoot) === realpathSync2(featurePackageRoot())) {
+  if (realpathSync3(installedRoot) === realpathSync3(featurePackageRoot())) {
     return { installFeature };
   }
   const entry = join17(installedRoot, "dist", "feature-installer.js");
@@ -6579,7 +6864,7 @@ var add_default = defineDeepspaceCommand({
       }
       return { data: { features: featureCatalog(root) } };
     }
-    const appDir = resolve13(args.dir ?? ".");
+    const appDir = resolve14(args.dir ?? ".");
     if (!existsSync18(appDir)) {
       throw new Refusal(
         `Target directory not found: ${appDir}
@@ -6659,13 +6944,13 @@ function fmtDate(iso) {
   if (!iso) return "\u2014";
   return iso.slice(0, 10);
 }
-async function confirm5(message) {
+async function confirm4(message) {
   process.stdout.write(`${message} [y/N] `);
-  return new Promise((resolve18) => {
+  return new Promise((resolve19) => {
     process.stdin.setEncoding("utf-8");
     process.stdin.once("data", (data) => {
       const answer = data.toString().trim().toLowerCase();
-      resolve18(answer === "y" || answer === "yes");
+      resolve19(answer === "y" || answer === "yes");
     });
   });
 }
@@ -6739,7 +7024,7 @@ var buy = defineDeepspaceCommand({
           "confirmation_required"
         );
       }
-      const ok2 = await confirm5(
+      const ok2 = await confirm4(
         `Buy ${domain} for ${price}/yr (auto-renews; non-refundable), attach to ${appId}? Provisioning takes ${expectedTime}.`
       );
       if (!ok2) {
@@ -6909,7 +7194,7 @@ var detach = defineDeepspaceCommand({
           "confirmation_required"
         );
       }
-      const ok2 = await confirm5(
+      const ok2 = await confirm4(
         `Detach ${domain}? Routing will stop; the domain stays registered (auto-renew is unchanged).`
       );
       if (!ok2) {
@@ -6992,8 +7277,8 @@ var list3 = defineDeepspaceCommand({
       }
       if (pending.length) {
         console.log(`PENDING INVITES ON ${app2}`);
-        for (const p34 of pending) {
-          console.log(`  ${p34.email} (expires ${new Date(p34.expiresAt).toLocaleDateString()})`);
+        for (const p35 of pending) {
+          console.log(`  ${p35.email} (expires ${new Date(p35.expiresAt).toLocaleDateString()})`);
         }
       }
     }
@@ -7091,7 +7376,7 @@ var cancel3 = defineDeepspaceCommand({
       `/api/app-collaborators/${encodeURIComponent(app2)}`
     );
     const target = email.trim().toLowerCase();
-    const found = pending.find((p34) => p34.email.toLowerCase() === target);
+    const found = pending.find((p35) => p35.email.toLowerCase() === target);
     if (!found) {
       throw new Refusal(`${email} has no pending invite on ${app2}`, "no_pending_invite", {
         action: cliAction("deepspace", "app", "collaborators", "list", "--app", app2)
@@ -7562,7 +7847,7 @@ var integrations_default = defineCommand8({
 // src/cli/commands/library.ts
 import { defineCommand as defineCommand9 } from "citty";
 import { existsSync as existsSync19, readFileSync as readFileSync19 } from "fs";
-import { join as join18, resolve as resolve14 } from "path";
+import { join as join18, resolve as resolve15 } from "path";
 import { parse as parseToml4 } from "smol-toml";
 import * as p16 from "@clack/prompts";
 var DEFAULT_LIBRARY_APP = "deepdotspace-site";
@@ -7632,7 +7917,7 @@ var publish = defineDeepspaceCommand({
     if (appErr) throw new Refusal(appErr, "invalid_app");
     let appName = str(args.app)?.trim();
     if (!appName) {
-      const appDir = resolve14(str(args.dir) ?? ".");
+      const appDir = resolve15(str(args.dir) ?? ".");
       const wranglerPath = join18(appDir, "wrangler.toml");
       if (!existsSync19(wranglerPath)) {
         throw new Refusal(
@@ -7818,7 +8103,7 @@ function detectAppName2() {
   try {
     const cwd = process.cwd();
     if (!hasWranglerConfig(cwd)) return void 0;
-    const config = readWranglerConfig(cwd);
+    const config = readWranglerConfig2(cwd);
     return typeof config.name === "string" ? config.name : void 0;
   } catch {
     return void 0;
@@ -8707,24 +8992,50 @@ var status_default = defineCommand11({
               commitOid: rel.commitOid,
               createdAt: rel.createdAt,
               url: rel.url,
-              byYou
+              byYou,
+              source: rel.source,
+              sourceRevision: rel.sourceRevision
             };
           };
           var reportWorkspace = reportWorkspace2, reportRemoteFailure = reportRemoteFailure2, reportRelease = reportRelease2;
           const api4 = repoApi(deployBaseUrl(), token, appId);
+          const sourceResult = await observeRemote(getAppSource(deployBaseUrl(), token, appId));
+          const source = sourceResult.ok ? sourceResult.value.source : null;
+          const githubSource = source?.provider === "github";
+          if (!sourceResult.ok) {
+            reportRemoteFailure2("Source", "source", sourceResult.error);
+          } else if (githubSource) {
+            lines.push(["Source", `GitHub \xB7 ${source.repository} (manual Git ownership)`]);
+            json.source = { ...source, revision: sourceResult.value.revision };
+          } else if (source?.provider === "deepspace") {
+            lines.push([
+              "Source",
+              `DeepSpace \xB7 packaged Git (revision ${sourceResult.value.revision})`
+            ]);
+            json.source = { ...source, revision: sourceResult.value.revision };
+          } else {
+            lines.push(["Source", "unclaimed \xB7 next normal deploy defaults to DeepSpace"]);
+            json.source = null;
+          }
           const [refsResult, wsResult, releaseResult] = await Promise.all([
-            observeRemote(api4.getRefs()),
-            facts.workspaceId ? observeRemote(api4.getWorkspace(facts.workspaceId).then((r) => r.view)) : Promise.resolve({ ok: true, value: null }),
+            githubSource ? Promise.resolve({ ok: true, value: null }) : observeRemote(api4.getRefs()),
+            facts.workspaceId && !githubSource ? observeRemote(api4.getWorkspace(facts.workspaceId).then((r) => r.view)) : Promise.resolve({ ok: true, value: null }),
             observeRemote(api4.latestRelease().then((r) => r.release))
           ]);
           if (facts.workspaceId) {
-            if (!wsResult.ok) reportRemoteFailure2("Workspace", "workspace", wsResult.error);
+            if (githubSource) {
+              lines.push(["Workspace", "DeepSpace workspaces are disabled for GitHub source"]);
+              json.workspace = { state: "disabled", provider: "github" };
+            } else if (!wsResult.ok) reportRemoteFailure2("Workspace", "workspace", wsResult.error);
             else if (wsResult.value) reportWorkspace2(wsResult.value);
           }
           const refs = refsResult.ok ? refsResult.value : void 0;
           const trunkRef = refs?.refs.find((r) => `refs/heads/${branch}` === r.name);
           if (!facts.workspaceId && branch) {
-            if (!refsResult.ok) reportRemoteFailure2("Trunk", "trunk", refsResult.error);
+            if (githubSource) {
+              lines.push(["Trunk", `${branch} is owned through normal Git/GitHub`]);
+              json.trunk = { state: "external", provider: "github", branch };
+            } else if (!refsResult.ok) reportRemoteFailure2("Trunk", "trunk", refsResult.error);
             else {
               const remoteOid = trunkRef?.oid ?? null;
               const localOid = resolveCommit(appDir, `refs/heads/${branch}`);
@@ -8965,7 +9276,7 @@ var push_default = defineDeepspaceCommand({
 
 // src/cli/commands/pull.ts
 import * as p20 from "@clack/prompts";
-import { realpathSync as realpathSync3 } from "fs";
+import { realpathSync as realpathSync4 } from "fs";
 function targetedVcAction(command, cwd, appId, branch) {
   return {
     cwd,
@@ -8989,7 +9300,7 @@ function workspaceBranchPullRefusal(branch, trunkBranch) {
 function worktreeHoldingBranch(worktrees, branch, selfPath) {
   const real = (pth) => {
     try {
-      return realpathSync3(pth);
+      return realpathSync4(pth);
     } catch {
       return pth;
     }
@@ -9245,7 +9556,7 @@ var pull_default = defineDeepspaceCommand({
 // src/cli/commands/clone.ts
 import * as p21 from "@clack/prompts";
 import { existsSync as existsSync22, readdirSync as readdirSync6, rmSync as rmSync5 } from "fs";
-import { resolve as resolve15, basename as basename3, join as join20 } from "path";
+import { resolve as resolve16, basename as basename3, join as join20 } from "path";
 function cleanFailedCloneDir(dir) {
   let entries;
   try {
@@ -9299,7 +9610,7 @@ var clone_default = defineDeepspaceCommand({
   async run({ args }) {
     assertAppTargetResolvable(String(args.app));
     const selector = String(args.app).trim();
-    const dir = resolve15(String(args.dir ?? selector));
+    const dir = resolve16(String(args.dir ?? selector));
     const dirPreexisted = validateCloneTarget(dir);
     const spinner2 = args.json ? null : createSpinner();
     spinner2?.start(`Resolving ${selector}\u2026`);
@@ -9553,7 +9864,7 @@ import { defineCommand as defineCommand12 } from "citty";
 
 // src/cli/commands/workspace/new.ts
 import * as p26 from "@clack/prompts";
-import { isAbsolute as isAbsolute6, resolve as resolve16 } from "path";
+import { isAbsolute as isAbsolute6, resolve as resolve17 } from "path";
 
 // src/cli/commands/workspace/analysis.ts
 import * as p24 from "@clack/prompts";
@@ -9678,18 +9989,18 @@ function printOverlaps(overlaps, json) {
 
 // src/cli/commands/workspace/local.ts
 import * as p25 from "@clack/prompts";
-import { mkdirSync as mkdirSync7, readFileSync as readFileSync23, realpathSync as realpathSync4, renameSync as renameSync2, statSync, writeFileSync as writeFileSync9 } from "fs";
+import { mkdirSync as mkdirSync7, readFileSync as readFileSync23, realpathSync as realpathSync5, renameSync as renameSync2, statSync, writeFileSync as writeFileSync9 } from "fs";
 import { dirname as dirname9, isAbsolute as isAbsolute5, join as join21, relative as relative2, sep as sep2 } from "path";
 var WORKSPACE_MARKER = "deepspace-workspace.json";
 function excludeWorktreeDir(appDir, dir) {
   try {
     ensureLocalExclude(appDir, ".deepspace/");
-    const realDir = realpathSync4(dir);
-    const rel = relative2(realpathSync4(repoToplevel(appDir)), realDir);
+    const realDir = realpathSync5(dir);
+    const rel = relative2(realpathSync5(repoToplevel(appDir)), realDir);
     if (!rel || rel === ".." || rel.startsWith(`..${sep2}`) || isAbsolute5(rel)) return;
     const pattern = rel.split(sep2).join("/");
     if (pattern === ".deepspace" || pattern.startsWith(".deepspace/")) return;
-    const relApp = relative2(realpathSync4(appDir), realDir).split(sep2).join("/");
+    const relApp = relative2(realpathSync5(appDir), realDir).split(sep2).join("/");
     if (relApp === ".deepspace" || relApp.startsWith(".deepspace/")) return;
     ensureLocalExclude(appDir, `/${pattern}/`);
   } catch {
@@ -9719,6 +10030,19 @@ function markManagedWorkspace(worktreeRoot, workspaceId) {
     return false;
   }
 }
+function rollbackUnmarkedWorkspace(appDir, worktreeRoot, branch, createdOid) {
+  const removed = runGit(appDir, ["worktree", "remove", worktreeRoot], { allowFail: true });
+  if (removed.status !== 0) {
+    return `git worktree remove failed: ${removed.stderr.toString("utf-8").trim() || "unknown git error"}`;
+  }
+  const deleted = runGit(appDir, ["update-ref", "-d", `refs/heads/${branch}`, createdOid], {
+    allowFail: true
+  });
+  if (deleted.status !== 0) {
+    return `the checkout was removed but branch ${branch} remains: ${deleted.stderr.toString("utf-8").trim() || "unknown git error"}`;
+  }
+  return null;
+}
 function isManagedWorkspaceWorktree(worktreeRoot, workspaceId) {
   const markerPath = worktreeMarkerPath(worktreeRoot);
   if (!markerPath) return false;
@@ -9735,13 +10059,21 @@ function defaultWorkspaceRoot(appDir, workspaceId) {
   return join21(primary.path, ".deepspace", "ws", workspaceId.slice(3).toLowerCase());
 }
 function appDirInWorktree(appDir, worktreeRoot) {
-  const appRelative = relative2(realpathSync4(repoToplevel(appDir)), realpathSync4(appDir));
+  const appRelative = relative2(realpathSync5(repoToplevel(appDir)), realpathSync5(appDir));
   return appRelative ? join21(worktreeRoot, appRelative) : worktreeRoot;
 }
-function materializeWorkspaceWorktree(appDir, worktreeRoot, branch, startPoint, workspaceId) {
+function materializeWorkspaceWorktree(appDir, worktreeRoot, branch, startPoint, workspaceId, options = {}) {
+  const createdOid = resolveCommit(appDir, startPoint);
+  if (!createdOid) throw new Error(`Could not resolve workspace start point ${startPoint}`);
   addWorktreeNewBranch(appDir, worktreeRoot, branch, startPoint);
+  const marked = (options.markManaged ?? markManagedWorkspace)(worktreeRoot, workspaceId);
+  if (!marked) {
+    const rollbackError = rollbackUnmarkedWorkspace(appDir, worktreeRoot, branch, createdOid);
+    throw new Error(
+      `Could not record DeepSpace ownership for ${worktreeRoot}.` + (rollbackError ? ` Automatic rollback was incomplete: ${rollbackError}` : " The just-created checkout and branch were rolled back.")
+    );
+  }
   excludeWorktreeDir(appDir, worktreeRoot);
-  markManagedWorkspace(worktreeRoot, workspaceId);
 }
 function inOwnLinkedWorktree(appDir, id) {
   if (workspaceIdFromBranch(currentBranch(appDir)) !== id) return false;
@@ -9799,7 +10131,7 @@ function cleanupWorkspaceLocal(appDir, id, trunkBranch) {
       }
       let inside = false;
       try {
-        inside = realpathSync4(repoToplevel(appDir)) === realpathSync4(linked.path);
+        inside = realpathSync5(repoToplevel(appDir)) === realpathSync5(linked.path);
       } catch {
         inside = false;
       }
@@ -10039,7 +10371,7 @@ var newWorkspaceCommand = defineDeepspaceCommand({
       idempotencyKey: mintIdempotencyKey()
     });
     const dirInput = typeof args.dir === "string" ? args.dir.trim() : "";
-    const worktreeRoot = dirInput ? isAbsolute6(dirInput) ? dirInput : resolve16(appDir, dirInput) : defaultWorkspaceRoot(appDir, id);
+    const worktreeRoot = dirInput ? isAbsolute6(dirInput) ? dirInput : resolve17(appDir, dirInput) : defaultWorkspaceRoot(appDir, id);
     const dir = appDirInWorktree(appDir, worktreeRoot);
     try {
       materializeWorkspaceWorktree(appDir, worktreeRoot, branch, baseOid, id);
@@ -10078,7 +10410,7 @@ var newWorkspaceCommand = defineDeepspaceCommand({
 // src/cli/commands/workspace/attach.ts
 import * as p27 from "@clack/prompts";
 import { existsSync as existsSync23, readdirSync as readdirSync7, rmSync as rmSync6 } from "fs";
-import { isAbsolute as isAbsolute7, resolve as resolve17 } from "path";
+import { isAbsolute as isAbsolute7, resolve as resolve18 } from "path";
 function finishedWorkspaceMessage(id, view) {
   const workspace = view.workspace;
   if (workspace.status === "landed") {
@@ -10162,7 +10494,7 @@ var attachWorkspaceCommand = defineDeepspaceCommand({
         );
       }
       const requestedDir = typeof args.dir === "string" ? args.dir.trim() : "";
-      const worktreeRoot = requestedDir ? isAbsolute7(requestedDir) ? requestedDir : resolve17(appDir, requestedDir) : defaultWorkspaceRoot(appDir, id);
+      const worktreeRoot = requestedDir ? isAbsolute7(requestedDir) ? requestedDir : resolve18(appDir, requestedDir) : defaultWorkspaceRoot(appDir, id);
       const dir2 = appDirInWorktree(appDir, worktreeRoot);
       if (resolveCommit(appDir, `refs/heads/${branch}`)) {
         throw new Refusal(
@@ -10201,7 +10533,7 @@ var attachWorkspaceCommand = defineDeepspaceCommand({
         extra: { status: view.workspace.status }
       });
     }
-    const dir = resolve17(
+    const dir = resolve18(
       process.cwd(),
       (typeof args.dir === "string" ? args.dir.trim() : "") || `ws-${id.slice(3).toLowerCase()}`
     );
@@ -11164,6 +11496,721 @@ var git_credential_default = defineCommand13({
   }
 });
 
+// src/cli/commands/source.ts
+import * as p34 from "@clack/prompts";
+var TRANSFER_PREFIX = "refs/deepspace/source-transfer";
+var source_default = defineDeepspaceCommand({
+  meta: {
+    name: "source",
+    description: "Show or change the app\u2019s one authoritative Git repository"
+  },
+  args: {
+    provider: {
+      type: "positional",
+      description: "Source provider: github or deepspace (omit to show)",
+      required: false
+    },
+    app: {
+      type: "string",
+      alias: "a",
+      description: "App id or subdomain name (default: current app)",
+      required: false
+    },
+    remote: {
+      type: "string",
+      description: "GitHub remote name when it cannot be inferred (default: origin)",
+      required: false
+    }
+  },
+  async run({ args }) {
+    const requested = typeof args.provider === "string" ? args.provider.trim().toLowerCase() : "";
+    if (requested && requested !== "github" && requested !== "deepspace") {
+      throw new Refusal("Source must be `github` or `deepspace`.", "invalid_source");
+    }
+    const token = await ensureToken();
+    const deployUrl = deployBaseUrl();
+    const appId = await resolveAppTarget(
+      deployUrl,
+      token,
+      typeof args.app === "string" ? args.app : void 0
+    );
+    const state = await getAppSource(deployUrl, token, appId);
+    if (!requested) {
+      reportSource(appId, state, args.json);
+      return { data: sourceData(state) };
+    }
+    const appDir = findAppDir();
+    if (!appDir) {
+      throw new Refusal(
+        "Changing source requires a local app checkout with wrangler.toml and Git history.",
+        "not_in_app_repo"
+      );
+    }
+    assertSyncableRepo(appDir);
+    const remoteArg = typeof args.remote === "string" ? args.remote.trim() : void 0;
+    const result = requested === "github" ? await moveToGitHub({ appDir, appId, token, deployUrl, state, remoteArg }) : await moveToDeepSpace({ appDir, appId, token, deployUrl, state, remoteArg });
+    if (!args.json) {
+      p34.log.success(
+        result.source.provider === "github" ? `Source: GitHub \xB7 ${result.source.repository} (revision ${result.revision})` : `Source: DeepSpace (revision ${result.revision})`
+      );
+    }
+    return { data: { appId, source: result.source, revision: result.revision } };
+  }
+});
+function sourceData(state) {
+  return {
+    appId: state.appId,
+    source: state.source,
+    revision: state.revision,
+    registered: state.registered
+  };
+}
+function reportSource(appId, state, json) {
+  if (json) return;
+  console.log(`App: ${appId}`);
+  if (state.source?.provider === "github") {
+    console.log(`Source: GitHub \xB7 ${state.source.repository}`);
+  } else if (state.source?.provider === "deepspace") {
+    console.log("Source: DeepSpace");
+  } else {
+    console.log("Source: unclaimed (the first normal deploy defaults to DeepSpace)");
+  }
+  console.log(`Revision: ${state.revision}`);
+}
+async function moveToGitHub(input) {
+  const { appDir, appId, token, deployUrl, state, remoteArg } = input;
+  const selected = requireGitHubRemote(appDir, remoteArg);
+  const target = { provider: "github", repository: selected.repository };
+  if (sameSource(state.source, target)) return { source: target, revision: state.revision };
+  if (state.source?.provider === "deepspace") {
+    requireLocalHead(appDir);
+    const api4 = repoApi(deployUrl, token, appId);
+    const { views } = await api4.listWorkspaces();
+    if (views.length > 0) {
+      throw new Refusal(
+        "Land or drop every active DeepSpace workspace before moving source to GitHub.",
+        "active_workspaces"
+      );
+    }
+    ensureSpaceRemote(appDir, appId);
+    runGitRemote(appDir, token, [
+      "fetch",
+      "--quiet",
+      "--prune",
+      SPACE_REMOTE,
+      `+refs/heads/*:${TRANSFER_PREFIX}/heads/*`,
+      `+refs/tags/*:${TRANSFER_PREFIX}/tags/*`
+    ]);
+    const { refs } = await api4.getRefs().then((value) => {
+      if (!value)
+        throw new Refusal("The DeepSpace source repository is unavailable.", "source_unavailable");
+      return value;
+    });
+    const wanted = refs.filter(isPublicRef).map(({ name, oid }) => ({ name, oid }));
+    const fetched = transferRefs(appDir);
+    if (!sameRefs(fetched, wanted)) {
+      throw new Refusal(
+        "DeepSpace branches or tags changed while they were being fetched. Retry the transfer from fresh refs.",
+        "source_changed"
+      );
+    }
+    const latest = await api4.latestRelease().then((value) => value.release);
+    requireReleaseReachable(appDir, latest, wanted);
+    const remote = new Map(
+      remotePublicRefs(appDir, selected.name).map((ref) => [ref.name, ref.oid])
+    );
+    const missing = wanted.filter((ref) => remote.get(ref.name) !== ref.oid);
+    if (missing.length > 0) {
+      const refspecs = missing.map((ref) => transferRefspec(ref.name));
+      throw new Refusal(
+        `GitHub ${selected.repository} is missing ${missing.length} authoritative branch/tag ref(s). Push them manually, then rerun this command.`,
+        "github_push_required",
+        {
+          actionRequired: true,
+          action: { cwd: appDir, argv: ["git", "push", "--atomic", selected.name, ...refspecs] },
+          extra: {
+            appId,
+            repository: selected.repository,
+            missing: missing.map((ref) => ref.name)
+          }
+        }
+      );
+    }
+    return setAppSource(deployUrl, token, appId, {
+      source: target,
+      expectedRevision: state.revision,
+      refs: wanted,
+      ...releaseExpectation(latest)
+    });
+  }
+  requirePublishedHead(appDir, selected, appId);
+  return setAppSource(deployUrl, token, appId, {
+    source: target,
+    expectedRevision: state.revision
+  });
+}
+async function moveToDeepSpace(input) {
+  const { appDir, appId, token, deployUrl, state, remoteArg } = input;
+  const target = { provider: "deepspace" };
+  if (sameSource(state.source, target)) return { source: target, revision: state.revision };
+  if (state.source?.provider !== "github") {
+    return setAppSource(deployUrl, token, appId, {
+      source: target,
+      expectedRevision: state.revision
+    });
+  }
+  const selected = requireGitHubRemote(appDir, remoteArg, state.source.repository);
+  const { branch, oid } = requirePublishedHead(appDir, selected);
+  fetchGitHubTransferRefs(appDir, selected.name);
+  const refs = transferRefs(appDir);
+  const latest = await repoApi(deployUrl, token, appId).latestRelease().then((value) => value.release);
+  requireReleaseReachable(appDir, latest, refs);
+  ensureSpaceRemote(appDir, appId);
+  if (refs.length === 0) {
+    throw new Refusal("GitHub has no branches or tags to import.", "source_empty");
+  }
+  const pushed = runGit(
+    appDir,
+    [
+      "push",
+      "--force",
+      "--atomic",
+      "--prune",
+      SPACE_REMOTE,
+      `${TRANSFER_PREFIX}/heads/*:refs/heads/*`,
+      `${TRANSFER_PREFIX}/tags/*:refs/tags/*`
+    ],
+    { allowFail: true, env: gitSourceImportEnv(token, state.revision, deployUrl) }
+  );
+  if (pushed.status !== 0) {
+    throw new Refusal(
+      `DeepSpace source import failed: ${pushed.stderr.toString("utf-8").trim() || "git push failed"}`,
+      "source_import_failed"
+    );
+  }
+  return setAppSource(deployUrl, token, appId, {
+    source: target,
+    expectedRevision: state.revision,
+    branch,
+    commitOid: oid,
+    refs,
+    ...releaseExpectation(latest)
+  });
+}
+function requireGitHubRemote(appDir, remoteArg, repository) {
+  const selected = selectGitHubRemote(appDir, { name: remoteArg, repository });
+  if (selected) return selected;
+  throw new Refusal(
+    remoteArg ? `Remote "${remoteArg}" is not a GitHub repository${repository ? ` for ${repository}` : ""}.` : repository ? `No local GitHub remote points at ${repository}. Add one or pass --remote <name>.` : "No unambiguous GitHub remote was found. Add `origin` or pass --remote <name>.",
+    "github_remote_required"
+  );
+}
+function requirePublishedHead(appDir, remote, appId = "") {
+  const head = requireLocalHead(appDir);
+  if (remoteBranchOid(appDir, remote.name, head.branch) !== head.oid) {
+    throw githubPushRequired(appDir, appId, remote, head.branch, head.oid);
+  }
+  return head;
+}
+function requireLocalHead(appDir) {
+  if (!isWorkTreeClean(appDir)) {
+    throw new Refusal("Commit or discard local changes before changing source.", "dirty_worktree");
+  }
+  const branch = currentBranch(appDir);
+  if (!branch) throw new Refusal("HEAD is detached; switch to a branch first.", "detached_head");
+  const oid = resolveCommit(appDir, "HEAD");
+  if (!oid) throw new Refusal("The repository has no commit to publish.", "no_commits");
+  return { branch, oid };
+}
+function githubPushRequired(appDir, appId, remote, branch, oid) {
+  return new Refusal(
+    `GitHub ${remote.repository} does not have ${branch} at ${oid.slice(0, 10)}. Push it manually, then rerun.`,
+    "github_push_required",
+    {
+      actionRequired: true,
+      action: { cwd: appDir, argv: ["git", "push", remote.name, branch] },
+      extra: { ...appId ? { appId } : {}, repository: remote.repository, branch, oid }
+    }
+  );
+}
+function fetchGitHubTransferRefs(appDir, remote) {
+  runGit(appDir, [
+    "fetch",
+    "--quiet",
+    "--prune",
+    remote,
+    `+refs/heads/*:${TRANSFER_PREFIX}/heads/*`,
+    `+refs/tags/*:${TRANSFER_PREFIX}/tags/*`
+  ]);
+}
+function transferRefs(appDir) {
+  return localTransferRefs(appDir, `${TRANSFER_PREFIX}/heads`, "refs/heads").concat(
+    localTransferRefs(appDir, `${TRANSFER_PREFIX}/tags`, "refs/tags")
+  );
+}
+function transferRefspec(ref) {
+  if (ref.startsWith("refs/heads/")) {
+    return `${TRANSFER_PREFIX}/heads/${ref.slice("refs/heads/".length)}:${ref}`;
+  }
+  return `${TRANSFER_PREFIX}/tags/${ref.slice("refs/tags/".length)}:${ref}`;
+}
+function isPublicRef(ref) {
+  return ref.name.startsWith("refs/heads/") || ref.name.startsWith("refs/tags/");
+}
+function requireReleaseReachable(appDir, release2, refs) {
+  if (!release2?.commitOid) return;
+  const known = resolveCommit(appDir, release2.commitOid) !== null;
+  const reachable = known && refs.some((ref) => isAncestor(appDir, release2.commitOid, ref.oid));
+  if (!reachable) {
+    throw new Refusal(
+      `Live release #${release2.seq} (${release2.commitOid.slice(0, 10)}) is not reachable from a public branch or tag. Redeploy a public branch before changing source.`,
+      "release_not_public"
+    );
+  }
+}
+function releaseExpectation(release2) {
+  return {
+    expectedReleaseId: release2?.id ?? null,
+    expectedReleaseCommitOid: release2?.commitOid ?? null
+  };
+}
+function sameSource(left, right) {
+  return left?.provider === right.provider && (left.provider !== "github" || right.provider === "github" && left.repository === right.repository);
+}
+function sameRefs(left, right) {
+  if (left.length !== right.length) return false;
+  const expected = new Map(right.map((ref) => [ref.name, ref.oid]));
+  return left.every((ref) => expected.get(ref.name) === ref.oid);
+}
+
+// src/cli/lib/identity-migration-api.ts
+async function getIdentityMigration(deployUrl, token, appId) {
+  try {
+    const result = await apiFetch(
+      deployUrl,
+      token,
+      `/api/apps/${encodeURIComponent(appId)}/identity-migration`
+    );
+    return result.migration;
+  } catch (error) {
+    if (error instanceof ApiError && error.code === "migration_not_found") return null;
+    throw error;
+  }
+}
+async function prepareIdentityMigration(deployUrl, token, legacyAppId, input) {
+  const result = await apiFetch(
+    deployUrl,
+    token,
+    `/api/apps/${encodeURIComponent(legacyAppId)}/identity-migration/prepare`,
+    { method: "POST", body: JSON.stringify(input) }
+  );
+  return result.migration;
+}
+async function inspectIdentityMigration(deployUrl, token, legacyAppId, input) {
+  const result = await apiFetch(
+    deployUrl,
+    token,
+    `/api/apps/${encodeURIComponent(legacyAppId)}/identity-migration/inspect`,
+    { method: "POST", body: JSON.stringify(input) }
+  );
+  return result.inventory;
+}
+async function commitIdentityMigration(deployUrl, token, appId, input) {
+  const result = await apiFetch(
+    deployUrl,
+    token,
+    `/api/apps/${encodeURIComponent(appId)}/identity-migration/commit`,
+    { method: "POST", body: JSON.stringify(input) }
+  );
+  return result.migration;
+}
+async function cancelIdentityMigration(deployUrl, token, appId) {
+  await apiFetch(
+    deployUrl,
+    token,
+    `/api/apps/${encodeURIComponent(appId)}/identity-migration`,
+    { method: "DELETE" }
+  );
+}
+async function rollbackIdentityMigration(deployUrl, token, appId) {
+  const result = await apiFetch(
+    deployUrl,
+    token,
+    `/api/apps/${encodeURIComponent(appId)}/identity-migration/rollback`,
+    { method: "POST" }
+  );
+  return result.migration;
+}
+
+// src/cli/commands/migrate.ts
+var STRICT_APP_ID_RE2 = /^app_[0-9A-HJKMNP-TV-Z]{26}$/;
+var migrate_default = defineDeepspaceCommand({
+  meta: {
+    name: "migrate",
+    description: "Upgrade a legacy GitHub app to an immutable app id without moving its data"
+  },
+  args: {
+    remote: {
+      type: "string",
+      description: "GitHub remote name when it cannot be inferred (default: origin)",
+      required: false
+    },
+    env: {
+      type: "string",
+      alias: "e",
+      description: "wrangler.toml environment whose app id should be migrated",
+      required: false
+    },
+    "dry-run": {
+      type: "boolean",
+      description: "Inspect prerequisites and show the migration without changing anything",
+      default: false
+    },
+    cancel: {
+      type: "boolean",
+      description: "Cancel a prepared migration after restoring and publishing the legacy id",
+      default: false
+    },
+    rollback: {
+      type: "boolean",
+      description: "Roll back a committed migration before any canonical deploy starts",
+      default: false
+    }
+  },
+  async run({ args }) {
+    const recoveryMode = args.cancel === true ? "cancel" : args.rollback === true ? "rollback" : null;
+    const exclusiveModes = [args["dry-run"], args.cancel, args.rollback].filter(Boolean).length;
+    if (exclusiveModes > 1) {
+      throw new Refusal(
+        "Use only one of --dry-run, --cancel, or --rollback.",
+        "conflicting_migration_mode"
+      );
+    }
+    const appDir = findAppDir();
+    if (!appDir) {
+      throw new Refusal("Run this command from a DeepSpace app Git checkout.", "not_in_app_repo");
+    }
+    assertSyncableRepo(appDir);
+    const envName = typeof args.env === "string" && args.env ? args.env : void 0;
+    const currentAppId = readAppId(appDir, envName) ?? readLegacyAppId(appDir, envName);
+    if (!currentAppId) {
+      throw new Refusal(
+        "wrangler.toml has no unambiguous DeepSpace app identity for this environment.",
+        "missing_app_id"
+      );
+    }
+    if (!STRICT_APP_ID_RE2.test(currentAppId)) requireTrackedWrangler(appDir);
+    const token = await ensureToken();
+    const deployUrl = deployBaseUrl();
+    const existingMigration = await getIdentityMigration(deployUrl, token, currentAppId);
+    if (recoveryMode) {
+      if (!existingMigration) {
+        if (!args.json) console.log("No reversible identity migration is recorded.");
+        return { data: { status: "no_migration", appId: currentAppId } };
+      }
+      return recoverMigration({
+        mode: recoveryMode,
+        appDir,
+        envName,
+        remoteName: typeof args.remote === "string" ? args.remote : void 0,
+        currentAppId,
+        token,
+        deployUrl,
+        migration: existingMigration,
+        json: args.json
+      });
+    }
+    if (STRICT_APP_ID_RE2.test(currentAppId)) {
+      if (!existingMigration) {
+        reportAlreadyModern(currentAppId, args.json);
+        return { data: { status: "already_modern", appId: currentAppId } };
+      }
+      if (args["dry-run"]) {
+        reportMigration(existingMigration, args.json);
+        return { data: { status: existingMigration.status, migration: existingMigration } };
+      }
+      return continuePreparedMigration({
+        appDir,
+        envName,
+        remoteName: typeof args.remote === "string" ? args.remote : void 0,
+        token,
+        deployUrl,
+        migration: existingMigration,
+        json: args.json
+      });
+    }
+    if (existingMigration && existingMigration.status !== "prepared" && existingMigration.status !== "rolled_back") {
+      throw new Refusal(
+        `The registry already uses ${existingMigration.appId}, but wrangler.toml still uses ${currentAppId}. Restore the migration commit before deploying.`,
+        "migration_config_stale",
+        { extra: { migration: existingMigration } }
+      );
+    }
+    const remote = requireGitHubRemote2(
+      appDir,
+      typeof args.remote === "string" ? args.remote : void 0
+    );
+    const head = requirePublishedHead2(appDir, remote);
+    const proposedAppId = existingMigration?.appId ?? mintAppId();
+    const inventory = await inspectIdentityMigration(deployUrl, token, currentAppId, {
+      destinationAppId: proposedAppId,
+      repository: remote.repository
+    });
+    if (!inventory.ready) {
+      throw new Refusal(
+        `Migration preflight is blocked: ${inventory.blockers.map((blocker) => blocker.message).join("; ")}`,
+        "migration_preflight_blocked",
+        { extra: { inventory } }
+      );
+    }
+    if (args["dry-run"]) {
+      if (!args.json) {
+        console.log(`Legacy app: ${currentAppId}`);
+        console.log(`GitHub: ${remote.repository} (${head.branch} @ ${head.oid.slice(0, 10)})`);
+        console.log(
+          `Immutable app id: ${proposedAppId}${existingMigration ? "" : " (not reserved)"}`
+        );
+        console.log(
+          `Registry rows to re-key: app=1 routes=${inventory.rekey.routes.length} collaborators=${inventory.rekey.collaborators.length} pendingInvites=${inventory.rekey.pendingCollaborators.length} transfers=${inventory.rekey.transfer ? 1 : 0}`
+        );
+        console.log(
+          `Physical stores retained at ${inventory.app.resourceId}: ${inventory.retainedPhysicalStores.map((store) => store.kind).join(", ")}`
+        );
+        console.log("No changes made.");
+      }
+      return {
+        data: {
+          status: "ready",
+          legacyAppId: currentAppId,
+          proposedAppId,
+          resourceId: inventory.app.resourceId,
+          repository: remote.repository,
+          branch: head.branch,
+          commitOid: head.oid,
+          sourceClaimRequired: inventory.app.sourceClaimRequired,
+          inventory
+        }
+      };
+    }
+    const migration = existingMigration?.status === "prepared" ? existingMigration : await prepareIdentityMigration(deployUrl, token, currentAppId, {
+      destinationAppId: proposedAppId,
+      repository: remote.repository,
+      expectedSourceRevision: inventory.app.sourceRevision
+    });
+    writeAppId(appDir, migration.appId, { wranglerEnv: envName, force: true });
+    throw commitRequired(appDir, migration, envName);
+  }
+});
+async function recoverMigration(input) {
+  const { mode, appDir, envName, remoteName, currentAppId, token, deployUrl, migration, json } = input;
+  if (migration.status === "verified" || migration.deployStartedAt) {
+    throw new Refusal(
+      "A canonical deployment has started. Registry rollback is no longer safe; use the forward-recovery procedure to repair or redeploy the canonical app.",
+      "forward_recovery_required",
+      { extra: { migration } }
+    );
+  }
+  if (migration.status === "rolled_back") {
+    if (currentAppId !== migration.legacyAppId) {
+      writeAppId(appDir, migration.legacyAppId, { wranglerEnv: envName, force: true });
+      throw restoreLegacyCommitRequired(appDir, migration, envName);
+    }
+    reportMigration(migration, json);
+    return { data: { status: "rolled_back", migration } };
+  }
+  if (mode === "cancel" && migration.status !== "prepared") {
+    throw new Refusal(
+      "This migration is committed. Use --rollback before any canonical deploy starts.",
+      "migration_rollback_required",
+      { extra: { migration } }
+    );
+  }
+  if (mode === "rollback" && migration.status !== "committed") {
+    throw new Refusal(
+      "This migration is only prepared. Use --cancel instead.",
+      "migration_cancel_required",
+      { extra: { migration } }
+    );
+  }
+  if (currentAppId !== migration.legacyAppId) {
+    writeAppId(appDir, migration.legacyAppId, { wranglerEnv: envName, force: true });
+    throw restoreLegacyCommitRequired(appDir, migration, envName);
+  }
+  const remote = requireGitHubRemote2(appDir, remoteName, migration.repository);
+  requirePublishedHead2(appDir, remote);
+  if (mode === "cancel") {
+    await cancelIdentityMigration(deployUrl, token, migration.legacyAppId);
+    if (!json) console.log(`Canceled ${migration.legacyAppId} \u2192 ${migration.appId}.`);
+    return { data: { status: "cancelled", legacyAppId: migration.legacyAppId } };
+  }
+  const rolledBack = await rollbackIdentityMigration(deployUrl, token, migration.appId);
+  reportMigration(rolledBack, json);
+  return { data: { status: "rolled_back", migration: rolledBack } };
+}
+async function continuePreparedMigration(input) {
+  const { appDir, envName, remoteName, token, deployUrl, migration, json } = input;
+  if (migration.status === "rolled_back") {
+    throw new Refusal(
+      `This migration was rolled back. Restore DEEPSPACE_APP_ID to ${migration.legacyAppId} before continuing.`,
+      "migration_rolled_back"
+    );
+  }
+  if (migration.status === "verified") {
+    reportMigration(migration, json);
+    return { data: { status: "verified", migration } };
+  }
+  if (migration.status === "committed") {
+    throw deployRequired(appDir, migration, envName);
+  }
+  if (!isWorkTreeClean(appDir)) {
+    const wranglerPath = wranglerRepoPath(appDir);
+    if (statusFiles(repoToplevel(appDir)).includes(wranglerPath)) {
+      throw commitRequired(appDir, migration, envName);
+    }
+    throw new Refusal(
+      "Commit or discard unrelated working-tree changes before completing the migration.",
+      "dirty_worktree"
+    );
+  }
+  const remote = requireGitHubRemote2(appDir, remoteName, migration.repository);
+  const head = requireLocalHead2(appDir);
+  const remoteOid = remoteBranchOid(appDir, remote.name, head.branch);
+  if (remoteOid !== head.oid) {
+    throw new Refusal(
+      `GitHub ${remote.repository} does not have ${head.branch} at ${head.oid.slice(0, 10)}. Push the migration commit, then rerun.`,
+      "github_push_required",
+      {
+        actionRequired: true,
+        action: { cwd: appDir, argv: ["git", "push", remote.name, head.branch] },
+        extra: { appId: migration.appId, repository: remote.repository, ...head }
+      }
+    );
+  }
+  const committed = await commitIdentityMigration(deployUrl, token, migration.appId, {
+    commitOid: head.oid,
+    branch: head.branch
+  });
+  throw deployRequired(appDir, committed, envName);
+}
+function requireGitHubRemote2(appDir, remoteName, repository) {
+  const selected = selectGitHubRemote(appDir, { name: remoteName, repository });
+  if (selected) return selected;
+  throw new Refusal(
+    remoteName ? `Remote "${remoteName}" is not the expected GitHub repository.` : repository ? `No local GitHub remote points at ${repository}. Add one or pass --remote <name>.` : "No unambiguous GitHub remote was found. Add `origin` or pass --remote <name>.",
+    "github_remote_required"
+  );
+}
+function requireLocalHead2(appDir) {
+  const branch = currentBranch(appDir);
+  if (!branch) throw new Refusal("HEAD is detached; switch to a branch first.", "detached_head");
+  const oid = resolveCommit(appDir, "HEAD");
+  if (!oid) throw new Refusal("The repository has no commit to publish.", "no_commits");
+  return { branch, oid };
+}
+function requirePublishedHead2(appDir, remote) {
+  if (!isWorkTreeClean(appDir)) {
+    throw new Refusal(
+      "Commit or discard local changes before preparing migration.",
+      "dirty_worktree"
+    );
+  }
+  const head = requireLocalHead2(appDir);
+  if (remoteBranchOid(appDir, remote.name, head.branch) !== head.oid) {
+    throw new Refusal(
+      `GitHub ${remote.repository} does not have ${head.branch} at ${head.oid.slice(0, 10)}. Push it, then rerun.`,
+      "github_push_required",
+      {
+        actionRequired: true,
+        action: { cwd: appDir, argv: ["git", "push", remote.name, head.branch] },
+        extra: { repository: remote.repository, ...head }
+      }
+    );
+  }
+  return head;
+}
+function commitRequired(appDir, migration, envName) {
+  const wranglerPath = wranglerRepoPath(appDir);
+  return new Refusal(
+    `Prepared ${migration.legacyAppId} \u2192 ${migration.appId}. Commit the deterministic wrangler.toml change, then rerun.`,
+    "migration_commit_required",
+    {
+      actionRequired: true,
+      action: {
+        cwd: repoToplevel(appDir),
+        argv: [
+          "git",
+          "commit",
+          "--only",
+          "--message",
+          `Migrate DeepSpace app identity to ${migration.appId}`,
+          "--",
+          wranglerPath
+        ]
+      },
+      extra: { migration, env: envName ?? null }
+    }
+  );
+}
+function restoreLegacyCommitRequired(appDir, migration, envName) {
+  const wranglerPath = wranglerRepoPath(appDir);
+  return new Refusal(
+    `Restored ${migration.legacyAppId} in wrangler.toml. Commit and push this recovery change, then rerun.`,
+    "migration_restore_commit_required",
+    {
+      actionRequired: true,
+      action: {
+        cwd: repoToplevel(appDir),
+        argv: [
+          "git",
+          "commit",
+          "--only",
+          "--message",
+          `Restore DeepSpace app identity to ${migration.legacyAppId}`,
+          "--",
+          wranglerPath
+        ]
+      },
+      extra: { migration, env: envName ?? null }
+    }
+  );
+}
+function wranglerRepoPath(appDir) {
+  return `${gitLine(appDir, ["rev-parse", "--show-prefix"])}wrangler.toml`;
+}
+function requireTrackedWrangler(appDir) {
+  const path = wranglerRepoPath(appDir);
+  if (runGit(repoToplevel(appDir), ["ls-files", "--error-unmatch", "--", path], { allowFail: true }).status !== 0) {
+    throw new Refusal(
+      "Track, commit, and push wrangler.toml before migrating; GitHub must already contain the deployment configuration.",
+      "wrangler_not_tracked"
+    );
+  }
+}
+function deployRequired(appDir, migration, envName) {
+  return new Refusal(
+    `Identity cutover committed; deploy once to verify ${migration.appId} on the existing physical resources.`,
+    "migration_deploy_required",
+    {
+      actionRequired: true,
+      action: {
+        cwd: appDir,
+        argv: ["deepspace", "deploy", ...envName ? ["--env", envName] : []]
+      },
+      extra: { migration, env: envName ?? null }
+    }
+  );
+}
+function reportAlreadyModern(appId, json) {
+  if (!json) console.log(`${appId} already uses an immutable DeepSpace app id.`);
+}
+function reportMigration(migration, json) {
+  if (json) return;
+  console.log(`Migration: ${migration.legacyAppId} \u2192 ${migration.appId}`);
+  console.log(`Status: ${migration.status}`);
+  console.log(`Physical resources: ${migration.resourceId}`);
+  console.log(`GitHub: ${migration.repository}`);
+}
+
 // src/cli/cli.ts
 var __dirname = dirname10(fileURLToPath3(import.meta.url));
 var pkg = JSON.parse(readFileSync25(join23(__dirname, "..", "package.json"), "utf-8"));
@@ -11216,7 +12263,7 @@ var auth = defineCommand14({
 var app = defineCommand14({
   meta: {
     name: "app",
-    description: "The app itself: create, init, list, undeploy, transfer, collaborators, domain, library, usage"
+    description: "The app itself: create, init, list, source, migrate, undeploy, transfer, collaborators, domain, library, usage"
   },
   subCommands: {
     create: create2,
@@ -11227,7 +12274,9 @@ var app = defineCommand14({
     collaborators: collaborators_default,
     domain: domain_default,
     library: library_default,
-    usage: usage_default
+    usage: usage_default,
+    source: source_default,
+    migrate: migrate_default
   }
 });
 var devGroup = defineCommand14({
@@ -11278,55 +12327,21 @@ var main = defineCommand14({
   // command. Citty's default behavior when no subcommand matches is to print
   // help, which is what we want for `deepspace` with no args.
 });
-function editDistance2(a, b) {
-  const dp = Array.from({ length: a.length + 1 }, (_, i) => [
-    i,
-    ...new Array(b.length).fill(0)
-  ]);
-  for (let j = 1; j <= b.length; j++) dp[0][j] = j;
-  for (let i = 1; i <= a.length; i++) {
-    for (let j = 1; j <= b.length; j++) {
-      dp[i][j] = Math.min(
-        dp[i - 1][j] + 1,
-        dp[i][j - 1] + 1,
-        dp[i - 1][j - 1] + (a[i - 1] === b[j - 1] ? 0 : 1)
-      );
-    }
-  }
-  return dp[a.length][b.length];
+function commandTree() {
+  return main.subCommands ?? {};
 }
-function closestCommand(input, candidates) {
-  let best = null;
-  let bestDist = 4;
-  for (const c of candidates) {
-    const d = editDistance2(input.toLowerCase(), c);
-    if (d < bestDist) {
-      best = c;
-      bestDist = d;
-    }
-  }
-  return best;
+function unknownCommandMessage(unknown) {
+  return `Unknown command: ${unknown.attemptedPath.join(" ")} \u2014 did you mean \`${unknown.suggestion.join(" ")}\`?`;
 }
 function assertKnownCommandPath(argv) {
-  let table = main.subCommands;
-  let path = "deepspace";
-  for (const tok of argv) {
-    if (!table || tok.startsWith("-")) return;
-    const entry = table[tok];
-    if (!entry) {
-      const hint = closestCommand(tok, Object.keys(table));
-      console.error(
-        `Unknown command: ${path} ${tok}${hint ? ` \u2014 did you mean \`${path} ${hint}\`?` : ""}
-Run \`${path} --help\` for the command list.`
-      );
-      if (hint) {
-        printAction({ cwd: process.cwd(), argv: [...path.split(" "), hint] });
-      }
-      process.exit(1);
-    }
-    path += ` ${tok}`;
-    table = entry.subCommands;
-  }
+  const unknown = findUnknownCommand(argv, commandTree());
+  if (!unknown) return;
+  console.error(
+    `${unknownCommandMessage(unknown)}
+Run \`${unknown.helpPath.join(" ")} --help\` for the command list.`
+  );
+  printAction({ cwd: process.cwd(), argv: unknown.suggestion });
+  process.exit(1);
 }
 var rawArgs = process.argv.slice(2);
 var wantsHelp = rawArgs.some((arg) => arg === "--help" || arg === "-h");
@@ -11340,15 +12355,14 @@ if (DEEPSPACE_ENV === "invalid") {
   process.exit(1);
 }
 if (rawArgs.includes("--json") && !wantsHelp) {
-  const first = rawArgs.find((a) => !a.startsWith("-"));
-  if (first && !Object.prototype.hasOwnProperty.call(main.subCommands ?? {}, first)) {
-    const hint = closestCommand(first, Object.keys(main.subCommands ?? {}));
+  const unknown = findUnknownCommand(rawArgs, commandTree());
+  if (unknown) {
     console.log(
       JSON.stringify({
         ok: false,
         code: "unknown_command",
-        error: `Unknown command: deepspace ${first}${hint ? ` \u2014 did you mean \`deepspace ${hint}\`?` : ""}`,
-        ...hint ? { action: { cwd: process.cwd(), argv: ["deepspace", hint] } } : {}
+        error: unknownCommandMessage(unknown),
+        action: { cwd: process.cwd(), argv: unknown.suggestion }
       })
     );
     process.exit(1);
@@ -11366,7 +12380,7 @@ if (rawArgs.includes("--json") && !wantsHelp) {
     process.exit(1);
   });
 } else {
-  if (!wantsHelp) assertKnownCommandPath(rawArgs);
+  assertKnownCommandPath(rawArgs);
   runMain(wrapCommandErrors(main));
 }
 //# sourceMappingURL=cli.js.map