deepspace 0.9.0 → 0.9.1

package/CHANGELOG.md

@@ -1,5 +1,15 @@
 # deepspace
 
+## 0.9.1
+
+### Patch Changes
+
+- Keep `deepspace app migrate` as the permanent ordered app-upgrade runner and
+  repair obsolete `x-app-name` platform identity wiring before a canonical app
+  deployment, without changing retained `APP_NAME` data namespaces. Track
+  source-only migration commits against live release lineage so both GitHub and
+  DeepSpace apps are guided through the required deploy.
+
 ## 0.9.0
 
 ### Minor Changes

package/README.md

@@ -90,9 +90,9 @@ npx deepspace deploy     # deploy to *.app.space
 ```
 
 The [normative CLI hierarchy](../../docs/platform/cli-contract.md#public-command-hierarchy)
-keeps durable app identity and lifecycle operations under `deepspace app`,
+keeps durable app lifecycle and version migrations under `deepspace app`,
 while checkout-oriented Git, workspace, release, and deploy operations stay
-top-level. In particular, legacy identity migration is
+top-level. In particular, app migration is
 `deepspace app migrate`; there is no top-level `deepspace migrate` alias.
 
 Every app has one authoritative Git repository. DeepSpace source is the packaged
@@ -118,17 +118,28 @@ atomic authority change; switching back uses the same commands. Commands support
 [repository guide](https://github.com/deepdotspace/deepspace/blob/main/docs/platform/repo-store-git.md)
 for workspaces, releases, and rollback.
 
-Legacy GitHub apps whose `DEEPSPACE_APP_ID` is still name-shaped migrate in
-place with one resumable command:
+`deepspace app migrate` is the permanent upgrade runner for breaking app
+changes. It contains an ordered set of structural, idempotent migrations, so
+agents and developers keep using the same command across releases:
 
 ```bash
 npx deepspace app migrate --dry-run
 npx deepspace app migrate
 ```
 
-The dry-run lists the exact registry rows that will be re-keyed and the
-physical stores that remain at the existing resource id. The command then
-pauses for the normal manual GitHub commit/push and finishes with one deploy.
+The dry-run lists pending source migrations without changing files. For a
+legacy GitHub app whose `DEEPSPACE_APP_ID` is still name-shaped, it also lists
+the exact registry rows that will be re-keyed and the physical stores that
+remain at the existing resource id. The command applies only transformations
+it recognizes safely, pauses for normal commit/push, and finishes with one
+deploy. Source migration commits carry a machine-readable Git trailer, so the
+next run can compare them with the live release and return the deploy action
+without a local state file. Rerun after each returned action; when nothing is
+pending it reports `up_to_date`. This is the same workflow for GitHub and
+DeepSpace source; only their normal push behavior differs. `APP_NAME`-based
+legacy room and storage addresses are retained; canonical `DEEPSPACE_APP_ID`
+is used only for logical identity and platform authentication.
+
 Keep deploy, release rollback, and undeploy idle from the mutating command until
 that returned deploy begins; normal app traffic continues throughout.
 Before that deploy starts, `--cancel` reverses a prepared migration and

package/dist/cli.js

@@ -3,8 +3,8 @@
 // src/cli/cli.ts
 import { defineCommand as defineCommand14, runMain, runCommand } from "citty";
 import { sync as spawnSync8 } from "cross-spawn";
-import { readFileSync as readFileSync25, existsSync as existsSync24 } from "fs";
-import { dirname as dirname10, join as join23 } from "path";
+import { readFileSync as readFileSync26, existsSync as existsSync24 } from "fs";
+import { dirname as dirname10, join as join24 } from "path";
 import { fileURLToPath as fileURLToPath3 } from "url";
 
 // src/cli/lib/spinner.ts
@@ -11783,6 +11783,177 @@ function sameRefs(left, right) {
   return left.every((ref) => expected.get(ref.name) === ref.oid);
 }
 
+// src/cli/lib/app-migrations.ts
+import { lstatSync, readFileSync as readFileSync25, writeFileSync as writeFileSync10 } from "fs";
+import { join as join23 } from "path";
+var CANONICAL_IDENTITY_WIRE_ID = "2026-08-canonical-app-identity-wire";
+var SOURCE_MIGRATIONS = [
+  {
+    id: CANONICAL_IDENTITY_WIRE_ID,
+    description: "Use the immutable app id for authenticated platform requests",
+    transform: migrateCanonicalIdentityWire,
+    findBlockers: findLegacyIdentityWireBlockers
+  }
+];
+var APP_MIGRATION_DEFINITIONS = SOURCE_MIGRATIONS.map(
+  ({ id, description }) => ({ id, description })
+);
+function planAppMigrations(appDir) {
+  const repo = repoToplevel(appDir);
+  const appPrefix = gitLine(appDir, ["rev-parse", "--show-prefix"]);
+  const tracked = splitNulFields(runGit(repo, ["ls-files", "-z"]).stdout);
+  const perMigration = /* @__PURE__ */ new Map();
+  const blockers = [];
+  const edits = [];
+  for (const repoPath of tracked) {
+    if (!isSourcePath(repoPath, appPrefix)) continue;
+    const absolutePath = join23(repo, repoPath);
+    let stat;
+    try {
+      stat = lstatSync(absolutePath);
+    } catch {
+      continue;
+    }
+    if (!stat.isFile() || stat.isSymbolicLink()) continue;
+    const before = readFileSync25(absolutePath, "utf-8");
+    let after = before;
+    for (const migration of SOURCE_MIGRATIONS) {
+      const result = migration.transform(after);
+      after = result.source;
+      if (result.replacements > 0) {
+        const planned = perMigration.get(migration.id) ?? {
+          id: migration.id,
+          description: migration.description,
+          files: [],
+          replacements: 0
+        };
+        planned.files.push(repoPath);
+        planned.replacements += result.replacements;
+        perMigration.set(migration.id, planned);
+      }
+      blockers.push(...migration.findBlockers(after, repoPath));
+    }
+    if (after !== before) edits.push({ path: repoPath, before, after });
+  }
+  return {
+    pending: SOURCE_MIGRATIONS.flatMap((migration) => {
+      const planned = perMigration.get(migration.id);
+      return planned ? [{ ...planned, files: [...new Set(planned.files)].sort() }] : [];
+    }),
+    changedFiles: edits.map((edit) => edit.path).sort(),
+    blockers,
+    edits
+  };
+}
+function applyAppMigrationPlan(appDir, plan) {
+  if (plan.blockers.length > 0) {
+    throw new Error("Cannot apply an app migration plan with unresolved blockers.");
+  }
+  const repo = repoToplevel(appDir);
+  for (const edit of plan.edits) {
+    const absolutePath = join23(repo, edit.path);
+    if (readFileSync25(absolutePath, "utf-8") !== edit.before) {
+      throw new Error(`Migration input changed after planning: ${edit.path}`);
+    }
+  }
+  for (const edit of plan.edits) writeFileSync10(join23(repo, edit.path), edit.after);
+}
+function isSourcePath(repoPath, appPrefix) {
+  if (appPrefix && !repoPath.startsWith(appPrefix)) return false;
+  return /\.(?:[cm]?[jt]sx?)$/.test(repoPath);
+}
+function migrateCanonicalIdentityWire(source) {
+  let replacements = 0;
+  const lines = source.split("\n");
+  for (let index = 0; index < lines.length; index++) {
+    let line = lines[index];
+    line = line.replace(
+      /(\.set\(\s*)(['"])x-app-name\2(\s*,\s*)([A-Za-z_$][\w$]*(?:\.[A-Za-z_$][\w$]*)*)\.APP_NAME(\s*\))/g,
+      (_match, open, quote, separator, receiver, close) => {
+        replacements++;
+        return `${open}${quote}x-app-id${quote}${separator}${receiver}.DEEPSPACE_APP_ID${close}`;
+      }
+    );
+    line = line.replace(
+      /(['"])x-app-name\1(\s*:\s*)([A-Za-z_$][\w$]*(?:\.[A-Za-z_$][\w$]*)*)\.APP_NAME/g,
+      (_match, quote, separator, receiver) => {
+        replacements++;
+        return `${quote}x-app-id${quote}${separator}${receiver}.DEEPSPACE_APP_ID`;
+      }
+    );
+    line = line.replace(
+      /(\[\s*)(['"])x-app-name\2(\s*\]\s*=\s*)([A-Za-z_$][\w$]*(?:\.[A-Za-z_$][\w$]*)*)\.APP_NAME/g,
+      (_match, open, quote, separator, receiver) => {
+        replacements++;
+        return `${open}${quote}x-app-id${quote}${separator}${receiver}.DEEPSPACE_APP_ID`;
+      }
+    );
+    line = line.replace(
+      /(forwardedParams\.set\(\s*)(['"])appName\2(\s*,\s*)([A-Za-z_$][\w$]*(?:\.[A-Za-z_$][\w$]*)*)\.APP_NAME(\s*\))/g,
+      (_match, open, quote, separator, receiver, close) => {
+        replacements++;
+        return `${open}${quote}appId${quote}${separator}${receiver}.DEEPSPACE_APP_ID${close}`;
+      }
+    );
+    lines[index] = line;
+  }
+  if (replacements === 0) return { source, replacements };
+  let migrated = lines.join("\n");
+  if (/forwardedParams\.set\(\s*['"]appId['"]/.test(migrated)) {
+    migrated = migrated.replaceAll("injectAppName", "injectAppId").replaceAll("`?appName=...`", "`?appId=...`").replaceAll("Inject appName into the query string", "Inject appId into the query string").replaceAll("caller-supplied appName", "caller-supplied appId").replaceAll(
+      "/_deepspace/subscriptions/plans?appName=",
+      "/_deepspace/subscriptions/plans?appId="
+    );
+  }
+  migrated = migrated.replaceAll(
+    "APP_IDENTITY_TOKEN + APP_NAME",
+    "APP_IDENTITY_TOKEN + DEEPSPACE_APP_ID"
+  );
+  return {
+    source: ensureCanonicalIdentityProperties(migrated),
+    replacements
+  };
+}
+function ensureCanonicalIdentityProperties(source) {
+  const lines = source.split("\n");
+  for (let index = lines.length - 1; index >= 0; index--) {
+    const match = /^(\s*)(?:readonly\s+)?APP_NAME\??\s*:\s*string\s*([;,]?)\s*$/.exec(lines[index]);
+    if (!match || blockAlreadyDeclaresCanonicalId(lines, index, match[1].length)) continue;
+    const suffix = match[2] ?? "";
+    lines.splice(index + 1, 0, `${match[1]}DEEPSPACE_APP_ID: string${suffix}`);
+  }
+  return lines.join("\n");
+}
+function blockAlreadyDeclaresCanonicalId(lines, propertyIndex, propertyIndent) {
+  for (const direction of [-1, 1]) {
+    for (let index = propertyIndex + direction; index >= 0 && index < lines.length; index += direction) {
+      const line = lines[index];
+      if (/^\s*(?:readonly\s+)?DEEPSPACE_APP_ID\??\s*:/.test(line)) return true;
+      const trimmed = line.trimStart();
+      if (!trimmed) continue;
+      const indent = line.length - trimmed.length;
+      if (indent < propertyIndent && (trimmed.includes("{") || trimmed.startsWith("}"))) break;
+    }
+  }
+  return false;
+}
+function findLegacyIdentityWireBlockers(source, file) {
+  const blockers = [];
+  for (const [index, line] of source.split("\n").entries()) {
+    const trimmed = line.trimStart();
+    if (!/['"]x-app-name['"]/.test(line) || /\.delete\(\s*['"]x-app-name['"]/.test(line) || trimmed.startsWith("//") || trimmed.startsWith("/*") || trimmed.startsWith("*")) {
+      continue;
+    }
+    blockers.push({
+      migrationId: CANONICAL_IDENTITY_WIRE_ID,
+      file,
+      line: index + 1,
+      message: "This app still sends the removed x-app-name identity header in a form the safe migration cannot rewrite."
+    });
+  }
+  return blockers;
+}
+
 // src/cli/lib/identity-migration-api.ts
 async function getIdentityMigration(deployUrl, token, appId) {
   try {
@@ -11847,7 +12018,7 @@ 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"
+    description: "Apply pending DeepSpace app migrations without moving retained data"
   },
   args: {
     remote: {
@@ -11920,14 +12091,54 @@ var migrate_default = defineDeepspaceCommand({
         json: args.json
       });
     }
+    const sourcePlan = planAppMigrations(appDir);
+    if (sourcePlan.blockers.length > 0) {
+      const first = sourcePlan.blockers[0];
+      throw new Refusal(
+        `Migration ${first.migrationId} needs a manual source update at ${first.file}:${first.line}. ${first.message}`,
+        "source_migration_blocked",
+        { extra: { blockers: sourcePlan.blockers } }
+      );
+    }
     if (STRICT_APP_ID_RE2.test(currentAppId)) {
       if (!existingMigration) {
-        reportAlreadyModern(currentAppId, args.json);
-        return { data: { status: "already_modern", appId: currentAppId } };
+        if (args["dry-run"] && sourcePlan.pending.length > 0) {
+          reportSourcePlan(sourcePlan, args.json);
+          return {
+            data: {
+              status: "ready",
+              appId: currentAppId,
+              sourceMigrations: sourcePlan.pending
+            }
+          };
+        }
+        if (sourcePlan.pending.length > 0) {
+          requireSourceMigrationWorktree(appDir);
+          applyAppMigrationPlan(appDir, sourcePlan);
+          throw sourceMigrationCommitRequired(appDir, sourcePlan);
+        }
+        await requireSourceMigrationDeploy(appDir, currentAppId, deployUrl, token);
+        reportUpToDate(currentAppId, args.json);
+        return { data: { status: "up_to_date", appId: currentAppId } };
+      }
+      if (sourcePlan.pending.length === 0 && existingMigration.status === "verified") {
+        await requireSourceMigrationDeploy(appDir, currentAppId, deployUrl, token);
       }
       if (args["dry-run"]) {
         reportMigration(existingMigration, args.json);
-        return { data: { status: existingMigration.status, migration: existingMigration } };
+        reportSourcePlan(sourcePlan, args.json);
+        return {
+          data: {
+            status: existingMigration.status,
+            migration: existingMigration,
+            sourceMigrations: sourcePlan.pending
+          }
+        };
+      }
+      if (sourcePlan.pending.length > 0) {
+        requireSourceMigrationWorktree(appDir, existingMigration.status === "prepared");
+        applyAppMigrationPlan(appDir, sourcePlan);
+        throw existingMigration.status === "prepared" ? commitRequired(appDir, existingMigration, envName, sourcePlan.changedFiles) : sourceMigrationCommitRequired(appDir, sourcePlan);
       }
       return continuePreparedMigration({
         appDir,
@@ -11978,6 +12189,7 @@ var migrate_default = defineDeepspaceCommand({
         );
         console.log("No changes made.");
       }
+      reportSourcePlan(sourcePlan, args.json);
       return {
         data: {
           status: "ready",
@@ -11988,6 +12200,7 @@ var migrate_default = defineDeepspaceCommand({
           branch: head.branch,
           commitOid: head.oid,
           sourceClaimRequired: inventory.app.sourceClaimRequired,
+          sourceMigrations: sourcePlan.pending,
           inventory
         }
       };
@@ -11997,8 +12210,9 @@ var migrate_default = defineDeepspaceCommand({
       repository: remote.repository,
       expectedSourceRevision: inventory.app.sourceRevision
     });
+    applyAppMigrationPlan(appDir, sourcePlan);
     writeAppId(appDir, migration.appId, { wranglerEnv: envName, force: true });
-    throw commitRequired(appDir, migration, envName);
+    throw commitRequired(appDir, migration, envName, sourcePlan.changedFiles);
   }
 });
 async function recoverMigration(input) {
@@ -12128,10 +12342,11 @@ function requirePublishedHead2(appDir, remote) {
   }
   return head;
 }
-function commitRequired(appDir, migration, envName) {
+function commitRequired(appDir, migration, envName, additionalPaths = []) {
   const wranglerPath = wranglerRepoPath(appDir);
+  const migrationPaths = [.../* @__PURE__ */ new Set([wranglerPath, ...additionalPaths])].sort();
   return new Refusal(
-    `Prepared ${migration.legacyAppId} \u2192 ${migration.appId}. Commit the deterministic wrangler.toml change, then rerun.`,
+    `Prepared ${migration.legacyAppId} \u2192 ${migration.appId}. Commit the deterministic app migration changes, then rerun.`,
     "migration_commit_required",
     {
       actionRequired: true,
@@ -12144,13 +12359,102 @@ function commitRequired(appDir, migration, envName) {
           "--message",
           `Migrate DeepSpace app identity to ${migration.appId}`,
           "--",
-          wranglerPath
+          ...migrationPaths
         ]
       },
       extra: { migration, env: envName ?? null }
     }
   );
 }
+function sourceMigrationCommitRequired(appDir, plan) {
+  const migrationIds = plan.pending.map((migration) => migration.id);
+  return new Refusal(
+    `Applied ${migrationIds.join(", ")}. Commit the deterministic app migration changes, then rerun.`,
+    "migration_commit_required",
+    {
+      actionRequired: true,
+      action: {
+        cwd: repoToplevel(appDir),
+        argv: [
+          "git",
+          "commit",
+          "--only",
+          "--message",
+          "Apply DeepSpace app migrations",
+          "--message",
+          `DeepSpace-Migrations: ${migrationIds.join(",")}`,
+          "--",
+          ...plan.changedFiles
+        ]
+      },
+      extra: { sourceMigrations: plan.pending }
+    }
+  );
+}
+async function requireSourceMigrationDeploy(appDir, appId, deployUrl, token) {
+  if (!isWorkTreeClean(appDir)) {
+    throw new Refusal(
+      "Commit or discard local changes before checking app migration deployment state.",
+      "dirty_worktree"
+    );
+  }
+  const head = resolveCommit(appDir, "HEAD");
+  if (!head) return;
+  const repo = repoToplevel(appDir);
+  const knownIds = new Set(APP_MIGRATION_DEFINITIONS.map((migration) => migration.id));
+  const migrationCommits = splitNulFields(
+    runGit(repo, [
+      "log",
+      "--format=%H%x00",
+      "--extended-regexp",
+      "--grep",
+      `^DeepSpace-Migrations:.*(${[...knownIds].join("|")})`
+    ]).stdout
+  ).map((oid) => oid.trim()).filter((oid) => /^[0-9a-f]{40}$/.test(oid));
+  if (migrationCommits.length === 0) return;
+  const { release: release2 } = await repoApi(deployUrl, token, appId).latestRelease();
+  if (release2?.commitOid === head) return;
+  const liveCommit = release2?.commitOid ?? null;
+  if (liveCommit && (resolveCommit(appDir, liveCommit) === null || !isAncestor(appDir, liveCommit, head))) {
+    throw new Refusal(
+      `The live release commit ${liveCommit.slice(0, 10)} is not an ancestor of this checkout, so migration deployment state cannot be proven. Fetch and integrate the live source history first.`,
+      "migration_lineage_unknown",
+      { extra: { appId, liveCommitOid: liveCommit, commitOid: head } }
+    );
+  }
+  const undeployedMigrationCommits = migrationCommits.filter(
+    (oid) => !liveCommit || oid !== liveCommit && isAncestor(appDir, liveCommit, oid)
+  );
+  const pendingIds = [
+    ...new Set(
+      undeployedMigrationCommits.flatMap((oid) => {
+        const message = runGit(repo, ["show", "-s", "--format=%B", oid]).stdout.toString("utf-8");
+        return [...message.matchAll(/^DeepSpace-Migrations:\s*(.+)$/gm)].flatMap(
+          (match) => (match[1] ?? "").split(",").map((id) => id.trim()).filter((id) => knownIds.has(id))
+        );
+      })
+    )
+  ];
+  if (pendingIds.length === 0) return;
+  throw new Refusal(
+    `App migrations ${pendingIds.join(", ")} are committed but are not in the live release. Deploy them, then rerun.`,
+    "migration_deploy_required",
+    {
+      actionRequired: true,
+      action: { cwd: appDir, argv: ["deepspace", "deploy"] },
+      extra: { appId, sourceMigrations: pendingIds, commitOid: head }
+    }
+  );
+}
+function requireSourceMigrationWorktree(appDir, allowDirtyWrangler = false) {
+  if (isWorkTreeClean(appDir)) return;
+  const changed = statusFiles(repoToplevel(appDir));
+  if (allowDirtyWrangler && changed.every((path) => path === wranglerRepoPath(appDir))) return;
+  throw new Refusal(
+    "Commit or discard unrelated working-tree changes before applying app migrations.",
+    "dirty_worktree"
+  );
+}
 function restoreLegacyCommitRequired(appDir, migration, envName) {
   const wranglerPath = wranglerRepoPath(appDir);
   return new Refusal(
@@ -12200,8 +12504,16 @@ function deployRequired(appDir, migration, envName) {
     }
   );
 }
-function reportAlreadyModern(appId, json) {
-  if (!json) console.log(`${appId} already uses an immutable DeepSpace app id.`);
+function reportUpToDate(appId, json) {
+  if (!json) console.log(`No pending DeepSpace app migrations for ${appId}.`);
+}
+function reportSourcePlan(plan, json) {
+  if (json || plan.pending.length === 0) return;
+  for (const migration of plan.pending) {
+    console.log(
+      `Pending source migration: ${migration.id} (${migration.files.length} file${migration.files.length === 1 ? "" : "s"})`
+    );
+  }
 }
 function reportMigration(migration, json) {
   if (json) return;
@@ -12213,7 +12525,7 @@ function reportMigration(migration, json) {
 
 // src/cli/cli.ts
 var __dirname = dirname10(fileURLToPath3(import.meta.url));
-var pkg = JSON.parse(readFileSync25(join23(__dirname, "..", "package.json"), "utf-8"));
+var pkg = JSON.parse(readFileSync26(join24(__dirname, "..", "package.json"), "utf-8"));
 if (process.platform === "linux" && !process.env.SSL_CERT_FILE && existsSync24("/etc/ssl/certs/ca-certificates.crt")) {
   process.env.SSL_CERT_FILE = "/etc/ssl/certs/ca-certificates.crt";
 }