@xanots/sdk 0.0.3 → 0.0.4

package/dist/{test-command-72Y5S22H.js → test-command-U4G5Y3UM.js}

@@ -1,9 +1,13 @@
 import {
   resolveMetaTarget
-} from "./chunk-BT2CSEC5.js";
+} from "./chunk-VWGJQTNA.js";
 import "./chunk-DGSF2Q5H.js";
-import "./chunk-7DKX2SPN.js";
+import "./chunk-ACQCK4DT.js";
 import "./chunk-NDZFBZHC.js";
+import {
+  getAccessToken
+} from "./chunk-C56BC2FY.js";
+import "./chunk-7REDODS2.js";
 import {
   isMachineOutput,
   writeJson
@@ -13,13 +17,10 @@ import {
   httpFailure,
   serverMessage
 } from "./chunk-3IGNIP6R.js";
-import {
-  getAccessToken
-} from "./chunk-C56BC2FY.js";
-import "./chunk-7REDODS2.js";
 import {
   unknownSubcommand
-} from "./chunk-6USV65XA.js";
+} from "./chunk-KGNJM4LN.js";
+import "./chunk-GNPVYOPB.js";
 import {
   blank,
   detail,
@@ -28,8 +29,7 @@ import {
   success,
   warn
 } from "./chunk-EZG76F7R.js";
-import "./chunk-GNPVYOPB.js";
-import "./chunk-DYCLVQXW.js";
+import "./chunk-YYSJAAJM.js";
 
 // src/deploy/tests.ts
 var TIMEOUT_MS = 12e4;
@@ -380,4 +380,4 @@ export {
   runSuite,
   runTestCommand
 };
-//# sourceMappingURL=test-command-72Y5S22H.js.map
+//# sourceMappingURL=test-command-U4G5Y3UM.js.map

package/dist/upgrade-command-CKJ4BS2P.js

@@ -0,0 +1,177 @@
+import {
+  assertProjectDir
+} from "./chunk-ERQZFWIW.js";
+import {
+  isMachineOutput,
+  writeJson
+} from "./chunk-NUQCEOKA.js";
+import {
+  refreshAgentFiles
+} from "./chunk-D6OGU2AI.js";
+import "./chunk-7SISR3CS.js";
+import {
+  runNpm
+} from "./chunk-ZSYZTGJH.js";
+import {
+  sdkDep
+} from "./chunk-QUUB7HYK.js";
+import "./chunk-6DHJVLYP.js";
+import {
+  checkForUpgrade,
+  detectInstallMode,
+  registryUrl,
+  suppressUpdateNotice,
+  upgradeCommand
+} from "./chunk-T6N3VMMO.js";
+import "./chunk-DUC3PXDG.js";
+import "./chunk-KGNJM4LN.js";
+import "./chunk-MFIHIS6B.js";
+import "./chunk-GNPVYOPB.js";
+import {
+  blank,
+  detail,
+  step,
+  style,
+  success,
+  warn
+} from "./chunk-EZG76F7R.js";
+import "./chunk-BPEEGJJA.js";
+import "./chunk-YYSJAAJM.js";
+import "./chunk-YUPQOLFX.js";
+import "./chunk-WHOJWOSV.js";
+import "./chunk-5XZ744TS.js";
+import "./chunk-YUBJLB6G.js";
+
+// src/emit/upgrade-command.ts
+import { readFileSync, writeFileSync } from "fs";
+import { createRequire } from "module";
+import { join } from "path";
+var EXIT_UPGRADE_AVAILABLE = 7;
+var PACKAGE = "@xanots/sdk";
+async function runUpgradeCommand(args) {
+  suppressUpdateNotice();
+  const mode = detectInstallMode();
+  const dir = process.cwd();
+  const installed = mode === "local" ? projectSdkVersion(dir) : void 0;
+  const result = await checkForUpgrade(installed === void 0 ? void 0 : { current: installed });
+  if (result.status === "unknown") throw new Error(explainUnknown(result.reason));
+  if (result.status === "current") {
+    if (isMachineOutput(args)) {
+      writeJson({ status: "current", current: result.current, latest: result.latest, installMode: mode });
+    } else {
+      success(`@xanots/sdk ${style.bold(result.current)} is the latest published version.`);
+    }
+    return;
+  }
+  if (args.check) {
+    if (isMachineOutput(args)) {
+      writeJson({
+        status: "available",
+        current: result.current,
+        latest: result.latest,
+        installMode: mode,
+        command: suggestedCommand(dir, mode)
+      });
+    } else {
+      warn(
+        `A new @xanots/sdk is available: ${style.dim(result.current)} \u2192 ${style.green(result.latest)}`
+      );
+      detail(`run \`xanots upgrade\`, or: ${suggestedCommand(dir, mode)}`);
+    }
+    process.exitCode = EXIT_UPGRADE_AVAILABLE;
+    return;
+  }
+  await applyUpgrade(args, dir, result.current, result.latest, mode);
+}
+function suggestedCommand(dir, mode) {
+  return mode === "global" ? upgradeCommand("global") : `npm i ${saveFlagFor(dir)} ${PACKAGE}@latest`;
+}
+function explainUnknown(reason) {
+  return reason === "registry" ? `xanots upgrade: could not reach the npm registry at ${registryUrl()}.
+  Check your connection, or point XANOTS_UPDATE_REGISTRY at a reachable mirror.` : `xanots upgrade: could not resolve the installed @xanots/sdk version, so there is nothing to compare against.
+  This is expected for a git build or a linked checkout \u2014 upgrade with npm directly.`;
+}
+async function applyUpgrade(args, dir, current, latest, mode) {
+  if (mode === "local") {
+    assertProjectDir(dir, {
+      what: "`xanots upgrade` installs into a XanoTS project",
+      remedy: "cd into your project first, or set XANOTS_INSTALL_MODE=global to upgrade the global CLI."
+    });
+  }
+  step(`Upgrading ${style.bold(PACKAGE)} ${style.dim(current)} \u2192 ${style.green(latest)}`);
+  const flag = mode === "global" ? "-g" : saveFlagFor(dir);
+  const status = runNpm(["i", flag, `${PACKAGE}@latest`], dir, { stdout: "stderr" });
+  if (status !== 0) {
+    throw new Error(`npm i ${flag} ${PACKAGE}@latest failed (exit ${status}).`);
+  }
+  const reconciled = mode === "local" ? reconcileProject(dir, latest) : [];
+  if (isMachineOutput(args)) {
+    writeJson({ status: "upgraded", current, latest, installMode: mode, reconciled });
+  } else {
+    blank();
+    success(`Upgraded to @xanots/sdk ${style.bold(latest)}.`);
+    for (const path of reconciled) detail(`reconciled ${path}`);
+  }
+}
+function reconcileProject(dir, version) {
+  const changed = [];
+  try {
+    if (restoreSdkRange(dir, version)) changed.push("package.json");
+  } catch (err) {
+    warn(`Could not restore the ${PACKAGE} range in package.json: ${messageOf(err)}`);
+  }
+  try {
+    changed.push(...refreshAgentFiles({ projectDir: dir, sdkVersion: version, explicit: true }));
+  } catch (err) {
+    warn(`Could not refresh the agent guidance blocks: ${messageOf(err)}`);
+  }
+  return changed;
+}
+function restoreSdkRange(dir, version) {
+  const manifest = join(dir, "package.json");
+  const raw = readFileSync(manifest, "utf8");
+  const pkg = JSON.parse(raw);
+  const block = sdkBlock(pkg);
+  if (block === void 0) return false;
+  const deps = pkg[block];
+  const want = sdkDep(version);
+  if (deps[PACKAGE] === want) return false;
+  deps[PACKAGE] = want;
+  writeFileSync(manifest, JSON.stringify(pkg, null, indentOf(raw)) + (raw.endsWith("\n") ? "\n" : ""));
+  return true;
+}
+function sdkBlock(pkg) {
+  return ["devDependencies", "dependencies"].find((key) => {
+    const deps = pkg[key];
+    return typeof deps === "object" && deps !== null && PACKAGE in deps;
+  });
+}
+function saveFlagFor(dir) {
+  try {
+    const pkg = JSON.parse(readFileSync(join(dir, "package.json"), "utf8"));
+    return sdkBlock(pkg) === "dependencies" ? "--save-prod" : "--save-dev";
+  } catch {
+    return "--save-dev";
+  }
+}
+function indentOf(raw) {
+  return /^(\t+)"/m.exec(raw)?.[1] ?? /^( +)"/m.exec(raw)?.[1]?.length ?? 2;
+}
+function projectSdkVersion(dir) {
+  try {
+    const requireFromDir = createRequire(join(dir, "package.json"));
+    const pkg = JSON.parse(
+      readFileSync(requireFromDir.resolve(`${PACKAGE}/package.json`), "utf8")
+    );
+    return typeof pkg.version === "string" ? pkg.version : void 0;
+  } catch {
+    return void 0;
+  }
+}
+function messageOf(err) {
+  return err instanceof Error ? err.message : String(err);
+}
+export {
+  runUpgradeCommand
+};
+//# sourceMappingURL=upgrade-command-CKJ4BS2P.js.map

package/dist/{validate-command-KDGH537H.js → validate-command-S5N37JRP.js}

@@ -1,10 +1,11 @@
 import {
   assertBundleInput,
   loadBundleText
-} from "./chunk-W2G2WPTB.js";
-import "./chunk-3NFUWXOC.js";
-import "./chunk-6USV65XA.js";
-import "./chunk-HJPTWBLH.js";
+} from "./chunk-SWIXWJIY.js";
+import "./chunk-DUC3PXDG.js";
+import "./chunk-KGNJM4LN.js";
+import "./chunk-MFIHIS6B.js";
+import "./chunk-GNPVYOPB.js";
 import {
   blank,
   detail,
@@ -13,13 +14,12 @@ import {
   success,
   warn
 } from "./chunk-EZG76F7R.js";
-import "./chunk-GNPVYOPB.js";
-import "./chunk-55VHDNW5.js";
-import "./chunk-DYCLVQXW.js";
-import "./chunk-5L4X5LS6.js";
+import "./chunk-BPEEGJJA.js";
+import "./chunk-YYSJAAJM.js";
+import "./chunk-YUPQOLFX.js";
 import "./chunk-WHOJWOSV.js";
 import "./chunk-5XZ744TS.js";
-import "./chunk-4HT3BNZ7.js";
+import "./chunk-YUBJLB6G.js";
 
 // src/emit/validate-command.ts
 var EXIT_VALIDATION_FAILED = 2;
@@ -44,7 +44,7 @@ async function runValidateCommand(args) {
   }
 }
 async function validateWithClient(args, client, bundle) {
-  const { runValidateLoop, runnableFunctionNames } = await import("./loop-SAWAOUFO.js");
+  const { runValidateLoop, runnableFunctionNames } = await import("./loop-7SAIGRCZ.js");
   const result = await runValidateLoop(client, bundle);
   if (!result.accepted) {
     warn("Import rejected by the engine:");
@@ -95,7 +95,7 @@ async function validateWithClient(args, client, bundle) {
     }
   }
   if (args.capture) {
-    const { captureFixtures } = await import("./capture-HUV5BNTC.js");
+    const { captureFixtures } = await import("./capture-7PO6SGB4.js");
     const written = captureFixtures(result.roundTrip, args.out);
     if (written.length === 0) warn("nothing to capture (no objects round-tripped)");
     for (const w of written) detail(`captured ${w.name} \u2192 ${w.path}`);
@@ -119,4 +119,4 @@ function fmt(v) {
 export {
   runValidateCommand
 };
-//# sourceMappingURL=validate-command-KDGH537H.js.map
+//# sourceMappingURL=validate-command-S5N37JRP.js.map

package/dist/{workspace-command-ICSI6PKO.js → workspace-command-RALSEJSW.js}

@@ -1,60 +1,61 @@
 import {
   fetchWorkspaceBundle,
   runCodegenCommand
-} from "./chunk-2V4YE6QC.js";
-import "./chunk-P3TTMWUP.js";
+} from "./chunk-VKD3EBKG.js";
+import "./chunk-ZOYMZZ3S.js";
 import {
   resolveOutputTarget
-} from "./chunk-XQ22GLYS.js";
-import "./chunk-QTNO2WD6.js";
-import "./chunk-ZUTSMMAG.js";
-import "./chunk-7DKX2SPN.js";
+} from "./chunk-AJ7JQ4OU.js";
+import "./chunk-ACQCK4DT.js";
 import {
   printMicroserviceSection,
   readMicroservices
 } from "./chunk-NDZFBZHC.js";
+import {
+  ENV_WORKSPACE,
+  getAccessToken
+} from "./chunk-C56BC2FY.js";
+import "./chunk-7REDODS2.js";
+import "./chunk-QTNO2WD6.js";
+import "./chunk-ZUTSMMAG.js";
+import "./chunk-X4DVXBFY.js";
+import "./chunk-EAIR6VUL.js";
 import {
   isMachineOutput,
   writeJson
 } from "./chunk-NUQCEOKA.js";
-import "./chunk-HQ2CBRVI.js";
-import "./chunk-CMZLPTGW.js";
-import "./chunk-WUSKBXXD.js";
+import "./chunk-7SISR3CS.js";
+import "./chunk-ZSYZTGJH.js";
 import {
   fetchOrExplain,
   httpFailure
 } from "./chunk-3IGNIP6R.js";
-import {
-  ENV_WORKSPACE,
-  getAccessToken
-} from "./chunk-C56BC2FY.js";
-import "./chunk-7REDODS2.js";
-import "./chunk-X4DVXBFY.js";
-import "./chunk-F6JCFRKO.js";
+import "./chunk-PXXLBXOP.js";
 import "./chunk-LU7TRWMC.js";
-import "./chunk-YZ4GU6F5.js";
+import "./chunk-WGDAOOXG.js";
+import "./chunk-QUUB7HYK.js";
 import "./chunk-6DHJVLYP.js";
 import "./chunk-4BXJGVZ3.js";
-import "./chunk-U3G2UW65.js";
-import "./chunk-3NFUWXOC.js";
+import "./chunk-CYJ7R3AD.js";
+import "./chunk-DUC3PXDG.js";
 import {
   removedSubcommand,
   unknownSubcommand
-} from "./chunk-6USV65XA.js";
-import "./chunk-HJPTWBLH.js";
+} from "./chunk-KGNJM4LN.js";
+import "./chunk-MFIHIS6B.js";
+import "./chunk-GNPVYOPB.js";
 import {
   formatFields,
   stdoutStyle,
   step,
   success
 } from "./chunk-EZG76F7R.js";
-import "./chunk-GNPVYOPB.js";
-import "./chunk-55VHDNW5.js";
-import "./chunk-DYCLVQXW.js";
-import "./chunk-5L4X5LS6.js";
+import "./chunk-BPEEGJJA.js";
+import "./chunk-YYSJAAJM.js";
+import "./chunk-YUPQOLFX.js";
 import "./chunk-WHOJWOSV.js";
 import "./chunk-5XZ744TS.js";
-import "./chunk-4HT3BNZ7.js";
+import "./chunk-YUBJLB6G.js";
 
 // src/emit/workspace-command.ts
 import { writeFileSync } from "fs";
@@ -155,4 +156,4 @@ async function runExport(args) {
 export {
   runWorkspaceCommand
 };
-//# sourceMappingURL=workspace-command-ICSI6PKO.js.map
+//# sourceMappingURL=workspace-command-RALSEJSW.js.map

package/dist/workspace-export-AJMGN3CQ.js

@@ -2,8 +2,8 @@ import {
   exportWorkspaceBundle
 } from "./chunk-QTNO2WD6.js";
 import "./chunk-ZUTSMMAG.js";
-import "./chunk-3IGNIP6R.js";
 import "./chunk-X4DVXBFY.js";
+import "./chunk-3IGNIP6R.js";
 export {
   exportWorkspaceBundle
 };

package/guides/README.md

@@ -0,0 +1,30 @@
+# XanoTS guides
+
+The written reference for people. Every kind, statement, filter, and field type is also
+typed, so your editor's autocomplete is usually the faster lookup — tab-complete `s.`,
+`f.`, `c.`, `fl.`, `input.`.
+
+| Guide | What's in it |
+|---|---|
+| [The scaffolded project](scaffold.md) | What `xanots init` writes, the two frontend presets, add-ons, SvelteKit rules |
+| [Project structure](project-structure.md) | How a `xano/` project is laid out, and why registration is explicit |
+| [Object kinds](object-kinds.md) | Every authorable kind, and splitting a workspace across microservices |
+| [Authoring reference](authoring.md) | Tables and fields, statements, values, inputs, middleware, request history |
+| [CLI](cli.md) | Every command, shell completion, and what failures look like |
+| [Signing in & deploying](deploying.md) | Auth, ephemerals, `--static`, releasing to production, `xanots validate` |
+| [Environment & identity](environment.md) | Every environment variable, and how `xano.lock` pins identity |
+| [The typed frontend surface](typed-frontend.md) | Path resolution, input/response inference, bundle cost, the route manifest |
+| [Pulling an existing workspace](codegen.md) | What `xanots codegen` writes, how faithful it is, and how to read its report |
+| [Coverage & agent grounding](coverage.md) | What's covered, what's out of scope, and the files agents read |
+
+## The agent-facing surface
+
+These guides are for humans. Agents read a different set, generated from the SDK's own
+sources so it cannot drift from what the code does:
+
+- **`llms.txt`** — a small always-read router: the mental model, the deploy contract, and
+  every gotcha, ending in a map of the topic files.
+- **`llms/*.md`** — one file per surface, opened only when that surface is in play.
+- **`manifest.json`** — the exhaustive per-entry catalog, reached by targeted lookup.
+
+See [Coverage & agent grounding](coverage.md) for what each one carries.