@xano/sdk 1.0.0

package/dist/chunk-PTHVMXZI.js

@@ -0,0 +1,3036 @@
+import {
+  suggest
+} from "./chunk-UTI5G6OJ.js";
+import {
+  setDiagnosticSink
+} from "./chunk-2EZ3ZJZZ.js";
+import {
+  shellQuote
+} from "./chunk-5ZSO4T2G.js";
+import {
+  fontIdsFor
+} from "./chunk-TFFGOFVZ.js";
+import {
+  withArticle
+} from "./chunk-36JUQZVQ.js";
+
+// src/emit/ui.ts
+import { randomBytes } from "crypto";
+
+// src/emit/output.ts
+import { AsyncLocalStorage } from "async_hooks";
+
+// src/emit/json-target.ts
+var BACKEND_KINDS = /* @__PURE__ */ new Set(["workspace", "ephemeral", "tenant", "local-engine"]);
+var isObject = (v) => typeof v === "object" && v !== null && !Array.isArray(v);
+var text = (v) => typeof v === "string" && v !== "" ? v : void 0;
+function backendSelector(kind, name) {
+  if (typeof kind !== "string" || !BACKEND_KINDS.has(kind)) return void 0;
+  if (kind === "workspace") return "workspace";
+  const n = text(name);
+  if (n !== void 0) return n.startsWith(`${kind}:`) ? n : `${kind}:${n}`;
+  return kind === "tenant" ? void 0 : kind;
+}
+function derive(doc) {
+  const out = {};
+  const destination = doc.destination;
+  if (isObject(destination)) {
+    out.selector = backendSelector(destination.kind, destination.label);
+    if (typeof destination.workspaceId === "number") out.workspaceId = destination.workspaceId;
+  } else if (typeof doc.kind === "string" && BACKEND_KINDS.has(doc.kind) && "name" in doc) {
+    out.selector = backendSelector(doc.kind, doc.name);
+  } else if (isObject(doc.deployed) && "environment" in doc) {
+    const kind = doc.deployed.kind;
+    const env = isObject(doc.environment) ? doc.environment.name : void 0;
+    if (kind === "ephemeral" && text(env) !== void 0) out.selector = `ephemeral:${env}`;
+    else if (kind === "local-engine") out.selector = "local-engine";
+  }
+  if (out.workspaceId === void 0 && isObject(doc.workspace) && typeof doc.workspace.id === "number") {
+    out.workspaceId = doc.workspace.id;
+  }
+  return out;
+}
+function withBackendFields(value) {
+  if (!isObject(value) || "error" in value) return value;
+  const { selector, workspaceId } = derive(value);
+  return {
+    ...value,
+    ...selector !== void 0 && !("selector" in value) ? { selector } : {},
+    ...workspaceId !== void 0 && !("workspaceId" in value) ? { workspaceId } : {}
+  };
+}
+
+// src/emit/invocation.ts
+import { existsSync, readFileSync, realpathSync, statSync } from "fs";
+import { basename, dirname, isAbsolute as isAbsolute3, join, relative as relative3, resolve as resolve3, sep as sep3 } from "path";
+import { homedir } from "os";
+
+// src/emit/typed-cwd.ts
+import { isAbsolute as isAbsolute2, relative as relative2, resolve as resolve2, sep as sep2 } from "path";
+
+// src/util/rel-path.ts
+import { isAbsolute, relative, resolve, sep } from "path";
+function relForwardSlash(root, target) {
+  const rel = relative(root, target);
+  return rel === "" || rel.startsWith("..") ? "" : rel.split(sep).join("/");
+}
+var typedFrom;
+function setPathsShownFrom(dir) {
+  typedFrom = dir;
+}
+function pathsShownFrom() {
+  return typedFrom;
+}
+function displayPath(target, root) {
+  if (root === void 0 && typedFrom !== void 0) {
+    const abs = resolve(target);
+    const fromTyped = relative(typedFrom, abs).split(sep).join("/");
+    if (fromTyped === "") return ".";
+    if (!fromTyped.startsWith("..") && !isAbsolute(fromTyped)) return fromTyped;
+    return relForwardSlash(process.cwd(), abs) !== "" ? fromTyped : abs;
+  }
+  return relForwardSlash(root ?? process.cwd(), target) || target;
+}
+
+// src/emit/typed-cwd.ts
+var base;
+function setTypedCwdBase(dir) {
+  base = dir;
+  setPathsShownFrom(dir);
+}
+function setTypedCwd(dir) {
+  setPathsShownFrom(dir ?? base);
+}
+function pastePath(path) {
+  const typed = pathsShownFrom();
+  if (typed === void 0 || isAbsolute2(path)) return path;
+  return relative2(typed, resolve2(path)).split(sep2).join("/") || ".";
+}
+
+// src/emit/invocation.ts
+var GLOBAL_STORES = [
+  `${sep3}lib${sep3}node_modules${sep3}`,
+  `${sep3}npm${sep3}node_modules${sep3}`,
+  `${sep3}pnpm${sep3}global${sep3}`,
+  `${sep3}yarn${sep3}global${sep3}`
+];
+function launcherFor(facts) {
+  const bin = facts.binPath;
+  const marker = `${sep3}node_modules${sep3}`;
+  const at = bin.lastIndexOf(marker);
+  if (at === -1) return "path";
+  if (bin.includes(`${sep3}_npx${sep3}`) || facts.env.npm_command === "exec") return "npx";
+  const installRoot = bin.slice(0, at);
+  const cwd = facts.cwd;
+  if (cwd === installRoot || cwd.startsWith(installRoot + sep3)) return "npx";
+  const store = bin.slice(0, at + marker.length);
+  if (GLOBAL_STORES.some((s) => store.endsWith(s) || bin.includes(s))) return "path";
+  return "npx";
+}
+function typedDirFor(cwd, env) {
+  const init = env.INIT_CWD;
+  if (init === void 0 || init === "" || env.npm_lifecycle_event === void 0) return cwd;
+  if (env.npm_package_json === void 0 || resolve3(env.npm_package_json) !== resolve3(cwd, "package.json")) return cwd;
+  const rel = relative3(cwd, init);
+  return rel === "" || !rel.startsWith("..") && !isAbsolute3(rel) ? resolve3(init) : cwd;
+}
+var installedCache = /* @__PURE__ */ new Map();
+function binDirAbove(from) {
+  for (let d = from; ; d = dirname(d)) {
+    const bin = join(d, "node_modules", ".bin");
+    if (existsSync(join(bin, "xanosdk")) || existsSync(join(bin, "xanosdk.cmd"))) return bin;
+    if (dirname(d) === d) return void 0;
+  }
+}
+function readManifest(dir) {
+  try {
+    return JSON.parse(readFileSync(join(dir, "package.json"), "utf8"));
+  } catch {
+    return void 0;
+  }
+}
+function isDir(path) {
+  try {
+    return statSync(path).isDirectory();
+  } catch {
+    return false;
+  }
+}
+function workspaceGlob(glob) {
+  const segs = glob.replace(/^\.\//, "").replace(/\/+$/, "").split("/");
+  const source = segs.map(
+    (seg, i) => seg === "**" ? i === segs.length - 1 ? ".*" : "(?:[^/]+/)*" : seg.replace(/[.+^${}()|[\]\\]/g, "\\$&").replace(/\*/g, "[^/]*").replace(/\?/g, "[^/]") + (i === segs.length - 1 ? "" : "/")
+  ).join("");
+  return new RegExp(`^${source}$`);
+}
+function listsWorkspace(root, workspaces, member) {
+  const list = Array.isArray(workspaces) ? workspaces : workspaces?.packages;
+  if (!Array.isArray(list)) return false;
+  const rel = relative3(root, member).split(sep3).join("/");
+  const globs = list.filter((g) => typeof g === "string");
+  const hit = (g) => workspaceGlob(g).test(rel);
+  return globs.some((g) => !g.startsWith("!") && hit(g)) && !globs.some((g) => g.startsWith("!") && hit(g.slice(1)));
+}
+function npxBinDir(from) {
+  let prefix;
+  for (let d = from; prefix === void 0; d = dirname(d)) {
+    if (existsSync(join(d, "package.json")) || isDir(join(d, "node_modules"))) prefix = d;
+    else if (dirname(d) === d) break;
+  }
+  if (prefix === void 0) return binDirAbove(from);
+  const root = listingWorkspaceRoot(prefix);
+  if (root === void 0) return binDirAbove(prefix);
+  const name = readManifest(prefix)?.name;
+  return binDirAbove(join(root, "node_modules", typeof name === "string" && name !== "" ? name : basename(prefix)));
+}
+function listingWorkspaceRoot(prefix) {
+  for (let d = dirname(prefix); ; d = dirname(d)) {
+    if (existsSync(join(d, "package.json"))) {
+      const manifest = readManifest(d);
+      if (manifest?.workspaces !== void 0 && listsWorkspace(d, manifest.workspaces, prefix)) return d;
+    }
+    if (dirname(d) === d) return void 0;
+  }
+}
+function projectFileCli(dir, manager) {
+  if (manager === "npm" || manager === "yarn") return "npx xanosdk";
+  return listingWorkspaceRoot(resolve3(dir)) === void 0 ? "npx xanosdk" : "npx --workspaces=false xanosdk";
+}
+function spellProjectCli(text2, cli) {
+  return cli === void 0 || cli === "npx xanosdk" ? text2 : text2.replace(/\bnpx xanosdk(?=[\s`'")\]]|$)/g, cli);
+}
+var PROJECT_SDK_DIR = "node_modules/@xano/sdk";
+function projectSdkDir(dir, manager) {
+  const project = resolve3(dir);
+  if (existsSync(join(project, PROJECT_SDK_DIR, "package.json"))) return PROJECT_SDK_DIR;
+  if (manager !== "npm" && manager !== "yarn") return PROJECT_SDK_DIR;
+  const root = listingWorkspaceRoot(project);
+  if (root === void 0) return PROJECT_SDK_DIR;
+  return `${relative3(project, root).split(sep3).join("/")}/${PROJECT_SDK_DIR}`;
+}
+function spellProjectSdkDir(text2, sdkDir) {
+  if (sdkDir === void 0 || sdkDir === PROJECT_SDK_DIR) return text2;
+  return text2.replace(/(?<![\w./-])node_modules\/@xano\/sdk(?=\/)/g, sdkDir);
+}
+function installedCliAt(dir) {
+  return sdkInstalledAt(dir) === "member-only" ? "npx --workspaces=false xanosdk" : "npx xanosdk";
+}
+function sameDir(a, b) {
+  try {
+    return realpathSync(a) === realpathSync(b);
+  } catch {
+    return false;
+  }
+}
+function sdkInstalledAt(dir) {
+  const start = resolve3(dir);
+  const cached = installedCache.get(start);
+  if (cached !== void 0) return cached;
+  const own = binDirAbove(start);
+  if (own === void 0) return false;
+  const npx = npxBinDir(start);
+  const found = npx !== void 0 && sameDir(npx, own) ? true : "member-only";
+  installedCache.set(start, found);
+  return found;
+}
+var state;
+function setCliLauncher(launcher, typedDir, installedAt = sdkInstalledAt) {
+  state = launcher === "path" ? void 0 : { launcher, typedDir: typedDir ?? process.cwd(), installedAt };
+}
+function cliPrefixAt(dir, s = state) {
+  if (s === void 0) return "xanosdk";
+  const installed = s.installedAt(resolve3(s.typedDir, dir ?? "."));
+  return installed === true ? "npx xanosdk" : installed === "member-only" ? "npx --workspaces=false xanosdk" : "npx @xano/sdk";
+}
+var pattern;
+function commandPattern() {
+  if (pattern !== void 0) return pattern;
+  const names = Object.keys(COMMANDS).sort((a, b) => b.length - a.length).map((n) => n.replace(/[-]/g, "\\-"));
+  pattern = new RegExp(
+    `(^|\\n|\`|&& |\\|\\| |\\| |; |\\$\\(|\\( ?|\\{ |(?<![\\w-])(?:do|then|else|!) |\\w: |\\x1b\\[[0-9;]*m)([ \\t]*(?:\\$ )?(?:env (?:(?:-u |--unset[= ])[A-Za-z_][A-Za-z0-9_]* )*)?(?:[A-Za-z_][A-Za-z0-9_]*=(?:'[^'\\n]*'|"[^"\\n]*"|[^\\s\`'"]*) )*)xanosdk (?=(?:${names.join("|")})\\b|--?[a-z]|<[a-z][a-z-]*>)`,
+    "g"
+  );
+  return pattern;
+}
+function cdTarget(text2, at) {
+  const from = Math.max(text2.lastIndexOf("`", at - 1), text2.lastIndexOf("\n", at - 1)) + 1;
+  const m = [...text2.slice(from, at).matchAll(/(?:^|\s)cd ('(?:[^']|'\\'')*'|"(?:[^"\\]|\\.)*"|[^\s`'"]+) && /g)].at(-1);
+  if (m === void 0) return void 0;
+  const word = m[1];
+  if (word.startsWith("'")) return word.slice(1, -1).replace(/'\\''/g, "'");
+  if (word.startsWith('"')) return word.slice(1, -1).replace(/\\(.)/g, "$1");
+  return word.startsWith("~/") ? join(homedir(), word.slice(2)) : word;
+}
+function withCliPrefix(text2, s = state) {
+  if (s === void 0 || !text2.includes("xanosdk ")) return text2;
+  return text2.replace(commandPattern(), (_whole, boundary, indent, offset) => {
+    const dir = boundary === "`" || boundary === "\n" ? void 0 : cdTarget(text2, offset + boundary.length);
+    return `${boundary}${indent}${cliPrefixAt(dir, s)} `;
+  });
+}
+function withCliPrefixDeep(value, s = state) {
+  if (s === void 0) return value;
+  const walk = (v) => {
+    if (typeof v === "string") return withCliPrefix(v, s);
+    if (Array.isArray(v)) return v.map(walk);
+    if (v !== null && typeof v === "object") {
+      const out = {};
+      for (const [k, inner] of Object.entries(v)) out[k] = walk(inner);
+      return out;
+    }
+    return v;
+  };
+  return walk(value);
+}
+function installCliPrefix(binPath) {
+  const cwd = process.cwd();
+  const launcher = launcherFor({ binPath, cwd, env: process.env });
+  const typed = typedDirFor(cwd, process.env);
+  if (typed !== cwd) setTypedCwdBase(typed);
+  setCliLauncher(launcher, typed);
+  if (launcher === "path") return;
+  const wrap = (stream) => {
+    const write = stream.write;
+    stream.write = function(chunk, ...rest) {
+      const text2 = typeof chunk === "string" ? withCliPrefix(chunk) : chunk;
+      return write.call(stream, text2, ...rest);
+    };
+  };
+  wrap(process.stderr);
+  if (process.stdout.isTTY === true) wrap(process.stdout);
+}
+
+// src/emit/output.ts
+function isMachineOutput(args) {
+  return args.json === true || process.stdout.isTTY !== true;
+}
+function jsonWarning(w) {
+  return { code: w.code, message: w.message, ...w.subject === void 0 ? {} : { subject: w.subject } };
+}
+function isJsonWarnings(value) {
+  return Array.isArray(value) && value.every(
+    (w) => typeof w === "object" && w !== null && typeof w.code === "string" && typeof w.message === "string"
+  );
+}
+function mergeJsonWarnings(own, extra) {
+  if (own !== void 0 && !isJsonWarnings(own)) return void 0;
+  const merged = [...own ?? []];
+  for (const w of extra) {
+    const at = merged.findIndex((m) => m.code === w.code && m.message === w.message);
+    if (at === -1) merged.push(jsonWarning(w));
+    else if (merged[at].subject === void 0 && w.subject !== void 0) merged[at] = jsonWarning(w);
+  }
+  return merged;
+}
+var runScope = new AsyncLocalStorage();
+var unscoped = { written: false };
+var currentState = () => runScope.getStore() ?? unscoped;
+var thrownAfterDocument = /* @__PURE__ */ new WeakSet();
+var liveRun;
+var signalState = () => runScope.getStore() ?? liveRun ?? unscoped;
+var runFinished = false;
+function interruptedRunFinished() {
+  return runFinished && liveRun === void 0;
+}
+function documentText(value, state2) {
+  const document = withCliPrefixDeep(withRunWarnings(withBackendFields(value), state2.warnings ?? [], state2.accepted ?? []));
+  return JSON.stringify(document, (_key, v) => typeof v === "string" ? plainText(v) : v, 2) + "\n";
+}
+function writeJson(value) {
+  const state2 = currentState();
+  state2.written = true;
+  state2.writtenExitCode = documentExitCode(value);
+  process.stdout.write(documentText(value, state2));
+}
+function interruptDocumentText(value) {
+  return documentText(value, signalState());
+}
+function interruptedRunWroteDocument() {
+  return signalState().written;
+}
+function interruptedRunDocumentExitCode() {
+  const state2 = signalState();
+  return state2 !== unscoped && state2.written ? state2.writtenExitCode : void 0;
+}
+function documentExitCode(value) {
+  if (typeof value !== "object" || value === null || value.ok !== false) return 0;
+  const code = value.error?.exitCode;
+  return typeof code === "number" && Number.isInteger(code) ? code : 1;
+}
+function noteRunWarning(code, message, subject) {
+  const state2 = runScope.getStore();
+  if (state2 === void 0) return;
+  state2.warnings = mergeJsonWarnings(state2.warnings, [{ code, message, subject }]);
+}
+function runWarnings() {
+  return runScope.getStore()?.warnings ?? [];
+}
+function noteRunAccepted(accepted) {
+  const state2 = runScope.getStore();
+  if (state2 === void 0 || accepted.length === 0) return;
+  state2.accepted = mergeJsonWarnings(state2.accepted, accepted);
+}
+function runAccepted() {
+  return runScope.getStore()?.accepted ?? [];
+}
+function setRunFailureExplainer(explain) {
+  const state2 = runScope.getStore();
+  if (state2 !== void 0) state2.explain = explain;
+}
+async function explainRunFailure(err) {
+  const explain = runScope.getStore()?.explain;
+  return explain === void 0 ? err : explain(err);
+}
+function withRunWarnings(value, warnings, accepted) {
+  if (typeof value !== "object" || value === null || Array.isArray(value)) return value;
+  let out = value;
+  for (const [key, extra] of [["warnings", warnings], ["accepted", accepted]]) {
+    if (extra.length === 0) continue;
+    const merged = mergeJsonWarnings(value[key], extra);
+    if (merged !== void 0) out = { ...out, [key]: merged };
+  }
+  return out;
+}
+async function inJsonDocumentScope(fn) {
+  const state2 = { written: false };
+  const outer = liveRun;
+  liveRun = state2;
+  runFinished = false;
+  try {
+    return await runScope.run(state2, fn);
+  } catch (err) {
+    if (state2.written && typeof err === "object" && err !== null) thrownAfterDocument.add(err);
+    throw err;
+  } finally {
+    liveRun = outer;
+    if (outer === void 0) runFinished = true;
+  }
+}
+function jsonDocumentWritten(failure) {
+  if (typeof failure === "object" && failure !== null && thrownAfterDocument.has(failure)) return true;
+  return currentState().written;
+}
+function installStdoutPipeGuard(stream = process.stdout) {
+  stream.on("error", (err) => {
+    if (err.code === "EPIPE" || err.code === "ERR_STREAM_DESTROYED") return;
+    throw err;
+  });
+}
+
+// src/emit/ui.ts
+function resolveColor(isTTY) {
+  return process.env.FORCE_COLOR ? process.env.FORCE_COLOR !== "0" : !process.env.NO_COLOR && isTTY === true && !dumbTerminal();
+}
+function dumbTerminal() {
+  return process.env.TERM === "dumb";
+}
+var MARK_OPEN = "\uE000";
+var MARK_CLOSE = "\uE001";
+var NONCE = Array.from(randomBytes(8), (b) => String.fromCharCode(57600 + b)).join("");
+var mark = (code) => `${MARK_OPEN}${NONCE}${code}${MARK_CLOSE}`;
+var TOKEN = `${MARK_OPEN}${NONCE}([0-9;]+)${MARK_CLOSE}`;
+function makePalette(on) {
+  const paint = (code, s) => on ? `${mark(code)}${s}${mark("0")}` : s;
+  return {
+    bold: (s) => paint("1", s),
+    dim: (s) => paint("2", s),
+    green: (s) => paint("32", s),
+    red: (s) => paint("31", s),
+    yellow: (s) => paint("33", s),
+    cyan: (s) => paint("36", s)
+  };
+}
+var style = makePalette(resolveColor(process.stderr.isTTY));
+function stderrStyle() {
+  return makePalette(resolveColor(process.stderr.isTTY));
+}
+function stdoutStyle() {
+  return makePalette(resolveColor(process.stdout.isTTY));
+}
+var SAFE_TEXT = new RegExp(`(${TOKEN})|[\\x00-\\x1f\\x7f-\\x9f\\u202a-\\u202e\\u2066-\\u2069\\ue000\\ue001]`, "g");
+var TERMINAL_TEXT = new RegExp(`${TOKEN}|[\\x00-\\x08\\x0b-\\x1f\\x7f-\\x9f\\u202a-\\u202e\\u2066-\\u2069\\ue000\\ue001]`, "g");
+var TOKENS = new RegExp(TOKEN, "g");
+var NAMED_ESCAPES = { "\n": "\\n", "\r": "\\r", "	": "\\t" };
+function visibleEscape(c) {
+  const named = NAMED_ESCAPES[c];
+  if (named !== void 0) return named;
+  const code = c.charCodeAt(0);
+  return code < 256 ? `\\x${code.toString(16).padStart(2, "0")}` : `\\u${code.toString(16).padStart(4, "0")}`;
+}
+function safeText(value) {
+  return value.replace(SAFE_TEXT, (match, token) => token ?? visibleEscape(match));
+}
+function quotedNames(names) {
+  return names.map((n) => `"${safeText(n)}"`).join(", ");
+}
+function withoutUrls(message) {
+  return message.replace(/\bhttps?:\/\/\S+?(?=[.,:;!?)\]'"]*(?:\s|$))/gi, "<url>");
+}
+function plainText(text2) {
+  return text2.replace(TOKENS, "");
+}
+function terminalText(text2) {
+  return text2.replace(
+    TERMINAL_TEXT,
+    (match, code) => code !== void 0 ? `\x1B[${code}m` : visibleEscape(match)
+  );
+}
+function printHuman(text2) {
+  process.stdout.write(terminalText(text2));
+}
+function formatTableListing(rows, indent = "") {
+  if (rows.length === 0) return "";
+  const idWidth = Math.max(...rows.map((r) => String(r.id).length));
+  const guidWidth = Math.max(...rows.map((r) => r.guid.length));
+  return rows.map(
+    (r) => `${indent}${String(r.id).padStart(idWidth)}  ${r.guid.padEnd(guidWidth)}  ${safeText(JSON.stringify(r.name))}`
+  ).join("\n");
+}
+function formatFields(rows) {
+  const s = stdoutStyle();
+  const width = Math.max(0, ...rows.map(([label]) => label.length));
+  return rows.map(([label, value]) => `  ${s.dim(safeText(label).padEnd(width))}  ${safeText(value)}`).join("\n") + "\n";
+}
+function step(msg) {
+  process.stderr.write(terminalText(`${style.cyan("\u2192")} ${msg}
+`));
+}
+function success(msg) {
+  process.stderr.write(terminalText(`${style.green("\u2713")} ${msg}
+`));
+}
+function error(msg) {
+  process.stderr.write(terminalText(`${stderrStyle().red("\u2717")} ${msg}
+`));
+}
+function continued(msg, pad) {
+  const [head, ...rest] = msg.split("\n");
+  if (rest.length === 0) return msg;
+  const text2 = rest.filter((line) => line.trim() !== "");
+  if (text2.length > 0 && text2.every((line) => /^\s/.test(line))) return msg;
+  return [head, ...rest.map((line) => line.trim() === "" ? "" : `${pad}${line}`)].join("\n");
+}
+function warn(msg, code, remedies = [], machine) {
+  process.stderr.write(terminalText(`${style.yellow("!")} ${continued(msg, "  ")}
+`));
+  for (const line of remedies) detail(line);
+  noteRunWarning(code, machine ?? [msg, ...remedies].join("\n"));
+}
+function info(msg) {
+  process.stderr.write(terminalText(`${style.cyan("i")} ${msg}
+`));
+}
+function detail(msg) {
+  process.stderr.write(terminalText(`  ${style.dim(continued(msg, "  "))}
+`));
+}
+function link(url) {
+  process.stderr.write(terminalText(`  ${style.bold(style.cyan(url))}
+`));
+}
+function blank() {
+  process.stderr.write("\n");
+}
+function formatDuration(ms) {
+  const safe = Math.max(0, ms);
+  if (safe < 1e3) return `${Math.round(safe)}ms`;
+  if (safe < 6e4) return `${(safe / 1e3).toFixed(1)}s`;
+  const minutes = Math.floor(safe / 6e4);
+  const seconds = Math.round(safe % 6e4 / 1e3);
+  return `${minutes}m ${String(seconds).padStart(2, "0")}s`;
+}
+function elapsedSuffix(startedAt, now = Date.now()) {
+  return ` ${style.dim(`(${formatDuration(now - startedAt)})`)}`;
+}
+var SPINNER_FRAMES = ["\u280B", "\u2819", "\u2839", "\u2838", "\u283C", "\u2834", "\u2826", "\u2827", "\u2807", "\u280F"];
+var SPINNER_FRAME_MS = 80;
+function spinner(msg) {
+  let text2 = msg;
+  if (process.stderr.isTTY !== true || dumbTerminal()) {
+    detail(msg);
+    return { update: () => {
+    }, stop: () => {
+    } };
+  }
+  const start = Date.now();
+  let frame = 0;
+  let live = true;
+  const clear = () => process.stderr.write("\r\x1B[2K");
+  const render = () => {
+    const secs = Math.round((Date.now() - start) / 1e3);
+    const suffix = secs >= 1 ? ` ${style.dim(`(${secs}s)`)}` : "";
+    clear();
+    process.stderr.write(terminalText(`${style.cyan(SPINNER_FRAMES[frame % SPINNER_FRAMES.length])} ${style.dim(text2)}${suffix}`));
+    frame += 1;
+  };
+  render();
+  const timer = setInterval(render, SPINNER_FRAME_MS);
+  timer.unref();
+  const self = {
+    update(next) {
+      text2 = next;
+    },
+    stop() {
+      if (!live) return;
+      live = false;
+      liveSpinners.delete(self);
+      clearInterval(timer);
+      clear();
+    }
+  };
+  liveSpinners.add(self);
+  return self;
+}
+var liveSpinners = /* @__PURE__ */ new Set();
+function clearProgress() {
+  for (const spin of [...liveSpinners]) spin.stop();
+}
+async function withSpinner(msg, work) {
+  const spin = spinner(msg);
+  try {
+    return await work();
+  } finally {
+    spin.stop();
+  }
+}
+function formatExpiration(expiresAt) {
+  if (expiresAt === void 0 || expiresAt === null || expiresAt === "") return "\u2014";
+  const ms = typeof expiresAt === "number" ? expiresAt * 1e3 : Date.parse(String(expiresAt).replace(" ", "T"));
+  if (Number.isNaN(ms)) return String(expiresAt);
+  const diff = (ms - Date.now()) / 1e3;
+  if (diff <= 0) return "expired";
+  const hours = Math.floor(diff / 3600);
+  const minutes = Math.floor(diff % 3600 / 60);
+  return `in ${hours}h ${minutes}m`;
+}
+function isLocalEngine(target) {
+  return "kind" in target && target.kind === "local-engine";
+}
+function describeWriteTarget(target) {
+  if (isLocalEngine(target)) {
+    return `local engine \xB7 ${hostLabel(target.url)} \xB7 workspace ${target.workspaceId}`;
+  }
+  const where = `${hostLabel(target.base)} \xB7 workspace ${target.workspaceId}`;
+  return target.label === void 0 || target.label === "" ? where : `${target.label} \u2014 ${where}`;
+}
+function discloseWriteTarget(target) {
+  detail(`on ${describeWriteTarget(target)}`);
+}
+function credentialWriteTarget(binding) {
+  return { base: binding.instance, workspaceId: binding.workspaceId, kind: "workspace" };
+}
+function writeTargetPayload(target) {
+  if (isLocalEngine(target)) {
+    return { instance: target.url, workspaceId: target.workspaceId, kind: "local-engine", local: true };
+  }
+  return {
+    instance: target.base,
+    workspaceId: target.workspaceId,
+    ...target.label === void 0 || target.label === "" ? {} : { label: target.label },
+    ...target.kind === void 0 ? {} : { kind: target.kind }
+  };
+}
+function backendDestinationPayload(parent, backend) {
+  return {
+    ...writeTargetPayload({
+      base: parent.instance.replace(/\/$/, ""),
+      workspaceId: parent.workspaceId,
+      label: backend.name,
+      kind: backend.kind
+    }),
+    url: backend.url,
+    ...backend.display === void 0 || backend.display === "" ? {} : { display: backend.display }
+  };
+}
+function hostLabel(origin) {
+  try {
+    return new URL(origin).host;
+  } catch {
+    return origin.replace(/^https?:\/\//, "").replace(/\/+$/, "");
+  }
+}
+
+// src/emit/operation-registry.ts
+var EXIT_OUTCOME_UNKNOWN = 9;
+var active;
+function registerOperation(input) {
+  if (active !== void 0) {
+    throw new Error("An operation is already registered for this run; clear it before registering another.");
+  }
+  let writeSent = false;
+  const registration = {
+    ...input,
+    get writeSent() {
+      return writeSent;
+    },
+    markWriteSent() {
+      writeSent = true;
+    },
+    clear() {
+      if (active === registration) active = void 0;
+    }
+  };
+  active = registration;
+  return registration;
+}
+function activeOperation() {
+  return active;
+}
+
+// src/emit/help.ts
+function table(rows, s, indent = "  ", fixedWidth) {
+  const width = fixedWidth ?? Math.max(0, ...rows.map(([name]) => name.length));
+  return rows.map(([name, desc]) => `${indent}${s.cyan(name.padEnd(width))}  ${s.dim(desc)}`);
+}
+function renderFlagSpec(ref) {
+  const spec = flagSpec(ref);
+  const values = flagValues(ref);
+  if (values === void 0 || typeof ref === "string" || ref.values === void 0) return spec;
+  return spec.replace(/<[^>]*>/, `<${values.join("|")}>`);
+}
+function flagSection(flags, s) {
+  if (!flags || flags.length === 0) return [];
+  const rows = flags.filter((ref) => Object.hasOwn(FLAGS, flagKey(ref))).map((ref) => [renderFlagSpec(ref), flagSummary(ref)]);
+  if (rows.length === 0) return [];
+  return ["", s.bold("Flags"), ...table(rows, s)];
+}
+function argSection(args, s) {
+  const rows = (args ?? []).flatMap((a) => {
+    if (a.selector !== void 0) {
+      return [[`<${a.name}>`, `${sourceSpellings(a.selector.accepted)}${OMITTED[a.selector.default]}`]];
+    }
+    return a.values !== void 0 && a.values.length > 0 ? [[`<${a.name}>`, a.values.join(", ")]] : [];
+  });
+  return rows.length === 0 ? [] : ["", s.bold("Arguments"), ...table(rows, s)];
+}
+var OMITTED = {
+  tracked: " (omitted: the backend this project last deployed to)",
+  entry: " (omitted: this project's entry file, compiled)",
+  none: ""
+};
+function exampleSection(example, s) {
+  return example ? ["", s.bold("Example"), `  ${s.dim(example)}`] : [];
+}
+function globalFlagRows() {
+  return GLOBAL_FLAGS.map((key) => [FLAGS[key].spec, FLAGS[key].summary]);
+}
+function globalFlagsLine(s, command, sub) {
+  const specs = GLOBAL_FLAGS.filter(
+    (key) => key !== "help" && key !== "version" && // A command that reaches no instance REFUSES `--profile` (see parseArgs).
+    (key !== "profile" || takesProfileFlag(command, sub)) && // `--no-refresh` turns off the AGENTS.md refresh a WORKSPACE compile does,
+    // so only a page for a command that runs one lists it — the commands that
+    // take the compile's env flags. `compile` and `routes` never refresh.
+    (key !== "no-refresh" || flagRefFor(command, sub, "backend-env-file") !== void 0) && // `completion` prints a script to source and refuses `--json`, so its
+    // page must not offer it.
+    (key !== "json" || command !== "completion")
+  ).map((key) => FLAGS[key].spec);
+  if (specs.length === 0) return [];
+  return ["", s.dim(`Also takes the global flags ${specs.join(" \xB7 ")} \u2014 see \`xanosdk --help\`.`)];
+}
+function renderGlobalHelp(s = stdoutStyle(), version = "") {
+  const byGroup = /* @__PURE__ */ new Map();
+  const push = (group, row) => {
+    const rows = byGroup.get(group) ?? [];
+    rows.push(row);
+    byGroup.set(group, rows);
+  };
+  for (const [name, spec] of Object.entries(COMMANDS)) {
+    if (spec.aliasOf === void 0) push(spec.group, [spec.display, spec.summary]);
+    for (const sub of Object.values(spec.subcommands ?? {})) {
+      if (sub.group === void 0) continue;
+      push(sub.group, [sub.display ?? `${name} ${sub.summary}`, sub.groupSummary ?? sub.summary]);
+    }
+  }
+  const width = Math.max(0, ...[...byGroup.values()].flat().map(([n]) => n.length));
+  const lines = [
+    `${s.bold("xanosdk")}${version ? ` ${s.dim(`v${version}`)}` : ""} \u2014 the AI-first SDK & CLI for Xano backends`,
+    "",
+    `${s.dim("Usage:")} xanosdk ${s.cyan("<command>")} ${s.dim("[options]")}`
+  ];
+  for (const group of HELP_GROUP_ORDER) {
+    const rows = byGroup.get(group);
+    if (!rows || rows.length === 0) continue;
+    lines.push("", s.bold(group), ...table(rows, s, "  ", width));
+  }
+  lines.push("", s.bold("Global flags"), ...table(globalFlagRows(), s, "  ", width));
+  lines.push(
+    "",
+    s.dim("Run `xanosdk <command> --help` for a command's arguments and flags."),
+    s.dim("Docs: https://www.npmjs.com/package/@xano/sdk")
+  );
+  return lines.join("\n") + "\n";
+}
+function renderCommandHelp(command, s = stdoutStyle()) {
+  const spec = getCommand(command);
+  if (!spec) return renderGlobalHelp(s);
+  const subs = liveSubcommandNames(command);
+  const usage = subs.length > 0 ? `xanosdk ${command} <subcommand> ${s.dim("[options]")}` : `xanosdk ${command}${renderArgs(spec.args) ? ` ${renderArgs(spec.args)}` : ""} ${s.dim("[options]")}`;
+  const lines = [`${s.bold(`xanosdk ${command}`)} \u2014 ${spec.summary}`, "", `${s.dim("Usage:")} ${usage}`];
+  if (subs.length > 0) {
+    const rows = subs.map((name) => {
+      const sub = getSubcommand(command, name);
+      const args = renderArgs(sub.args);
+      return [args ? `${name} ${args}` : name, sub.summary];
+    });
+    lines.push("", s.bold("Subcommands"), ...table(rows, s));
+  }
+  lines.push(...argSection(spec.args, s));
+  lines.push(...flagSection(visibleFlags(spec), s));
+  if (spec.notes !== void 0) lines.push("", s.bold("Notes"), `  ${spec.notes}`);
+  lines.push(...exampleSection(spec.example, s));
+  lines.push(...globalFlagsLine(s, command));
+  if (subs.length > 0) {
+    lines.push("", s.dim(`Run \`xanosdk ${command} <subcommand> --help\` for a subcommand's flags.`));
+  }
+  return lines.join("\n") + "\n";
+}
+function renderSubcommandHelp(command, sub, s = stdoutStyle()) {
+  const spec = getSubcommand(command, sub);
+  if (!spec) return renderCommandHelp(command, s);
+  const args = renderArgs(spec.args);
+  const lines = [
+    `${s.bold(`xanosdk ${command} ${sub}`)} \u2014 ${spec.summary}`,
+    "",
+    `${s.dim("Usage:")} xanosdk ${command} ${sub}${args ? ` ${args}` : ""} ${s.dim("[options]")}`
+  ];
+  lines.push(...argSection(spec.args, s));
+  lines.push(...flagSection(visibleFlags(spec), s));
+  lines.push(...exampleSection(spec.example, s));
+  lines.push(...globalFlagsLine(s, command, sub));
+  return lines.join("\n") + "\n";
+}
+function renderHelpFor(target, s, version = "") {
+  if (target?.command === void 0) return renderGlobalHelp(s, version);
+  if (target.subcommand !== void 0) return renderSubcommandHelp(target.command, target.subcommand, s);
+  return renderCommandHelp(target.command, s);
+}
+function indentBlock(text2, indent = "  ") {
+  return text2.split("\n").map((line) => line === "" ? line : indent + line).join("\n");
+}
+
+// src/emit/errors.ts
+function statesOutcomeUnknown(message) {
+  return /\bmay or may not have (taken effect|landed|published|been \w+)/.test(message);
+}
+var UsageError = class extends Error {
+  name = "UsageError";
+  /** The help block to print under the message. */
+  helpFor;
+  /**
+   * A one-line pointer to this help page, in place of the block. For a conflict
+   * between flags that each parsed fine: the message already names which to
+   * drop, and a full usage block under it buries that sentence. {@link helpFor}
+   * is for a mistake in the command's SHAPE, where the block lists what works.
+   */
+  hintFor;
+  /** A closest-match hint (`Did you mean: details`), when one is close enough. */
+  suggestion;
+  constructor(message, opts = {}) {
+    super(message);
+    this.helpFor = opts.helpFor;
+    this.hintFor = opts.hintFor;
+    this.suggestion = opts.suggestion;
+  }
+};
+var LocalFileNotFoundError = class extends UsageError {
+  exitCode = 1;
+};
+var CliError = class extends Error {
+  constructor(code, message, opts = {}) {
+    super(message, opts.cause === void 0 ? void 0 : { cause: opts.cause });
+    this.code = code;
+    this.details = opts.details;
+    this.exitCode = opts.exitCode;
+  }
+  code;
+  name = "CliError";
+  details;
+  exitCode;
+};
+function isUsageError(err) {
+  return err instanceof UsageError || err instanceof Error && err.name === "UsageError";
+}
+function unknownCommand(name, opts = {}) {
+  if (name.startsWith("-") && name !== "-") {
+    const flag = flagName(name);
+    const hint = suggestFlag(flag, void 0);
+    return new UsageError(
+      `Unknown flag ${flag} before the command. Global flags go after it: \`xanosdk <command> ${hint ?? "<flag>"}${hint === "-p" || hint === "--profile" ? " <profile>" : ""}\`.`,
+      { helpFor: {}, suggestion: hint }
+    );
+  }
+  const owned = verbOwnerHint(name, opts.help === true);
+  if (owned !== void 0) {
+    return new UsageError(`Unknown command "${name}". ${owned.hint}`, {
+      helpFor: { command: owned.command }
+    });
+  }
+  return new UsageError(`Unknown command "${name}".`, {
+    helpFor: {},
+    suggestion: suggestVerb(name, liveCommandNames())
+  });
+}
+function verbOwnerHint(name, help) {
+  const owners = liveCommandNames().filter(
+    (c) => liveSubcommandNames(c).includes(name)
+  );
+  if (owners.length === 0) return void 0;
+  const paths = owners.map((c) => `\`xanosdk ${help ? "help " : ""}${c} ${name}\``).join(" or ");
+  const nouns = owners.map((c) => `\`${c}\``).join(" and ");
+  return {
+    command: owners[0],
+    hint: `\`${name}\` is a subcommand of ${nouns}: ${paths}.`
+  };
+}
+function unknownHelpTopic(name) {
+  const owned = verbOwnerHint(name, true);
+  if (owned !== void 0) {
+    return new UsageError(
+      `\`xanosdk help\`: no help topic "${name}". ${owned.hint}`,
+      {
+        helpFor: { command: owned.command }
+      }
+    );
+  }
+  return new UsageError(`\`xanosdk help\`: no help topic "${name}".`, {
+    helpFor: {},
+    suggestion: suggest(name, liveCommandNames())
+  });
+}
+function unknownSubcommand(command, sub, positionals = []) {
+  const moved = movedVerb(command, sub, positionals);
+  if (moved !== void 0) return moved;
+  const missing = sub === void 0 || sub === "" || sub.startsWith("-");
+  const what = missing ? "no subcommand given" : `unknown subcommand "${sub}"`;
+  const verbs = liveSubcommandNames(command);
+  return new UsageError(`\`xanosdk ${command}\`: ${what}.`, {
+    helpFor: { command },
+    suggestion: !missing ? suggestVerb(sub, verbs) : void 0
+  });
+}
+function suggestVerb(typed, verbs) {
+  const synonym = VERB_SYNONYMS[typed]?.find((v) => verbs.includes(v));
+  if (synonym !== void 0) return synonym;
+  const spelled = suggest(typed, verbs);
+  if (spelled === void 0 || negates(typed, spelled)) return void 0;
+  const meant = Object.hasOwn(VERB_INTENT, typed) ? typed : suggest(typed, Object.keys(VERB_INTENT));
+  const want = meant === void 0 ? void 0 : VERB_INTENT[meant];
+  const got = Object.hasOwn(VERB_INTENT, spelled) ? VERB_INTENT[spelled] : void 0;
+  return want !== void 0 && got !== void 0 && want !== got ? void 0 : spelled;
+}
+function negates(a, b) {
+  const stem = (w, p) => w.startsWith(p) ? w.slice(p.length).replace(/^-/, "") : void 0;
+  return ["un", "de"].some((p) => stem(a, p) === b || stem(b, p) === a);
+}
+var VERB_INTENT = {
+  list: "read",
+  ls: "read",
+  show: "read",
+  get: "read",
+  details: "read",
+  view: "read",
+  info: "read",
+  describe: "read",
+  search: "read",
+  cat: "read",
+  pull: "fetch",
+  fetch: "fetch",
+  download: "fetch",
+  export: "fetch",
+  push: "send",
+  upload: "send",
+  put: "send",
+  set: "send",
+  unset: "send",
+  delete: "send",
+  remove: "send",
+  rm: "send",
+  install: "send",
+  reinstall: "send",
+  create: "send",
+  add: "send",
+  prune: "send",
+  rename: "send",
+  deploy: "send",
+  "set-live": "send",
+  "set-default": "send",
+  use: "send"
+};
+var VERB_SYNONYMS = {
+  remove: ["delete", "unset", "prune"],
+  rm: ["delete", "remove", "unset", "prune"],
+  del: ["delete", "remove", "unset"],
+  delete: ["remove", "unset"],
+  destroy: ["delete", "remove"],
+  uninstall: ["remove", "delete"],
+  un: ["remove", "delete"],
+  unset: ["delete", "remove"],
+  mv: ["rename"],
+  move: ["rename"],
+  switch: ["use", "set-live"],
+  promote: ["set-live"],
+  activate: ["set-live", "use"],
+  default: ["set-default"],
+  select: ["use"],
+  ls: ["list"],
+  new: ["create", "add"],
+  add: ["create", "install"],
+  create: ["add"],
+  info: ["show", "get", "details"],
+  view: ["show", "get", "details"],
+  describe: ["show", "get", "details"],
+  get: ["show", "details"],
+  show: ["get", "details"]
+};
+function unknownFlag(flags, target, alsoKnown = []) {
+  const names = [...new Set(flags.map(flagName))];
+  const known = (name) => suggestFlag(name, target, alsoKnown) === name || scopedFlagNames(target).some((n) => shortSpellings(n).includes(name));
+  const valued = names.filter((n) => known(n) && flags.some((f) => f !== n && flagName(f) === n));
+  const unknown = names.filter((n) => !valued.includes(n));
+  const noValue = valued.length === 0 ? "" : `${valued.map((n) => `\`${n}\``).join(", ")} ${valued.length === 1 ? "takes" : "take"} no value \u2014 drop the \`=\` and what follows it.`;
+  const [first, ...rest] = unknown;
+  if (first === void 0) return new UsageError(noValue, { helpFor: target });
+  const tokenNote = target?.command === "profile" && target.subcommand === "add" && unknown.includes("--token") ? ` The token is read from stdin: \`printf %s "$TOKEN" | xanosdk profile add <name>\`.` : "";
+  return new UsageError(
+    `Unknown flag ${first}${rest.length ? ` (also ${rest.join(", ")})` : ""}.${noValue === "" ? "" : ` ${noValue}`}${tokenNote}`,
+    {
+      helpFor: target,
+      suggestion: suggestFlag(first, target, alsoKnown)
+    }
+  );
+}
+function shortSpellings(key) {
+  const spec = FLAGS[key]?.spec ?? "";
+  return spec.split(/[\s,=[]+/).filter((t) => /^-[A-Za-z]$/.test(t));
+}
+function flagName(token) {
+  const eq = token.indexOf("=");
+  return eq < 0 ? token : token.slice(0, eq);
+}
+function suggestFlag(flag, target, alsoKnown = []) {
+  const names = [...scopedFlagNames(target), ...alsoKnown];
+  const short = /^-([A-Za-z])$/.exec(flagName(flag))?.[1];
+  if (short !== void 0) {
+    const shorts = names.flatMap((n) => shortSpellings(n));
+    const other = short === short.toLowerCase() ? short.toUpperCase() : short.toLowerCase();
+    if (shorts.includes(`-${other}`)) return `-${other}`;
+  }
+  const typed = flagName(flag).replace(/^-+/, "");
+  const match = suggest(typed, names);
+  return match === void 0 ? void 0 : `--${match}`;
+}
+function scopedFlagNames(target) {
+  const command = target?.command;
+  const spec = command === void 0 ? void 0 : getCommand(command);
+  const own = spec === void 0 ? [] : target?.subcommand !== void 0 ? [getSubcommand(command, target.subcommand)] : spec.subcommands !== void 0 ? Object.values(spec.subcommands) : [spec];
+  const declared = own.flatMap((s) => s === void 0 ? [] : (visibleFlags(s) ?? []).map(flagKey));
+  const globals = GLOBAL_FLAGS.filter(
+    (f) => f !== "profile" || command === void 0 || takesProfileFlag(command, target?.subcommand)
+  );
+  return [.../* @__PURE__ */ new Set([...globals, ...declared])];
+}
+function extraArguments(extras, target, max, attachedValueFlag) {
+  const where = target.subcommand ? `${target.command} ${target.subcommand}` : target.command;
+  const named = extras.map((e) => `"${e.includes("=") ? `${flagName(e)}=\u2026` : e}"`).join(", ");
+  const noun = extras.length === 1 ? "argument" : "arguments";
+  const selector = max === 0 && extras.length === 1 ? positionalSelectorHint(extras[0], target) : void 0;
+  const why = selector !== void 0 ? `\`xanosdk ${where}\` takes no positional arguments; it names its backend with \`${selector.flag}\`: \`${selector.flag} ${extras[0]}\`.` : attachedValueFlag !== void 0 ? (
+    // `--lock` is the only flag with an attached-only value form, and its
+    // value is a path — spelled out here rather than reconstructed from the
+    // flag registry, whose `spec` strings are written for help, not reuse.
+    `\`${attachedValueFlag}\` takes its value attached: \`${attachedValueFlag}=<path>\`.`
+  ) : specFor(target)?.extraArgHint ?? (max === 0 ? `\`xanosdk ${where}\` takes no positional arguments.` : `\`xanosdk ${where}\` takes at most ${max}: ${renderArgs(specFor(target)?.args)}.`);
+  return new UsageError(
+    `\`xanosdk ${where}\`: unexpected ${noun} ${named} \u2014 ${why}`,
+    {
+      helpFor: target,
+      ...selector === void 0 ? {} : { suggestion: selector.flag }
+    }
+  );
+}
+var BACKEND_HANDLE = /^(?:workspace|ephemeral|local-engine|tenant)(?::[^\s=]+)?$/;
+function positionalSelectorHint(extra, target) {
+  if (!BACKEND_HANDLE.test(extra)) return void 0;
+  const own = selectorSpellings(target.command, target.subcommand);
+  return own.length === 1 && /^`--/.test(own[0]) ? { flag: own[0].slice(1, -1) } : void 0;
+}
+function envSetArgumentsRefused(problem, flags = []) {
+  const target = { command: "env", subcommand: "set" };
+  const suggestion = flags.filter((f) => f.startsWith("--")).map((f) => suggestFlag(f, target)).find((m) => m !== void 0);
+  const what = problem === "flag" ? "an argument starting with `-` is not a flag it knows" : "it takes at most NAME and VALUE, and got more";
+  return new UsageError(
+    `\`xanosdk env set\`: ${what}. It is not repeated here in case it is the value. A value that starts with \`-\` or holds spaces is safest piped on stdin: \`printf %s "$VALUE" | xanosdk env set NAME\`.`,
+    { helpFor: target, suggestion }
+  );
+}
+function specFor(target) {
+  return target.subcommand !== void 0 ? getSubcommand(target.command, target.subcommand) : getCommand(target.command);
+}
+function missingArgument(arg, target) {
+  const where = target.subcommand ? `${target.command} ${target.subcommand}` : target.command;
+  return new UsageError(`\`xanosdk ${where}\`: missing required <${arg}>.`, {
+    helpFor: target
+  });
+}
+function reportFailure(err, version = "", argv = []) {
+  const s = stderrStyle();
+  const message = (err instanceof Error ? err.message : String(err)).replace(
+    /^xanosdk: /,
+    ""
+  );
+  if (failureWritesDocument(argv, err) && !jsonDocumentWritten(err))
+    writeJson(failureDocument(err, message));
+  error(indentContinuation(message));
+  if (!isUsageError(err)) return;
+  const many = err.suggestions;
+  const near = (Array.isArray(many) && many.length > 1 && many.every((n) => typeof n === "string") ? many : err.suggestion === void 0 ? [] : [err.suggestion]).filter((n) => !namesSuggestion(message, n));
+  if (near.length > 0) {
+    process.stderr.write("\n");
+    detail(`Did you mean: ${near.map((n) => s.cyan(n)).join(" or ")}`);
+  }
+  if (err.hintFor?.command !== void 0) {
+    const path = [err.hintFor.command, err.hintFor.subcommand].filter((p) => p !== void 0).join(" ");
+    process.stderr.write("\n");
+    detail(`Run \`xanosdk ${path} --help\` for its usage and flags.`);
+  }
+  if (err.helpFor === void 0) return;
+  process.stderr.write(terminalText("\n" + indentBlock(renderHelpFor(err.helpFor, s, version))));
+}
+function failureWritesDocument(argv, err) {
+  const json = argv.includes("--json");
+  return json || isMachineOutput({ json }) && !stdoutCarriesData(argv, err);
+}
+function namesSuggestion(message, suggestion) {
+  return message.includes(`"${suggestion}"`) || message.includes(`\`${suggestion}\``);
+}
+var DATA_STDOUT_COMMANDS = /* @__PURE__ */ new Set([
+  "export",
+  "llms",
+  "completion",
+  "version",
+  "help"
+]);
+var VALUE_FLAGS = /* @__PURE__ */ new Set(["--profile", "-p", "--config", "--origin"]);
+function stdoutCarriesData(argv, err) {
+  if ((argv.includes("--help") || argv.includes("-h")) && !isUsageError(err)) return true;
+  if (argv.includes("--path=-") || argv.some((a, i) => a === "--path" && argv[i + 1] === "-"))
+    return true;
+  const command = argv.find(
+    (a, i) => !a.startsWith("-") && !VALUE_FLAGS.has(argv[i - 1] ?? "")
+  );
+  if (command === "export")
+    return !writesToFile(argv) && !argv.includes("--check");
+  return command === void 0 || DATA_STDOUT_COMMANDS.has(command);
+}
+function writesToFile(argv) {
+  for (let i = 0; i < argv.length; i++) {
+    const a = argv[i];
+    const value = a === "--out" || a === "-o" ? argv[i + 1] : a.startsWith("--out=") ? a.slice("--out=".length) : void 0;
+    if (value !== void 0 && value !== "" && value !== "-") return true;
+  }
+  return false;
+}
+function indentContinuation(message) {
+  const [head, ...rest] = message.split("\n");
+  if (rest.length === 0) return message;
+  const text2 = rest.filter((line) => line.trim() !== "");
+  if (text2.length > 0 && text2.every((line) => /^\s/.test(line))) return message;
+  return [
+    head,
+    ...rest.map((line) => line.trim() === "" ? "" : `  ${line}`)
+  ].join("\n");
+}
+function failureDocument(err, message) {
+  return { ok: false, error: failureError(err, message, processExitCode(err)) };
+}
+function failureError(err, message, exitCode) {
+  const details = ownCode(err)?.details;
+  const own = err?.suggestion;
+  const suggestion = isUsageError(err) ? err.suggestion : typeof own === "string" ? own : void 0;
+  const many = err?.suggestions;
+  const suggestions = Array.isArray(many) && many.length > 1 && many.every((s) => typeof s === "string") ? many : void 0;
+  return {
+    code: failureCode(err),
+    message,
+    exitCode,
+    ...details === void 0 ? {} : { details },
+    ...suggestion === void 0 ? {} : { suggestion },
+    ...suggestion === void 0 || suggestions === void 0 ? {} : { suggestions }
+  };
+}
+function failureCode(err) {
+  return ownCode(err)?.code ?? (isUsageError(err) ? "SDK_USAGE" : "SDK_ERROR");
+}
+function ownCode(err) {
+  const { code, details } = err ?? {};
+  return typeof code === "string" && code.startsWith("SDK_") ? { code, details } : void 0;
+}
+function exitCodeOf(err) {
+  const code = err?.exitCode;
+  return typeof code === "number" && Number.isInteger(code) && code > 0 && code < 256 ? code : 1;
+}
+function processExitCode(err) {
+  const own = exitCodeOf(err);
+  if (own !== 1 || err?.exitCode === 1)
+    return own;
+  return err instanceof Error && statesOutcomeUnknown(err.message) ? EXIT_OUTCOME_UNKNOWN : 1;
+}
+var MOVED_TO_TOP_LEVEL = /* @__PURE__ */ new Map([
+  ["tables", /* @__PURE__ */ new Set(["workspace", "ephemeral", "tenant", "local-engine"])],
+  ["impersonate", /* @__PURE__ */ new Set(["ephemeral", "tenant", "local-engine"])]
+]);
+function movedVerb(command, sub, positionals) {
+  if (command === void 0 || sub === void 0 || MOVED_TO_TOP_LEVEL.get(sub)?.has(command) !== true) {
+    return void 0;
+  }
+  const name = positionals[0];
+  const backend = command === "workspace" ? "workspace" : name !== void 0 && name !== "" ? `${command}:${name}` : command === "tenant" ? "tenant:<name>" : command;
+  const replacement = sub === "tables" ? tablesCommand(backend) : `xanosdk ${sub} ${backend}`;
+  return new UsageError(
+    `\`xanosdk ${command} ${sub}\` is now \`${replacement}\`: \`${sub}\` is one top-level verb that takes the backend as its argument, and bare it follows what this project last deployed to.`,
+    { helpFor: { command: sub } }
+  );
+}
+function installCliDiagnosticSink() {
+  setDiagnosticSink((diagnostic) => {
+    warn(diagnostic.message, diagnostic.code);
+    if (diagnostic.subject !== void 0) noteRunWarning(diagnostic.code, diagnostic.message, diagnostic.subject);
+  });
+}
+
+// src/emit/name-check.ts
+var CONTROL = /[\u0000-\u001f\u007f-\u009f\u2028\u2029]/u;
+var CONTROL_NAMES = {
+  "	": "a tab",
+  "\r": "a carriage return",
+  "\n": "a line break",
+  "\u2028": "a line break",
+  "\u2029": "a line break"
+};
+var runContext = {};
+function setRunNameContext(ctx) {
+  runContext = ctx ?? {};
+}
+function runNameContext() {
+  return runContext;
+}
+function checkOneName(value, what, opts = {}) {
+  const trimmed = value.trim();
+  const bad = CONTROL.exec(trimmed);
+  if (bad === null) return;
+  const hint = opts.helpFor === void 0 ? {} : { hintFor: opts.helpFor };
+  if (opts.echo === false) {
+    throw new UsageError(
+      `${capital(what)} holds ${describe(bad[0])}, and a name cannot (it is not repeated here). Nothing was sent.`,
+      hint
+    );
+  }
+  const lines = trimmed.split(/\r?\n|[\u2028\u2029]/u).map((l) => l.trim()).filter((l) => l !== "");
+  if (lines.length > 1 && lines.every((l) => !CONTROL.test(l))) {
+    const prefix = /^[a-z][a-z-]*:/.exec(lines[0])?.[0] ?? "";
+    const names = lines.map((l) => prefix !== "" && l.startsWith(prefix) ? l.slice(prefix.length) : l);
+    const shown = names.slice(0, 3).map((n) => `"${n}"`).join(", ") + (names.length > 3 ? ", \u2026" : "");
+    const loop = opts.loop?.(value, prefix, names);
+    throw new UsageError(
+      `${opts.verb === void 0 ? "A command" : `\`${opts.verb}\``} takes one name per command, and ${what} holds ${names.length}, one per line (${shown}). Nothing was sent.` + (loop === void 0 ? " Run the command once for each name." : `
+Run it once for each name:
+  ${loop}`),
+      hint
+    );
+  }
+  throw new UsageError(
+    `${capital(what)} ${JSON.stringify(trimmed)} holds ${describe(bad[0])}, which no name carries. Nothing was sent.`,
+    hint
+  );
+}
+function describe(ch) {
+  return `a control character (${CONTROL_NAMES[ch] ?? `U+${ch.codePointAt(0).toString(16).toUpperCase().padStart(4, "0")}`})`;
+}
+function capital(s) {
+  return s.charAt(0).toUpperCase() + s.slice(1);
+}
+
+// src/emit/source-selector.ts
+var CUT_KINDS = ["workspace", "ephemeral", "tenant"];
+var EXIT_SOURCE_UNRESOLVABLE = 8;
+var PREFIXED = {
+  release: "required",
+  tenant: "required",
+  ephemeral: "optional",
+  "local-engine": "optional"
+};
+var BARE = ["workspace", "ephemeral", "local-engine"];
+function isKindShaped(raw) {
+  return /^[a-z][a-z-]*:/.test(raw);
+}
+function spellingsOf(kind) {
+  switch (kind) {
+    case "workspace":
+      return ["workspace"];
+    case "ephemeral":
+      return ["ephemeral", "ephemeral:<name>"];
+    case "local-engine":
+      return ["local-engine", "local-engine:<name>"];
+    case "release":
+      return ["release:<name>"];
+    case "tenant":
+      return ["tenant:<name>"];
+    case "file":
+      return ["a path to a bundle .json"];
+  }
+}
+function sourceSpellings(accepted) {
+  const parts = accepted.flatMap(spellingsOf);
+  if (parts.length <= 1) return parts.join("");
+  return `${parts.slice(0, -1).join(", ")}, or ${parts[parts.length - 1]}`;
+}
+function refuse(raw, accepted, helpFor, because, noun = SOURCE_NOUN, suggestion) {
+  return new UsageError(
+    `"${raw}" ${because}. ${noun.plural} are ${sourceSpellings(accepted)}.`,
+    { hintFor: helpFor, ...suggestion === void 0 ? {} : { suggestion } }
+  );
+}
+function keywordSuggestion(raw, accepted) {
+  const colon = raw.indexOf(":");
+  if (colon > 0) {
+    const kinds = accepted.filter((k) => (Object.hasOwn(PREFIXED, k) ? PREFIXED[k] : void 0) !== void 0);
+    const kind = suggest(raw.slice(0, colon), kinds);
+    return kind === void 0 ? void 0 : `${kind}${raw.slice(colon)}`;
+  }
+  return suggest(raw, accepted.filter((k) => BARE.includes(k)));
+}
+var SOURCE_NOUN = { singular: "source", plural: "Sources" };
+function parseSource(raw, accepted, helpFor, noun = SOURCE_NOUN) {
+  checkOneName(raw, `the ${noun.singular}`, { helpFor, ...runNameContext() });
+  if (isKindShaped(raw)) {
+    const colon = raw.indexOf(":");
+    const kind = raw.slice(0, colon);
+    const name = raw.slice(colon + 1).trim();
+    if ((Object.hasOwn(PREFIXED, kind) ? PREFIXED[kind] : void 0) === void 0) {
+      throw BARE.includes(kind) ? refuse(raw, accepted, helpFor, `takes no name \u2014 ${kind} names one thing`, noun) : refuse(raw, accepted, helpFor, `names no ${noun.singular} kind "${kind}"`, noun, keywordSuggestion(raw, accepted));
+    }
+    if (!accepted.includes(kind)) {
+      throw refuse(raw, accepted, helpFor, `names ${withArticle(kind.replace("-", " "))}, which this command does not take`, noun);
+    }
+    if (name === "") throw refuse(raw, accepted, helpFor, `names no ${kind}`, noun);
+    return { kind, name };
+  }
+  if (BARE.includes(raw)) {
+    const kind = raw;
+    if (!accepted.includes(kind)) {
+      throw refuse(raw, accepted, helpFor, `names the ${kind}, which this command does not take`, noun);
+    }
+    return { kind };
+  }
+  if (accepted.includes("file") && (/\.json$/i.test(raw) || /[\\/]/.test(raw))) {
+    return { kind: "file", path: raw };
+  }
+  if (/\.json$/i.test(raw) || /[\\/]/.test(raw)) {
+    throw refuse(raw, accepted, helpFor, "names a path, and a path has never run", noun);
+  }
+  const named = accepted.filter((k) => (Object.hasOwn(PREFIXED, k) ? PREFIXED[k] : void 0) !== void 0);
+  const others = accepted.filter((k) => k !== "file" && (Object.hasOwn(PREFIXED, k) ? PREFIXED[k] : void 0) === void 0);
+  if (named.length === 1 && others.length === 0) {
+    return { kind: named[0], name: raw };
+  }
+  throw refuse(raw, accepted, helpFor, `names no ${noun.singular}`, noun, keywordSuggestion(raw, accepted));
+}
+function verbBackendName(raw, kind, helpFor, flags = "") {
+  const value = raw.trim();
+  if (!isKindShaped(value)) return value;
+  const colon = value.indexOf(":");
+  const typed = value.slice(0, colon);
+  const name = value.slice(colon + 1).trim();
+  const verb = `xanosdk ${kind} ${helpFor.subcommand}`;
+  if (typed === kind) {
+    if (name === "") throw new UsageError(`"${raw}" names no ${kind}. \`${verb}\` takes ${withArticle(kind)} name.`, { hintFor: helpFor });
+    return name;
+  }
+  const shared = helpFor.subcommand === "get" || helpFor.subcommand === "delete";
+  const other = shared && (typed === "tenant" || typed === "ephemeral") ? `xanosdk ${typed} ${helpFor.subcommand}` : void 0;
+  const known = Object.hasOwn(PREFIXED, typed) || BARE.includes(typed);
+  throw new UsageError(
+    `"${raw}" ${known ? `names ${withArticle(typed.replace("-", " "))}` : `names no backend kind "${typed}"`}, and \`${verb}\` takes ${withArticle(kind)} name (\`${kind}:<name>\` or the bare name).` + (other !== void 0 && name !== "" ? ` For ${withArticle(typed)}, run \`${other} ${shellQuote(name)}${flags}\`.` : ""),
+    { hintFor: helpFor }
+  );
+}
+function isBackendHandle(name) {
+  return /^[a-z0-9]{4}-[a-z0-9]{4}-[a-z0-9]{4}$/.test(name);
+}
+
+// src/emit/commands.ts
+function renderArgs(args) {
+  return (args ?? []).map((a) => a.required && a.satisfiedBy === void 0 ? `<${a.name}>` : `[${a.name}]`).join(" ");
+}
+var HELP_GROUP_ORDER = [
+  "Author",
+  "Deploy",
+  "Environments",
+  "Account",
+  "Maintenance"
+];
+var FLAGS = {
+  out: { spec: "--out, -o <path>", summary: "Write the artifact to this path instead of stdout (`-` is stdout)" },
+  lock: { spec: "--lock[=<path>]", summary: "Name the xano.lock to use \u2014 default: beside the entry file" },
+  "no-lock": { spec: "--no-lock", summary: "Build with no lock: identities derive from names, public URLs are left to the instance" },
+  entry: {
+    // `--entry <path>` and `--entry=<path>` both parse; the spaced spelling is
+    // what makes completion offer files after it.
+    spec: "--entry <path>",
+    summary: "Workspace entry to resolve xano.lock beside (for lock subcommands that take no entry file)"
+  },
+  "frozen-lock": { spec: "--frozen-lock", summary: "CI guard: fail instead of changing the lock, or on a lock entry nothing matches" },
+  "allow-lock-orphans": {
+    spec: "--allow-lock-orphans",
+    summary: "With --frozen-lock: accept lock entries no exported object matches, for a workspace adopted with `lock import` and ported a piece at a time"
+  },
+  strict: { spec: "--strict", summary: "Promote every export warning (data-losing shapes, unresolvable filters) to a hard failure" },
+  yes: { spec: "--yes, -y", summary: "Confirm a destructive action non-interactively" },
+  bundle: { spec: "--bundle <path>", summary: "Use an already-exported bundle instead of an entry file" },
+  reset: {
+    spec: "--reset",
+    summary: "Replace the environment and re-seed it, overriding --keep-data (a deploy without --keep-data already does)"
+  },
+  "keep-data": {
+    spec: "--keep-data",
+    summary: "Keep the environment's table rows: merge into what an earlier deploy filled instead of replacing it. Seed rows are not re-written, objects removed from the project are deleted, and a new or never-filled environment is replaced and seeded as usual. --reset overrides it; --to already merges"
+  },
+  // `test`'s selector. It was `--env`, which read as "an environment variable"
+  // beside `--env-var`/`--backend-env-file` and named only two of the backend kinds.
+  // Its accepted spellings and completion values come from the slot declared
+  // on each `test` verb, not from this row.
+  on: {
+    spec: "--on <backend>",
+    summary: "Run on this backend instead of the one this project last deployed to"
+  },
+  kind: {
+    spec: "--kind <unit|workflow>",
+    summary: "Only this test family (default: both)",
+    values: ["unit", "workflow"]
+  },
+  concurrency: {
+    spec: "--concurrency <n>",
+    summary: "Run this many tests at once (default: 1). Tests share the environment database, so raise it only when yours do not depend on shared state."
+  },
+  "expires-hours": { spec: "--expires-hours <n>", summary: "Ephemeral TTL at create time, 1\u201324 (default: 1)" },
+  static: { spec: "--static <dir>", summary: "Archive this built frontend and deploy it to the static host" },
+  "local-engine": {
+    spec: "--local-engine[=<version|url|path>]",
+    summary: "Deploy to an engine on this machine instead of an ephemeral. Bare: runs the project's pinned engine version (the latest on first run, then pinned in package.json \u2014 commit it); a newer engine is offered, never applied without a yes. A version, URL or archive path (or XANOSDK_LOCAL_ENGINE_OVERRIDE, for every run in a shell) runs that engine as an override and never touches the pin; a URL must be https (plain http only from this machine). Not combinable with --to or --static"
+  },
+  // Keyed apart from the global `version` row: that one is the first-argument
+  // `xanosdk --version`, this one a value an engine verb takes after the verb.
+  "engine-version": {
+    spec: "--version <v>",
+    summary: "An engine version, like v0.1.5 (the leading v is optional)"
+  },
+  "no-dev-env": {
+    spec: "--no-dev-env",
+    summary: "Do not point this project's .env.local at the deployed backend (only written when no static site is published)"
+  },
+  "static-env": { spec: "--static-env KEY=VALUE", summary: "Public config baked in as window.<KEY> (repeatable; never secrets)" },
+  "env-var": {
+    spec: "--env-var KEY=VALUE",
+    summary: "Set one BACKEND workspace env var for this run (repeatable). Beats xano/.env and --backend-env-file; the value never touches disk"
+  },
+  "backend-env-file": {
+    spec: "--backend-env-file <path>",
+    summary: "Read backend env values from this dotenv-style file INSTEAD of the default xano/.env (for CI, which does not have the ignored default)"
+  },
+  "allow-empty-env": {
+    spec: "--allow-empty-env=NAME[,NAME]",
+    summary: "Send these declared names EMPTY when no value is supplied, clearing them in whatever imports the bundle. Only `deploy` refuses without it; per-name on purpose, and a bare --allow-empty-env is refused"
+  },
+  "allow-empty-doc-token": {
+    spec: "--allow-empty-doc-token=<scope>",
+    summary: "Send this scope's documentation token EMPTY when none is supplied, clearing that doc site's gate in whatever imports the bundle \u2014 `workspace`, or an API group's name. Repeat for more than one. Without it `deploy` refuses any gate left with no token, and every build refuses one on a group that publishes its docs (`swagger` on); a bare --allow-empty-doc-token is refused"
+  },
+  "secrets-file": {
+    spec: "--secrets-file <path>",
+    summary: "Read documentation tokens from this file INSTEAD of the default xano/.secrets.json (for CI, which does not have the ignored default)"
+  },
+  "doc-token": {
+    spec: "--doc-token <scope>=<value>",
+    summary: "Supply one documentation token inline \u2014 `workspace=\u2026`, or an API group's name. Repeat for more than one. Prefer --secrets-file: a value here is visible in shell history, the process list, and any CI log that echoes the command"
+  },
+  "no-secrets": {
+    spec: "--no-secrets",
+    summary: "Find the documentation tokens and write none \u2014 for a machine where a secret on disk is not wanted. The tree still declares the gates, so a later deploy refuses rather than clearing one"
+  },
+  export: {
+    spec: "--export <name>",
+    summary: "The named export to compile, when the module exports several defs"
+  },
+  emit: {
+    spec: "--emit <path>",
+    summary: "Write a generated route + socket module there (plain data, no SDK import; `-` is stdout)"
+  },
+  "static-host": { spec: "--static-host <name>", summary: "Static-host name to deploy to (default: default)" },
+  "static-routing": {
+    spec: "--static-routing spa|multipage",
+    summary: "Override URL resolution (inferred from the bundle; rarely needed)",
+    values: ["spa", "multipage"]
+  },
+  test: {
+    spec: "--test",
+    summary: "After deploying, run the environment's tests; exit 5 if one fails, 6 if they cannot be reached; the deploy stands either way"
+  },
+  // Three flags where there was one. `--no-verify` meant a post-deploy liveness
+  // probe, an offline round-trip diff, and "do not load the entry file" — three
+  // unrelated checks whose only shared property was the word "verify", so the
+  // one summary had to say "instead" mid-sentence and a reader had to know
+  // which command they were on to know what they were turning off.
+  "skip-liveness": {
+    spec: "--skip-liveness",
+    summary: "Do not wait to confirm the deploy came up (static host, microservices)"
+  },
+  "skip-roundtrip": {
+    spec: "--skip-roundtrip",
+    summary: "Do not check that the written tree re-exports as it was pulled (offline; no network, no deploy)"
+  },
+  "identity-only": {
+    spec: "--identity-only",
+    summary: "Act on the named lock entries without loading the entry file"
+  },
+  "require-microservices": {
+    spec: "--require-microservices",
+    summary: "Fail the deploy (exit 4) when a microservice is not ready by the end of the wait"
+  },
+  report: {
+    spec: "--report <grouped|full|json>",
+    summary: "Findings as grouped root causes (default), every site, or JSON",
+    values: ["grouped", "full", "json"]
+  },
+  origin: {
+    spec: "--origin <origin>",
+    summary: "Xano OAuth host for `login` and a XANO_REFRESH_TOKEN exchange (default: $XANO_ORIGIN)"
+  },
+  config: { spec: "--config <path>", summary: "Explicit credential file (default: $XANO_CONFIG)" },
+  local: { spec: "--local", summary: "Use the project-local ./.xano/auth.json instead of the shared cache" },
+  profile: {
+    spec: "--profile, -p <name>",
+    summary: "Commands that sign in: which stored credential profile to act as \u2014 the only thing that overrides this project's xano.profile.json (then $XANO_PROFILE, then the credential file default)"
+  },
+  all: { spec: "--all", summary: "Every stored profile, not just the active one" },
+  "all-workspaces": { spec: "--all-workspaces", summary: "Enumerate across every workspace, not just the token's" },
+  guest: { spec: "--guest, -g", summary: "Mint a read-only guest session (browse only)" },
+  "url-only": { spec: "--url-only, -u", summary: "Print the dashboard URL instead of opening a browser" },
+  prompt: { spec: "--prompt", summary: "Print only the add-on wiring prompt, for piping to a coding agent" },
+  port: { spec: "--port <n>", summary: "Loopback callback port (default: 47100)" },
+  "workspace-id": { spec: "--workspace-id <n>", summary: "Numeric workspace the meta API token acts on" },
+  paste: {
+    spec: "--paste",
+    summary: "Sign in without the loopback callback: open the printed URL in any browser and paste the redirect back. For a host whose 127.0.0.1 the browser cannot reach \u2014 remote shell, container, Codespace. Needs a terminal."
+  },
+  scope: { spec: '--scope "<list>"', summary: "OAuth scopes to request (default: the built-in set)" },
+  runtime: { spec: "--runtime", summary: "After the round-trip, run each deployed function and report" },
+  capture: { spec: "--capture", summary: "Write each round-tripped function's fetched JSON" },
+  "legacy-runtime": { spec: "--legacy-runtime", summary: "Remove the runtime copy earlier versions left in your own cache directory" },
+  verbose: { spec: "--verbose", summary: "Print full diffs and raw engine detail" },
+  instance: { spec: "--instance <url>", summary: "Override XANO_VALIDATE_INSTANCE for this run" },
+  format: {
+    spec: "--format <json|multidoc>",
+    summary: "Which artifact to emit: json (default), or multidoc (the backend as XanoScript, rendered by the engine)",
+    values: ["json", "multidoc"]
+  },
+  path: { spec: "--path <p>", summary: "Output location \u2014 `-` for stdout, a dir, or a file path" },
+  name: { spec: "--name <n>", summary: "Name for what this command produces" },
+  framework: {
+    spec: "--framework <id>",
+    summary: "Frontend framework to scaffold: react (default), svelte",
+    values: ["react", "svelte"]
+  },
+  theme: {
+    spec: "--theme <id>",
+    summary: "shadcn/ui theme \u2014 <base> or <base>-<accent> (e.g. zinc-blue), a registry theme URL, or a registry item JSON path; an unknown id lists every base and accent",
+    // Completion offers the base colors alone — the accent half multiplies them
+    // into 126 values, which is a menu no one reads at a tab-complete prompt.
+    // `--help` carries the accent list; this carries the starting points.
+    values: ["neutral", "stone", "zinc", "mauve", "olive", "mist", "taupe"],
+    open: true
+  },
+  radius: {
+    spec: "--radius <len>",
+    summary: "Corner radius for the scaffold's theme \u2014 a number of rem (0, 0.5, 1) or a CSS length",
+    values: ["0", "0.25", "0.5", "0.625", "0.75", "1"],
+    open: true
+  },
+  dark: {
+    spec: "--dark <mode>",
+    summary: "What switches the app into its dark palette: system (default, follows the OS), toggle (adds a control), off",
+    values: ["system", "toggle", "off"]
+  },
+  font: {
+    spec: "--font <id>",
+    summary: "Body typeface \u2014 sans faces only (mono: --font-mono; serif: --font-heading), self-hosted from its @fontsource package (default: the system stack)",
+    values: fontIdsFor("sans")
+  },
+  "font-mono": {
+    spec: "--font-mono <id>",
+    summary: "Code typeface \u2014 mono faces only (default: the system mono stack)",
+    values: fontIdsFor("mono")
+  },
+  "font-heading": {
+    spec: "--font-heading <id>",
+    summary: "Heading typeface, any face, bound to h1\u2013h6 (default: inherits the body face)",
+    values: fontIdsFor("heading")
+  },
+  icons: {
+    spec: "--icons <id>",
+    summary: "Icon set: lucide (default), tabler, phosphor",
+    values: ["lucide", "tabler", "phosphor"]
+  },
+  "no-agents-md": { spec: "--no-agents-md", summary: "Do not write the AGENTS.md agent brief" },
+  ai: {
+    spec: "--ai <preset|none>",
+    summary: "For scripted callers: `none` is --no-agents-md; any other value (an agent name) writes the one AGENTS.md every agent reads"
+  },
+  marketplace: {
+    spec: "--marketplace <pkgs>",
+    summary: "Marketplace modules to install and register, comma-separated, by the names `marketplace install` takes (auth resolves to @xano-sdk/auth); a name the marketplace does not list exits 8 before anything is written. An add-on install or the project npm install that fails exits 2 with the project left in place"
+  },
+  // `--from` and `--to` are every read's and every write's selector. Which
+  // backends each command takes is declared on its own reference (a
+  // `selector`), so these shared rows carry no spelling list and no values.
+  from: {
+    spec: "--from <source>",
+    summary: "The backend to read from"
+  },
+  to: {
+    spec: "--to <destination>",
+    summary: "The backend to write to"
+  },
+  description: {
+    spec: "--description <text>",
+    summary: "What this release is for"
+  },
+  release: {
+    spec: "--release <name>",
+    summary: "The release this frontend belongs to \u2014 checked to exist and reported with the publish"
+  },
+  web: {
+    spec: "--web",
+    summary: "Collect the scaffold options in a browser instead of on the command line"
+  },
+  check: {
+    spec: "--check",
+    summary: "Report whether an upgrade is available and exit 7, without installing it"
+  },
+  /**
+   * One meaning, everywhere: OVERWRITE something that already exists.
+   *
+   * `--yes` is the other half of the pair and means "do not ask me". They were
+   * synonyms on three commands, where `--force` bought a second spelling for a
+   * confirmation prompt and nothing else — so a reader could not tell, from the
+   * flag alone, whether a command was going to overwrite anything. No command
+   * takes both.
+   */
+  force: { spec: "--force", summary: "Overwrite something that already exists" },
+  "backend-dir": {
+    spec: "--backend-dir <path>",
+    summary: "The backend directory to act on, when this project does not keep it in xano/ and nothing on disk says so"
+  },
+  "no-install": { spec: "--no-install", summary: "Skip the post-scaffold npm install" },
+  "dry-run": { spec: "--dry-run", summary: "Print what would change and exit without sending it" },
+  prune: { spec: "--prune", summary: "Also delete workspace objects your project no longer defines" },
+  "reset-data": { spec: "--reset-data", summary: "Empty every table the bundle carries before importing" },
+  seed: { spec: "--seed", summary: "Write the bundle's table rows (off by default; `--replace` always writes them)" },
+  table: {
+    spec: "--table <guid>",
+    summary: `Which table to act on, by guid (repeatable) \u2014 \`${tablesCommand("workspace")}\` lists them`
+  },
+  write: {
+    spec: "--write",
+    summary: "Actually perform the write \u2014 without it this is a dry run that changes nothing"
+  },
+  replace: {
+    spec: "--replace",
+    summary: "Wipe the workspace \u2014 including ALL its branches \u2014 and import in its place"
+  },
+  branch: {
+    spec: "--branch <label>",
+    summary: "Release to this branch instead of the live one (stages logic; schema is shared)"
+  },
+  "set-live": { spec: "--set-live", summary: "Promote the branch to live once the import lands" },
+  "expect-live": {
+    spec: "--expect-live <label>",
+    summary: "With --set-live: refuse unless <label> is live \u2014 checked before landing and again before switching (not atomic)"
+  },
+  "to-profile": {
+    spec: "--to-profile <name>",
+    summary: "The stored credential profile whose instance and workspace receive the release"
+  },
+  "allow-shared-schema-changes": {
+    spec: "--allow-shared-schema-changes",
+    summary: "Proceed even though table/microservice changes reach every branch"
+  },
+  "allow-branch-deletion": {
+    spec: "--allow-branch-deletion",
+    summary: "Acknowledge that --replace permanently deletes the workspace's other branches"
+  },
+  "backup-branch": {
+    spec: "--backup-branch[=<label>]",
+    summary: "Snapshot the live branch's logic first; set-live back restores logic, not tables (shared by every branch)"
+  },
+  open: { spec: "--open", summary: "Open the deployed URL in your browser when it lands" },
+  // ── Global (accepted by every command; see GLOBAL_FLAGS) ───────────────
+  json: {
+    spec: "--json",
+    summary: "Force JSON on stdout (default: whenever stdout is not a terminal, a failure's document too \u2014 except help, `version`, which stays text for `$(xanosdk version)`, and a command whose stdout is its data, such as `export` or `--path -`)"
+  },
+  "no-refresh": {
+    spec: "--no-refresh",
+    summary: "Do not refresh the managed block in AGENTS.md"
+  },
+  help: { spec: "--help, -h", summary: "Show help for the command and exit" },
+  version: { spec: "--version, -v", summary: "Print the CLI version and exit" }
+};
+var GLOBAL_FLAGS = [
+  "json",
+  // Global rather than part of the shared AUTH bundle: it occupies ONE help row
+  // here, against one on each of ~35 authenticated commands' manifest entries.
+  // Commands that cannot honour it REFUSE it (see the post-loop cross-check in
+  // `parseArgs`) rather than accepting and ignoring it.
+  "profile",
+  "no-refresh",
+  "help",
+  "version"
+];
+var AUTH = ["origin", "config", "local"];
+var CREDENTIAL_FILE = ["config", "local"];
+function isAuthenticatedCommand(command, subcommand) {
+  return flagRefFor(command, subcommand, "config") !== void 0;
+}
+var PROFILE_BY_NAME = ["add", "use", "set-default", "delete"];
+function takesProfileFlag(command, subcommand) {
+  if (command === "profile" && subcommand !== void 0 && PROFILE_BY_NAME.includes(subcommand)) return false;
+  return isAuthenticatedCommand(command, subcommand);
+}
+var CUT = ["workspace", "ephemeral", "tenant"];
+var BACKEND = ["workspace", "ephemeral", "local-engine", "tenant"];
+var TEST_ON = {
+  key: "on",
+  summary: "Run on this backend instead of the one this project last deployed to",
+  selector: { accepted: BACKEND, role: "on", default: "tracked" }
+};
+var TEST_LIST_ON = {
+  ...TEST_ON,
+  summary: "List the tests on this backend instead of the one this project last deployed to"
+};
+var REFUSES_EMPTY_ENV = /* @__PURE__ */ new Set(["deploy"]);
+var REFUSES_EMPTY_DOC_TOKEN = /* @__PURE__ */ new Set(["deploy"]);
+var ENV_VALUE_FLAGS = [
+  "env-var",
+  "backend-env-file",
+  "allow-empty-env",
+  "allow-empty-doc-token",
+  "secrets-file",
+  "doc-token"
+];
+var ENV_VAR_TARGET_FLAGS = [
+  {
+    key: "to",
+    summary: "Write to this backend instead of the one this project last deployed to",
+    selector: { accepted: BACKEND, role: "to", default: "tracked" }
+  },
+  { key: "yes", summary: "Skip the confirmation a workspace or tenant write asks for (required when there is no terminal)" }
+];
+var COMPILE = [
+  "lock",
+  "no-lock",
+  "frozen-lock",
+  "allow-lock-orphans",
+  "strict",
+  ...ENV_VALUE_FLAGS
+];
+var COMPARISON_LOCK_FLAGS = [
+  "lock",
+  "no-lock",
+  "frozen-lock",
+  "allow-lock-orphans"
+];
+var COMPILE_COMPARISON_ONLY = COMPILE.filter(
+  (key) => !COMPARISON_LOCK_FLAGS.includes(key)
+).map(
+  (key) => ENV_VALUE_FLAGS.includes(key) ? {
+    key,
+    // The shared summary's trailing punctuation is not load-bearing for
+    // another command's help text: normalize it before appending.
+    summary: `${FLAGS[key].summary.replace(/[.\s]+$/, "")}. Applies ONLY to the local-compile comparison this command runs against the source \u2014 the released bytes come from what is running`
+  } : key
+);
+var SCAFFOLD = [
+  { key: "name", summary: "Project name (default: the target directory's basename)" },
+  "framework",
+  "theme",
+  "radius",
+  "dark",
+  "font",
+  "font-mono",
+  "font-heading",
+  "icons",
+  "no-agents-md",
+  "ai",
+  {
+    key: "force",
+    summary: "Write into a non-empty target directory. Over an existing project it lists every file it would overwrite and confirms first (--yes without a terminal); files the scaffold does not write are kept"
+  },
+  "no-install"
+];
+var GUID_STABILITY_NOTE = "Guids survive a redeploy, so one written down earlier keeps matching \u2014 and a rename whose xano.lock entry moves with it (`lock rename`) keeps it too; one the lock is not told about gives the table a new guid";
+function tablesCommand(backend = "<backend>") {
+  return `xanosdk tables ${backend}`;
+}
+function withToOnly(key) {
+  return { key, summary: `${FLAGS[key].summary} \u2014 only with --to` };
+}
+function withoutTo(key, summary = FLAGS[key].summary) {
+  return { key, summary: `${summary} \u2014 not with --to` };
+}
+var COMMANDS = {
+  // ── Author ──────────────────────────────────────────────────────────────
+  compile: {
+    group: "Author",
+    display: "compile <file>",
+    // Says "single object def", not "workspace": this command takes ONE def and
+    // prints its JSON artifact. `compile` is the first command listed under
+    // Author, so it is the first thing tried on the scaffold entry (a
+    // workspace), which fails — the summary must not promise otherwise.
+    // `export` is the workspace command. It does not type-check: the entry is
+    // loaded with its types stripped, so `tsc` is what catches a type error.
+    summary: "Compile a single object def and print its JSON artifact (not type-checked \u2014 run `tsc` for that)",
+    args: [{ name: "file", required: true, path: true }],
+    flags: ["out", "lock", "strict", "export"],
+    example: "xanosdk compile ./xano/query/public/health_GET.ts"
+  },
+  export: {
+    group: "Author",
+    display: "export <file>",
+    summary: "Compile and write the deployable JSON bundle",
+    args: [{ name: "file", required: true, path: true }],
+    flags: [
+      "out",
+      ...COMPILE,
+      {
+        key: "check",
+        summary: "CI check: run every export check and fail instead of changing the lock, writing nothing \u2014 no bundle, no lock, so no secrets are needed"
+      }
+    ],
+    example: "xanosdk export ./index.ts --out bundle.json"
+  },
+  routes: {
+    group: "Author",
+    display: "routes <file>",
+    summary: "List each query's verb + resolved api:<canonical>/<name>",
+    args: [{ name: "file", required: true, path: true }],
+    flags: [
+      "lock",
+      "emit",
+      {
+        key: "strict",
+        summary: "With --emit: write nothing, and fail when the file is missing or out of date (what xano:check runs)"
+      }
+    ],
+    example: "xanosdk routes ./index.ts --emit xano/routes.gen.ts"
+  },
+  // `routes` is the canonical spelling: it is the word every web framework uses
+  // for this list, where `paths` is OpenAPI's term for the same thing and reads
+  // as filesystem paths to everyone else. `paths` still dispatches — it is what
+  // the command was called — but it is off the menu.
+  paths: {
+    group: "Author",
+    display: "paths <file>",
+    summary: "Alias for `routes`",
+    aliasOf: "routes",
+    args: [{ name: "file", required: true, path: true }],
+    flags: [
+      "lock",
+      "emit",
+      {
+        key: "strict",
+        summary: "With --emit: write nothing, and fail when the file is missing or out of date (what xano:check runs)"
+      }
+    ]
+  },
+  init: {
+    group: "Author",
+    display: "init [dir]",
+    // Toolchain modules contribute their own question flags; see the field's
+    // doc for the obligation this takes on.
+    deferUnknownFlags: true,
+    summary: "Scaffold a Xano SDK project \u2014 empty, or filled from an existing backend",
+    args: [{ name: "dir", required: false, path: true }],
+    // Two axes on top of the shared scaffold flags: WHERE `xano/` comes from
+    // (`--from`) and HOW the options were collected (`--web`). They compose —
+    // a browser-chosen shell around a decoded workspace is one invocation.
+    //
+    // `--marketplace` rides with them but is not in SCAFFOLD: a `--from` run
+    // writes a project around a workspace that already exists, and adding
+    // add-ons to one is `marketplace install`, not a scaffold decision.
+    //
+    // `--report`, `--skip-roundtrip` and the auth flags only bite under `--from`;
+    // passing them without it is a usage error rather than a silent no-op.
+    flags: [
+      ...SCAFFOLD,
+      "marketplace",
+      {
+        key: "from",
+        summary: "Fill xano/ by decoding an existing backend instead of writing the empty starter",
+        selector: { accepted: [...BACKEND, "release", "file"], role: "from", default: "none" }
+      },
+      "web",
+      "skip-roundtrip",
+      "report",
+      "no-secrets",
+      {
+        key: "yes",
+        summary: "Confirm without asking what --force overwrites, or what --from replaces in an existing xano/ \u2014 required when there is no terminal"
+      },
+      {
+        key: "branch",
+        summary: "Read this branch instead of the live one (`--from workspace` only)"
+      },
+      ...AUTH
+    ],
+    // One flag from each axis the command now has — look, add-ons —
+    // rather than every flag it accepts.
+    example: "xanosdk init my-app --theme zinc-blue --marketplace @xano-sdk/auth"
+  },
+  marketplace: {
+    group: "Author",
+    // Every verb, spelled out. The family is a lifecycle — find it, add it,
+    // change it, drop it — and a row that stopped at `install` read as though
+    // the last two did not exist. `tenant` already carries six the same way.
+    display: "marketplace <list|search|details|install|reinstall|remove>",
+    summary: "Find Xano SDK add-on packages and add them to this project",
+    subcommands: {
+      // No apostrophes in any registry string: zsh completion single-quotes
+      // these, and the completion suite fails the whole script on an odd quote.
+      list: {
+        summary: "List every published add-on, newest first",
+        extraArgHint: "`list` prints the whole catalogue; `xanosdk marketplace search <query>` is the filter.",
+        example: "xanosdk marketplace list"
+      },
+      search: {
+        summary: "Search add-ons by keyword across name, tagline and description",
+        // Variadic: the handler joins every term into one phrase query, so
+        // `search ai agent` searches for "ai agent" rather than dropping "agent".
+        args: [{ name: "query", required: true, variadic: true }],
+        example: "xanosdk marketplace search auth"
+      },
+      details: {
+        summary: "Show what an add-on installs, what it needs, and how to register it",
+        args: [{ name: "package", required: true }],
+        flags: ["prompt"],
+        example: "xanosdk marketplace details @xano-sdk/auth"
+      },
+      install: {
+        summary: "Install a marketplace module into the Xano SDK project in the current directory, by package or catalogue name (auth resolves to @xano-sdk/auth); a name the marketplace does not list exits 8",
+        args: [{ name: "package", required: true }],
+        // An installed toolchain module contributes questions, each deriving a
+        // flag that answers it non-interactively — and which modules exist is
+        // not knowable until npm has run, long after parsing. Declared on the
+        // VERB, never on `marketplace`: see SubcommandSpec.deferUnknownFlags.
+        deferUnknownFlags: true,
+        example: "xanosdk marketplace install @xano-sdk/auth"
+      },
+      reinstall: {
+        summary: "Re-ask the questions for an installed toolchain module and re-apply its settings (takes the names install takes)",
+        args: [{ name: "package", required: true }],
+        // Same reason as `install`: this verb runs the questionnaire, so the
+        // flags a module derives from its own questions cannot be known until
+        // the module has been imported.
+        deferUnknownFlags: true,
+        example: "xanosdk marketplace reinstall <toolchain-package>"
+      },
+      remove: {
+        summary: "Uninstall a Xano SDK module and drop the settings and file lines it contributed (takes the names install takes)",
+        args: [{ name: "package", required: true }],
+        // Deliberately NO deferUnknownFlags: this verb runs no
+        // questionnaire, so nothing downstream could ever claim a plugin flag.
+        // Deferring here would accept `--renderer-dir=x` on a removal and
+        // silently discard it.
+        example: "xanosdk marketplace remove <toolchain-package>"
+      }
+    }
+  },
+  // ── Deploy ──────────────────────────────────────────────────────────────
+  deploy: {
+    group: "Deploy",
+    display: "deploy [source]",
+    summary: "Ship to a live ephemeral env \u2192 URL",
+    // Optional: a bare `deploy` inside a project compiles its entry, and the
+    // argument may name a backend to take the bytes FROM instead of a path.
+    args: [
+      {
+        name: "source",
+        required: false,
+        path: true,
+        satisfiedBy: ["bundle"],
+        selector: { accepted: ["release", ...BACKEND, "file"], role: "subject", default: "entry" }
+      }
+    ],
+    flags: [
+      withoutTo("expires-hours"),
+      withoutTo(
+        "name",
+        "Display name for the ephemeral env (default for a new one: the release name for release:<name>, else the workspace name, else this directory's)"
+      ),
+      {
+        key: "to",
+        summary: "Merge into a real destination instead of replacing an ephemeral. The escape hatch from the release flow",
+        // An ephemeral and a local engine are where a deploy goes WITHOUT
+        // `--to`; naming one here is the other path spelled wrong, and the
+        // reason says which flag that path is.
+        selector: {
+          accepted: ["workspace", "tenant"],
+          role: "to",
+          default: "none",
+          refused: {
+            "local-engine": "a deploy to a local engine is `--local-engine`, which also downloads, pins and starts one",
+            ephemeral: "a deploy with no `--to` already replaces an ephemeral. To merge into one instead, name it as the tenant it is: `--to tenant:<ephemeral name>`"
+          }
+        }
+      },
+      "local-engine",
+      withToOnly("dry-run"),
+      withToOnly("prune"),
+      withToOnly("reset-data"),
+      withToOnly("seed"),
+      withToOnly("replace"),
+      withToOnly("allow-shared-schema-changes"),
+      withToOnly("allow-branch-deletion"),
+      withToOnly("branch"),
+      withToOnly("set-live"),
+      withToOnly("backup-branch"),
+      "yes",
+      "bundle",
+      "static",
+      { key: "static-host", summary: "With --static: static-host name to deploy to (default: default)" },
+      { key: "static-routing", summary: "With --static: override URL resolution (inferred from the bundle; rarely needed)" },
+      {
+        key: "static-env",
+        summary: "With --static: public config baked in as window.<KEY> (repeatable; never secrets)"
+      },
+      withoutTo("no-dev-env"),
+      "skip-liveness",
+      withoutTo("require-microservices"),
+      withoutTo("test"),
+      withoutTo("kind", "With --test: only this test family (default: both)"),
+      withoutTo("concurrency", "With --test: run this many tests at once (default: 1)"),
+      withoutTo("open"),
+      "keep-data",
+      withoutTo("reset"),
+      ...COMPILE,
+      ...AUTH
+    ],
+    example: "xanosdk deploy ./index.ts --test"
+  },
+  env: {
+    group: "Deploy",
+    display: "env <pull|set|unset>",
+    summary: "The backend env VALUES in .env beside the backend (xano/.env by default) \u2014 one of the two files there that are not committed \u2014 and one value at a time on a running backend",
+    subcommands: {
+      pull: {
+        // Self-contained: the scoped help page renders this line ALONE, without
+        // the `env` summary above it that says which file "that" is.
+        summary: "Fill the local .env from a backend that is running. Over an existing file it lists what changes and confirms, then rewrites the whole file; a missing file is created without asking, and identical values write nothing",
+        flags: [
+          {
+            key: "from",
+            summary: "Read the values from this backend instead of the one this project last deployed to",
+            selector: { accepted: BACKEND, role: "from", default: "tracked" }
+          },
+          {
+            key: "yes",
+            summary: "Skip the confirmation before an existing .env is changed (required for that when there is no terminal)"
+          },
+          "backend-dir",
+          ...AUTH
+        ],
+        example: "xanosdk env pull --from workspace"
+      },
+      set: {
+        summary: "Set ONE env var on a running backend by name \u2014 creates it or replaces its value, leaves every other one alone. The value is the second argument, or stdin when omitted; it is never printed",
+        args: [
+          { name: "name", required: true },
+          { name: "value", required: false }
+        ],
+        flags: [
+          ...ENV_VAR_TARGET_FLAGS,
+          {
+            key: "allow-empty-env",
+            spec: "--allow-empty-env=NAME",
+            summary: "Store an EMPTY value for NAME. Refused without it: an empty value is usually an unset shell variable. To remove the variable, use `env unset`"
+          },
+          ...AUTH
+        ],
+        example: 'printf %s "$STRIPE_KEY" | xanosdk env set STRIPE_KEY --to workspace --yes'
+      },
+      unset: {
+        summary: "Clear ONE env var on a running backend by name, leaving every other one alone. A name it does not have is reported, not an error",
+        args: [{ name: "name", required: true }],
+        flags: [...ENV_VAR_TARGET_FLAGS, ...AUTH],
+        example: "xanosdk env unset STRIPE_KEY --to workspace --yes"
+      }
+    }
+  },
+  secrets: {
+    group: "Deploy",
+    // One verb today, and the noun is still the right shape: the file this
+    // family owns is the project's secret STORE, and `xanosdk fill` would say
+    // nothing about what is being filled.
+    display: "secrets <fill>",
+    summary: "The documentation tokens in .secrets.json beside the backend (xano/.secrets.json by default) \u2014 the other file there that is not committed",
+    subcommands: {
+      fill: {
+        summary: "Mint a token for every documentation gate that has none (never replaces one)",
+        args: [{ name: "file", required: false, path: true }],
+        flags: ["lock"],
+        example: "xanosdk secrets fill"
+      }
+    }
+  },
+  release: {
+    group: "Deploy",
+    display: "release <create|list|show|export|delete|transfer>",
+    summary: "Cut and manage releases \u2014 the stored record of a backend that ran",
+    subcommands: {
+      create: {
+        summary: "Cut a release from a running environment, tenant, or the workspace",
+        args: [{ name: "name", required: true }],
+        flags: [
+          // A release is cut from something that RAN, so a path is not in the
+          // set, and the cut runs on the instance, so a local engine is refused
+          // with that reason rather than left unknown.
+          {
+            key: "from",
+            summary: "Cut from this backend instead of the one this project last deployed to (a tenant only when it is a throwaway one: ephemeral or sandbox)",
+            selector: {
+              accepted: CUT,
+              role: "from",
+              default: "tracked",
+              refused: {
+                "local-engine": "the cut runs on the instance, which cannot reach an engine on this machine"
+              }
+            }
+          },
+          "description",
+          // Only meaningful with `--from workspace`: it names which branch to
+          // package. An environment has one, so it takes no label.
+          { key: "branch", summary: "Cut from this branch of your workspace (default: the one it serves)" },
+          // Deploy's own summary describes writing a BUNDLE's rows into a
+          // target. This is the opposite direction — it captures the source's
+          // current rows into the archive — so the shared summary would be a
+          // category error here.
+          // The re-mint caveat's second surface: the refusal catches a
+          // stale guid, but only after one has been written down. This states it
+          // before anything is run.
+          {
+            key: "seed",
+            spec: "--seed[=<guids>]",
+            summary: `Carry the source's table ROWS in the archive: every table, or only these guids (\`${tablesCommand()}\` lists them for the backend you are cutting from). ${GUID_STABILITY_NOTE}. Off by default \u2014 schema always travels either way`
+          },
+          { key: "yes", summary: "Skip the confirmation when seeded rows include non-public columns" },
+          // The comparison's input, and the only reason a bundle path appears on
+          // a command that cannot be cut FROM one. Advertised because it was
+          // always accepted — the parser takes `--bundle` for every command —
+          // and an accepted flag missing from the page is how the comparison
+          // came to be documented by rows that named it and a page that did not.
+          {
+            key: "bundle",
+            summary: "Compare the source against this already-exported bundle instead of compiling the project's entry. The release still carries what is RUNNING"
+          },
+          {
+            key: "entry",
+            summary: "Compare the source against a compile of this entry instead of the project's default one (a nested backend, `--entry=suites/alpha/xano/index.ts`). The release still carries what is RUNNING"
+          },
+          ...COMPILE_COMPARISON_ONLY,
+          ...AUTH
+        ],
+        example: "xanosdk release create v2 --seed=386c35157cc010fb685bdf967258b502"
+      },
+      list: {
+        summary: "Every release in this workspace",
+        flags: [...AUTH]
+      },
+      show: {
+        summary: "One release: where it came from, and what it carries",
+        args: [{ name: "name", required: true }],
+        flags: [...AUTH]
+      },
+      export: {
+        summary: "Write a release out as XanoScript (its `workspace` block is named after the release)",
+        args: [{ name: "name", required: true }],
+        flags: ["path", ...AUTH]
+      },
+      delete: {
+        summary: "Remove a release. Anything running it keeps running",
+        args: [{ name: "name", required: true }],
+        flags: ["yes", ...AUTH]
+      },
+      transfer: {
+        summary: "Copy a stored release to another workspace or instance, checked by content hash",
+        args: [{ name: "name", required: true }],
+        flags: [
+          "to-profile",
+          {
+            key: "dry-run",
+            summary: "Report whether the release is already at the destination, and write nothing"
+          },
+          { key: "yes", summary: "Skip the confirmation (the seeded-table listing still prints)" },
+          ...AUTH
+        ],
+        example: "xanosdk release transfer v2 --to-profile prod"
+      }
+    },
+    example: "xanosdk release create v2"
+  },
+  pull: {
+    group: "Author",
+    display: "pull [source]",
+    summary: "Refresh the backend of this project from a live one \u2014 rewrites the files it decodes, keeps and names files you added, and lists and confirms first",
+    args: [
+      {
+        name: "source",
+        required: false,
+        selector: { accepted: [...BACKEND, "release"], role: "subject", default: "tracked" }
+      }
+    ],
+    // `--yes`, as `env pull` spells the same act: everything it waives is one
+    // meaning — replace local state anyway — and the registry holds each
+    // command to one flag per meaning. The confirmation, uncommitted changes
+    // and a lock that shares no identity with the source are all the same
+    // answer to the same question.
+    flags: [
+      {
+        key: "yes",
+        summary: "Rewrite without asking (required when there is no terminal), over uncommitted changes and a lock that shares no identity with the source too \u2014 files you added are still kept"
+      },
+      "no-secrets",
+      // The shared summary says "act on"; for `pull` the act is a refresh, and
+      // a flag page that does not say what it rewrites is describing a different command.
+      {
+        key: "backend-dir",
+        summary: "The backend directory to refresh (its decoded files are rewritten, files you added are kept), when this project does not keep it in xano/ and nothing on disk says so"
+      },
+      "skip-roundtrip",
+      { key: "branch", summary: "Read this branch of the workspace instead of the live one (`workspace` only)" },
+      ...AUTH
+    ],
+    example: "xanosdk pull release:main"
+  },
+  generate: {
+    group: "Author",
+    display: "generate <source>",
+    summary: "Decode a backend or a bundle .json into a Xano SDK source tree, with no project around it",
+    args: [
+      {
+        name: "source",
+        required: true,
+        path: true,
+        selector: { accepted: [...BACKEND, "release", "file"], role: "subject", default: "none" }
+      }
+    ],
+    flags: [
+      { key: "out", spec: "--out, -o <dir>", summary: "Directory to write the tree into (default: ./xano)" },
+      {
+        key: "force",
+        summary: "Replace a backend tree a decode wrote in --out (keeps .env and .secrets.json; reconciles xano.lock against the source)"
+      },
+      {
+        key: "yes",
+        summary: "With --force, replace files you edited since the last decode without asking (required when there is no terminal)"
+      },
+      { key: "branch", summary: "Read this branch of the workspace instead of the live one (`workspace` only)" },
+      "no-secrets",
+      ...AUTH
+    ],
+    example: "xanosdk generate release:v1 --out ./xano"
+  },
+  promote: {
+    group: "Deploy",
+    display: "promote <release>",
+    summary: "Land a release in your real workspace",
+    args: [{ name: "release", required: true }],
+    // A promote NEVER lands on live, so the shared `--branch` summary ("instead
+    // of the live one") describes the wrong thing here: the flag names the
+    // branch, it does not divert from live. Absent, a label is derived — the
+    // engine's own default is an empty one, which nothing can address.
+    flags: [
+      {
+        key: "branch",
+        summary: "Land on this branch (default: derived from the release name; never live)"
+      },
+      "set-live",
+      "expect-live",
+      {
+        key: "allow-shared-schema-changes",
+        summary: "Land a release that alters tables live serves from (tables are shared by every branch)"
+      },
+      "yes",
+      {
+        key: "entry",
+        summary: "Record the landing in this nested backend's xano.lock, from a directory that is no project"
+      },
+      ...AUTH
+    ],
+    example: "xanosdk promote main"
+  },
+  publish: {
+    group: "Deploy",
+    display: "publish <dir>",
+    summary: "Publish an already-built frontend to a static host \u2014 no compile, no backend import",
+    args: [{ name: "dir", required: true, path: true }],
+    // The destination's own base URL is injected as `window.XANO_HOST`, so the
+    // SAME build published to two destinations serves two different documents.
+    flags: [
+      {
+        key: "to",
+        summary: "Where to publish, instead of the backend this project last deployed to",
+        selector: {
+          accepted: CUT,
+          role: "to",
+          default: "tracked",
+          refused: { "local-engine": "a local engine takes a frontend only through `xanosdk deploy --local-engine --static <dir>`" }
+        }
+      },
+      "release",
+      {
+        key: "branch",
+        summary: "Refuse unless this branch is live on your workspace \u2014 the check that the frontend lands in front of the backend it was built for (--to workspace only)"
+      },
+      "static-env",
+      "static-host",
+      "static-routing",
+      "skip-liveness",
+      { key: "yes", summary: "Skip the confirmation before replacing a workspace's or tenant's frontend" },
+      ...AUTH
+    ],
+    example: "xanosdk publish ./frontend/dist --to workspace --release v2 --branch v2-20260922T120000Z"
+  },
+  tenant: {
+    group: "Environments",
+    display: "tenant <list|get|deploy|delete>",
+    summary: "Your real tenants \u2014 list, inspect, and land a release on one",
+    subcommands: {
+      list: { summary: "Every tenant under this workspace", flags: [...AUTH] },
+      get: {
+        summary: "The URL and state of one tenant",
+        args: [{ name: "name", required: true }],
+        flags: [...AUTH]
+      },
+      deploy: {
+        summary: "Replace what a tenant serves with a release",
+        args: [
+          { name: "name", required: true },
+          { name: "release", required: true }
+        ],
+        flags: ["yes", ...AUTH],
+        example: "xanosdk tenant deploy acme v2"
+      },
+      delete: {
+        summary: "Destroy a tenant and everything it serves",
+        args: [{ name: "name", required: true }],
+        flags: [
+          "yes",
+          {
+            key: "lock",
+            summary: "The xano.lock whose landing record for it is cleared \u2014 default: the project's. A name that is not there any more clears a stale record too"
+          },
+          ...AUTH
+        ]
+      }
+    },
+    example: "xanosdk tenant deploy acme v2"
+  },
+  preflight: {
+    group: "Deploy",
+    display: "preflight <file>",
+    // Says "deploy" in the summary because the name has to keep signalling the
+    // cost: this authenticates, creates a throwaway environment, and imports
+    // into it. `validate` read as a local type-check, which is what people
+    // reached for first and what this is not.
+    summary: "Deploy to a throwaway tenant and verify the round-trip (needs auth)",
+    args: [{ name: "file", required: true, path: true, satisfiedBy: ["bundle"] }],
+    // `...AUTH` is what makes the "(needs auth)" above true for a user who has
+    // only ever run `xanosdk login`: it declares the credential flags, and
+    // `isAuthenticatedCommand` derives from that declaration — so registering
+    // it here is also what gets `--profile` honoured rather than refused.
+    // `--instance` remains the maintainer override and wins over all of it.
+    flags: [
+      "bundle",
+      "runtime",
+      "capture",
+      "verbose",
+      "instance",
+      { key: "out", spec: "--out, -o <dir>", summary: "With --capture: the directory the fixtures land in (default: validate-out)" },
+      ...COMPILE,
+      ...AUTH
+    ],
+    example: "xanosdk preflight ./index.ts --runtime"
+  },
+  // ── Environments ────────────────────────────────────────────────────────
+  workspace: {
+    group: "Environments",
+    display: "workspace",
+    summary: "Your real workspace \u2014 details, export, diff, table resets, and branches",
+    subcommands: {
+      details: {
+        summary: "Which instance and workspace am I bound to?",
+        flags: [...AUTH],
+        example: "xanosdk workspace details"
+      },
+      export: {
+        summary: "Write its bundle JSON",
+        flags: [
+          "path",
+          { key: "name", summary: "Output basename (default: `workspace`)" },
+          { key: "branch", summary: "Export this branch instead of the live one" },
+          ...AUTH
+        ],
+        example: "xanosdk workspace export --branch staging --path -"
+      },
+      diff: {
+        // Named for the question, not the mechanism: "did my release land" is
+        // what a staged branch cannot otherwise answer. The release reports what
+        // it SENT; this reports what is there.
+        summary: "Compare it (or one of its branches) against a local compile \u2014 which objects differ, are missing, or are unexpected. Exits 2 when anything declared differs or is missing",
+        args: [{ name: "file", required: true, path: true, satisfiedBy: ["bundle"] }],
+        flags: [
+          "bundle",
+          { key: "branch", summary: "Compare this branch instead of the live one" },
+          ...COMPILE,
+          ...AUTH
+        ],
+        example: "xanosdk workspace diff ./index.ts --branch staging"
+      },
+      "reset-tables": {
+        // Named for what it does to the DATA, not for the two calls it makes.
+        // "reset" is the promise: afterwards the table holds what the project
+        // says it holds, no more and no less.
+        summary: "Put named tables back to the seed rows your project compiles \u2014 every other table is left alone",
+        // No `--bundle`: an exported bundle carries no seed rows, so there is
+        // nothing in one to reset to. Undeclaring it also keeps a `.json`
+        // positional from being read as one — the command refuses it by name.
+        args: [{ name: "file", required: true, path: true }],
+        flags: ["table", "write", "yes", ...COMPILE, ...AUTH],
+        example: "xanosdk workspace reset-tables ./index.ts --table <guid> --write"
+      },
+      branch: {
+        summary: "List its branches, set one live, or delete one",
+        display: "workspace branch <list|set-live|delete> [label]",
+        args: [
+          // The closed set, so `--help` lists the verbs (and completion offers them).
+          { name: "verb", required: true, values: ["list", "set-live", "delete"] },
+          { name: "label", required: false }
+        ],
+        flags: [
+          "yes",
+          {
+            key: "expect-live",
+            summary: "With set-live: refuse unless <label> is live \u2014 checked before asking and again before switching (not atomic)"
+          },
+          ...AUTH
+        ],
+        example: "xanosdk workspace branch list"
+      }
+    }
+  },
+  ephemeral: {
+    group: "Environments",
+    display: "ephemeral",
+    summary: "Manage ephemeral envs \u2014 list, get, delete, export",
+    subcommands: {
+      list: {
+        summary: "List the ephemeral envs under your workspace",
+        flags: ["all-workspaces", ...AUTH],
+        example: "xanosdk ephemeral list"
+      },
+      get: {
+        summary: "Show one env's URL, status, and expiry",
+        args: [{ name: "name", required: true }],
+        flags: [...AUTH]
+      },
+      delete: {
+        summary: "Tear an env down now instead of waiting for its TTL",
+        args: [{ name: "name", required: true }],
+        flags: ["yes", ...AUTH]
+      },
+      export: {
+        summary: "Write an env's bundle JSON (default: the ephemeral this project deployed to)",
+        args: [{ name: "name", required: false }],
+        flags: ["format", "path", { key: "name", summary: "Output basename (default: the env name)" }, ...AUTH]
+      }
+    }
+  },
+  "local-engine": {
+    group: "Environments",
+    display: "local-engine",
+    // The handles that ship with `deploy --local-engine`: a local engine has no
+    // TTL and nothing reclaims it, and its binary is never on `PATH`, so these
+    // verbs are the only way to see or stop one (`impersonate local-engine`
+    // opens one, like any other backend).
+    summary: "See, authenticate against and stop local engines on this machine; move the project's engine pin and manage cached engine versions",
+    subcommands: {
+      list: {
+        summary: "List local engines on this machine, marking the ones xanosdk started",
+        example: "xanosdk local-engine list"
+      },
+      token: {
+        // The engine's meta API accepts only its own bearer, and no summary
+        // carries it — so this verb is the only way a suite gets one. Bare on
+        // stdout even when piped, because `$(…)` is the form it exists for.
+        summary: "Print a local engine's meta API bearer \u2014 the local XANO_META_TOKEN; `--json` adds its url and workspace id. Re-run after a restart, which re-mints it (default: the engine this project deployed to)",
+        args: [{ name: "name", required: false }],
+        example: "XANO_META_TOKEN=$(xanosdk local-engine token)"
+      },
+      stop: {
+        // The name is optional because `--all` stands in for it — and `--all`
+        // is the form most runs want, since it covers every project.
+        summary: "Stop one local engine by name, or every one xanosdk started on this machine",
+        args: [{ name: "name", required: true, satisfiedBy: ["all"] }],
+        flags: [
+          {
+            key: "all",
+            summary: "Every engine xanosdk started on this machine, across projects (foreign ones are reported, not stopped)"
+          }
+        ],
+        example: "xanosdk local-engine stop --all"
+      },
+      update: {
+        // Running it IS the confirmation, so it never prompts — the deploy only
+        // offers a newer engine; this is the verb that takes it.
+        summary: "Move this project's pinned engine to the latest release (or `--version <v>`, downgrades included), download it, and restart the project's running engine on it \u2014 the restarted engine starts empty, so the next deploy seeds it. Writes package.json: commit it",
+        flags: [
+          {
+            key: "engine-version",
+            summary: "Pin this engine version instead of the latest, like v0.1.5 \u2014 or `latest`, the default"
+          }
+        ],
+        example: "xanosdk local-engine update"
+      },
+      cache: {
+        // One verb with an action argument, not two top-level verbs: both act on
+        // the same cached binaries under the engine cache.
+        summary: "`list`: each cached engine version, its size on disk, and the engines running on it. `clear`: remove every cached engine and the runtime they unpacked, or one with `--version <v>` \u2014 any engine running on a removed version is stopped first; the next deploy fetches and restarts it",
+        args: [{ name: "action", required: true, values: ["list", "clear"] }],
+        flags: [
+          {
+            key: "engine-version",
+            summary: "`clear` only: remove just this cached version \u2014 v0.1.5, `latest` (the release `update` would pin), `override`, or an override's `src-\u2026` id from `cache list`"
+          },
+          {
+            key: "legacy-runtime",
+            summary: "`clear` only: remove instead the runtime copy earlier versions unpacked in your own cache directory (`cache list` shows it); asks first"
+          },
+          { key: "yes", summary: "Skip the `--legacy-runtime` confirmation (required when there is no terminal)" }
+        ],
+        example: "xanosdk local-engine cache clear --version v0.1.5"
+      }
+    }
+  },
+  test: {
+    group: "Environments",
+    display: "test",
+    summary: "Run the unit and workflow tests an environment carries",
+    subcommands: {
+      list: {
+        summary: "List the tests in an environment, without running any",
+        flags: [TEST_LIST_ON, "kind", ...AUTH],
+        example: "xanosdk test list --on workspace"
+      },
+      run: {
+        summary: "Run one test by name",
+        args: [{ name: "name", required: true }],
+        flags: [TEST_ON, ...AUTH],
+        example: 'xanosdk test run "happy path" --on workspace'
+      },
+      "run-all": {
+        summary: "Run every test in an environment and report pass/fail",
+        flags: [TEST_ON, "kind", "concurrency", ...AUTH],
+        example: "xanosdk test run-all --on ephemeral:pr-3"
+      }
+    }
+  },
+  tables: {
+    group: "Environments",
+    display: "tables [backend]",
+    // How the guids `release create --seed` takes are obtained at all: they
+    // appear in no artifact a user holds, and names cannot substitute (see
+    // `TableSummary.name`). One verb for every running backend rather than a
+    // copy under each noun, so bare follows what the project last deployed to.
+    // The caveat rides in the SUMMARY rather than in the output: a line printed
+    // on every run becomes furniture, and `--json` is a data channel.
+    summary: `List a backend's tables with their guids, for \`release create --seed\` (default: the backend this project last deployed to). ${GUID_STABILITY_NOTE}`,
+    args: [
+      {
+        name: "backend",
+        required: false,
+        selector: {
+          accepted: BACKEND,
+          role: "subject",
+          default: "tracked",
+          refused: {
+            release: "a release is not a running backend \u2014 list the backend it was cut from, or land it and list that"
+          }
+        }
+      }
+    ],
+    flags: [...AUTH],
+    example: "xanosdk tables ephemeral:pr-3"
+  },
+  impersonate: {
+    group: "Environments",
+    display: "impersonate [backend]",
+    // One verb for every backend a session can be minted for, so every kind
+    // prints one JSON shape and bare opens what the project last deployed to.
+    // The workspace is refused: it opens from the Xano dashboard as whoever is
+    // signed in, so there is no session to mint.
+    summary: "Open a backend's dashboard in the builder as a scoped session \u2014 the url carries it, so treat it as a credential (default: the backend this project last deployed to)",
+    args: [
+      {
+        name: "backend",
+        required: false,
+        selector: {
+          accepted: ["ephemeral", "local-engine", "tenant"],
+          role: "subject",
+          default: "tracked",
+          refused: {
+            workspace: "your workspace opens from the Xano dashboard as whoever is signed in, so there is no session to mint",
+            release: "a release is not a running backend \u2014 land it with `xanosdk deploy release:<name>` and open that"
+          }
+        }
+      }
+    ],
+    flags: [
+      { key: "guest", summary: "Mint a read-only guest session (browse only)" },
+      "url-only",
+      ...AUTH
+    ],
+    example: "xanosdk impersonate --guest"
+  },
+  // ── Account ─────────────────────────────────────────────────────────────
+  login: {
+    group: "Account",
+    display: "login",
+    summary: "OAuth sign-in \u2014 shared cache, or --local per project",
+    flags: [
+      "local",
+      "paste",
+      "port",
+      "scope",
+      "origin",
+      "config",
+      { key: "force", summary: "Overwrite the cached credential \u2014 sign in again even when one is already there" }
+    ],
+    example: "xanosdk login --local"
+  },
+  logout: {
+    group: "Account",
+    display: "logout",
+    summary: "Revoke the active profile and remove it from the credential file",
+    flags: ["all", "yes", "local", "config"],
+    example: "xanosdk logout --profile staging"
+  },
+  status: {
+    group: "Account",
+    display: "status",
+    summary: "Who am I, which workspace, and the env this project last deployed to",
+    flags: [...AUTH],
+    // Where a profile that is not stored is said: a typed one is a refusal, a
+    // pinned one is state the report carries (E2E pass 21 — documented, not changed).
+    notes: "A typed --profile that is not stored exits 8; one this project pins (xano.profile.json, $XANO_PROFILE) is reported as not signed in, exit 0.",
+    example: "xanosdk status --json  # \u2192 { signedIn, signIn, instance, profile, user, workspace, environment }"
+  },
+  whoami: {
+    group: "Account",
+    display: "whoami",
+    summary: "Show the signed-in user and instance URL",
+    flags: [...AUTH],
+    example: "xanosdk whoami"
+  },
+  // `whoami` is the canonical spelling for the QUESTION — it is the word every
+  // other CLI answers it under. `profile` is the noun that owns the stored
+  // credentials themselves, and its verbs manage them.
+  profile: {
+    group: "Account",
+    display: "profile <verb>",
+    summary: "Manage stored credential profiles",
+    subcommands: {
+      list: {
+        summary: "Every stored profile, with the default and the active one marked",
+        flags: [...CREDENTIAL_FILE],
+        example: "xanosdk profile list"
+      },
+      show: {
+        summary: "What one profile addresses \u2014 never its token (default: the active one)",
+        args: [{ name: "name", required: false }],
+        flags: [...CREDENTIAL_FILE],
+        example: "xanosdk profile show staging"
+      },
+      // `use` and `set-default` differ only in SCOPE and sit one keystroke
+      // apart, so each summary says which — the output does too.
+      use: {
+        summary: "Pin THIS PROJECT to a profile, in a committed xano.profile.json",
+        args: [{ name: "name", required: true }],
+        flags: [...CREDENTIAL_FILE],
+        example: "xanosdk profile use staging"
+      },
+      "set-default": {
+        summary: "Set the profile THIS MACHINE falls back to when nothing else selects one",
+        args: [{ name: "name", required: true }],
+        flags: [...CREDENTIAL_FILE],
+        example: "xanosdk profile set-default prod"
+      },
+      add: {
+        summary: "Store a meta API token credential under a name \u2014 the token is read from piped stdin or the terminal, and checked against the instance",
+        args: [{ name: "name", required: true }],
+        flags: [
+          { key: "instance", summary: "Instance URL the meta API token addresses" },
+          "workspace-id",
+          { key: "force", summary: "Replace a profile that already exists under this name" },
+          ...CREDENTIAL_FILE
+        ],
+        example: "xanosdk profile add ci --instance https://x8ki.xano.io --workspace-id 7"
+      },
+      delete: {
+        summary: "Remove a profile, revoking its sign-in session \u2014 a meta API token stays valid until revoked at its source",
+        args: [{ name: "name", required: true }],
+        flags: ["yes", ...CREDENTIAL_FILE],
+        example: "xanosdk profile delete staging --yes"
+      }
+    }
+  },
+  // ── Maintenance ─────────────────────────────────────────────────────────
+  lock: {
+    group: "Maintenance",
+    display: "lock",
+    summary: "Maintain xano.lock identities \u2014 rename, prune, import",
+    subcommands: {
+      rename: {
+        summary: "Move an entry keeping its identity, so the next export renames in place",
+        args: [
+          { name: "kind", required: true },
+          { name: "old", required: true },
+          { name: "new", required: true }
+        ],
+        flags: [
+          { key: "lock", summary: "Name the xano.lock to edit \u2014 default: beside --entry or the project entry" },
+          "entry"
+        ],
+        example: "xanosdk lock rename --entry=xano/index.ts table users members"
+      },
+      prune: {
+        summary: "Drop orphaned entries (all, or just the named keys)",
+        args: [
+          // `--entry=<path>` names the same file; with it, every positional is a key.
+          { name: "entry-file", required: true, path: true, satisfiedBy: ["identity-only", "entry"] },
+          { name: "keys\u2026", required: false, variadic: true }
+        ],
+        flags: [
+          "yes",
+          "lock",
+          { key: "entry", summary: "The entry file as a flag, in place of <entry-file> \u2014 every positional is then a key" },
+          {
+            key: "identity-only",
+            summary: "Prune the named keys without loading the entry file"
+          }
+        ],
+        example: "xanosdk lock prune ./index.ts --yes"
+      },
+      // `import`, not `adopt`: the verb names where the identities COME FROM,
+      // which is the only thing a reader needs in order to know whether this is
+      // the command they want. "Adopt" described the internal effect and left
+      // the input — a live export — entirely unstated.
+      import: {
+        summary: "Import identities from a live backend's exported bundle (`xanosdk workspace export`), so existing objects are not recreated",
+        args: [{ name: "bundle.json", required: true, path: true }],
+        flags: [
+          "yes",
+          { key: "lock", summary: "Name the xano.lock to write \u2014 default: beside --entry or the project entry" },
+          "entry"
+        ],
+        example: "xanosdk lock import ./live.json --entry=xano/index.ts"
+      }
+    }
+  },
+  completion: {
+    group: "Maintenance",
+    display: "completion <shell>",
+    summary: "Print a shell completion script (bash, zsh, fish)",
+    args: [{ name: "shell", required: true, values: ["bash", "zsh", "fish"] }],
+    example: 'xanosdk completion zsh > "${fpath[1]}/_xanosdk"'
+  },
+  version: {
+    group: "Maintenance",
+    display: "version",
+    summary: "Print the CLI version"
+  },
+  upgrade: {
+    group: "Maintenance",
+    display: "upgrade",
+    summary: "Install the latest @xano/sdk, or report an available upgrade with --check",
+    flags: ["check"],
+    example: "xanosdk upgrade --check"
+  },
+  help: {
+    group: "Maintenance",
+    display: "help",
+    summary: "Show this help",
+    // Variadic: a help target is a command PATH (`help workspace export`), and
+    // `resolveHelpRequest` reads it from the raw argv before any arity check.
+    args: [{ name: "command", required: false, variadic: true }],
+    example: "xanosdk help deploy"
+  }
+};
+function isCommand(name) {
+  return Object.hasOwn(COMMANDS, name);
+}
+function getCommand(name) {
+  return isCommand(name) ? COMMANDS[name] : void 0;
+}
+function acceptsFlag(command, subcommand, key) {
+  return flagRefFor(command, subcommand, key) !== void 0;
+}
+function flagRefFor(command, subcommand, key) {
+  if (command === void 0) return void 0;
+  const spec = subcommand === void 0 ? getCommand(command) : getSubcommand(command, subcommand);
+  return (spec?.flags ?? []).find((f) => flagKey(f) === key);
+}
+function getSubcommand(command, sub) {
+  const subs = getCommand(command)?.subcommands;
+  return subs && Object.hasOwn(subs, sub) ? subs[sub] : void 0;
+}
+function liveCommandNames() {
+  return Object.entries(COMMANDS).filter(([, spec]) => spec.aliasOf === void 0).map(([name]) => name);
+}
+function flagNames() {
+  return Object.keys(FLAGS);
+}
+function flagKey(ref) {
+  return typeof ref === "string" ? ref : ref.key;
+}
+function flagSpec(ref) {
+  if (typeof ref !== "string" && ref.spec !== void 0) return ref.spec;
+  return FLAGS[flagKey(ref)].spec;
+}
+function flagSummary(ref) {
+  if (typeof ref === "string") return FLAGS[ref].summary;
+  if (ref.selector !== void 0) return `${ref.summary}: ${sourceSpellings(ref.selector.accepted)}`;
+  return ref.summary;
+}
+function selectorValues(selector) {
+  return SELECTOR_BARE.filter((k) => selector.accepted.includes(k));
+}
+var SELECTOR_BARE = ["workspace", "ephemeral", "local-engine"];
+function argValues(arg) {
+  if (arg.values !== void 0) return arg.values;
+  return arg.selector !== void 0 ? selectorValues(arg.selector) : void 0;
+}
+function flagValues(ref) {
+  if (typeof ref !== "string" && ref.values !== void 0) return ref.values;
+  if (typeof ref !== "string" && ref.selector !== void 0) return selectorValues(ref.selector);
+  return FLAGS[flagKey(ref)]?.values;
+}
+function flagValuesClosed(ref) {
+  if (typeof ref !== "string" && ref.values !== void 0) return true;
+  if (typeof ref !== "string" && ref.selector !== void 0) return ref.selector.accepted.every((k) => k === "workspace");
+  return FLAGS[flagKey(ref)]?.open !== true;
+}
+function publishedFlagValues(ref) {
+  const values = flagValues(ref);
+  if (values === void 0 || values.length === 0) return {};
+  return flagValuesClosed(ref) ? { values: [...values] } : { examples: [...values] };
+}
+function liveSubcommandNames(command) {
+  const subs = getCommand(command)?.subcommands;
+  if (!subs) return [];
+  return Object.entries(subs).filter(([, spec]) => spec.unreleased === void 0).map(([name]) => name);
+}
+function visibleFlags(spec) {
+  const hidden = spec.unreleasedFlags;
+  if (!spec.flags || !hidden || hidden.length === 0) return spec.flags;
+  return spec.flags.filter((ref) => !hidden.includes(flagKey(ref)));
+}
+function selectorSpellings(command, subcommand) {
+  if (command === void 0) return [];
+  const spec = subcommand === void 0 ? getCommand(command) : getSubcommand(command, subcommand);
+  const flags = (spec?.flags ?? []).filter((f) => typeof f !== "string" && f.selector !== void 0).map((f) => `\`--${flagKey(f)}\``);
+  if (flags.length > 0) return flags;
+  const positional = (spec?.args ?? []).find((a) => a.selector !== void 0);
+  return positional === void 0 ? [] : [`its \`<${positional.name}>\` argument`];
+}
+function structuredFlag(ref) {
+  const m = /^(--[a-z][a-z-]*)(?:, (-[a-z]))?(.*)$/.exec(flagSpec(ref));
+  const name = m?.[1] ?? `--${flagKey(ref)}`;
+  const arg = (m?.[3] ?? "").trim();
+  return {
+    name,
+    ...m?.[2] === void 0 ? {} : { short: m[2] },
+    ...arg === "" ? {} : { arg },
+    ...publishedFlagValues(ref),
+    description: flagSummary(ref)
+  };
+}
+function helpDocument(request) {
+  const flags = (spec2) => (visibleFlags(spec2) ?? []).map((ref) => ({ flag: flagSpec(ref), summary: flagSummary(ref), ...structuredFlag(ref) }));
+  const spec = request.command === void 0 ? void 0 : getCommand(request.command);
+  if (spec === void 0 || request.command === void 0) {
+    return {
+      commands: liveCommandNames().map((name) => {
+        const c = getCommand(name);
+        return { name, usage: c.display, summary: c.summary, subcommands: liveSubcommandNames(name) };
+      })
+    };
+  }
+  const sub = request.subcommand === void 0 ? void 0 : getSubcommand(request.command, request.subcommand);
+  if (sub !== void 0) {
+    return {
+      command: request.command,
+      subcommand: request.subcommand,
+      summary: sub.summary,
+      flags: flags(sub),
+      ...sub.example === void 0 ? {} : { example: sub.example }
+    };
+  }
+  return {
+    command: request.command,
+    usage: spec.display,
+    summary: spec.summary,
+    flags: flags(spec),
+    subcommands: liveSubcommandNames(request.command).map((name) => ({ name, summary: spec.subcommands[name].summary })),
+    ...spec.example === void 0 ? {} : { example: spec.example }
+  };
+}
+
+export {
+  setRunNameContext,
+  checkOneName,
+  CUT_KINDS,
+  EXIT_SOURCE_UNRESOLVABLE,
+  BARE,
+  isKindShaped,
+  sourceSpellings,
+  parseSource,
+  verbBackendName,
+  isBackendHandle,
+  renderArgs,
+  HELP_GROUP_ORDER,
+  FLAGS,
+  GLOBAL_FLAGS,
+  isAuthenticatedCommand,
+  takesProfileFlag,
+  REFUSES_EMPTY_ENV,
+  REFUSES_EMPTY_DOC_TOKEN,
+  GUID_STABILITY_NOTE,
+  tablesCommand,
+  COMMANDS,
+  isCommand,
+  getCommand,
+  acceptsFlag,
+  flagRefFor,
+  getSubcommand,
+  liveCommandNames,
+  flagNames,
+  flagKey,
+  flagSpec,
+  flagSummary,
+  selectorValues,
+  argValues,
+  flagValues,
+  flagValuesClosed,
+  publishedFlagValues,
+  liveSubcommandNames,
+  visibleFlags,
+  selectorSpellings,
+  structuredFlag,
+  helpDocument,
+  relForwardSlash,
+  pathsShownFrom,
+  displayPath,
+  setTypedCwd,
+  pastePath,
+  projectFileCli,
+  spellProjectCli,
+  projectSdkDir,
+  spellProjectSdkDir,
+  installedCliAt,
+  cliPrefixAt,
+  withCliPrefix,
+  installCliPrefix,
+  isMachineOutput,
+  jsonWarning,
+  mergeJsonWarnings,
+  interruptedRunFinished,
+  writeJson,
+  interruptDocumentText,
+  interruptedRunWroteDocument,
+  interruptedRunDocumentExitCode,
+  noteRunWarning,
+  runWarnings,
+  noteRunAccepted,
+  runAccepted,
+  setRunFailureExplainer,
+  explainRunFailure,
+  inJsonDocumentScope,
+  installStdoutPipeGuard,
+  style,
+  stderrStyle,
+  stdoutStyle,
+  safeText,
+  quotedNames,
+  withoutUrls,
+  terminalText,
+  printHuman,
+  formatTableListing,
+  formatFields,
+  step,
+  success,
+  error,
+  warn,
+  info,
+  detail,
+  link,
+  blank,
+  elapsedSuffix,
+  spinner,
+  clearProgress,
+  withSpinner,
+  formatExpiration,
+  describeWriteTarget,
+  discloseWriteTarget,
+  credentialWriteTarget,
+  writeTargetPayload,
+  backendDestinationPayload,
+  hostLabel,
+  EXIT_OUTCOME_UNKNOWN,
+  registerOperation,
+  activeOperation,
+  renderGlobalHelp,
+  renderHelpFor,
+  indentBlock,
+  statesOutcomeUnknown,
+  UsageError,
+  LocalFileNotFoundError,
+  CliError,
+  isUsageError,
+  unknownCommand,
+  unknownHelpTopic,
+  unknownSubcommand,
+  suggestVerb,
+  unknownFlag,
+  flagName,
+  extraArguments,
+  envSetArgumentsRefused,
+  missingArgument,
+  reportFailure,
+  failureWritesDocument,
+  failureError,
+  failureCode,
+  exitCodeOf,
+  processExitCode,
+  movedVerb,
+  installCliDiagnosticSink
+};
+//# sourceMappingURL=chunk-PTHVMXZI.js.map