@xano/sdk 1.0.0

package/dist/chunk-XBKMWY7F.js

@@ -0,0 +1,612 @@
+import {
+  engineVersion,
+  engineVersionToken,
+  listEngines,
+  resolveRecordedEngine,
+  startEngine,
+  stopEngineNamed,
+  stopOrphanedEngineProcesses
+} from "./chunk-BAUZOWGX.js";
+import {
+  RELEASE_VERSION,
+  readEngineEntry,
+  stageEngine,
+  verifiedEngineExecutable
+} from "./chunk-6ELFRN3P.js";
+import {
+  sha256Hex
+} from "./chunk-NA3PXMEF.js";
+import {
+  normalizeEngineVersion,
+  resolveEngineRelease,
+  usesCustomReleaseManager
+} from "./chunk-APWXY5SL.js";
+import {
+  compareSemver,
+  parseSemver
+} from "./chunk-2TFRR6JV.js";
+import {
+  recordDeployed
+} from "./chunk-LPECSJ2J.js";
+import {
+  ImportHttpError
+} from "./chunk-AN6BL47T.js";
+import {
+  engineNameForProject,
+  getEngineRecord,
+  setEngineRecord
+} from "./chunk-3M4LFYNQ.js";
+import {
+  SUPPORTED_PLATFORMS,
+  assertLoopbackUrl,
+  expandArchivePath,
+  isTrustedEngineUrl,
+  resolveEnginePlatform
+} from "./chunk-AM4FKL4J.js";
+import {
+  registerSecret,
+  tokenTextProblem
+} from "./chunk-AWQ7BQTQ.js";
+import {
+  TransportError,
+  fetchOrExplain
+} from "./chunk-YLDALTWZ.js";
+import {
+  readEnvVar
+} from "./chunk-X2NL4KUO.js";
+import {
+  UsageError
+} from "./chunk-PTHVMXZI.js";
+
+// src/deploy/local-engine-release.ts
+import { readFileSync } from "fs";
+import { gunzipSync } from "zlib";
+var LOCAL_ENGINE_TOKEN_ENV = "XANOSDK_LOCAL_ENGINE_TOKEN";
+var MAX_ENGINE_BYTES = 256 * 1024 * 1024;
+var DOWNLOAD_TIMEOUT_MS = 6e5;
+var MAX_REDIRECTS = 5;
+function displayDownloadUrl(url) {
+  try {
+    const u = new URL(url);
+    return `${u.origin}${u.pathname}${u.search !== "" ? "?\u2026" : ""}`;
+  } catch {
+    return "the engine download URL";
+  }
+}
+var defaultFetch = (url, init) => fetchOrExplain(url, init, "The local engine download", DOWNLOAD_TIMEOUT_MS, displayDownloadUrl(url));
+function isRedirect(status) {
+  return status === 301 || status === 302 || status === 303 || status === 307 || status === 308;
+}
+async function fetchFollowingRedirects(url, opts) {
+  const origin = safeOrigin(url);
+  let current = url;
+  for (let hop = 0; hop <= MAX_REDIRECTS; hop++) {
+    const headers = { accept: "application/octet-stream" };
+    if (opts.token !== void 0 && safeOrigin(current) === origin) {
+      headers.Authorization = `Bearer ${opts.token}`;
+    }
+    const res = await opts.fetch(current, {
+      method: "GET",
+      headers,
+      // Manual, or `fetch` would follow the hop with the header still attached.
+      redirect: "manual",
+      signal: AbortSignal.timeout(DOWNLOAD_TIMEOUT_MS)
+    });
+    if (!isRedirect(res.status)) return res;
+    const location = res.headers.get("location");
+    if (location === null || location === "") return res;
+    current = new URL(location, current).href;
+  }
+  throw new Error(
+    `The engine download redirected more than ${MAX_REDIRECTS} times, so it was abandoned.
+` + (opts.release === void 0 ? `Check the URL passed to \`--local-engine\` addresses the artifact itself.` : `Re-run in a moment; if it keeps failing, engine ${opts.release}'s archive is unavailable \u2014 \`xanosdk local-engine update\` moves to another release.`)
+  );
+}
+function safeOrigin(url) {
+  try {
+    return new URL(url).origin;
+  } catch {
+    return url;
+  }
+}
+function releaseDownloadRefusal(status, version) {
+  return unresolvedOn5xx(
+    status,
+    new Error(
+      `The download of engine ${version} failed (HTTP ${status}), so nothing was written.
+Re-run in a moment; if it keeps failing, that release's archive is unavailable \u2014 \`xanosdk local-engine update\` moves to another release.`
+    )
+  );
+}
+function unresolvedOn5xx(status, err) {
+  if (status >= 500) Object.defineProperty(err, "exitCode", { value: EXIT_ENGINE_UNREACHABLE, enumerable: true });
+  return err;
+}
+function downloadRefusal(status, hasToken) {
+  if (status === 404) {
+    return new Error(
+      `The engine download found nothing at that URL (HTTP 404 Not Found).
+Check the URL passed to \`--local-engine\` addresses the artifact` + (hasToken ? ` and that ${LOCAL_ENGINE_TOKEN_ENV} can read it` : `; if it is a private release, which also answers 404 without a credential, set ${LOCAL_ENGINE_TOKEN_ENV} to one that can read it`) + `, then re-run.`
+    );
+  }
+  if (status === 401 || status === 403) {
+    return new Error(
+      `The engine download was refused (HTTP ${status}), which is what an engine release answers when the credential is missing or no longer authorized \u2014 not that the artifact is absent.
+Set ${LOCAL_ENGINE_TOKEN_ENV} to a credential that can read the release and re-run.`
+    );
+  }
+  if (status >= 500) {
+    return unresolvedOn5xx(
+      status,
+      new Error(
+        `The engine download failed (HTTP ${status}) \u2014 the server hosting it erred, so nothing was written.
+Re-run in a moment; if it keeps failing, check the URL passed to \`--local-engine\` is still served.`
+      )
+    );
+  }
+  return new Error(
+    `The engine download failed (HTTP ${status}).
+Check the URL passed to \`--local-engine\` still addresses the artifact` + (hasToken ? ` and that ${LOCAL_ENGINE_TOKEN_ENV} can read it` : ``) + `, then re-run.`
+  );
+}
+function artifactName(url) {
+  try {
+    const last = new URL(url).pathname.split("/").pop();
+    return last === void 0 || last === "" ? void 0 : decodeURIComponent(last);
+  } catch {
+    return void 0;
+  }
+}
+function checksumCandidates(url) {
+  try {
+    const sidecar = new URL(url);
+    sidecar.pathname = `${sidecar.pathname}.sha256`;
+    const siblings = new URL(url);
+    const parts = siblings.pathname.split("/");
+    parts[parts.length - 1] = "SHA256SUMS";
+    siblings.pathname = parts.join("/");
+    return [sidecar.href, siblings.href];
+  } catch {
+    return [];
+  }
+}
+function parsePublishedChecksum(text, name) {
+  const rows = [...text.matchAll(/^([0-9a-f]{64})[ \t]+[*]?(\S+)[ \t]*$/gm)].map((m) => ({
+    digest: m[1],
+    file: m[2].replace(/^\.\//, "").split("/").pop()
+  }));
+  if (rows.length === 0) {
+    const bare = /^[ \t]*([0-9a-f]{64})[ \t]*$/m.exec(text);
+    return bare?.[1];
+  }
+  if (name === void 0) return void 0;
+  const matched = rows.filter((r) => r.file === name);
+  return matched.length === 1 ? matched[0].digest : void 0;
+}
+async function publishedChecksum(url, opts) {
+  const name = artifactName(url);
+  for (const candidate of checksumCandidates(url)) {
+    try {
+      const res = await fetchFollowingRedirects(candidate, opts);
+      if (!res.ok) continue;
+      const digest = parsePublishedChecksum(await res.text(), name);
+      if (digest !== void 0) return digest;
+    } catch {
+    }
+  }
+  return void 0;
+}
+function octal(buf) {
+  const text = new TextDecoder().decode(buf).replace(/\0.*$/s, "").trim();
+  const n = Number.parseInt(text, 8);
+  return Number.isFinite(n) ? n : 0;
+}
+function headerName(block) {
+  return new TextDecoder().decode(block.subarray(0, 100)).replace(/\0.*$/s, "");
+}
+function headerChecksumOk(block) {
+  const stored = octal(block.subarray(148, 156));
+  let sum = 0;
+  for (let i = 0; i < 512; i++) sum += i >= 148 && i < 156 ? 32 : block[i];
+  return sum === stored;
+}
+var badArchive = (why, release) => new Error(
+  `The engine archive ${why}.
+It is not the artifact this expects, so nothing was written. ` + (release === void 0 ? `Check the URL or path passed to \`--local-engine\` addresses the engine archive itself \u2014 a partial download, a login page and a release listing all save as ordinary files.` : `Engine ${release}'s published archive is unusable; \`xanosdk local-engine update\` moves to another release.`)
+);
+function extractEngineExecutable(archive, opts = {}) {
+  const maxBytes = opts.maxBytes ?? MAX_ENGINE_BYTES;
+  const refuse = (why) => badArchive(why, opts.release);
+  let tar;
+  try {
+    tar = gunzipSync(archive, { maxOutputLength: maxBytes });
+  } catch (err) {
+    if (err.code === "ERR_BUFFER_TOO_LARGE") {
+      throw refuse(`decompresses to more than the ${maxBytes}-byte bound and is too large`);
+    }
+    throw refuse("is not a gzip archive");
+  }
+  const found = [];
+  for (let offset = 0; offset + 512 <= tar.length; ) {
+    const block = tar.subarray(offset, offset + 512);
+    if (block.every((b) => b === 0)) break;
+    if (!headerChecksumOk(block)) throw refuse("is not a tar archive");
+    const type = String.fromCharCode(block[156]);
+    if (type !== "0" && type !== "\0") {
+      throw refuse(`holds a ${type === "5" ? "directory" : "link"} where a regular file belongs`);
+    }
+    const mode = octal(block.subarray(100, 108));
+    if ((mode & 3584) !== 0) {
+      throw refuse("stores a setuid, setgid or sticky mode bit on its contents");
+    }
+    const name = headerName(block);
+    const prefix = new TextDecoder().decode(block.subarray(345, 500)).replace(/\0.*$/s, "");
+    if (name === "" || name.startsWith("/") || name.includes("/") || name.includes("\\") || prefix !== "") {
+      throw refuse(`holds a member whose name addresses a location ("${prefix}${name}")`);
+    }
+    const size = octal(block.subarray(124, 136));
+    const start = offset + 512;
+    if (start + size > tar.length) throw refuse("is truncated");
+    found.push(new Uint8Array(tar.subarray(start, start + size)));
+    if (found.length > 1) throw refuse("holds more than the one file it should");
+    offset = start + Math.ceil(size / 512) * 512;
+  }
+  const only = found[0];
+  if (only === void 0) throw refuse("holds no files, where it should hold one file");
+  return only;
+}
+function isDownloadUrl(source) {
+  return /^https?:\/\//i.test(source);
+}
+function resolveArchivePath(source, env) {
+  return expandArchivePath(source, env);
+}
+function readArchiveFile(path) {
+  try {
+    return new Uint8Array(readFileSync(path));
+  } catch {
+    throw new Error(
+      `There is no engine archive to read at ${path}.
+Check the path \u2014 it is read exactly as passed to \`--local-engine\`, with \`~\` and relative paths resolved from where the command ran.`
+    );
+  }
+}
+async function acquireEngine(opts) {
+  try {
+    return await acquireEngineUnclassified(opts);
+  } catch (err) {
+    let transport = false;
+    for (let e = err; e instanceof Error && !transport; e = e.cause) transport = e instanceof TransportError;
+    if (transport) Object.defineProperty(err, "exitCode", { value: EXIT_ENGINE_UNREACHABLE, enumerable: true });
+    if (opts.rerun !== void 0 && err instanceof Error) {
+      const named = namingRerun(err.message, opts.rerun);
+      err.message = named !== err.message && opts.rerunNote !== void 0 ? `${named}${opts.rerunNote}` : named;
+    }
+    throw err;
+  }
+}
+function namingRerun(message, command) {
+  return message.replace(/\bRe-run in a moment/g, `Run \`${command}\` again in a moment`).replace(/(,? then| and) re-run\./g, `$1 run \`${command}\` again.`);
+}
+var EXIT_ENGINE_UNREACHABLE = 8;
+async function acquireEngineUnclassified(opts) {
+  const env = opts.env ?? process.env;
+  const platform = resolveEnginePlatform(opts.platform ?? process.platform, opts.arch ?? process.arch);
+  if (platform === void 0) {
+    throw new Error(
+      `There is no local engine build for ${opts.platform ?? process.platform} ${opts.arch ?? process.arch} \u2014 it runs on ${SUPPORTED_PLATFORMS.join(", ")} and nothing else.
+Deploy from one of those machines, or drop \`--local-engine\`: \`xanosdk deploy\` reaches an ephemeral from anywhere.`
+    );
+  }
+  if (opts.spec.kind === "release") {
+    return acquireRelease(opts.spec.version, platform, env, opts.fetch);
+  }
+  const entry = await acquireOverride(opts.spec.source, env, opts.fetch ?? defaultFetch);
+  return { entry, version: void 0 };
+}
+async function acquireRelease(requested, platform, env, fetch) {
+  const pinned = requested === void 0 || requested === "latest" ? void 0 : normalizeEngineVersion(requested);
+  const cacheByVersion = !usesCustomReleaseManager(env);
+  if (pinned !== void 0 && cacheByVersion) {
+    const hit = readEngineEntry({ version: pinned }, env);
+    if (hit !== void 0) {
+      verifiedEngineExecutable(hit, env);
+      return { entry: hit, version: pinned };
+    }
+  }
+  let asset;
+  try {
+    asset = await resolveEngineRelease({
+      ...pinned === void 0 ? {} : { version: pinned },
+      platform,
+      env,
+      ...fetch === void 0 ? {} : { fetch }
+    });
+  } catch (err) {
+    const message = err.message;
+    if (pinned === void 0 || message.includes(pinned)) throw err;
+    const wrapped = new Error(
+      `Engine ${pinned} is not cached on this machine, and getting it needs one download:
+${message}`,
+      { cause: err }
+    );
+    const exitCode = err.exitCode;
+    if (typeof exitCode === "number") Object.defineProperty(wrapped, "exitCode", { value: exitCode, enumerable: true });
+    throw wrapped;
+  }
+  const cached = cacheByVersion ? readEngineEntry({ version: asset.version }, env) : void 0;
+  if (cached !== void 0) {
+    verifiedEngineExecutable(cached, env);
+    return { entry: cached, version: asset.version };
+  }
+  const res = await fetchFollowingRedirects(asset.downloadUrl, {
+    token: void 0,
+    fetch: fetch ?? defaultFetch,
+    release: asset.version
+  });
+  if (!res.ok) throw releaseDownloadRefusal(res.status, asset.version);
+  const archive = new Uint8Array(await res.arrayBuffer());
+  const archiveDigest = sha256Hex(archive);
+  if (archiveDigest !== asset.sha256) {
+    throw new Error(
+      `The engine ${asset.version} archive's sha256 disagrees with the one its release recorded, so nothing was written.
+Re-run to rule out a truncated download; if it disagrees again, the archive is not the one the release published and should not be run.`
+    );
+  }
+  const executable = extractEngineExecutable(archive, { release: asset.version });
+  const entry = stageEngine({
+    url: asset.downloadUrl,
+    ...cacheByVersion ? { version: asset.version } : {},
+    executable,
+    digest: sha256Hex(executable),
+    archiveDigest,
+    env
+  });
+  verifiedEngineExecutable(entry, env);
+  return { entry, version: asset.version };
+}
+async function acquireOverride(source, env, fetch) {
+  if (!isDownloadUrl(source)) {
+    const path = resolveArchivePath(source, env);
+    const archive2 = readArchiveFile(path);
+    const archiveDigest2 = sha256Hex(archive2);
+    const cached = readEngineEntry({ source: path }, env);
+    if (cached !== void 0 && cached.archiveDigest === archiveDigest2) {
+      verifiedEngineExecutable(cached, env);
+      return cached;
+    }
+    const executable2 = extractEngineExecutable(archive2);
+    const staged = stageEngine({
+      url: path,
+      executable: executable2,
+      digest: sha256Hex(executable2),
+      archiveDigest: archiveDigest2,
+      env
+    });
+    verifiedEngineExecutable(staged, env);
+    return staged;
+  }
+  const hit = readEngineEntry({ source }, env);
+  if (hit !== void 0) {
+    verifiedEngineExecutable(hit, env);
+    return hit;
+  }
+  const url = source;
+  if (!isTrustedEngineUrl(url)) {
+    throw new Error(
+      `The engine download URL is plain http on a host that is not this machine, so nothing was requested.
+Serve the archive over https://, or over http:// from loopback.`
+    );
+  }
+  const rawToken = readEnvVar(LOCAL_ENGINE_TOKEN_ENV, env);
+  registerSecret(rawToken);
+  const token = rawToken?.trim();
+  const problem = token === void 0 ? void 0 : tokenTextProblem(token);
+  if (problem !== void 0) {
+    throw new UsageError(
+      `\`${LOCAL_ENGINE_TOKEN_ENV}\` in the environment ${problem}, which no request can carry, so nothing was requested. Set it to the token alone \u2014 one line, nothing else.`
+    );
+  }
+  const res = await fetchFollowingRedirects(url, { token, fetch });
+  if (!res.ok) throw downloadRefusal(res.status, token !== void 0);
+  const archive = new Uint8Array(await res.arrayBuffer());
+  const archiveDigest = sha256Hex(archive);
+  const published = await publishedChecksum(url, { token, fetch });
+  if (published !== void 0 && published !== archiveDigest) {
+    throw new Error(
+      `The engine archive's bytes disagree with the checksum published beside it, so nothing was written.
+Re-run to rule out a truncated download; if it disagrees again, the artifact is not the one the release recorded and should not be run.`
+    );
+  }
+  const executable = extractEngineExecutable(archive);
+  const entry = stageEngine({
+    url,
+    executable,
+    digest: sha256Hex(executable),
+    archiveDigest,
+    env
+  });
+  verifiedEngineExecutable(entry, env);
+  return entry;
+}
+
+// src/deploy/local-engine-deploy.ts
+async function ensureProjectEngine(opts) {
+  try {
+    return await ensureProjectEngineUnnoted(opts);
+  } catch (err) {
+    throw withDeployFallbackNote(err);
+  }
+}
+var DEPLOY_FALLBACK_NOTE = "Meanwhile `xanosdk deploy` still deploys to an ephemeral.";
+function withDeployFallbackNote(err) {
+  if (!(err instanceof Error) || err.message.includes(DEPLOY_FALLBACK_NOTE)) return err;
+  err.message = `${err.message.trimEnd()}
+${DEPLOY_FALLBACK_NOTE}`;
+  return err;
+}
+async function ensureProjectEngineUnnoted(opts) {
+  const env = opts.env ?? process.env;
+  const acquired = await acquireEngine({
+    spec: opts.source,
+    env,
+    ...opts.rerun === void 0 ? {} : { rerun: opts.rerun },
+    ...opts.rerunNote === void 0 || opts.rerunNote === "" ? {} : { rerunNote: opts.rerunNote },
+    ...opts.fetch === void 0 ? {} : { fetch: opts.fetch }
+  });
+  const { entry, version } = acquired;
+  opts.onAcquired?.(acquired);
+  const shownVersion = version ?? overrideVersion(entry, env, opts.run);
+  const { record, name, live, replaced } = reconcileLive(opts.dir, entry, shownVersion, env, opts.run);
+  const sweep = opts.sweepOrphans ?? (opts.spawn === void 0 ? () => stopOrphanedEngineProcesses({ env }).stopped : void 0);
+  const sweptOrphans = live === void 0 && sweep !== void 0 ? sweep() : [];
+  const engine = live ?? await startEngine({
+    entry,
+    name,
+    env,
+    ...shownVersion === void 0 ? {} : { version: shownVersion },
+    ...opts.spawn === void 0 ? {} : { spawn: opts.spawn }
+  });
+  const reused = live !== void 0;
+  const hadRecord = record !== void 0;
+  const priorFilled = record?.filled;
+  const carry = opts.carryFilled?.({ reused, hadRecord, priorFilled, url: engine.url }) === true;
+  writeRecord(opts.dir, engine, entry, shownVersion, reused && carry ? priorFilled : void 0, env);
+  if (!reused) recordDeployed(opts.dir, "local-engine");
+  return {
+    engine,
+    reused,
+    previousUrl: record?.url,
+    entry,
+    version,
+    engineVersion: shownVersion,
+    ...replaced === void 0 ? {} : { replaced },
+    ...sweptOrphans.length === 0 ? {} : { sweptOrphans },
+    hadRecord,
+    priorFilled
+  };
+}
+async function restartMismatchedEngine(opts) {
+  const env = opts.env ?? process.env;
+  const { entry, version } = opts.acquired;
+  const shownVersion = version ?? overrideVersion(entry, env, opts.run);
+  const { record, name, replaced } = reconcileLive(opts.dir, entry, shownVersion, env, opts.run);
+  if (replaced === void 0) return void 0;
+  const engine = await startEngine({
+    entry,
+    name,
+    env,
+    ...shownVersion === void 0 ? {} : { version: shownVersion },
+    ...opts.spawn === void 0 ? {} : { spawn: opts.spawn }
+  });
+  writeRecord(opts.dir, engine, entry, shownVersion, void 0, env);
+  return { ...replaced, url: engine.url, previousUrl: record?.url };
+}
+function reconcileLive(dir, entry, shownVersion, env, run) {
+  const record = getEngineRecord(dir, env);
+  const name = record?.name ?? engineNameForProject(dir);
+  const running = listEngines({ entry, env, ...run === void 0 ? {} : { run } });
+  const found = reuseCandidate(name, record, running);
+  if (found === void 0 || record?.engineDigest === entry.digest) return { record, name, live: found };
+  stopMismatched(found.name, record, entry, env, run);
+  return { record, name, live: void 0, replaced: { name: found.name, from: record?.engineVersion, to: shownVersion } };
+}
+function writeRecord(dir, engine, entry, shownVersion, filled, env) {
+  setEngineRecord(
+    dir,
+    {
+      name: engine.name,
+      url: engine.url,
+      workspaceId: engine.workspaceId,
+      project: dir,
+      engineUrl: entry.url,
+      engineDigest: entry.digest,
+      ...shownVersion === void 0 ? {} : { engineVersion: shownVersion },
+      startedAt: Date.now(),
+      ...filled === void 0 ? {} : { filled }
+    },
+    env
+  );
+}
+function overrideVersion(entry, env, run) {
+  let out;
+  try {
+    out = engineVersion({ entry, env, ...run === void 0 ? {} : { run } });
+  } catch {
+    return void 0;
+  }
+  return engineVersionToken(out);
+}
+function stopMismatched(name, record, entry, env, run) {
+  const seam = run === void 0 ? {} : { run };
+  const attempt = (binary) => {
+    try {
+      return stopEngineNamed(name, { entry: binary, env, ...seam }).stopped;
+    } catch {
+      return false;
+    }
+  };
+  if (attempt(entry)) return;
+  const previous = recordedBinary(record, env);
+  if (previous !== void 0 && previous.digest !== entry.digest && attempt(previous)) return;
+  throw new Error(
+    `The local engine "${name}" already serving this project is not the engine this deploy resolved to, and it could not be stopped` + (previous === void 0 ? `` : ` by either engine version`) + `.
+Stop it with \`xanosdk local-engine stop ${name}\` (or end the process), then deploy again.`
+  );
+}
+function recordedBinary(record, env) {
+  const version = record?.engineVersion;
+  if (version === void 0 || !RELEASE_VERSION.test(version)) return void 0;
+  try {
+    return readEngineEntry({ version }, env);
+  } catch {
+    return void 0;
+  }
+}
+function reuseCandidate(name, record, running) {
+  if (record !== void 0) {
+    const resolved = resolveRecordedEngine(record, running);
+    if (resolved.state === "unusable") throw new Error(resolved.reason);
+    return resolved.state === "live" ? resolved.engine : void 0;
+  }
+  const engine = running.find((e) => e.name === name);
+  if (engine === void 0) return void 0;
+  assertLoopbackUrl(engine.url, "The engine already serving this project");
+  return engine;
+}
+function explainUnsupportedEngineImport(err, engineVersion2, ctx = {}) {
+  if (!(err instanceof ImportHttpError) || err.status !== 501) return void 0;
+  const which = engineVersion2 === void 0 ? "The local engine" : `Local engine ${engineVersion2}`;
+  const newer = newerRelease(engineVersion2, ctx.latest);
+  if (newer !== void 0) {
+    return new Error(
+      `${which} does not support this import (HTTP 501): it is older than this SDK needs. Nothing was written. Deploy with ${newer} \u2014 \`xanosdk local-engine update\` moves this project's pin to it, or pass \`--local-engine=${newer}\` for one deploy.`,
+      { cause: err }
+    );
+  }
+  if (ctx.resetRerun !== void 0) {
+    return new Error(
+      `${which} cannot apply this merge (HTTP 501): keeping the rows through this schema change is not available on the local engine yet. Nothing was written. Deploy with \`${ctx.resetRerun}\` instead \u2014 it replaces the workspace and writes every table's seed rows, so rows entered since the last deploy are lost.`,
+      { cause: err }
+    );
+  }
+  return new Error(
+    `${which} does not support this import (HTTP 501). Nothing was written. \`xanosdk deploy\` deploys to an ephemeral meanwhile.`,
+    { cause: err }
+  );
+}
+function newerRelease(current, latest) {
+  if (current === void 0 || latest === void 0) return void 0;
+  const a = parseSemver(current);
+  const b = parseSemver(latest);
+  return a !== null && b !== null && compareSemver(b, a) > 0 ? latest : void 0;
+}
+
+export {
+  acquireEngine,
+  ensureProjectEngine,
+  DEPLOY_FALLBACK_NOTE,
+  restartMismatchedEngine,
+  explainUnsupportedEngineImport
+};
+//# sourceMappingURL=chunk-XBKMWY7F.js.map

package/dist/chunk-XNCP4KYO.js

@@ -0,0 +1,78 @@
+// src/fields/hosted-file.ts
+var HOSTED_FILE = /* @__PURE__ */ Symbol.for("xanosdk.hosted.file");
+function hostedFile(path, base, opts = {}) {
+  return {
+    [HOSTED_FILE]: { path, base: typeof base === "string" ? base : base.href, access: opts.access ?? "public" }
+  };
+}
+function isHostedFile(value) {
+  return typeof value === "object" && value !== null && HOSTED_FILE in value;
+}
+var HOSTED_FILE_SCHEME = "xanosdk-file://";
+function isPrivateLibraryRow(row) {
+  return !(typeof row === "object" && row !== null && row.access === "public");
+}
+var HOSTED_ICON_KINDS = ["tool", "prompt", "resource"];
+function hostedIconOwners(payload) {
+  const out = [];
+  for (const kind of HOSTED_ICON_KINDS) {
+    const rows = payload[kind];
+    if (!Array.isArray(rows)) continue;
+    for (const row of rows) {
+      const icons = row !== null && typeof row === "object" && Array.isArray(row.icons) ? row.icons : [];
+      const hosted = icons.some(
+        (icon) => typeof icon === "object" && icon !== null && String(icon.src).startsWith(HOSTED_FILE_SCHEME)
+      );
+      if (hosted) out.push(`${kind} "${String(row.name ?? "")}"`);
+    }
+  }
+  return out;
+}
+function uncarriedHostedIcons(payload, carried) {
+  const out = [];
+  for (const kind of HOSTED_ICON_KINDS) {
+    const rows = payload[kind];
+    if (!Array.isArray(rows)) continue;
+    for (const row of rows) {
+      const icons = row !== null && typeof row === "object" && Array.isArray(row.icons) ? row.icons : [];
+      icons.forEach((icon, index) => {
+        const src = typeof icon === "object" && icon !== null ? icon.src : void 0;
+        if (typeof src !== "string" || !src.startsWith(HOSTED_FILE_SCHEME)) return;
+        const [canonical = "", file = ""] = src.slice(HOSTED_FILE_SCHEME.length).split("/");
+        if (carried.has(canonical)) return;
+        let name = file;
+        try {
+          name = decodeURIComponent(file);
+        } catch {
+        }
+        out.push({ owner: `${kind} "${String(row.name ?? "")}"`, index, src, name });
+      });
+    }
+  }
+  return out;
+}
+var HOSTED_ROW_PATH_PREFIX = "/vault/_/";
+var pending = /* @__PURE__ */ new WeakMap();
+function pendingHostedSrc(holder, ref, rules) {
+  pending.set(holder, { ref, rules });
+  const name = ref[HOSTED_FILE].path.split(/[\\/]/).pop() ?? "";
+  return `${HOSTED_FILE_SCHEME}pending/${encodeURIComponent(name)}`;
+}
+function pendingHostedFile(holder) {
+  return pending.get(holder);
+}
+
+export {
+  HOSTED_FILE,
+  hostedFile,
+  isHostedFile,
+  HOSTED_FILE_SCHEME,
+  isPrivateLibraryRow,
+  HOSTED_ICON_KINDS,
+  hostedIconOwners,
+  uncarriedHostedIcons,
+  HOSTED_ROW_PATH_PREFIX,
+  pendingHostedSrc,
+  pendingHostedFile
+};
+//# sourceMappingURL=chunk-XNCP4KYO.js.map