@xano/sdk 1.0.0

package/dist/chunk-BHACRS6R.js

@@ -0,0 +1,940 @@
+import {
+  createOperation,
+  runOperation
+} from "./chunk-TLHIFK4M.js";
+import {
+  fetchWorkspaceBundle
+} from "./chunk-X677DMZM.js";
+import {
+  assertReleaseIdentitiesFree,
+  pinnedCanonicalGuids,
+  setLiveRollback
+} from "./chunk-WKQLGKCL.js";
+import {
+  liveBranchMismatch,
+  liveMismatch
+} from "./chunk-K6RXBGUB.js";
+import {
+  confirm
+} from "./chunk-65HWOMGV.js";
+import {
+  landingLockPath,
+  recordForeignLanding
+} from "./chunk-CGVQZXYG.js";
+import {
+  CONSTRAINT_FIX,
+  CONSTRAINT_PHRASE,
+  additiveChanges,
+  alteringChanges,
+  assertStorageModesKept,
+  constraintStop,
+  constraintWhere,
+  discloseCanonicalMoves,
+  discloseTableEffects,
+  droppedAndAdded,
+  movesClause,
+  namedConstraint,
+  readOnce,
+  releaseCanonicalMoves,
+  releaseTableEffects,
+  renameHint,
+  tableEffectsPayload
+} from "./chunk-BWPNT55T.js";
+import {
+  tableRowCounter
+} from "./chunk-C6RIMRU4.js";
+import {
+  asWorkspaceArchive,
+  resolveProjectEntry
+} from "./chunk-AOSYVMUS.js";
+import {
+  exportWorkspaceBundle
+} from "./chunk-CJHQKJU4.js";
+import {
+  decodeWorkspaceArchive
+} from "./chunk-3DRXWLJ5.js";
+import {
+  SettledWriteFailure,
+  classifyFailure
+} from "./chunk-A6E77GDW.js";
+import {
+  BranchTakenError,
+  assertBranchAbsent,
+  assertUsableBranchLabel,
+  derivedLabelTail,
+  findBranch,
+  freeBranchLabel,
+  listBranchListing,
+  liveBranchLabel,
+  setLiveBranch
+} from "./chunk-TRJCALW3.js";
+import {
+  envValuesOf
+} from "./chunk-45UIT5T2.js";
+import {
+  assertOneName
+} from "./chunk-ZIY7RNUT.js";
+import {
+  resolveSource
+} from "./chunk-QCNYHBL7.js";
+import {
+  ReleaseHttpError,
+  UNPROMOTABLE_RELEASE_PARTS,
+  deployRelease,
+  downloadRelease,
+  promotableReleaseName,
+  unpromotableReleasePart,
+  untenantDeployableReleasePart
+} from "./chunk-2ZUEE4EK.js";
+import {
+  getAccessToken
+} from "./chunk-ET4Y4XCB.js";
+import {
+  pipedYes,
+  retryCommand,
+  withheldNote
+} from "./chunk-T5KELPAR.js";
+import {
+  contextFlags
+} from "./chunk-NAQDMEHV.js";
+import {
+  shellWord
+} from "./chunk-FWD7AL6N.js";
+import {
+  readLockFile
+} from "./chunk-P2HAGF6H.js";
+import {
+  withoutReadAftermath
+} from "./chunk-YLDALTWZ.js";
+import {
+  CliError,
+  LocalFileNotFoundError,
+  UsageError,
+  blank,
+  credentialWriteTarget,
+  detail,
+  discloseWriteTarget,
+  error,
+  info,
+  isMachineOutput,
+  parseSource,
+  pastePath,
+  step,
+  success,
+  warn,
+  withoutUrls
+} from "./chunk-PTHVMXZI.js";
+import {
+  envNamesRead
+} from "./chunk-YGZHHAAB.js";
+import {
+  safeNames
+} from "./chunk-GSGDWJB5.js";
+import {
+  setDiagnosticSink
+} from "./chunk-2EZ3ZJZZ.js";
+import {
+  sdkKindName2 as sdkKindName
+} from "./chunk-6MR5TI5V.js";
+import {
+  shellQuote
+} from "./chunk-5ZSO4T2G.js";
+
+// src/emit/promote-command.ts
+import { existsSync, statSync } from "fs";
+
+// src/emit/env-landing-report.ts
+async function reportEnvLanding(auth, opts) {
+  if (opts.release.id === void 0) return;
+  try {
+    const archive = opts.loadArchive !== void 0 ? await opts.loadArchive() : decodeWorkspaceArchive(
+      await downloadRelease(auth, {
+        workspaceId: opts.releaseHost.workspaceId,
+        id: opts.release.id,
+        base: opts.releaseHost.base
+      })
+    );
+    const releaseEnv = envValuesOf(archive);
+    const read = envNamesRead(payloadSections(archive));
+    const named = [.../* @__PURE__ */ new Set([...releaseEnv.keys(), ...read])];
+    if (named.length === 0) return;
+    const live = opts.loadLive !== void 0 ? await opts.loadLive() : await exportWorkspaceBundle(auth, {
+      base: opts.target.base,
+      workspaceId: opts.target.workspaceId,
+      label: `reading ${opts.targetLabel}`,
+      // This reads a destination someone keeps. A failure here must not echo a
+      // response body, for the same reason `env pull` must not.
+      safeErrors: true
+    });
+    const destination = envValuesOf(live);
+    const missing = named.filter((name) => !destination.has(name));
+    const created = missing.filter((name) => releaseEnv.has(name));
+    if (created.length > 0) {
+      warn(
+        `${created.length} env var${created.length === 1 ? "" : "s"} in "${opts.release.name}" ${created.length === 1 ? "is" : "are"} NOT set on ${opts.targetLabel} and will be CREATED carrying the value the release was cut with: ${safeNames(created)}.`,
+        "release.env-created",
+        [
+          `Every other name keeps ${opts.targetLabel}'s own value \u2014 a release merge is add-only by name.`,
+          `Set these on the destination first if they should differ there.`
+        ]
+      );
+    }
+    const unset = missing.filter((name) => !releaseEnv.has(name));
+    if (unset.length > 0) {
+      const one = unset.length === 1;
+      warn(
+        `Release "${opts.release.name}" reads ${unset.length} env var${one ? "" : "s"} ${opts.targetLabel} doesn't set: ${safeNames(unset)}. A release carries no env values, so ${one ? "it reads" : "they read"} as null there until set \u2014 run:`,
+        "release.env-unset",
+        unset.map((name) => `printf %s "$VALUE" | xanosdk env set ${shellQuote(name)}${opts.envSetTo}`)
+      );
+    }
+  } catch (err) {
+    detail(
+      `Could not check which env vars this release reads that the destination lacks (${withoutUrls(((err instanceof Error ? err.message : String(err)).trim().split("\n")[0] ?? "").replace(/[.:]$/, ""))}).`
+    );
+  }
+}
+function payloadSections(archive) {
+  const payload = archive?.payload;
+  const out = {};
+  if (payload === null || typeof payload !== "object") return out;
+  for (const [key, value] of Object.entries(payload)) if (Array.isArray(value)) out[key] = value;
+  return out;
+}
+
+// src/emit/promote-command.ts
+function derivedPromoteLabel(releaseName, now, random) {
+  return `${promoteLabelStem(releaseName)}-${derivedLabelTail(now, random)}`;
+}
+function promoteLabelStem(releaseName) {
+  const stem = releaseName.replace(/[^A-Za-z0-9._-]+/g, "-").replace(/^[-.]+|-+$/g, "");
+  return stem === "" ? "release" : stem;
+}
+function isDerivedPromoteLabel(label, releaseName) {
+  const stem = promoteLabelStem(releaseName);
+  return label.startsWith(`${stem}-`) && /^\d{8}T\d{6}Z-[0-9a-f]{4}$/.test(label.slice(stem.length + 1));
+}
+var MERGE_ONLY = [
+  { key: "prune", flag: "--prune" },
+  { key: "replace", flag: "--replace" },
+  { key: "resetData", flag: "--reset-data" },
+  { key: "seed", flag: "--seed" },
+  { key: "dryRun", flag: "--dry-run" }
+];
+function assertNoBackupFlag(args) {
+  if (args.backupBranch === void 0) return;
+  throw new UsageError(
+    `\`--backup-branch\` snapshots the live branch before an import overwrites it, and a promote overwrites nothing: the release lands on a branch of its own and the live one keeps serving until \`--set-live\`. There is no point to snapshot.
+\`xanosdk deploy --to workspace${contextFlags(args)}\` is the path that imports over live, and the one that has it.`,
+    // Both flags parsed fine; the sentence says what to drop, so a pointer, not the block.
+    { hintFor: { command: "promote" } }
+  );
+}
+function assertNoMergeFlags(args) {
+  const passed = MERGE_ONLY.filter((f) => args[f.key] !== void 0 && args[f.key] !== false);
+  if (passed.length === 0) return;
+  const names = passed.map((f) => f.flag);
+  throw new UsageError(
+    `${names.join(" and ")} ${names.length === 1 ? "scopes" : "scope"} a merge computed from a local build, and a promote lands a release the server already holds \u2014 there is nothing here for ${names.length === 1 ? "it" : "them"} to act on. \`xanosdk deploy --to workspace${contextFlags(args)}\` is the path that has ${names.length === 1 ? "it" : "them"}.`,
+    { helpFor: { command: "promote" } }
+  );
+}
+var EXIT_VERIFICATION_FAILED = 2;
+var CANONICAL_SECTIONS = ["app", "toolset", "realtime_server"];
+function sectionRows(bundle, key) {
+  const payload = bundle?.payload;
+  if (payload === null || typeof payload !== "object") return [];
+  const rows = payload[key];
+  return Array.isArray(rows) ? rows.filter((r) => r !== null && typeof r === "object") : [];
+}
+function canonicalMismatches(declared, landed, pinned) {
+  const out = [];
+  for (const key of CANONICAL_SECTIONS) {
+    const served = /* @__PURE__ */ new Map();
+    for (const row of sectionRows(landed, key)) {
+      if (typeof row.guid !== "string" || typeof row.canonical !== "string") continue;
+      served.set(row.guid, [...served.get(row.guid) ?? [], row.canonical]);
+    }
+    for (const row of sectionRows(declared, key)) {
+      const { guid, name, canonical } = row;
+      if (typeof guid !== "string" || guid === "" || typeof name !== "string") continue;
+      if (typeof canonical !== "string" || canonical === "") continue;
+      const there = served.get(guid);
+      if (there === void 0 || there.includes(canonical)) continue;
+      const kind = key === "toolset" ? row.type === "agent" ? "agent" : "mcpServer" : sdkKindName(key);
+      out.push({ kind, name, declared: canonical, served: there[0], pinned: pinned.has(guid) });
+    }
+  }
+  return out;
+}
+async function verifyLanding(auth, opts) {
+  const unverified = (reason) => ({
+    outcome: "unverified",
+    missing: [],
+    undeclared: [],
+    suffixed: [],
+    compared: 0,
+    canonicals: [],
+    reason
+  });
+  let declared;
+  try {
+    declared = await opts.loadArchive();
+  } catch {
+    return unverified("the release archive could not be read");
+  }
+  if (declared === void 0) {
+    return unverified("the release carries no id to read its archive from");
+  }
+  let landedBundle;
+  try {
+    landedBundle = await fetchWorkspaceBundle(auth, opts.branch);
+  } catch (err) {
+    return unverified(shortReason(err));
+  }
+  const { compareToLive, declaredLabels } = await import("./live-diff-YONW2VI3.js");
+  let result;
+  try {
+    result = compareToLive(declared, landedBundle, void 0, { sample: "all" });
+  } catch {
+    return unverified("the release archive and the landed branch could not be compared");
+  }
+  if (result.compared === 0) {
+    return unverified("the release archive declared no comparable objects");
+  }
+  const missing = [...new Set(result.missing)];
+  const undeclared = [...new Set(result.liveOnly)];
+  const canonicals = canonicalMismatches(declared, landedBundle, opts.pinned(declared));
+  return {
+    outcome: missing.length === 0 && !canonicals.some((c) => c.pinned) ? "passed" : "failed",
+    missing,
+    undeclared,
+    suffixed: suffixedSiblings(declaredLabels(declared), undeclared),
+    compared: result.compared,
+    canonicals
+  };
+}
+function shortReason(err) {
+  const raw = err instanceof Error ? withoutReadAftermath(err.message) : "the landed branch could not be read";
+  const scrubbed = withoutUrls(raw).replace(/\s+/g, " ").trim().replace(/\.+$/, "");
+  return scrubbed.length > 200 ? `${scrubbed.slice(0, 200)}\u2026` : scrubbed;
+}
+function verificationPayload(v) {
+  return {
+    outcome: v.outcome,
+    missing: v.missing,
+    undeclared: v.undeclared,
+    compared: v.compared,
+    canonicals: v.canonicals,
+    ...v.reason === void 0 ? {} : { reason: v.reason }
+  };
+}
+function suffixedSiblings(declared, undeclared) {
+  const stems = new Set(declared);
+  return undeclared.filter((entry) => {
+    const stripped = entry.replace(/_\d+( \(apiGroup .*\))?$/, "$1");
+    return stripped !== entry && stems.has(stripped);
+  });
+}
+function reportNotRun(target = "workspace", tablesBelow = true) {
+  const lines = [
+    tablesBelow ? "no plan preview, no prune scope \u2014 its table changes are checked against the destination below" : "no plan preview, no prune scope \u2014 its tables were checked against the destination, and it alters none there"
+  ];
+  if (target === "workspace") {
+    lines.push(
+      "and the release's workspace settings (preferences, request history, realtime, workspace middleware) apply to the whole workspace \u2014 they are shared by every branch; its name and description are kept"
+    );
+  }
+  lines.push("what it has instead: a named release that came up and answered, and can be re-landed");
+  warn(
+    "This lands a release the server holds, so the local pre-flight did not run:",
+    target === "tenant" ? "tenant.server-release" : "promote.server-release",
+    lines
+  );
+}
+function archiveLoader(auth, release, host) {
+  let bytes;
+  let decoded;
+  const loadBytes = async () => {
+    if (bytes !== void 0) return bytes;
+    if (release.id === void 0) return void 0;
+    bytes = await downloadRelease(auth, {
+      workspaceId: host.workspaceId,
+      id: release.id,
+      base: host.base
+    });
+    return bytes;
+  };
+  return {
+    bytes: loadBytes,
+    decoded: async () => {
+      if (decoded !== void 0) return decoded;
+      const raw = await loadBytes();
+      if (raw === void 0) return void 0;
+      decoded = decodeWorkspaceArchive(raw);
+      return decoded;
+    }
+  };
+}
+function gatedTableChanges(e) {
+  return alteringChanges({ ...e, indexChanges: e.indexChanges.filter((c) => c.action === "add" && c.unique) });
+}
+var LandingIncompleteError = class extends Error {
+  name = "LandingIncompleteError";
+  exitCode = EXIT_VERIFICATION_FAILED;
+};
+var PROMOTE_WITHOUT_BRANCH = "drop the flag to land on a new branch named after the release (add `--set-live` to make it live)";
+async function projectSeededTables(entry) {
+  if (entry === void 0) return void 0;
+  const previous = setDiagnosticSink(() => {
+  });
+  try {
+    const { loadDefault } = await import("./cli.js");
+    const registry = await loadDefault(entry);
+    if (typeof registry?.tables !== "function") return /* @__PURE__ */ new Set();
+    return new Set(
+      registry.tables().filter((t) => t.seed !== void 0 && typeof t.name === "string").map((t) => t.name)
+    );
+  } catch {
+    return void 0;
+  } finally {
+    setDiagnosticSink(previous);
+  }
+}
+async function seedRowRemedies(release, tables, flags, named) {
+  const entry = named ?? resolveProjectEntry(process.cwd());
+  const seededHere = await projectSeededTables(entry);
+  const resettable = seededHere === void 0 ? [] : tables.filter((t) => seededHere.has(t.name) && t.guid !== void 0);
+  const r = shellWord(release.name);
+  const before = [
+    `The release's rows land with a deploy of the release: \`xanosdk deploy release:${r}${flags}\` on this project's ephemeral, or \`xanosdk tenant deploy <tenant> ${r}${flags}\` on a tenant.`
+  ];
+  if (resettable.length === 0) return { before };
+  const one = resettable.length === 1;
+  return {
+    before,
+    afterLanding: `This project seeds ${resettable.map((t) => t.name).join(", ")} in code: \`xanosdk workspace reset-tables ${shellWord(pastePath(entry))}${resettable.map((t) => ` --table ${shellWord(t.guid)}`).join("")} --write${flags}\` writes ${one ? "its" : "their"} project rows into the workspace.`
+  };
+}
+function assertPromotableName(name, args) {
+  const part = unpromotableReleasePart(name);
+  if (part === void 0) return;
+  const flags = contextFlags(args);
+  const renamed = promotableReleaseName(name);
+  throw new UsageError(
+    `Release "${name}" cannot be promoted: its name holds \`${part}\`, and the route a promote lands a release by cannot address a name holding ${UNPROMOTABLE_RELEASE_PARTS}. Nothing was sent.
+Cut it again as \`xanosdk release create ${shellWord(renamed)}\` from the source \`xanosdk release show ${shellWord(name)}${flags}\` names, and promote that.` + (untenantDeployableReleasePart(name) === void 0 ? ` \`xanosdk tenant deploy <tenant> ${shellWord(name)}${flags}\` still lands this one on a tenant.` : ""),
+    { hintFor: { command: "promote" } }
+  );
+}
+async function runPromoteCommand(args) {
+  assertNoMergeFlags(args);
+  assertNoBackupFlag(args);
+  if (args.expectLive !== void 0 && args.setLive !== true) {
+    throw new UsageError(
+      `\`--expect-live\` guards the switch to live, and without \`--set-live\` a promote never switches: the release lands on a branch of its own and live keeps serving. Add \`--set-live\`, or drop \`--expect-live\`.`,
+      { hintFor: { command: "promote" } }
+    );
+  }
+  const typedBranch = args.branch === void 0 ? void 0 : assertUsableBranchLabel(args.branch, "--branch", PROMOTE_WITHOUT_BRANCH);
+  const raw = args.positionals[0];
+  if (raw === void 0 || raw === "") {
+    throw new UsageError(
+      `\`xanosdk promote\` needs a release name. Run \`xanosdk release list${contextFlags(args)}\` to see them.`,
+      { hintFor: { command: "promote" } }
+    );
+  }
+  assertOneName(raw, "the release name", { args, helpFor: { command: "promote" } });
+  const source = parseSource(raw, ["release"], { command: "promote" });
+  if (args.entryPath !== void 0 && (!existsSync(args.entryPath) || !statSync(args.entryPath).isFile())) {
+    const Refusal = existsSync(args.entryPath) ? UsageError : LocalFileNotFoundError;
+    throw new Refusal(
+      `\`--entry ${pastePath(args.entryPath)}\` ${existsSync(args.entryPath) ? "is not a file" : "does not exist"}. Pass the backend's entry file (its \`index.ts\`). Nothing was sent.`,
+      { hintFor: { command: "promote" } }
+    );
+  }
+  const auth = await getAccessToken(args);
+  const resolved = await resolveSource(source, async () => auth);
+  const release = resolved.release;
+  if (release === void 0) throw new Error(`promote: resolved no release for "${raw}".`);
+  assertPromotableName(release.name, args);
+  const setLiveRequested = args.setLive === true;
+  const destination = { ...credentialWriteTarget(auth), kind: "workspace" };
+  step(`Promoting release ${release.name}`);
+  discloseWriteTarget(destination);
+  const lockPath = landingLockPath(args, args.entryPath === void 0 ? {} : { entryFile: args.entryPath });
+  if (lockPath === void 0 && args.noLock !== true) {
+    const { nestedBackendEntries } = await import("./tracked-backend-EIBUMDZA.js");
+    const nested = nestedBackendEntries(process.cwd());
+    if (nested.length > 0) {
+      warn(
+        `No landing will be recorded: this directory is no project, so no xano.lock records what lands (a later \`--prune\` deletes only what a lock records).`,
+        "promote.no-landing-record",
+        nested.length === 1 ? [`The backend below it: \`--entry=${shellWord(nested[0])}\` records the landing in its lock, or run from its directory.`] : [`Backends below it: ${nested.join(", ")}. Name the one this release came from with \`--entry=<entry>\`, or run from its directory.`]
+      );
+    }
+  }
+  const entryFlag = args.entryPath === void 0 ? "" : ` --entry=${shellWord(pastePath(args.entryPath))}`;
+  const branch = typedBranch ?? assertUsableBranchLabel(derivedPromoteLabel(release.name, /* @__PURE__ */ new Date()), "--branch", PROMOTE_WITHOUT_BRANCH);
+  const listFrom = { baseUrl: resolved.target.base, workspaceId: resolved.target.workspaceId };
+  const op = createOperation({
+    operation: "promote",
+    destination,
+    release: { instance: auth.instance, workspaceId: auth.workspaceId, id: release.id, name: release.name },
+    branch,
+    steps: setLiveRequested ? ["land", "verify", "setLive"] : ["land", "verify"],
+    // Verification checks the landing; it does not produce it. One that could
+    // not run leaves the landing done (and exit 0, as before), rather than
+    // sending every caller on an instance with an unreadable export to resolve
+    // a write that already answered.
+    checks: ["verify"],
+    extras: { declined: false, landingRecord: null, tableEffects: null, canonicalMoves: [] }
+  });
+  const flags = contextFlags(args);
+  const yesFlags = `${pipedYes(args)}${flags}`;
+  const residue = { name: branch, removeWith: `xanosdk workspace branch delete ${shellWord(branch)}${yesFlags}` };
+  const promoteRerun = (onBranch, allowShared = args.allowSharedSchemaChanges === true) => `xanosdk promote ${shellWord(release.name)}${onBranch === void 0 ? "" : ` --branch ${shellWord(onBranch)}`}${setLiveRequested ? " --set-live" : ""}${args.expectLive === void 0 ? "" : ` --expect-live ${shellWord(args.expectLive)}`}${allowShared ? " --allow-shared-schema-changes" : ""} --yes${args.json === true ? " --json" : ""}${entryFlag}${flags}`;
+  const labelRace = async (err) => {
+    if (!(err instanceof ReleaseHttpError) || err.status !== 500 || !/duplicate record/i.test(err.message)) return err;
+    const now = await listBranchListing(auth, listFrom).catch(() => void 0);
+    if (now === void 0 || findBranch(now.branches, branch) === void 0) return err;
+    const free = typedBranch === void 0 ? void 0 : freeBranchLabel(now.branches, branch);
+    return new BranchTakenError(
+      `Another landing created branch "${branch}" while this one was landing, and the instance refused the duplicate label. Nothing of release ${release.name} landed.
+` + (free === void 0 ? `Re-run as \`${promoteRerun(void 0)}\` \u2014 it derives a fresh label.` : `Pick a label that is free: \`${promoteRerun(free)}\`.`),
+      branch,
+      free
+    );
+  };
+  const resolveWith = `xanosdk workspace branch list --json${flags}`;
+  const resolveSteps = [
+    `If "${branch}" is absent, nothing landed: re-run as \`${promoteRerun(branch)}\`.`,
+    `If it is present and not live, check it with \`xanosdk workspace export --branch ${shellWord(branch)}${flags}\` before \`xanosdk workspace branch set-live ${shellWord(branch)}${yesFlags}\`.`
+  ];
+  const assertTablesAcknowledged = (read) => {
+    if (args.allowSharedSchemaChanges === true) return;
+    const rerun = promoteRerun(typedBranch, true);
+    if ("failure" in read) {
+      throw new CliError(
+        "SDK_SHARED_SCHEMA_CHANGE",
+        `Refusing to promote "${release.name}": whether it changes your workspace's tables is unknown \u2014 ${read.failure}.
+Tables are shared by every branch, so a promote applies the release's table definitions to live as soon as it lands, before any \`--set-live\`. A failed read is not evidence that it changes none.
+Retry when the instance answers, or land it without the check: \`${rerun}\`.`,
+        { exitCode: 2, details: { reason: "tables-unreadable", landed: false, declined: false, changes: null } }
+      );
+    }
+    const gated = gatedTableChanges(read.effects);
+    if (gated.length === 0) return;
+    const changes = [...gated, ...additiveChanges(read.effects)];
+    const paired = droppedAndAdded(read.effects);
+    const one = gated.length === 1;
+    throw new CliError(
+      "SDK_SHARED_SCHEMA_CHANGE",
+      `Refusing to promote "${release.name}": it alters ${one ? "a table" : "tables"} your live workspace serves from. A promote lands logic on a branch of its own, but tables are shared by every branch \u2014 ${one ? "this applies" : "these apply"} to live as soon as it lands, before any \`--set-live\`, and are not undone by deleting the branch:
+${changes.map((c) => `  ${c}`).join("\n")}
+` + paired.map((p) => `${renameHint(p)}
+`).join("") + `\`--yes\` does not cover this. Cut a release without ${one ? "it" : "them"}, or land ${one ? "it" : "them"} knowing live changes too: \`${rerun}\`.`,
+      {
+        exitCode: 2,
+        details: { reason: "shared-schema-changes", landed: false, declined: false, changes, pairedColumns: paired }
+      }
+    );
+  };
+  const constraintRefusal = (err, stop) => {
+    const where = constraintWhere(stop);
+    return new CliError(
+      "SDK_CONSTRAINT_VIOLATION",
+      `Release "${release.name}" did not land: your workspace's rows break ${CONSTRAINT_PHRASE[stop.kind]} it declares${where}. Nothing landed \u2014 no branch was made, and live is as it was.
+${CONSTRAINT_FIX[stop.kind]}, then promote again.`,
+      {
+        exitCode: 2,
+        cause: new SettledWriteFailure(err instanceof Error ? err.message : String(err), { cause: err }),
+        details: {
+          landed: false,
+          declined: false,
+          constraint: stop,
+          ...stop.kind === "unique" ? { uniqueViolation: true } : {}
+        }
+      }
+    );
+  };
+  const projectLock = () => {
+    if (lockPath === void 0 || !existsSync(lockPath)) return void 0;
+    try {
+      return readLockFile(lockPath);
+    } catch {
+      return void 0;
+    }
+  };
+  const pinnedIn = (declared) => new Set(pinnedCanonicalGuids(JSON.stringify(declared), projectLock(), false));
+  const assertIdentitiesFree = async (archive, loadLive) => {
+    let bytes;
+    let bundle;
+    try {
+      bytes = await archive.bytes();
+      bundle = await archive.decoded();
+    } catch {
+      bytes = void 0;
+    }
+    let check;
+    if (bytes === void 0 || bundle === void 0) {
+      check = { checked: false, reason: "the release archive could not be read" };
+    } else {
+      let typed;
+      try {
+        typed = asWorkspaceArchive(bytes, release.name);
+      } catch {
+        typed = void 0;
+      }
+      check = typed === void 0 ? { checked: false, reason: "the release archive carries no workspace to plan" } : await assertReleaseIdentitiesFree(args, auth, {
+        archive: typed,
+        bundle,
+        branch,
+        lockPath,
+        live: await loadLive().catch(() => void 0),
+        subject: `promote "${release.name}"`,
+        verb: "promote",
+        remedySuffix: `A release's names and slugs are fixed when it is cut: make the change in the project, deploy it, cut a new release from it with \`xanosdk release create\`, and promote that one.`
+      });
+    }
+    if (!check.checked) {
+      warn(
+        `Whether this release's names and pinned public URL slugs are free in your workspace was not checked \u2014 ${check.reason}.`,
+        "promote.identities-unchecked",
+        [
+          `A name another object holds lands as a suffixed second object, and a pinned slug another workspace serves lands under a minted one.`,
+          `The landed branch is read back afterwards, and a pinned slug it does not serve fails the promote.`
+        ]
+      );
+    }
+    return check;
+  };
+  const machine = isMachineOutput(args);
+  let declined = false;
+  let landingEffects;
+  let resetTablesAfterLanding;
+  try {
+    await runOperation(
+      op,
+      { machine, resolveWith, resolveSteps, what: `the landing of ${release.name}` },
+      async () => {
+        op.begin("land");
+        const before = await listBranchListing(auth, listFrom).catch(async (err) => {
+          throw await unansweredBranchRead(err, args);
+        });
+        assertBranchAbsent(before.branches, branch);
+        if (args.expectLive !== void 0) {
+          const mismatch = liveMismatch(before, args.expectLive);
+          if (mismatch !== void 0) {
+            throw liveBranchMismatch(
+              `\`--expect-live ${args.expectLive}\` does not hold: ${mismatch.why}. Nothing was landed.
+Check what is serving with \`xanosdk workspace branch list${flags}\`, then promote again.`,
+              mismatch.live
+            );
+          }
+        }
+        const archive = archiveLoader(auth, release, resolved.target);
+        const loadArchive = archive.decoded;
+        const loadLive = readOnce(
+          () => exportWorkspaceBundle(auth, {
+            base: auth.instance,
+            workspaceId: auth.workspaceId,
+            label: "reading your workspace",
+            safeErrors: true
+          })
+        );
+        const firstRead = await releaseTableEffects(loadArchive, loadLive);
+        reportNotRun(
+          "workspace",
+          !("effects" in firstRead) || alteringChanges(firstRead.effects).length + additiveChanges(firstRead.effects).length > 0
+        );
+        await reportEnvLanding(auth, {
+          release: { id: release.id, name: release.name },
+          releaseHost: resolved.target,
+          target: { base: resolved.target.base, workspaceId: auth.workspaceId },
+          targetLabel: "your workspace",
+          envSetTo: ` --to workspace --yes${flags}`,
+          loadArchive,
+          loadLive
+        });
+        const seededTables = (release.seededTables ?? []).filter((t) => t.count !== 0);
+        const seeded = seededTables.map((t) => t.name);
+        if (seeded.length > 0) {
+          op.set("seedRowsNotWritten", seeded);
+          const remedies = await seedRowRemedies(release, seededTables, flags, args.entryPath);
+          resetTablesAfterLanding = remedies.afterLanding;
+          warn(
+            `"${release.name}" carries rows for ${seeded.length} table${seeded.length === 1 ? "" : "s"} (${seeded.join(", ")}), and they are not written: a promote lands logic on a branch, and tables are shared by every branch.`,
+            "promote.seed-rows",
+            remedies.before
+          );
+        }
+        await assertIdentitiesFree(archive, loadLive);
+        const tables = "effects" in firstRead ? firstRead : await releaseTableEffects(loadArchive, loadLive);
+        if ("failure" in tables && tables.cause !== void 0 && args.allowSharedSchemaChanges !== true) {
+          const what = tables.read === "archive" ? `release "${release.name}"'s archive` : "your workspace";
+          const unanswered = await unansweredBranchRead(tables.cause, args, what);
+          if (unanswered !== tables.cause) throw unanswered;
+        }
+        landingEffects = "effects" in tables ? tables.effects : void 0;
+        op.set("tableEffects", landingEffects === void 0 ? null : tableEffectsPayload(landingEffects));
+        assertTablesAcknowledged(tables);
+        const tableChanges = landingEffects === void 0 ? 0 : alteringChanges(landingEffects).length + additiveChanges(landingEffects).length;
+        if (landingEffects !== void 0) {
+          discloseTableEffects(landingEffects, {
+            subject: "the promote",
+            additiveWhere: "the tables every branch shares \u2014 live included, as soon as it lands"
+          });
+          await assertStorageModesKept(landingEffects.storageChanges, tableRowCounter(auth, { workspaceId: auth.workspaceId, base: auth.instance }), {
+            target: "your workspace",
+            subject: "the promote"
+          });
+        }
+        const moves = await Promise.all([loadArchive(), loadLive()]).then(
+          ([archive2, live]) => releaseCanonicalMoves(archive2, live),
+          () => []
+        );
+        op.set("canonicalMoves", moves);
+        discloseCanonicalMoves(moves, {
+          subject: "the promote",
+          will: setLiveRequested ? "will" : "would",
+          when: setLiveRequested ? "as it goes live" : "once its branch is made live"
+        });
+        if (args.yes !== true) {
+          const ok = await confirm(
+            `Land release "${release.name}" in your workspace${typedBranch === void 0 ? "" : ` on branch "${typedBranch}"`}${setLiveRequested ? ", and make it live" : ""}${tableChanges === 0 ? "" : `, applying its ${tableChanges === 1 ? "table change" : `${tableChanges} table changes`} to the live workspace too`}?` + movesClause(moves, setLiveRequested ? "It" : "Once live, it"),
+            {
+              flag: "--yes",
+              // Off a terminal, the details `tenant deploy` and `deploy --to`
+              // carry (E2E pass 29: a bare SDK_USAGE), and this promote with `--yes`.
+              refusal: {
+                details: { landed: false, declined: false },
+                rerun: promoteRerun(typedBranch)
+              }
+            }
+          );
+          if (!ok) {
+            info("Promote cancelled \u2014 nothing was written.");
+            op.set("declined", true);
+            declined = true;
+            return;
+          }
+        }
+        step(`Landing ${release.name} in your workspace on branch "${branch}"`);
+        op.sending();
+        const landed = await deployRelease(auth, {
+          workspaceId: auth.workspaceId,
+          name: release.name,
+          branch,
+          setLive: false
+        }).catch(async (err) => {
+          const stop = constraintStop(err);
+          if (stop !== void 0) throw constraintRefusal(err, namedConstraint(stop, landingEffects));
+          throw await labelRace(err);
+        });
+        op.finish("land");
+        op.setRelease({
+          instance: auth.instance,
+          workspaceId: auth.workspaceId,
+          id: landed.id ?? release.id,
+          name: landed.name
+        });
+        try {
+          await afterLanding({ landedName: landed.name, loadArchive, liveBefore: liveBranchLabel(before.branches) });
+        } catch (err) {
+          if (classifyFailure(err, { writeSent: op.inProgressSent }) === "no") op.setResidue(residue);
+          throw err;
+        }
+      }
+    );
+  } catch (err) {
+    if (declined) return;
+    throw err;
+  }
+  async function afterLanding(ctx) {
+    op.begin("verify");
+    const verification = await verifyLanding(auth, { loadArchive: ctx.loadArchive, branch, pinned: pinnedIn });
+    op.set("verification", verificationPayload(verification));
+    op.finish(
+      "verify",
+      verification.outcome === "passed" ? "yes" : verification.outcome === "failed" ? "no" : "unknown"
+    );
+    if (verification.outcome === "failed") op.setResidue(residue);
+    if (verification.outcome !== "failed") {
+      const archive = await ctx.loadArchive().catch(() => void 0);
+      if (archive !== void 0) {
+        op.set(
+          "landingRecord",
+          recordForeignLanding({
+            lockPath,
+            instance: auth.instance,
+            dest: { kind: "workspace", workspaceId: auth.workspaceId },
+            bundle: archive,
+            mode: "merge"
+          })
+        );
+      }
+    }
+    let live = false;
+    let rollback;
+    if (setLiveRequested) {
+      if (verification.outcome !== "passed") {
+        op.finish("setLive", "no");
+        op.setResidue(residue);
+      } else {
+        op.begin("setLive");
+        let previousLive = ctx.liveBefore;
+        if (args.expectLive !== void 0) {
+          const now = await listBranchListing(auth, listFrom);
+          previousLive = liveBranchLabel(now.branches);
+          const drift = liveMismatch(now, args.expectLive);
+          if (drift !== void 0) {
+            op.finish("setLive", "no");
+            op.setResidue(residue);
+            throw liveBranchMismatch(
+              `Landed and verified ${ctx.landedName} on branch "${branch}", but did not make it live: \`--expect-live ${args.expectLive}\` no longer holds \u2014 ${drift.why}. Live changed after the landing; the check is not atomic, so it is re-read before switching and the switch refused.
+Nothing was switched. Serve it deliberately with \`xanosdk workspace branch set-live ${branch}${yesFlags}\`, or remove it with \`xanosdk workspace branch delete ${branch}${yesFlags}\`.`,
+              drift.live
+            );
+          }
+        }
+        step(`Making branch "${branch}" live`);
+        op.sending();
+        try {
+          await setLiveBranch(auth, { baseUrl: auth.instance, workspaceId: auth.workspaceId, label: branch });
+        } catch (err) {
+          error(`Landed and verified ${ctx.landedName}, but making branch "${branch}" live failed.`);
+          if (classifyFailure(err, { writeSent: true }) === "no") {
+            detail(`The branch is there and checked; only the live pointer did not move.`);
+            detail(`Retry with \`xanosdk workspace branch set-live ${branch}${yesFlags}\`.`);
+          } else {
+            detail(`Whether the live pointer moved is not known \u2014 \`xanosdk workspace branch list${flags}\` shows it.`);
+          }
+          throw err;
+        }
+        op.finish("setLive");
+        live = true;
+        op.set("previousLive", previousLive ?? null);
+        rollback = previousLive === void 0 ? void 0 : setLiveRollback(previousLive, args);
+      }
+    }
+    const substituted = verification.canonicals.filter((c) => !c.pinned);
+    if (substituted.length > 0) {
+      warn(
+        `Public URL slug${substituted.length === 1 ? "" : `s (${substituted.length})`} the release declares ${substituted.length === 1 ? "is" : "are"} served under another value (not pinned in code, so the instance chose):`,
+        "promote.canonical-substituted",
+        substituted.map((c) => `${c.kind} ${c.name}: serves "${c.served}", declared "${c.declared}"`)
+      );
+    }
+    if (!machine) renderLanding({ landedName: ctx.landedName, verification, live, rollback });
+    else if (verification.outcome !== "failed") {
+      success(`Landed ${ctx.landedName}`);
+      detail(whereItLanded(live));
+      if (rollback !== void 0) detail(rollback);
+      if (verification.outcome === "unverified") warnUnverified(verification);
+    }
+    if (verification.outcome === "failed") {
+      const unserved = verification.canonicals.filter((c) => c.pinned);
+      const what = [
+        ...verification.missing.length === 0 ? [] : [`${verification.missing.length} declared object${verification.missing.length === 1 ? "" : "s"} did not arrive`],
+        ...unserved.length === 0 ? [] : [
+          `${unserved.length} public URL slug${unserved.length === 1 ? "" : "s"} pinned in code ${unserved.length === 1 ? "is" : "are"} not served (${unserved.map((c) => `${c.kind} ${c.name}: "${c.served}", not "${c.declared}"`).join("; ")})`
+        ]
+      ];
+      throw new LandingIncompleteError(`Landed ${ctx.landedName} on branch "${branch}", but ${what.join(", and ")}.`);
+    }
+  }
+  function whereItLanded(live) {
+    return live ? `live on branch ${branch}` : `on branch ${branch}, not live yet \u2014 serve it with \`xanosdk workspace branch set-live ${shellWord(branch)}${yesFlags}\` (a promote with \`--set-live\` lands and serves in one run)`;
+  }
+  function warnUnverified(verification) {
+    warn(
+      `Contents NOT verified \u2014 the release landed, but verification could not run (${verification.reason}) \u2014 check what landed with \`xanosdk workspace export --branch ${shellWord(branch)} --path -${flags}\``,
+      "promote.unverified",
+      // The one place this command declines something the caller explicitly
+      // asked for, so it says both halves: what it did not do, and the command
+      // that does it anyway once they have decided the risk is theirs to take.
+      setLiveRequested ? [
+        `NOT made live \u2014 \`--set-live\` serves a landing that was checked, and this one could not be.`,
+        `Serve it deliberately with \`xanosdk workspace branch set-live ${branch}${yesFlags}\`.`
+      ] : []
+    );
+  }
+  function renderLanding(r) {
+    const { verification } = r;
+    if (verification.outcome === "failed") {
+      if (verification.missing.length > 0) {
+        warn(
+          `${verification.missing.length} declared object${verification.missing.length === 1 ? "" : "s"} did not arrive:`,
+          "promote.missing-objects",
+          verification.missing
+        );
+      }
+      const unserved = verification.canonicals.filter((c) => c.pinned);
+      if (unserved.length > 0) {
+        warn(
+          `Public URL slug${unserved.length === 1 ? "" : `s (${unserved.length})`} pinned in code ${unserved.length === 1 ? "is" : "are"} served under another value \u2014 every route a frontend builds from ${unserved.length === 1 ? "it" : "them"} answers 404 there:`,
+          "promote.canonical-not-served",
+          [
+            ...unserved.map((c) => `${c.kind} ${c.name}: serves "${c.served}", declared "${c.declared}"`),
+            `The slug is held elsewhere on this instance (slugs are unique per instance). Change the \`canonical\` in code to one nothing serves, or free it where it is held; then deploy, cut a new release and promote that.`
+          ]
+        );
+      }
+      blank();
+      if (setLiveRequested) {
+        detail(`Nothing was made live \u2014 the branch that was serving before is still serving.`);
+      }
+      detail(`Nothing here is cleaned up automatically: the branch is the evidence for why the landing was partial.`);
+      detail(`Remove it with \`xanosdk workspace branch delete ${branch}${yesFlags}\` once you have looked.`);
+      return;
+    }
+    success(`Landed ${r.landedName}`);
+    detail(whereItLanded(r.live));
+    if (r.rollback !== void 0) detail(r.rollback);
+    if (resetTablesAfterLanding !== void 0) info(resetTablesAfterLanding);
+    if (verification.outcome === "unverified") {
+      warnUnverified(verification);
+    } else {
+      detail(`Verified: all ${verification.compared} declared object(s) arrived.`);
+    }
+    if (verification.undeclared.length > 0) {
+      const suspicious = verification.suffixed;
+      detail(
+        `${verification.undeclared.length} object(s) on the branch the release did not declare: ` + verification.undeclared.join(", ")
+      );
+      if (suspicious.length > 0) {
+        warn(`${suspicious.join(", ")} look${suspicious.length === 1 ? "s" : ""} like a suffixed rename of a declared name \u2014 check it is the object you meant.`, "promote.suffixed-rename");
+      }
+    }
+    detail(`See what landed with \`xanosdk workspace export --branch ${branch}${flags}\`.`);
+  }
+}
+async function unansweredBranchRead(err, args, what) {
+  const { LookupFailedError, isServerError, isTransportFailure, unansweredCause } = await import("./source-resolve-S2XA3XZF.js");
+  const transport = isTransportFailure(err);
+  if (!transport && !isServerError(err)) return err;
+  const first = what !== void 0 ? `could not read ${what}` : ((err instanceof Error ? err.message : String(err)).trim().split("\n")[0] ?? "").replace(/[.:]$/, "");
+  const retry = retryCommand(args, {
+    add: pipedYes(args) === "" ? [] : ["--yes"],
+    command: ["promote", ...args.positionals.map(shellWord)].join(" ")
+  });
+  const failed = new LookupFailedError(
+    `${first[0]?.toUpperCase() ?? ""}${first.slice(1)}. ${unansweredCause(err)} before the landing \u2014 nothing was sent`,
+    "unreachable",
+    "workspace",
+    `run \`${retry.command}\` again`
+  );
+  failed.message += withheldNote(retry.withheld);
+  return failed;
+}
+
+export {
+  reportEnvLanding,
+  derivedPromoteLabel,
+  isDerivedPromoteLabel,
+  assertNoMergeFlags,
+  reportNotRun,
+  runPromoteCommand
+};
+//# sourceMappingURL=chunk-BHACRS6R.js.map