@xanots/sdk 0.0.3-beta.0 → 0.0.4

package/dist/{chunk-U3G2UW65.js → chunk-CYJ7R3AD.js}

@@ -35,7 +35,7 @@ import {
   registerKind,
   tableColumns,
   withFilters
-} from "./chunk-5L4X5LS6.js";
+} from "./chunk-YUPQOLFX.js";
 import {
   assertPathParamInputs,
   fillPathParams,
@@ -51,7 +51,7 @@ import {
   deriveGuid,
   realtimeChannelSeedName,
   resolveRef
-} from "./chunk-4HT3BNZ7.js";
+} from "./chunk-YUBJLB6G.js";
 
 // src/statements/set-var.ts
 var SET_VAR = "mvp:set_var";
@@ -3721,4 +3721,4 @@ export {
   workspaceKind,
   workspaceConfig
 };
-//# sourceMappingURL=chunk-U3G2UW65.js.map
+//# sourceMappingURL=chunk-CYJ7R3AD.js.map

package/dist/{agent-file-refresh-J3KY54E5.js → chunk-D6OGU2AI.js}

@@ -5,9 +5,7 @@ import {
   presetFilePath,
   renderPreset,
   upsertManagedBlock
-} from "./chunk-WRYT2PAX.js";
-import "./chunk-47WDWMBJ.js";
-import "./chunk-6DHJVLYP.js";
+} from "./chunk-7SISR3CS.js";
 import {
   warn
 } from "./chunk-EZG76F7R.js";
@@ -50,7 +48,7 @@ function appNameFor(projectDir) {
 }
 function refreshAgentFiles(opts) {
   const env = opts.env ?? process.env;
-  if (isCI(env) || !codingAgentDetected(env)) return [];
+  if (opts.explicit !== true && (isCI(env) || !codingAgentDetected(env))) return [];
   const mode = opts.mode ?? guidanceModeFor(opts.projectDir);
   const appName = opts.appName ?? appNameFor(opts.projectDir);
   const managed = [];
@@ -87,10 +85,11 @@ function refreshAgentFiles(opts) {
   }
   return refreshed;
 }
+
 export {
-  CI_ENV_VARS,
   codingAgentDetected,
+  CI_ENV_VARS,
   isCI,
   refreshAgentFiles
 };
-//# sourceMappingURL=agent-file-refresh-J3KY54E5.js.map
+//# sourceMappingURL=chunk-D6OGU2AI.js.map

package/dist/{chunk-VVXPK6SE.js → chunk-DUC3PXDG.js}

@@ -9,11 +9,11 @@ import {
   unknownFlag,
   unknownHelpTopic,
   unknownSubcommand
-} from "./chunk-FY6LXRR6.js";
+} from "./chunk-KGNJM4LN.js";
 import {
   readLockFile,
   writeLockFile
-} from "./chunk-HJPTWBLH.js";
+} from "./chunk-MFIHIS6B.js";
 import {
   detail,
   info,
@@ -24,15 +24,17 @@ import {
   Xano,
   assertSeedIds,
   coerceSeedRowValues
-} from "./chunk-55VHDNW5.js";
+} from "./chunk-BPEEGJJA.js";
 import {
   getCommand,
   getSubcommand,
   isCommand,
   suggest
-} from "./chunk-QO4I5OYF.js";
+} from "./chunk-YYSJAAJM.js";
 import {
   FILTER_NAMES,
+  KNOWLEDGE_DIR,
+  KNOWLEDGE_FILE,
   SEED_FILE,
   buildContentEnvelope,
   emit,
@@ -42,7 +44,7 @@ import {
   pathSegment,
   serializeBundle,
   tableColumns
-} from "./chunk-5L4X5LS6.js";
+} from "./chunk-YUPQOLFX.js";
 import {
   WORKSPACE_KEY,
   createLockContext,
@@ -54,12 +56,12 @@ import {
   seedLockOverrides,
   serializeLock,
   validateLockModel
-} from "./chunk-4HT3BNZ7.js";
+} from "./chunk-YUBJLB6G.js";
 
 // src/emit/cli.ts
-import { pathToFileURL as pathToFileURL2, fileURLToPath as fileURLToPath2 } from "url";
-import { existsSync, readdirSync, readFileSync as readFileSync2, writeFileSync as writeFileSync2 } from "fs";
-import { basename, dirname, join, relative, resolve } from "path";
+import { pathToFileURL as pathToFileURL3, fileURLToPath as fileURLToPath3 } from "url";
+import { existsSync, readdirSync as readdirSync2, readFileSync as readFileSync3, writeFileSync as writeFileSync2 } from "fs";
+import { basename, dirname, join as join2, relative as relative2, resolve } from "path";
 import { createRequire } from "module";
 
 // src/workspace/seed.ts
@@ -250,6 +252,84 @@ function findUnresolvableFilters(bundle) {
   return findings;
 }
 
+// src/workspace/knowledge.ts
+import { readFileSync as readFileSync2, readdirSync, statSync } from "fs";
+import { fileURLToPath as fileURLToPath2, pathToFileURL as pathToFileURL2 } from "url";
+import { join, relative, sep } from "path";
+var MAX_KNOWLEDGE_FILE_BYTES = 1024 * 1024;
+function resolveMarker(ref) {
+  const base = /^[a-z][a-z0-9+.-]*:/i.test(ref.base) ? ref.base : pathToFileURL2(ref.base).href;
+  return fileURLToPath2(new URL(ref.path, base));
+}
+function collectRefFiles(dir, itemName) {
+  const out = [];
+  const walk = (cur) => {
+    for (const entry of readdirSync(cur, { withFileTypes: true })) {
+      const full = join(cur, entry.name);
+      if (entry.isDirectory()) {
+        walk(full);
+        continue;
+      }
+      if (!entry.isFile()) continue;
+      const content = readFileSync2(full, "utf8");
+      const size = Buffer.byteLength(content, "utf8");
+      const rel = relative(dir, full).split(sep).join("/");
+      if (size > MAX_KNOWLEDGE_FILE_BYTES) {
+        throw new Error(
+          `knowledge "${itemName}": reference file "${rel}" is ${size} bytes, over the ${MAX_KNOWLEDGE_FILE_BYTES}-byte limit the engine accepts. Split it, or move the bulk of it somewhere the agent fetches at run time.`
+        );
+      }
+      out.push({ path: rel, content, size });
+    }
+  };
+  walk(dir);
+  out.sort((a, b) => a.path < b.path ? -1 : a.path > b.path ? 1 : 0);
+  return out;
+}
+function resolveKnowledge(defs) {
+  const resolved = [];
+  for (const def of defs) {
+    const bodyRef = def.body[KNOWLEDGE_FILE];
+    const where = `knowledgeFile("${bodyRef.path}")`;
+    let content;
+    try {
+      const abs = resolveMarker(bodyRef);
+      if (statSync(abs).isDirectory()) {
+        throw new Error(
+          `knowledge "${def.name}": ${where} points at a DIRECTORY. A body is one markdown file; use \`refs: knowledgeDir(...)\` for a folder of reference files.`
+        );
+      }
+      content = readFileSync2(abs, "utf8");
+    } catch (err) {
+      if (err instanceof Error && /points at a DIRECTORY/.test(err.message)) throw err;
+      throw new Error(
+        `knowledge "${def.name}": cannot read ${where} \u2014 ${err.message}. The path resolves relative to the module that declares the item (its \`import.meta.url\`).`
+      );
+    }
+    let files = [];
+    if (def.refs !== void 0) {
+      const refsRef = def.refs[KNOWLEDGE_DIR];
+      const refsWhere = `knowledgeDir("${refsRef.path}")`;
+      const abs = resolveMarker(refsRef);
+      try {
+        if (!statSync(abs).isDirectory()) {
+          throw new Error(
+            `knowledge "${def.name}": ${refsWhere} is not a directory. Reference files are a FOLDER the agent searches; a single file belongs in the body.`
+          );
+        }
+      } catch (err) {
+        if (err instanceof Error && /is not a directory/.test(err.message)) throw err;
+        throw new Error(
+          `knowledge "${def.name}": cannot read ${refsWhere} \u2014 ${err.message}.`
+        );
+      }
+      files = collectRefFiles(abs, def.name);
+    }
+    resolved.push({ name: def.name, content, files });
+  }
+  return resolved;
+}
+
 // src/emit/cli.ts
 function parsePort(raw) {
   const n = Number(raw);
@@ -300,6 +380,7 @@ function parseArgs(argv) {
   let frozenLock = false;
   let strict = false;
   let yes = false;
+  let check = false;
   let bundle;
   let reset = false;
   let dest;
@@ -328,6 +409,7 @@ function parseArgs(argv) {
   let path;
   let name;
   const ai = [];
+  const marketplace = [];
   let framework;
   let theme;
   let radius;
@@ -376,6 +458,8 @@ function parseArgs(argv) {
       strict = true;
     } else if (arg === "--yes" || arg === "-y") {
       yes = true;
+    } else if (arg === "--check") {
+      check = true;
     } else if (arg === "--bundle") {
       bundle = rest[++i];
     } else if (arg.startsWith("--bundle=")) {
@@ -505,6 +589,12 @@ function parseArgs(argv) {
       icons = rest[++i];
     } else if (arg.startsWith("--icons=")) {
       icons = arg.slice("--icons=".length);
+    } else if (arg === "--marketplace" || arg.startsWith("--marketplace=")) {
+      const raw = arg === "--marketplace" ? rest[++i] : arg.slice("--marketplace=".length);
+      for (const p of (raw ?? "").split(",")) {
+        const pkg = p.trim();
+        if (pkg !== "") marketplace.push(pkg);
+      }
     } else if (arg === "--ai" || arg.startsWith("--ai=")) {
       const raw = arg === "--ai" ? rest[++i] : arg.slice("--ai=".length);
       for (const p of (raw ?? "").split(",")) {
@@ -581,6 +671,7 @@ function parseArgs(argv) {
     frozenLock,
     strict,
     yes,
+    check,
     bundle,
     reset,
     dest,
@@ -609,6 +700,7 @@ function parseArgs(argv) {
     path,
     name,
     ai,
+    marketplace,
     force,
     noInstall,
     framework,
@@ -673,9 +765,9 @@ function parseExpiresHours(raw) {
 }
 async function importTsxApi(file) {
   try {
-    const requireFromEntry = createRequire(pathToFileURL2(resolve(file)));
+    const requireFromEntry = createRequire(pathToFileURL3(resolve(file)));
     const apiPath = requireFromEntry.resolve("tsx/esm/api");
-    return await import(pathToFileURL2(apiPath).href);
+    return await import(pathToFileURL3(apiPath).href);
   } catch {
     return await import("tsx/esm/api");
   }
@@ -693,10 +785,10 @@ function entryIsCommonJs(file) {
   if (/\.cts$/.test(path)) return true;
   let dir = dirname(path);
   for (; ; ) {
-    const manifest = join(dir, "package.json");
+    const manifest = join2(dir, "package.json");
     if (existsSync(manifest)) {
       try {
-        const pkg = JSON.parse(readFileSync2(manifest, "utf8"));
+        const pkg = JSON.parse(readFileSync3(manifest, "utf8"));
         return pkg.type !== "module";
       } catch {
         return false;
@@ -715,7 +807,7 @@ function commonJsEntryError(file, cause) {
 }
 function suggestSiblingFile(path) {
   try {
-    return suggest(basename(path), readdirSync(dirname(path)));
+    return suggest(basename(path), readdirSync2(dirname(path)));
   } catch {
     return void 0;
   }
@@ -727,7 +819,7 @@ async function loadDefault(file) {
       suggestion: suggestSiblingFile(path)
     });
   }
-  const url = pathToFileURL2(path).href;
+  const url = pathToFileURL3(path).href;
   const isTypeScript = /\.[mc]?ts$/.test(file);
   if (isTypeScript) {
     if (entryIsCommonJs(file)) throw commonJsEntryError(file);
@@ -761,12 +853,12 @@ async function loadDefault(file) {
   }
 }
 function readVersion() {
-  let dir = dirname(fileURLToPath2(import.meta.url));
+  let dir = dirname(fileURLToPath3(import.meta.url));
   for (let i = 0; i < 6; i++) {
-    const p = join(dir, "package.json");
+    const p = join2(dir, "package.json");
     if (existsSync(p)) {
       try {
-        const pkg = JSON.parse(readFileSync2(p, "utf8"));
+        const pkg = JSON.parse(readFileSync3(p, "utf8"));
         if (pkg.name === "@xanots/sdk" && typeof pkg.version === "string") return pkg.version;
       } catch {
       }
@@ -791,9 +883,9 @@ function warnOrphans(orphans, dropped, cededCanonicals, previous, observed) {
       );
       continue;
     }
-    const sep = key.indexOf(":");
-    const payloadKey = key.slice(0, sep);
-    const name = key.slice(sep + 1);
+    const sep2 = key.indexOf(":");
+    const payloadKey = key.slice(0, sep2);
+    const name = key.slice(sep2 + 1);
     const newcomers = Object.keys(observed).filter((k) => k.startsWith(`${payloadKey}:`) && !(k in previous.objects)).map((k) => k.slice(payloadKey.length + 1));
     const hint = newcomers.length > 0 ? ` (new ${payloadKey} names this export: ${newcomers.join(", ")})` : "";
     warn(
@@ -814,6 +906,10 @@ function warnOrphans(orphans, dropped, cededCanonicals, previous, observed) {
   }
 }
 async function run(argv) {
+  if (argv[0] === "onboard") {
+    const { runOnboardCommand } = await import("./onboard-command-EHOHKQQU.js");
+    return runOnboardCommand(argv.slice(1));
+  }
   const helpRequest = resolveHelpRequest(argv);
   if (helpRequest) {
     if (helpRequest.unknownTopic !== void 0) throw unknownHelpTopic(helpRequest.unknownTopic);
@@ -832,11 +928,11 @@ async function run(argv) {
     return;
   }
   if (command === "init") {
-    const { runInitCommand } = await import("./init-command-6DGXEVZD.js");
+    const { runInitCommand } = await import("./init-command-GJUPWTKA.js");
     return runInitCommand(args);
   }
   if (command === "completion") {
-    const { isCompletionShell, runCompletionCommand, COMPLETION_SHELLS } = await import("./completion-2PVZK6YX.js");
+    const { isCompletionShell, runCompletionCommand, COMPLETION_SHELLS } = await import("./completion-4GYN752B.js");
     const shell = args.positionals[0];
     if (shell === void 0 || !isCompletionShell(shell)) {
       throw new UsageError(
@@ -846,28 +942,32 @@ async function run(argv) {
     }
     return runCompletionCommand(shell);
   }
+  if (command === "upgrade") {
+    const { runUpgradeCommand } = await import("./upgrade-command-CKJ4BS2P.js");
+    return runUpgradeCommand(args);
+  }
   if (command === "lock") {
-    const { runLockCommand } = await import("./lock-commands-R22J54XV.js");
+    const { runLockCommand } = await import("./lock-commands-7IH7RSSP.js");
     return runLockCommand(args);
   }
   if (command === "login") {
-    const { runLoginCommand } = await import("./login-command-ACJF6KWQ.js");
+    const { runLoginCommand } = await import("./login-command-QM5SBBI2.js");
     return runLoginCommand(args);
   }
   if (command === "logout") {
-    const { runLogoutCommand } = await import("./logout-command-MX3MJS5U.js");
+    const { runLogoutCommand } = await import("./logout-command-THPASOHM.js");
     return runLogoutCommand(args);
   }
   if (command === "deploy") {
-    const { runDeployCommand } = await import("./deploy-command-SXX6RJWM.js");
+    const { runDeployCommand } = await import("./deploy-command-M2S4HHLC.js");
     return runDeployCommand(args);
   }
   if (command === "ephemeral") {
-    const { runEphemeralCommand } = await import("./ephemeral-command-OGOYP7D6.js");
+    const { runEphemeralCommand } = await import("./ephemeral-command-6WJW7LP6.js");
     return runEphemeralCommand(args);
   }
   if (command === "release") {
-    const { runReleaseCommand } = await import("./release-command-6PLMLGDK.js");
+    const { runReleaseCommand } = await import("./release-command-M4CVNTWL.js");
     return runReleaseCommand(args);
   }
   if (command === "sandbox") {
@@ -875,47 +975,47 @@ async function run(argv) {
       throw removedSubcommand("sandbox", "deploy");
     }
     if (args.subcommand === "details") {
-      const { runSandboxDetailsCommand } = await import("./sandbox-details-command-HJE5SPVG.js");
+      const { runSandboxDetailsCommand } = await import("./sandbox-details-command-BRII3QHG.js");
       return runSandboxDetailsCommand(args);
     }
     if (args.subcommand === "export") {
-      const { runSandboxExportCommand } = await import("./sandbox-export-command-QCJY4GMV.js");
+      const { runSandboxExportCommand } = await import("./sandbox-export-command-PCZ5FL4U.js");
       return runSandboxExportCommand(args);
     }
     if (args.subcommand === "codegen") {
-      const { runCodegenCommand } = await import("./codegen-command-EXLKZ2ZI.js");
+      const { runCodegenCommand } = await import("./codegen-command-Z7WQMOJ7.js");
       return runCodegenCommand(args, { kind: "sandbox" });
     }
     throw unknownSubcommand("sandbox", args.subcommand);
   }
   if (command === "test") {
-    const { runTestCommand } = await import("./test-command-LLPXKT35.js");
+    const { runTestCommand } = await import("./test-command-U4G5Y3UM.js");
     return runTestCommand(args);
   }
   if (command === "workspace") {
-    const { runWorkspaceCommand } = await import("./workspace-command-JKMI7RZ4.js");
+    const { runWorkspaceCommand } = await import("./workspace-command-RALSEJSW.js");
     return runWorkspaceCommand(args);
   }
   if (command === "codegen") {
-    const { runCodegenCommand } = await import("./codegen-command-EXLKZ2ZI.js");
+    const { runCodegenCommand } = await import("./codegen-command-Z7WQMOJ7.js");
     return runCodegenCommand(args, { kind: "file" });
   }
   if (command === "profile") {
     if (args.subcommand !== "me") {
       throw unknownSubcommand("profile", args.subcommand);
     }
-    const { runProfileCommand } = await import("./profile-command-SWJ3SPKR.js");
+    const { runProfileCommand } = await import("./profile-command-EUWPVWED.js");
     return runProfileCommand(args);
   }
   if (command === "whoami") {
-    const { runProfileCommand } = await import("./profile-command-SWJ3SPKR.js");
+    const { runProfileCommand } = await import("./profile-command-EUWPVWED.js");
     return runProfileCommand(args);
   }
   if (command === "marketplace") {
     if (!["list", "search", "details", "install"].includes(args.subcommand ?? "")) {
       throw unknownSubcommand("marketplace", args.subcommand);
     }
-    const marketplace = await import("./marketplace-command-XJIWL4YP.js");
+    const marketplace = await import("./marketplace-command-463DT7O7.js");
     if (args.subcommand === "list") return marketplace.runMarketplaceListCommand(args);
     if (args.subcommand === "search") return marketplace.runMarketplaceSearchCommand(args);
     if (args.subcommand === "details") return marketplace.runMarketplaceDetailsCommand(args);
@@ -925,7 +1025,7 @@ async function run(argv) {
     throw unknownCommand("push");
   }
   if (command === "validate") {
-    const { runValidateCommand } = await import("./validate-command-WAT3ZJT3.js");
+    const { runValidateCommand } = await import("./validate-command-S5N37JRP.js");
     return runValidateCommand(args);
   }
   if (command !== "compile" && command !== "export" && command !== "paths" && command !== "routes") {
@@ -957,7 +1057,7 @@ async function run(argv) {
 }
 async function refreshAgentGuidance() {
   try {
-    const { refreshAgentFiles } = await import("./agent-file-refresh-J3KY54E5.js");
+    const { refreshAgentFiles } = await import("./agent-file-refresh-IJ7GN2FJ.js");
     const refreshed = refreshAgentFiles({
       projectDir: process.cwd(),
       sdkVersion: readVersion()
@@ -970,7 +1070,7 @@ async function refreshAgentGuidance() {
   }
 }
 function resolveLockPath(args, file) {
-  return args.lockPath !== void 0 ? resolve(args.lockPath) : join(dirname(resolve(file)), "xano.lock");
+  return args.lockPath !== void 0 ? resolve(args.lockPath) : join2(dirname(resolve(file)), "xano.lock");
 }
 function describeDefaultExport(def) {
   if (def === void 0) return "no default export";
@@ -1082,7 +1182,7 @@ async function runPaths(args) {
       const channelCount = channelRows.length === 1 ? "1 channel" : `${channelRows.length} channels`;
       const count = describableServers.length > 0 ? `${routeCount}, ${channelCount}` : routeCount;
       if (args.strict) {
-        const current = existsSync(args.emit) ? readFileSync2(args.emit, "utf8") : void 0;
+        const current = existsSync(args.emit) ? readFileSync3(args.emit, "utf8") : void 0;
         if (current !== source) {
           throw new Error(
             `--strict: ${args.emit} is ${current === void 0 ? "missing" : "out of date"}. Run \`xanots paths <entry> --emit ${args.emit}\` and commit the result \u2014 a stale route manifest keeps compiling while the endpoints have moved.`
@@ -1134,7 +1234,12 @@ async function compileBundle(args, opts = {}) {
   if (!Xano.isXano(def)) {
     throw new Error(`Module "${file}" must default-export a Xano registry for \`export\`.`);
   }
-  const bundle = def.export({ ...lockCtx ? { lock: lockCtx } : {}, strict: args.strict });
+  const resolvedKnowledge = resolveKnowledge(def.knowledge());
+  const bundle = def.export({
+    ...lockCtx ? { lock: lockCtx } : {},
+    strict: args.strict,
+    knowledge: resolvedKnowledge
+  });
   if (lockCtx) {
     const { lock: merged, orphans, dropped, cededCanonicals } = mergeObserved(
       lockCtx.lock,
@@ -1148,7 +1253,7 @@ async function compileBundle(args, opts = {}) {
       );
     }
     writeLockFile(lockPath, merged);
-    if (!lockExists) info(`Wrote ${relative(process.cwd(), lockPath) || lockPath} (commit this).`);
+    if (!lockExists) info(`Wrote ${relative2(process.cwd(), lockPath) || lockPath} (commit this).`);
     warnOrphans(orphans, dropped, cededCanonicals, lockCtx.lock, lockCtx.observed);
   }
   checkFilterNames(bundle, args.strict);
@@ -1185,4 +1290,4 @@ export {
   exportBundleJson,
   compileBundle
 };
-//# sourceMappingURL=chunk-VVXPK6SE.js.map
+//# sourceMappingURL=chunk-DUC3PXDG.js.map