@xano/sdk 1.0.0

package/dist/chunk-K4WX6UUU.js

@@ -0,0 +1,923 @@
+import {
+  keptDuplicates,
+  replacedRegistrations,
+  reportSuperseded
+} from "./chunk-D53J55C5.js";
+import {
+  rerenderEnvExample
+} from "./chunk-W3HBUKFO.js";
+import {
+  carriedSeedRows,
+  decodeBundle,
+  fetchWorkspaceBundle,
+  placeGeneratedFiles,
+  refuseDuplicateSourceGuids,
+  reportSeedRows,
+  seedRowsLanding,
+  verifyPulledTree,
+  withSourceIdentities,
+  writeDocumentationTokens
+} from "./chunk-X677DMZM.js";
+import {
+  confirm
+} from "./chunk-65HWOMGV.js";
+import {
+  fetchSourceArchive
+} from "./chunk-AOSYVMUS.js";
+import {
+  decodeWorkspaceArchive,
+  encodeWorkspaceArchive
+} from "./chunk-3DRXWLJ5.js";
+import {
+  ensureSecretPathGitignored
+} from "./chunk-YHEFQUQB.js";
+import {
+  readVersion,
+  refreshAgentGuidance
+} from "./chunk-ETO6LGLD.js";
+import {
+  WORKSPACE_ENV_BASENAME,
+  WORKSPACE_ENV_EXAMPLE_BASENAME,
+  namesInEnvExample,
+  readWorkspaceEnvFile
+} from "./chunk-DAD3ONIS.js";
+import {
+  memoCredential,
+  refuseProfileForLocal,
+  selectBackend
+} from "./chunk-HHN734BU.js";
+import {
+  getAccessToken
+} from "./chunk-ET4Y4XCB.js";
+import {
+  requireBackendSlot
+} from "./chunk-STSFNCY4.js";
+import {
+  contextFlags
+} from "./chunk-NAQDMEHV.js";
+import {
+  backendDirIn,
+  resolveBackendDir
+} from "./chunk-5A2PLKZB.js";
+import {
+  CODEGEN_MARKER,
+  DECODE_MARKER,
+  PRESERVED_ON_REFRESH,
+  SHELL_FILES_IN_BACKEND,
+  XANO_DIR,
+  containedWrites,
+  describeDecodeReplace,
+  filesUnder,
+  planDecodeReplace,
+  planTouchesExisting,
+  readDecodeRecord,
+  removeEmptiedDirs,
+  removeFiles
+} from "./chunk-AHJWCYQO.js";
+import {
+  readLockFile,
+  writeLockFile
+} from "./chunk-P2HAGF6H.js";
+import {
+  decodeMarkerHead,
+  decodeMarkerWith
+} from "./chunk-UCQ2VUTG.js";
+import {
+  CliError,
+  UsageError,
+  detail,
+  info,
+  isMachineOutput,
+  pastePath,
+  step,
+  success,
+  terminalText,
+  warn,
+  writeJson
+} from "./chunk-PTHVMXZI.js";
+import {
+  WORKSPACE_SECRETS_BASENAME
+} from "./chunk-3JDU4VRL.js";
+import {
+  WORKSPACE_KEY,
+  identityNamesByGuid,
+  lockKey,
+  lockNameForObject,
+  withObjects
+} from "./chunk-6MR5TI5V.js";
+import {
+  shellQuote
+} from "./chunk-5ZSO4T2G.js";
+
+// src/emit/pull-command.ts
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from "fs";
+import { basename, join, dirname, isAbsolute, relative, resolve, sep } from "path";
+import { execFileSync } from "child_process";
+import { createRequire } from "module";
+import { pathToFileURL } from "url";
+var PRESERVED = /* @__PURE__ */ new Set([...PRESERVED_ON_REFRESH, ...SHELL_FILES_IN_BACKEND, basename(CODEGEN_MARKER)]);
+function backendDirCleanliness(cwd, backendDir) {
+  try {
+    const out = execFileSync("git", ["status", "--porcelain", "--", backendDir], {
+      cwd,
+      encoding: "utf8",
+      stdio: ["ignore", "pipe", "ignore"]
+    });
+    return out.trim() === "" ? "clean" : "dirty";
+  } catch {
+    return "unknown";
+  }
+}
+function gitChangedUnder(cwd, backendDir) {
+  try {
+    const out = execFileSync("git", ["diff", "--name-only", "--relative", "HEAD", "--", backendDir], {
+      cwd,
+      encoding: "utf8",
+      stdio: ["ignore", "pipe", "ignore"]
+    });
+    const prefix = `${backendDir.replace(/\/+$/, "")}/`;
+    return new Set(
+      out.split("\n").map((line) => line.trim()).filter((line) => line.startsWith(prefix)).map((line) => line.slice(prefix.length))
+    );
+  } catch {
+    return /* @__PURE__ */ new Set();
+  }
+}
+function withGitEdits(plan, changed) {
+  if (changed.size === 0) return plan;
+  const moved = plan.rewrittenUnknown.filter((p) => changed.has(p));
+  if (moved.length === 0) return plan;
+  return {
+    ...plan,
+    edited: [...plan.edited, ...moved],
+    rewrittenUnknown: plan.rewrittenUnknown.filter((p) => !changed.has(p))
+  };
+}
+function lockReportOf(reconciliation) {
+  if (reconciliation === void 0) return { dropped: [], repinned: [], renamed: [] };
+  const renamed = reconciliation.renamed ?? [];
+  const moved = /* @__PURE__ */ new Set([...reconciliation.repinned.map((r) => r.key), ...renamed.map((r) => r.from)]);
+  return { dropped: reconciliation.dropped.filter((k) => !moved.has(k)), repinned: reconciliation.repinned, renamed };
+}
+function pulledIdentities(payload) {
+  const out = /* @__PURE__ */ new Map();
+  const appNames = identityNamesByGuid(payload);
+  for (const [payloadKey, value] of Object.entries(payload)) {
+    if (!Array.isArray(value)) continue;
+    for (const row of value) {
+      if (row === null || typeof row !== "object") continue;
+      const rec = row;
+      if (typeof rec.name !== "string") continue;
+      const name = lockNameForObject(payloadKey, rec, appNames);
+      out.set(lockKey(payloadKey, name), typeof rec.guid === "string" ? rec.guid : void 0);
+    }
+  }
+  return out;
+}
+function noneOfTheIdentities(count, lock) {
+  return count === 1 ? `The one identity in ${lock} does not appear in` : `None of the ${count} identities in ${lock} appear in`;
+}
+function reconcileLock(lock, pulled) {
+  const kept = [];
+  const dropped = [];
+  const repinned = [];
+  const renamed = [];
+  const keyByGuid = /* @__PURE__ */ new Map();
+  for (const [key, guid] of pulled) if (guid !== void 0) keyByGuid.set(guid, key);
+  for (const [key, entry] of Object.entries(lock.objects)) {
+    if (key === WORKSPACE_KEY) continue;
+    const identity = pulled.get(key);
+    const present = pulled.has(key);
+    if (present && (entry.guid === void 0 || identity === void 0 || entry.guid === identity)) {
+      kept.push(key);
+    } else {
+      dropped.push(key);
+      if (present && identity !== void 0 && entry.guid !== void 0) {
+        repinned.push({ key, from: entry.guid, to: identity });
+      } else if (!present && entry.guid !== void 0) {
+        const to = keyByGuid.get(entry.guid);
+        if (to !== void 0 && to !== key && to.slice(0, to.indexOf(":")) === key.slice(0, key.indexOf(":")) && !(to in lock.objects)) {
+          renamed.push({ from: key, to, guid: entry.guid });
+        }
+      }
+    }
+  }
+  return {
+    kept,
+    dropped,
+    repinned,
+    ...renamed.length > 0 ? { renamed } : {},
+    disjoint: kept.length === 0 && renamed.length === 0 && dropped.length > 0
+  };
+}
+function reconciledLock(lock, reconciliation, payload) {
+  const next = withObjects(lock, {});
+  for (const key of reconciliation.kept) next.objects[key] = lock.objects[key];
+  const ws = payload[WORKSPACE_KEY];
+  const pulled = ws !== null && typeof ws === "object" && typeof ws.canonical === "string" ? ws.canonical : "";
+  const recorded = lock.objects[WORKSPACE_KEY];
+  if (pulled !== "") next.objects[WORKSPACE_KEY] = { ...recorded, canonical: pulled };
+  else if (recorded !== void 0) next.objects[WORKSPACE_KEY] = recorded;
+  return next;
+}
+function pulledLock(lock, reconciliation, payload) {
+  const reconciled = reconciledLock(lock, reconciliation, payload);
+  try {
+    return withSourceIdentities(reconciled, payload);
+  } catch (err) {
+    warn(
+      `Could not record the source's identities in xano.lock (${err instanceof Error ? err.message : String(err)}). The first \`xanosdk export\` records them.`,
+      "lock.write-failed"
+    );
+    return reconciled;
+  }
+}
+function projectBackendAbove(cwd) {
+  let dir = resolve(cwd);
+  for (; ; ) {
+    const parent = dirname(dir);
+    if (parent === dir) return void 0;
+    dir = parent;
+    const backend = existsSync(join(dir, "package.json")) ? backendDirIn(dir) : join(dir, XANO_DIR);
+    if (existsSync(join(backend, "index.ts"))) return relative(cwd, backend).split(sep).join("/");
+  }
+}
+function decodeHint(cwd, file, out) {
+  const backend = resolve(cwd, out);
+  if (existsSync(join(backend, basename(CODEGEN_MARKER)))) {
+    return `To decode a bundle file into this project's backend use \`${generateHint(cwd, file, out)}\`.`;
+  }
+  const base = basename(backend);
+  let fresh = join(dirname(backend), `${base}-decoded`);
+  for (let n = 2; existsSync(fresh); n++) fresh = join(dirname(backend), `${base}-decoded-${n}`);
+  const shown = relative(cwd, backend).split(sep).join("/") || ".";
+  const target = relative(cwd, fresh).split(sep).join("/");
+  return `${shown}/ was not written by a decode (it holds no ${basename(CODEGEN_MARKER)}), so a decode will not replace it. To decode the bundle into a new directory beside it use \`xanosdk generate ${shellQuote(file)} --out ${shellQuote(target)}\`.`;
+}
+function generateHint(cwd, file, out) {
+  const yes = process.stdin.isTTY === true ? "" : " --yes";
+  const backend = resolve(cwd, out);
+  const here = resolve(cwd);
+  if (here !== backend && !here.startsWith(`${backend}${sep}`)) {
+    return `xanosdk generate ${shellQuote(file)} --out ${shellQuote(out)} --force${yes}`;
+  }
+  const root = dirname(backend);
+  const fromRoot = (p) => relative(root, p).split(sep).join("/") || ".";
+  const target = isAbsolute(file) ? file : fromRoot(resolve(cwd, file));
+  return `cd ${shellQuote(relative(here, root).split(sep).join("/"))} && xanosdk generate ${shellQuote(target)} --out ${shellQuote(fromRoot(backend))} --force${yes}`;
+}
+async function runPullCommand(args) {
+  const cwd = process.cwd();
+  const backendDir = resolveBackendDir(cwd, args.backendDir, (m) => new UsageError(
+    `${m} A pull replaces the directory it is given.`,
+    { hintFor: { command: "pull" } }
+  ));
+  const first = args.positionals[0];
+  if (first !== void 0 && !/^[a-z][a-z-]+:/i.test(first) && (/\.json$/i.test(first) || /[\\/]/.test(first))) {
+    const out = args.backendDir !== void 0 || existsSync(join(cwd, backendDir, "index.ts")) ? backendDir : projectBackendAbove(cwd);
+    throw new UsageError(
+      `\`xanosdk pull\` refreshes from a live backend, and "${first}" names a file. ` + (out !== void 0 ? decodeHint(cwd, first, out) : `There is no project here to decode it into: \`xanosdk init <dir> --from ${shellQuote(first)}\` writes a whole project around it.`),
+      { hintFor: { command: "pull" } }
+    );
+  }
+  if (!existsSync(join(cwd, backendDir, "index.ts"))) {
+    throw new UsageError(
+      `\`xanosdk pull\` refreshes the backend of a project that already exists, and there is no ${backendDir}/index.ts here. \`xanosdk init <dir> --from <source>\` writes a whole project around a decoded backend` + (args.backendDir === void 0 ? `, and \`--backend-dir <path>\` names the directory when this project keeps its backend somewhere discovery cannot find it.` : `.`)
+    );
+  }
+  const slot = requireBackendSlot("pull", void 0, "subject");
+  const credential = memoCredential(() => getAccessToken(args));
+  const source = await selectBackend(slot, args.positionals[0], { credential, deps: { cwd } });
+  refuseProfileForLocal(args.profile, [source.kind], slot);
+  const raw = args.positionals[0] ?? source.kind;
+  if (args.branch !== void 0 && source.kind !== "workspace") {
+    throw new UsageError(
+      `\`--branch\` applies to \`workspace\` only. ${args.positionals[0] === void 0 ? `This project's ${source.kind}` : `"${raw}"`} carries the logic it was built from, not a branch to choose between.`,
+      { hintFor: { command: "pull" } }
+    );
+  }
+  step(`Reading ${raw}`);
+  const fetched = args.branch !== void 0 ? { archive: encodeWorkspaceArchive(JSON.stringify(await fetchWorkspaceBundle(await credential(), args.branch))), provenance: "workspace", label: `workspace branch "${args.branch.trim()}"` } : await fetchSourceArchive(credential, raw, cwd);
+  const bundle = decodeWorkspaceArchive(fetched.archive);
+  const keptName = source.kind === "workspace" || source.kind === "local-engine" ? void 0 : projectWorkspaceName(join(cwd, backendDir, "index.ts"));
+  const project = decodeBundle(bundle, {
+    secretsFile: `${backendDir}/${WORKSPACE_SECRETS_BASENAME}`,
+    writesSecrets: args.noSecrets !== true,
+    ...keptName !== void 0 ? { workspaceName: keptName } : {}
+  });
+  refuseDuplicateSourceGuids(project);
+  const seedRows = carriedSeedRows(fetched.archive, bundle.payload);
+  const placed = placeGeneratedFiles(project, backendDir);
+  const settings = source.kind === "release" ? keepProjectSettings(placed, backendDir, join(cwd, backendDir)) : { files: placed, kept: false, lost: [], from: WORKSPACE_SETTINGS_FILE };
+  const files = settings.files;
+  const dirAbs = join(cwd, backendDir);
+  const prefix = `${backendDir}/`;
+  const decoded = files.map((f) => ({ path: f.path.slice(prefix.length), content: f.content }));
+  const incoming = new Map(decoded.map((f) => [f.path, f.content]));
+  const existing = filesUnder(dirAbs).filter((p) => !PRESERVED.has(p));
+  let plan = planDecodeReplace(dirAbs, incoming, existing, readDecodeRecord(dirAbs, existing));
+  const deletions = plan.removals;
+  const lockPath = join(cwd, backendDir, "xano.lock");
+  const lock = existsSync(lockPath) ? readLockFile(lockPath) : void 0;
+  const reconciliation = lock === void 0 ? void 0 : reconcileLock(lock, pulledIdentities(bundle.payload));
+  if (reconciliation?.disjoint === true && args.yes !== true) {
+    throw await needsYes(
+      args,
+      `${noneOfTheIdentities(reconciliation.dropped.length, "xano.lock")} ${fetched.label}. That is what pointing a project at an unrelated backend looks like, and carrying the lock across would arm a wrong prune later.`,
+      "if you meant to repoint this project",
+      { refused: "unrelated-lock" }
+    );
+  }
+  const existingSet = new Set(existing);
+  const upToDate = !planTouchesExisting(plan) && [...incoming.keys()].every((p) => existingSet.has(p)) && (reconciliation?.dropped.length ?? 0) === 0;
+  const duplicates = keptDuplicates(dirAbs, incoming, plan.kept, backendDir);
+  if (upToDate) {
+    await refreshAgentGuidance({ ...args, file: join(cwd, backendDir, "index.ts") });
+    finishUpToDate(cwd, backendDir, project, args, fetched, lock, lockPath, reconciliation, bundle.payload, files.length, plan.kept, settingsReport(settings, backendDir), seedRows, duplicates);
+    return;
+  }
+  const cleanliness = backendDirCleanliness(cwd, backendDir);
+  if (cleanliness === "dirty" && args.yes !== true) {
+    throw await needsYes(
+      args,
+      `${backendDir}/ has uncommitted changes, and a pull rewrites the files it decodes. Commit or stash them first.`,
+      "to go ahead \u2014 it overwrites your edits to decoded files and keeps files you added",
+      { refused: "uncommitted-changes" }
+    );
+  }
+  if (cleanliness === "unknown") {
+    warn(`Not a git repository \u2014 nothing here holds the version of ${backendDir}/ about to be replaced.`, "pull.no-git");
+  }
+  if (cleanliness === "dirty") plan = withGitEdits(plan, gitChangedUnder(cwd, backendDir));
+  describeDecodeReplace(plan, backendDir, fetched.label, (line, files2) => warn(line, "pull.replace", files2));
+  const newFiles = [...incoming.keys()].filter((p) => !existingSet.has(p)).sort();
+  if (newFiles.length > 0) {
+    info(`${newFiles.length} new file${newFiles.length === 1 ? "" : "s"} will be written:`);
+    for (const p of newFiles.slice(0, 20)) detail(`${backendDir}/${p}`);
+    if (newFiles.length > 20) detail(`\u2026 and ${newFiles.length - 20} more`);
+  }
+  const droppedSeeds = codeSeedsDropped(dirAbs, incoming, plan, backendDir);
+  const rowsOnly = seedRows.filter((s) => !droppedSeeds.some((d) => d.table === s.table));
+  reportDroppedSeeds(
+    droppedSeeds,
+    seedRows,
+    fetched,
+    contextFlags(args),
+    cleanliness !== "unknown",
+    rowsOnly.length === 0,
+    source.kind === "release"
+  );
+  const modulesReplaced = replacedRegistrations(
+    dirAbs,
+    incoming,
+    existing.filter((p) => !plan.kept.includes(p)),
+    backendDir
+  );
+  reportSuperseded(duplicates, modulesReplaced, backendDir, cleanliness === "clean");
+  if (keptName !== void 0) {
+    detail(`Kept this project's workspace name "${keptName}" \u2014 ${fetched.label} does not carry it.`);
+  }
+  reportSeedRows(rowsOnly, fetched.label, fetched.provenance, backendDir, contextFlags(args));
+  if (settings.kept) {
+    detail(
+      `Kept this project's ${backendDir}/${WORKSPACE_SETTINGS_FILE} \u2014 ${fetched.label} carries no workspace settings.`
+    );
+  } else if (settings.lost.length > 0) {
+    warn(
+      `${fetched.label} carries no workspace settings, so the workspaceConfig in ${backendDir}/${settings.from} is rewritten without its ${settings.lost.join(", ")}. ${cleanliness === "unknown" ? "Add them back by hand" : "Restore them from git"} to keep them` + (settings.from === WORKSPACE_SETTINGS_FILE ? ` (a release pull keeps ${backendDir}/${WORKSPACE_SETTINGS_FILE} when ${backendDir}/index.ts imports its export and passes it to \`.registerWorkspace()\`)` : ` (declared in ${backendDir}/${WORKSPACE_SETTINGS_FILE} as \`export const workspaceSettings\`, a release pull keeps them)`) + `, or pull from the workspace that holds them.`,
+      "pull.settings-lost"
+    );
+  }
+  if (plan.removals.includes(WORKSPACE_SETTINGS_FILE)) {
+    warn(
+      `${fetched.label} carries no workspace settings, so ${backendDir}/${WORKSPACE_SETTINGS_FILE} (the previous decode's) is removed and index.ts registers none. Restore it from git to keep them, or pull from the workspace that holds them.`,
+      "pull.settings-lost"
+    );
+  }
+  const lockReport = lockReportOf(reconciliation);
+  if (lockReport.dropped.length > 0) {
+    const dropped = lockReport.dropped;
+    warn(
+      `${dropped.length} ${backendDir}/xano.lock entr${dropped.length === 1 ? "y has" : "ies have"} no counterpart in ${fetched.label} and will be dropped:`,
+      "pull.lock-dropped",
+      // The lock's own key spelling (`dbo:users`), so it can be found in the file.
+      capped(dropped)
+    );
+  }
+  if (lockReport.renamed.length > 0) {
+    const renamed = lockReport.renamed;
+    info(
+      `${renamed.length} ${backendDir}/xano.lock entr${renamed.length === 1 ? "y keeps its" : "ies keep their"} identity under the name ${fetched.label} carries ${renamed.length === 1 ? "it" : "them"} by (renamed there):`
+    );
+    for (const line of capped(renamed.map((r) => `${r.from} \u2192 ${r.to} (guid ${r.guid})`))) detail(line);
+  }
+  if (lockReport.repinned.length > 0) {
+    const repinned = lockReport.repinned;
+    warn(
+      `${repinned.length} ${backendDir}/xano.lock entr${repinned.length === 1 ? "y" : "ies"} will be re-pinned to the object ${fetched.label} holds under the same name:`,
+      "pull.lock-repinned",
+      capped(repinned.map((r) => `${r.key}: ${r.from} \u2192 ${r.to}`))
+    );
+  }
+  if (args.yes !== true) {
+    const { yesRerun } = await import("./retry-command-AS5EVREX.js");
+    const { rerun, note } = yesRerun(args, "pull");
+    const ok = await confirm(`Replace ${backendDir}/ from ${fetched.label}?`, {
+      flag: "--yes",
+      refusal: { details: { written: false }, rerun, note }
+    });
+    if (!ok) {
+      info("Pull cancelled. Nothing was written.");
+      return;
+    }
+  }
+  const planned = containedWrites(
+    join(cwd, backendDir),
+    files,
+    (path) => new UsageError(
+      `${fetched.label} carries a file that would be written outside ${backendDir}/ ("${path}"). Nothing was written. A source cannot place files anywhere else in this project, so this one is refused rather than trusted.`
+    ),
+    cwd
+  );
+  const previousNames = [
+    .../* @__PURE__ */ new Set([
+      ...namesInEnvExample(join(cwd, backendDir, WORKSPACE_ENV_EXAMPLE_BASENAME)),
+      ...declaredEnvNames(dirAbs)
+    ])
+  ];
+  step(`Writing ${backendDir}/ from ${fetched.label}`);
+  removeFiles(dirAbs, plan.removals);
+  removeEmptiedDirs(dirAbs, plan.removals);
+  for (const file of planned) {
+    mkdirSync(dirname(file.full), { recursive: true });
+    writeFileSync(file.full, file.content, "utf8");
+  }
+  const head = decodeMarkerHead(previousMarker(dirAbs), "pull", fetched.provenance, readVersion(), project.report.toJson());
+  writeFileSync(join(dirAbs, DECODE_MARKER), `${JSON.stringify(decodeMarkerWith(head, decoded), null, 2)}
+`, "utf8");
+  reportKept(backendDir, plan.kept);
+  reportFindings(project, backendDir);
+  ensureSecretPathGitignored(join(cwd, backendDir, WORKSPACE_ENV_BASENAME));
+  writeDocumentationTokens(
+    cwd,
+    project.documentationTokens,
+    args,
+    fetched.label,
+    join(cwd, backendDir, WORKSPACE_SECRETS_BASENAME)
+  );
+  if (lock !== void 0 && reconciliation !== void 0) {
+    writeLockFile(lockPath, pulledLock(lock, reconciliation, bundle.payload));
+  }
+  try {
+    const keptNames = settings.kept ? settings.envNames ?? previousNames : void 0;
+    reportEnvNameChanges(
+      cwd,
+      backendDir,
+      keptNames ?? previousNames,
+      keptNames ?? Object.keys(project.env),
+      (one) => envFillRemedy(source.kind, args, one)
+    );
+  } catch (err) {
+    warn(
+      `Could not check ${backendDir}/${WORKSPACE_ENV_BASENAME} for missing values (${err instanceof Error ? err.message : String(err)}). The pull itself is complete.`,
+      "pull.env-check-failed"
+    );
+  }
+  warnTsxNeeded(join(cwd, backendDir, "index.ts"), planned.map((f) => f.full), backendDir);
+  await refreshAgentGuidance({ ...args, file: join(cwd, backendDir, "index.ts") });
+  let verified = null;
+  if (args.skipRoundtrip !== true) {
+    step(`Verifying ${backendDir}/ round-trips`);
+    verified = await verifyPulledTree(cwd, backendDir, project, source.kind, settings.kept);
+    if (verified === false) {
+      process.stderr.write(`${terminalText(project.report.renderCli({ fileBase: `${backendDir}/` }))}
+`);
+      warn(
+        `${backendDir}/ is NOT verified \u2014 the objects listed above do not re-export as ${fetched.label} holds them. Do not deploy it; reconcile the objects the report names, or re-run the pull once the source is fixed.`,
+        "pull.unverified"
+      );
+    }
+  }
+  if (isMachineOutput(args)) {
+    writeJson({
+      source: fetched.provenance,
+      upToDate: false,
+      files: files.length,
+      deleted: deletions.length,
+      removedEdited: plan.removedEdited.map((p) => `${backendDir}/${p}`),
+      rewrittenEdited: plan.edited.map((p) => `${backendDir}/${p}`),
+      kept: plan.kept.map((p) => `${backendDir}/${p}`),
+      lockKept: reconciliation?.kept.length ?? 0,
+      lockDropped: lockReport.dropped.length,
+      lockRepinned: lockReport.repinned.length,
+      lockRenamed: lockReport.renamed.length,
+      workspaceSettings: settingsReport(settings, backendDir),
+      seedRows,
+      newFiles: newFiles.map((p) => `${backendDir}/${p}`),
+      droppedSeeds,
+      keptDuplicates: duplicates,
+      modulesReplaced,
+      verified
+    });
+    if (verified === false) throw pullVerifyFailed(cwd, backendDir);
+    success(`Pulled ${fetched.label}`);
+    detail(`${files.length} files written, ${deletions.length} removed`);
+    return;
+  }
+  if (verified === false) throw pullVerifyFailed(cwd, backendDir);
+  success(`Pulled ${fetched.label}`);
+  detail(`${files.length} files written, ${deletions.length} removed`);
+  if (reconciliation !== void 0) {
+    detail(
+      // Every count `--json` carries, renamed included (E2E pass 29: it was not said).
+      `lock: ${reconciliation.kept.length} kept, ${lockReport.repinned.length} re-pinned, ${lockReport.renamed.length} renamed, ${lockReport.dropped.length} dropped`
+    );
+  }
+}
+function tsxResolvable(entry) {
+  for (const from of [pathToFileURL(resolve(entry)).href, import.meta.url]) {
+    try {
+      createRequire(from).resolve("tsx/esm/api");
+      return true;
+    } catch {
+    }
+  }
+  return false;
+}
+function warnTsxNeeded(entry, written, backendDir, resolvable = tsxResolvable) {
+  const modules = written.filter((f) => /\.[cm]?ts$/.test(f) && !/\.d\.[cm]?ts$/.test(f));
+  if (modules.length < 2 || resolvable(entry)) return;
+  warn(
+    `${backendDir}/ is now ${modules.length} TypeScript files, and an entry that imports its own modules loads only under tsx, which this project does not have \u2014 the next deploy fails until it does. Install it: \`npm i -D tsx\`.`,
+    "pull.tsx-needed"
+  );
+}
+function finishUpToDate(cwd, backendDir, project, args, fetched, lock, lockPath, reconciliation, payload, fileCount, kept, workspaceSettings, seedRows, duplicates) {
+  reportSeedRows(seedRows, fetched.label, fetched.provenance, backendDir, contextFlags(args));
+  ensureSecretPathGitignored(join(cwd, backendDir, WORKSPACE_ENV_BASENAME));
+  writeDocumentationTokens(cwd, project.documentationTokens, args, fetched.label, join(cwd, backendDir, WORKSPACE_SECRETS_BASENAME));
+  if (lock !== void 0 && reconciliation !== void 0) writeLockFile(lockPath, pulledLock(lock, reconciliation, payload));
+  if (isMachineOutput(args)) {
+    writeJson({
+      source: fetched.provenance,
+      upToDate: true,
+      files: fileCount,
+      deleted: 0,
+      removedEdited: [],
+      rewrittenEdited: [],
+      // The files no decode wrote are still there, and still the author's — the
+      // same list a replacing pull reports, so the field means one thing.
+      kept: kept.map((p) => `${backendDir}/${p}`),
+      lockKept: reconciliation?.kept.length ?? 0,
+      lockDropped: 0,
+      lockRepinned: 0,
+      lockRenamed: 0,
+      workspaceSettings,
+      seedRows,
+      newFiles: [],
+      droppedSeeds: [],
+      keptDuplicates: duplicates,
+      modulesReplaced: [],
+      // Nothing was written, so there is nothing new to check.
+      verified: null
+    });
+  }
+  success(`${backendDir}/ is already up to date with ${fetched.label} \u2014 nothing to replace.`);
+  if (!isMachineOutput(args)) {
+    reportKept(backendDir, kept);
+    reportSuperseded(duplicates, [], backendDir, false);
+  }
+}
+function codeSeedsDropped(dirAbs, incoming, plan, backendDir) {
+  const pulled = /* @__PURE__ */ new Map();
+  for (const text of incoming.values()) {
+    for (const t of declaredTables(text)) {
+      if (t.name !== null) pulled.set(t.name, (pulled.get(t.name) ?? false) || t.seeded);
+    }
+  }
+  const out = [];
+  const into = (table, own) => {
+    if (table === null) return incoming.has(own) ? `${backendDir}/${own}` : null;
+    for (const [p, text] of incoming) if (declaredTables(text).some((t) => t.name === table)) return `${backendDir}/${p}`;
+    return null;
+  };
+  const read = (p) => {
+    try {
+      return readFileSync(join(dirAbs, p), "utf8");
+    } catch {
+      return void 0;
+    }
+  };
+  for (const p of [...plan.edited, ...plan.rewrittenUnknown, ...plan.changedBySource, ...plan.removals]) {
+    const current = read(p);
+    if (current === void 0) continue;
+    for (const t of declaredTables(current)) {
+      if (!t.seeded) continue;
+      const kept = t.name === null ? SEED.test(incoming.get(p) ?? "") : pulled.get(t.name) === true;
+      if (!kept) out.push({ table: t.name, file: `${backendDir}/${p}`, kept: false, into: into(t.name, p) });
+    }
+  }
+  for (const p of plan.kept) {
+    const current = read(p);
+    if (current === void 0) continue;
+    for (const t of declaredTables(current)) {
+      if (t.seeded && t.name !== null && pulled.get(t.name) === false) {
+        out.push({ table: t.name, file: `${backendDir}/${p}`, kept: true, into: into(t.name, p) });
+      }
+    }
+  }
+  return out;
+}
+var SEED = /\bseed\s*:/;
+function declaredTables(text) {
+  const starts = [...text.matchAll(/\btable\s*\(\s*\{/g)].map((m) => m.index);
+  return starts.map((start, i) => {
+    const chunk = text.slice(start, starts[i + 1] ?? text.length);
+    const name = /\bname\s*:\s*(["'`])([^"'`]+)\1/.exec(chunk)?.[2];
+    return { name: name ?? null, seeded: SEED.test(chunk) };
+  });
+}
+function reportDroppedSeeds(dropped, seedRows, fetched, flags, inGit, saysLanding, fromRelease) {
+  if (dropped.length === 0) return;
+  const { label } = fetched;
+  const one = dropped.length === 1;
+  const rowsFor = (table) => seedRows.find((s) => s.table === table)?.rows;
+  const lines = dropped.map((d) => {
+    const rows = rowsFor(d.table);
+    const carried = rows !== void 0 ? `${label} carries ${rows} seed ${rows === 1 ? "row" : "rows"} for it, which a decoded tree does not hold either` : fromRelease ? `${label} carries no seed rows for it` : `a pull doesn't carry live rows, so none come from ${label}`;
+    const file = pastePath(d.file);
+    const target = pastePath(d.into ?? d.file);
+    const gitPath = file.startsWith("../") || file.startsWith("/") ? file : `./${file}`;
+    const keep = d.kept ? `${file} stays on disk but is no longer part of the project \u2014 copy its \`seed:\` array into ${target} after the pull` : inGit ? `after the pull, copy its \`seed:\` array from \`git show HEAD:${gitPath}\` into ${target}` : `nothing here holds the current version \u2014 copy its \`seed:\` array out of ${file} before pulling, then into ${target}`;
+    const from = dirname(d.file);
+    const to = dirname(d.into ?? d.file);
+    const rebase = from === to ? "" : ` \u2014 its \`seedFile(\u2026)\`/\`hostedFile(\u2026)\` paths are relative to ${file}, so in ${target} prefix each relative one with \`${relative(to, from).split(sep).join("/")}/\` (\`./seed/x.json\` \u2192 \`${relative(to, join(from, "seed", "x.json")).split(sep).join("/").replace(/^(?!\.)/, "./")}\`)`;
+    return `${d.table === null ? file : `${d.table} (${file})`}: ${carried}. To keep the code seed, ${keep}${rebase}.`;
+  });
+  warn(
+    `${dropped.length} table${one ? " is" : "s are"} seeded in code, and the pulled tree drops ${one ? "that" : "each"} \`seed:\`:`,
+    "pull.seeds-dropped",
+    saysLanding && dropped.some((d) => rowsFor(d.table) !== void 0) ? [...lines, seedRowsLanding(fetched.provenance, flags)] : lines
+  );
+}
+function settingsReport(settings, backendDir) {
+  return { kept: settings.kept, dropped: settings.lost, file: `${backendDir}/${settings.from}` };
+}
+var WORKSPACE_SETTINGS_FILE = "workspace.ts";
+var WORKSPACE_SETTINGS_BINDING = "workspaceSettings";
+function registeredSettingsExport(index, settings) {
+  const local = /\.registerWorkspace\(\s*([A-Za-z_$][\w$]*)\s*\)/.exec(index)?.[1];
+  if (local === void 0) return void 0;
+  const imports = /\bimport\s+(?:type\s+)?([A-Za-z_$][\w$]*)?\s*,?\s*(?:\{([^}]*)\})?\s*from\s*["']\.\/workspace(?:\.js|\.ts)?["']/g;
+  for (const m of index.matchAll(imports)) {
+    if (m[1] === local) return /\bexport\s+default\b/.test(settings) ? "default" : void 0;
+    for (const spec of (m[2] ?? "").split(",")) {
+      const [imported = "", as] = spec.trim().split(/\s+as\s+/);
+      const name = imported.trim();
+      if (name === "" || (as?.trim() ?? name) !== local) continue;
+      const word = name.replace(/\$/g, "\\$");
+      const exported = new RegExp(`\\bexport\\s+(?:const|let|var)\\s+${word}\\b|\\bexport\\s*\\{[^}]*\\b${word}\\b[^}]*\\}`);
+      return exported.test(settings) ? { name } : void 0;
+    }
+  }
+  return void 0;
+}
+function importingKeptSettings(index, binding) {
+  if (binding !== "default" && binding.name === WORKSPACE_SETTINGS_BINDING) return index;
+  const spec = binding === "default" ? WORKSPACE_SETTINGS_BINDING : `{ ${binding.name} as ${WORKSPACE_SETTINGS_BINDING} }`;
+  return index.replace(
+    /\bimport\s*\{\s*workspaceSettings\s*\}\s*from\s*(["']\.\/workspace\.js["'])/,
+    (_m, from) => `import ${spec} from ${from}`
+  );
+}
+function literalEntries(text, open) {
+  const entries = [];
+  let depth = 0;
+  let key = true;
+  for (let i = open; i < text.length; i++) {
+    const c = text[i];
+    if (c === '"' || c === "'" || c === "`") {
+      let j = i + 1;
+      while (j < text.length && text[j] !== c) j += text[j] === "\\" ? 2 : 1;
+      if (depth === 1 && key) entries.push({ key: text.slice(i + 1, j), value: j + 1 });
+      i = j;
+      key = false;
+    } else if (depth === 1 && key && text.startsWith("...", i)) {
+      entries.push({ key: void 0, value: i + 3 });
+      i += 2;
+      key = false;
+    } else if ("{[(".includes(c)) {
+      if (depth === 1 && key && c === "[") entries.push({ key: void 0, value: i });
+      key = ++depth === 1;
+    } else if ("}])".includes(c)) {
+      if (--depth === 0) break;
+    } else if (depth === 1 && c === ",") {
+      key = true;
+    } else if (depth === 1 && key && /[A-Za-z_$]/.test(c)) {
+      const word = /^[\w$]+/.exec(text.slice(i))[0];
+      entries.push({ key: word, value: i + word.length });
+      i += word.length - 1;
+      key = false;
+    }
+  }
+  return entries;
+}
+function settingsLiteral(text) {
+  const at = /\bworkspaceConfig\s*\(\s*\{/.exec(text);
+  return at === null ? -1 : at.index + at[0].length - 1;
+}
+function settingsKeys(text) {
+  const open = settingsLiteral(text);
+  if (open < 0) return [];
+  return literalEntries(text, open).flatMap((e) => e.key === void 0 ? [] : [e.key]);
+}
+function settingsEnvNames(text) {
+  const open = settingsLiteral(text);
+  if (open < 0) return void 0;
+  const entries = literalEntries(text, open);
+  const env = entries.find((e) => e.key === "env");
+  if (env === void 0) return entries.some((e) => e.key === void 0) ? void 0 : [];
+  const value = /^\s*:\s*\{/.exec(text.slice(env.value));
+  if (value === null) return void 0;
+  const names = literalEntries(text, env.value + value[0].length - 1);
+  return names.some((e) => e.key === void 0) ? void 0 : names.map((e) => e.key);
+}
+function readableDeclaredEnvNames(dirAbs) {
+  let found = false;
+  const names = [];
+  for (const name of [WORKSPACE_SETTINGS_FILE, "index.ts"]) {
+    let text;
+    try {
+      text = readFileSync(join(dirAbs, name), "utf8");
+    } catch {
+      continue;
+    }
+    if (settingsLiteral(text) < 0) continue;
+    const read = settingsEnvNames(text);
+    if (read === void 0) return void 0;
+    found = true;
+    names.push(...read);
+  }
+  return found ? [...new Set(names)] : void 0;
+}
+function declaredEnvNames(dirAbs) {
+  return [WORKSPACE_SETTINGS_FILE, "index.ts"].flatMap((name) => {
+    try {
+      return settingsEnvNames(readFileSync(join(dirAbs, name), "utf8")) ?? [];
+    } catch {
+      return [];
+    }
+  });
+}
+function keepProjectSettings(files, backendDir, dirAbs) {
+  const incoming = files.find((f) => f.path === `${backendDir}/${WORKSPACE_SETTINGS_FILE}`);
+  const read = (name) => {
+    try {
+      return readFileSync(join(dirAbs, name), "utf8");
+    } catch {
+      return void 0;
+    }
+  };
+  const ours = read(WORKSPACE_SETTINGS_FILE);
+  const index = read("index.ts") ?? "";
+  const binding = ours === void 0 ? void 0 : registeredSettingsExport(index, ours);
+  if (incoming !== void 0 && ours !== void 0 && binding !== void 0) {
+    const example = `${backendDir}/${WORKSPACE_ENV_EXAMPLE_BASENAME}`;
+    const entry = `${backendDir}/index.ts`;
+    const ourExample = read(WORKSPACE_ENV_EXAMPLE_BASENAME);
+    const envNames = settingsEnvNames(ours);
+    const exampleContent = (decoded) => ourExample ?? (envNames === void 0 ? void 0 : rerenderEnvExample(decoded, envNames));
+    const out = files.flatMap((f) => {
+      if (f === incoming) return [{ ...f, content: ours }];
+      if (f.path === entry) return [{ ...f, content: importingKeptSettings(f.content, binding) }];
+      if (f.path !== example) return [f];
+      const content = exampleContent(f.content);
+      return content === void 0 ? [] : [{ ...f, content }];
+    });
+    return { files: out, kept: true, lost: [], from: WORKSPACE_SETTINGS_FILE, ...envNames === void 0 ? {} : { envNames } };
+  }
+  const inline = binding === void 0 && settingsLiteral(index) >= 0;
+  const from = ours !== void 0 && !inline ? WORKSPACE_SETTINGS_FILE : "index.ts";
+  const theirs = new Set(incoming === void 0 ? [] : settingsKeys(incoming.content));
+  const lost = settingsKeys(from === "index.ts" ? index : ours ?? "").filter((k) => k === "env" || !theirs.has(k));
+  return { files, kept: false, lost, from };
+}
+function projectWorkspaceName(entry) {
+  let text;
+  try {
+    text = readFileSync(entry, "utf8");
+  } catch {
+    return void 0;
+  }
+  const m = /\bworkspace\(\s*("(?:[^"\\\n]|\\.)*"|'(?:[^'\\\n]|\\.)*')\s*[,)]/.exec(text);
+  if (m === null) return void 0;
+  const lit = m[1];
+  try {
+    const name = lit.startsWith('"') ? JSON.parse(lit) : lit.slice(1, -1);
+    return name.trim() === "" ? void 0 : name;
+  } catch {
+    return void 0;
+  }
+}
+function reportFindings(project, backendDir) {
+  const rendered = project.report.renderCli({ fileBase: `${backendDir}/` });
+  if (rendered === "") return;
+  const summary = project.report.summarize();
+  if (summary.bySeverity.error + summary.bySeverity.warning > 0) {
+    warn(`Not everything was carried into the tree \u2014 ${project.report.headline()} (listed below).`, "decode.findings");
+  } else {
+    info("Some values are deliberately not carried into the tree:");
+  }
+  process.stderr.write(`${terminalText(rendered)}
+`);
+}
+function pullVerifyFailed(cwd, backendDir) {
+  return Object.assign(
+    new Error(
+      `Round-trip verification failed for ${join(cwd, backendDir)} \u2014 see the mismatches above. The files were written so you can inspect them; do not deploy them.`
+    ),
+    { exitCode: 2 }
+  );
+}
+function reportKept(backendDir, kept) {
+  if (kept.length === 0) return;
+  warn(
+    `Kept ${kept.length} file${kept.length === 1 ? "" : "s"} in ${backendDir}/ no decode wrote \u2014 ${kept.length === 1 ? "it is" : "they are"} yours, and not part of the decoded tree:`,
+    "pull.kept-files",
+    capped(kept.map((p) => `${backendDir}/${p}`))
+  );
+}
+function capped(lines) {
+  return [...lines.slice(0, 20), ...lines.length > 20 ? [`\u2026 and ${lines.length - 20} more`] : []];
+}
+function previousMarker(dir) {
+  try {
+    const parsed = JSON.parse(readFileSync(join(dir, DECODE_MARKER), "utf8"));
+    if (parsed !== null && typeof parsed === "object" && !Array.isArray(parsed)) return parsed;
+  } catch {
+  }
+  return {};
+}
+function reportEnvNameChanges(cwd, backendDir, before, after, remedy) {
+  const envFile = `${backendDir}/${WORKSPACE_ENV_BASENAME}`;
+  const exampleFile = `${backendDir}/${WORKSPACE_ENV_EXAMPLE_BASENAME}`;
+  const had = new Set(before);
+  const has = new Set(after);
+  const added = after.filter((n) => !had.has(n));
+  const removed = before.filter((n) => !has.has(n));
+  if (added.length > 0) {
+    info(`Env vars added by this pull: ${added.join(", ")} (declared in ${exampleFile}).`);
+  }
+  if (removed.length > 0) {
+    info(`Env vars no longer declared: ${removed.join(", ")}.`);
+  }
+  if (after.length === 0) return;
+  const values = readWorkspaceEnvFile(join(cwd, envFile)) ?? {};
+  const missing = after.filter((n) => !Object.hasOwn(values, n));
+  if (missing.length === 0) return;
+  warn(
+    `${missing.length} declared env var${missing.length === 1 ? " has" : "s have"} no value in ${envFile}: ${missing.join(", ")}. A deploy will refuse until ${missing.length === 1 ? "it does" : "they do"} \u2014 ${remedy(missing.length === 1)}`,
+    "workspace-env.missing-values"
+  );
+}
+function envFillRemedy(kind, args, one = false) {
+  const them = one ? "it" : "them";
+  const raw = args.positionals[0];
+  if (kind === "release") {
+    return `a release carries no env values, so fill ${them} in by hand, or read ${them} from a running backend with \`xanosdk env pull --from <backend>\`.`;
+  }
+  const from = raw === void 0 ? "" : ` --from ${shellQuote(raw)}`;
+  const flags = kind === "local-engine" ? "" : contextFlags(args);
+  return `fill ${them} in, or run \`xanosdk env pull${from}${flags}\`.`;
+}
+async function needsYes(args, head, why, details) {
+  const { yesRerun } = await import("./retry-command-AS5EVREX.js");
+  const { rerun, note } = yesRerun(args, "pull");
+  return new CliError("SDK_USAGE", `${head} Re-run as \`${rerun}\` ${why}.${note}`, {
+    exitCode: 1,
+    details: { reason: "needs-confirmation", written: false, ...details }
+  });
+}
+
+export {
+  backendDirCleanliness,
+  gitChangedUnder,
+  withGitEdits,
+  lockReportOf,
+  pulledIdentities,
+  noneOfTheIdentities,
+  reconcileLock,
+  reconciledLock,
+  pulledLock,
+  runPullCommand,
+  tsxResolvable,
+  warnTsxNeeded,
+  codeSeedsDropped,
+  registeredSettingsExport,
+  settingsEnvNames,
+  readableDeclaredEnvNames,
+  declaredEnvNames,
+  projectWorkspaceName,
+  envFillRemedy
+};
+//# sourceMappingURL=chunk-K4WX6UUU.js.map