@xano/sdk 1.0.5 → 1.0.7

package/CHANGELOG.md

@@ -8,9 +8,39 @@ one release and links to its full notes.
 
 ---
 
+## 1.0.6 — Request types reach the frontend
+
+_2026-10-05_ · [release notes](https://github.com/xano-sdk/sdk/releases/tag/v1.0.6)
+
+This release types every request a frontend sends from `routes.gen.ts` alone, opens that file to marketplace modules so runtime validators can sit beside the types, and teaches `workspace diff` to say which side changed since the project and a workspace branch last matched. ⚠️ One behavior break: `s.db.transaction` no longer accepts `as`, which always bound `null`.
+
+- `routes.gen.ts` types every request the frontend sends
+- Toolchain modules add their own section to `routes.gen.ts`
+- `workspace diff` says which side changed since the last sync
+- ⚠️ `s.db.transaction` no longer takes `as`
+- A required input that carries a default is flagged
+- The scaffolded README keeps its platform section
+
+---
+
+## 1.0.5 — The Xano Engine is the default
+
+_2026-10-05_ · [release notes](https://github.com/xano-sdk/sdk/releases/tag/v1.0.5)
+
+This release makes the **Xano Engine**, the engine that runs on your machine, the default place your code goes. A bare `xanosdk deploy` now runs your backend locally with no Xano account, and `--ephemeral` sends it to Xano's cloud as the bare command used to. The engine is now called `local` everywhere in the CLI, and `publish` can put a frontend on it. ⚠️ Scripts that run a bare `deploy` expecting an ephemeral, or that use the `local-engine` spellings, need the changes below.
+
+- ⚠️ `xanosdk deploy` goes to the Xano Engine by default
+- ⚠️ The engine is `local` in the CLI
+- `xanosdk publish` reaches the Xano Engine
+- ⚠️ Scaffolded projects deploy locally first
+- The README and scaffolded README introduce Xano
+- The SDK lives at github.com/xano-sdk/sdk
+
+---
+
 ## 1.0.4 — Marketplace moves to its new catalogue
 
-_2026-10-03_ · [release notes](https://github.com/xano-sdk/sdk/releases/tag/v1.0.4)
+_2026-10-04_ · [release notes](https://github.com/xano-sdk/sdk/releases/tag/v1.0.4)
 
 This patch release moves `xanosdk marketplace` to the catalogue's new home. The CLI now reads modules from a new default host, `XANOSDK_MARKETPLACE_URL` works with a tenant or ephemeral base, and a module withdrawn from the marketplace is refused by `install` again. No call-site changes are needed.
 
@@ -22,7 +52,7 @@ This patch release moves `xanosdk marketplace` to the catalogue's new home. The
 
 ## 1.0.3 — Agents and MCP servers pass preflight
 
-_2026-10-03_ · [release notes](https://github.com/xano-sdk/sdk/releases/tag/v1.0.3)
+_2026-10-04_ · [release notes](https://github.com/xano-sdk/sdk/releases/tag/v1.0.3)
 
 This patch release fixes `xanosdk preflight` on workspaces that have agents or MCP servers, and makes pulling an existing workspace into code more reliable. Agents and MCP servers without sign-in no longer fail the round trip. Workspaces pulled with `export`/codegen now re-export as they were stored and the generated tree typechecks, including shapes older workspaces carry.
 
@@ -36,7 +66,7 @@ This patch release fixes `xanosdk preflight` on workspaces that have agents or M
 
 ## 1.0.2 — Fixtures can pin accepted hazards
 
-_2026-10-03_ · [release notes](https://github.com/xano-sdk/sdk/releases/tag/v1.0.2)
+_2026-10-04_ · [release notes](https://github.com/xano-sdk/sdk/releases/tag/v1.0.2)
 
 This patch release lets a def deliberately author three shapes the engine accepts but 1.0 refused outright: an active cache with `ttl: 0`, a call passing an input its target does not declare, and a lambda body that does not parse. Each is still flagged by default, and `export --strict` still fails on it, but a fixture that pins the engine's behavior for that input can now say so.
 
@@ -48,7 +78,7 @@ This patch release lets a def deliberately author three shapes the engine accept
 
 ## 1.0.1 — Safer local-engine records
 
-_2026-10-03_ · [release notes](https://github.com/xano-sdk/sdk/releases/tag/v1.0.1)
+_2026-10-04_ · [release notes](https://github.com/xano-sdk/sdk/releases/tag/v1.0.1)
 
 This patch release makes the local engine's record file safe under concurrent use and removes the SDK's handling of its retired package names. If you run several local-engine deploys or stops at once, they no longer undo each other's bookkeeping.
 
@@ -60,7 +90,7 @@ This patch release makes the local engine's record file safe under concurrent us
 
 ## 1.0.0 — Xano SDK, the new name
 
-_2026-10-02_ · [release notes](https://github.com/xano-sdk/sdk/releases/tag/v1.0.0)
+_2026-10-04_ · [release notes](https://github.com/xano-sdk/sdk/releases/tag/v1.0.0)
 
 The SDK is now **Xano SDK**, published as `@xano/sdk` and restarting at 1.0.0. The CLI is `xanosdk`, and add-on modules ship as `@xano-sdk/*`. The earlier `@xanots/sdk` 0.0.x and `@xanots/core` 2.0.x lines are retired.
 

package/README.md

@@ -19,6 +19,7 @@ network. When it's ready, one command puts the same code live on Xano's cloud.**
 [The model](#the-model) ·
 [Typed frontend](#a-type-safe-frontend-for-free) ·
 [Already on Xano?](#already-have-a-xano-workspace) ·
+[Agent skill](#the-agent-skill) ·
 [Deploying](#deploying) ·
 [Reference](#reference)
 
@@ -105,9 +106,9 @@ the platform is where it runs.
   objects, and the `xano.lock` every build writes keeps renames as renames, so your public
   URLs stay yours.
 
-- **🧩 The types flow to your frontend.** `import type` a `query()` def for its typed request
-  and response, and read its path and verb from a generated route manifest. Rename a column
-  and every consumer lights up red.
+- **🧩 The types flow to your frontend.** A generated route manifest gives it every path, verb
+  and request type; `import type` a `query()` def for its response. Rename a column and every
+  consumer lights up red.
 
 - **🔁 It works both ways.** Already have a workspace? `init --from workspace` reads it back
   as real, readable TypeScript — then deploys.
@@ -120,8 +121,8 @@ The three commands at the top of this page are the whole local loop. Here it is
 time, then out to the cloud.
 
 **1. Scaffold.** No sign-in needed. `init` writes a Vite frontend under `frontend/` (React 19 +
-shadcn/ui by default, or SvelteKit with `--framework svelte`), a Xano SDK backend under
-`xano/`, and the `xano:deploy*` scripts already wired.
+shadcn/ui by default, SvelteKit with `--framework svelte`, none with `--framework none`), a Xano
+SDK backend under `xano/`, and the `xano:deploy*` scripts already wired.
 
 ```bash
 npx @xano/sdk init my-app && cd my-app
@@ -131,6 +132,12 @@ Theme it with a flag (`--theme zinc-blue --dark toggle`) or pick everything in a
 `--web`. The starter backend is empty but already deploys — grow it from `xano/EXAMPLE.md`.
 Flags, presets, theming and add-ons: [The scaffolded project](https://github.com/xano-sdk/sdk/blob/main/guides/scaffold.md).
 
+**Already have an app?** Run `init` inside it. In a directory that already has files, `init`
+adds only the backend, with no prompt: it writes `xano/`, merges the `xano:*` scripts and
+dependencies into your `package.json`, and writes no frontend. Anything it would overwrite is
+listed and refused unless you pass `--force`
+([details](https://github.com/xano-sdk/sdk/blob/main/guides/scaffold.md#no-frontend-and-existing-apps)).
+
 **2. Run it on the Xano Engine.** The first deploy downloads the engine for your platform and
 pins its version in `package.json`; every one after starts in seconds, offline.
 
@@ -183,9 +190,12 @@ your laptop. `xanosdk deploy` brings one up and deploys into it — it is where
   commit it and every checkout runs the same engine. Newer ones are offered, never forced.
 - **Every command reaches it.** After a local deploy, `test run-all`, `tables`, `env set`,
   `impersonate` and `status` target the engine without a flag, and with no account.
+- **An MCP server for your agent.** `init` connects Claude Code and Cursor to it: they read tables and
+  rows, seed data, and run functions and tests. Code still changes in `xano/` and ships with a deploy.
 
 ```bash
 npx xanosdk local list          # the engines running on this machine
+npx xanosdk local mcp           # how a coding agent connects to the engine's MCP server
 npx xanosdk local stop <name>   # stop one
 npx xanosdk local update        # move the pin to the latest engine
 npx xanosdk local cache clear   # reclaim the disk space
@@ -202,7 +212,7 @@ You author declarative def-objects, register them on one `Xano` instance, and Xa
 compiles the whole thing into Xano's importable bundle.
 
 ```ts
-import { workspace, table, query, apiGroup, f, s, ref, c, expr, col } from "@xano/sdk";
+import { workspace, table, query, apiGroup, f, input, s, inp, ref, c, expr, col } from "@xano/sdk";
 
 // A database table — `id` + `created_at` auto-inject, so declare only your own columns.
 const user = table({
@@ -237,10 +247,17 @@ const listPosts = query({
   response: ref("rows"),
 });
 
+const createPost = query({
+  verb: "POST", apiGroup: blog, name: "posts",
+  input: { title: input.text({ required: true }), body: input.text() },
+  stack: [s.db.add({ table: post, row: { title: inp("title"), body: inp("body") }, as: "row" })],
+  response: ref("row"),
+});
+
 export default workspace("blog")
   .registerApiGroups([blog])
   .registerTables([user, post])
-  .registerQueries([listPosts]);
+  .registerQueries([listPosts, createPost]);
 ```
 
 Tab-complete `s.` to discover the entire statement catalog — `s.db.*`, `s.math.*`,
@@ -278,25 +295,27 @@ kind you can author is in [Object kinds](https://github.com/xano-sdk/sdk/blob/ma
 
 ## A type-safe frontend, for free
 
-Because your API is a typed def, the code that *calls* it reuses that def instead of
-re-typing URLs and request bodies. Paths come from a generated route manifest, types
-straight from the defs:
+Because your API is a typed def, the code that *calls* it never re-types a URL or a request
+body: paths and request types come from a generated route manifest, responses from the defs:
 
 ```bash
 npx xanosdk routes ./xano/index.ts --emit xano/routes.gen.ts   # scaffolds run this before dev/build/typecheck
 ```
 
 ```ts
-import { ROUTES, routePath } from "../xano/routes.gen.js"; // plain data, imports nothing
+import { ROUTES, routePath, type RouteInputs } from "../xano/routes.gen.js"; // plain data, imports nothing
 import type { post } from "../xano/index.js";            // the model above
 import type { InferRow } from "@xano/sdk";
 
 const BASE = window.XANO_HOST ?? import.meta.env.VITE_XANO_HOST; // deploy injects it; .env.local in dev
 
+type NewPost = RouteInputs["POST posts"];              // { title: string; body?: string }
 type Post = InferRow<typeof post>;                     // { id: number; created_at: number; title: string; … }
 
-async function fetchPosts(): Promise<Post[]> {
-  const res = await fetch(BASE + routePath("GET list_posts"), { method: ROUTES["GET list_posts"].verb });
+async function createPost(body: NewPost): Promise<Post> {
+  const res = await fetch(BASE + routePath("POST posts"), {
+    method: ROUTES["POST posts"].verb, headers: { "content-type": "application/json" }, body: JSON.stringify(body),
+  });
   return res.json();                                   // typed end to end
 }
 ```
@@ -304,15 +323,16 @@ async function fetchPosts(): Promise<Post[]> {
 - **`routePath("GET blog/{slug}", { slug })`** → the endpoint path, resolved from your code
   (or the frozen `xano.lock`). Keys are `"<VERB> <name>"` and are checked at compile time,
   `{param}` names included: a backend rename is a compile error rather than a 404.
-- **`InferInput<typeof someQuery>`** → the request-payload type, derived from a query's
-  `input` map. **No codegen, always in sync.**
+- **`RouteInputs["POST posts"]`** → the request-payload type, under the same keys
+  (`ChannelInputs`/`MessageInputs` for realtime); `InferInput<typeof q>` is the def-side twin.
 - **`InferRow<typeof post>`** / **`InferResponse<typeof someQuery>`** → the table's row type
   and the endpoint's response type, closing the round trip. Rename or retype a column and
   every consumer breaks at compile time — exactly where you want it.
+- **Runtime validation:** `npx xanosdk marketplace install zod` adds zod schemas to the file,
+  keyed alike (`ROUTE_SCHEMAS["POST posts"].parse(body)`) and typechecked against the types.
 
-Import defs into a frontend with `import type` only — a def imported as a value runs its
-factory calls at module load and carries the SDK runtime into your bundle. The measured bundle
-numbers, the full response-inference rules, and the realtime helpers are in
+Import defs with `import type` only: a def imported as a value carries the SDK runtime into
+your bundle. Bundle numbers, inference rules, and the realtime helpers are in
 [The typed frontend surface](https://github.com/xano-sdk/sdk/blob/main/guides/typed-frontend.md).
 
 ---
@@ -344,6 +364,22 @@ values travel, the doc-site token, and how to read the decode report are in
 
 ---
 
+## The agent skill
+
+`xano-backend` is an agent skill (`SKILL.md`) for the coding agent you already use: Claude Code,
+Codex, Cursor, Copilot, Gemini CLI, Amp or OpenCode. When a project needs a backend and has none,
+it has the agent confirm Xano with you, run `init`, deploy, and follow the `AGENTS.md` that `init`
+wrote. (It is unrelated to `knowledge()`, the docs your workspace's own AI agents read.)
+
+```bash
+npx @xano/sdk agent-skill install   # into each coding agent on this machine (also: status, uninstall)
+npx skills add xano-sdk/sdk         # or with the skills installer
+```
+
+In Claude Code: `/plugin marketplace add xano-sdk/sdk`, then `/plugin install xano@xano-sdk`.
+
+---
+
 ## Deploying
 
 Code moves through three places: the **Xano Engine** on your machine, a disposable
@@ -400,12 +436,12 @@ reference, the guides carry the shape of a project and the behavior that will bi
 | Guide | What's in it |
 |---|---|
 | [Project structure](https://github.com/xano-sdk/sdk/blob/main/guides/project-structure.md) | How a `xano/` project is laid out, why registration is explicit, wiring one by hand |
-| [The scaffolded project](https://github.com/xano-sdk/sdk/blob/main/guides/scaffold.md) | What `xanosdk init` writes, the two frontend presets, theming, add-ons, SvelteKit rules |
+| [The scaffolded project](https://github.com/xano-sdk/sdk/blob/main/guides/scaffold.md) | What `xanosdk init` writes, the two frontend presets, no frontend, existing apps, theming, add-ons, SvelteKit rules |
 | [The marketplace](https://github.com/xano-sdk/sdk/blob/main/guides/marketplace.md) | Finding add-ons, the two kinds of module, and the install/reinstall/remove lifecycle |
 | [The module contract](https://github.com/xano-sdk/sdk/blob/main/guides/module-contract.md) | Building an add-on: the manifest fields, the plugin types, every hook, and what is refused |
 | [Object kinds](https://github.com/xano-sdk/sdk/blob/main/guides/object-kinds.md) | Every authorable kind, and splitting a workspace across microservices |
 | [Authoring reference](https://github.com/xano-sdk/sdk/blob/main/guides/authoring.md) | Tables and fields, statements, values, inputs, middleware, seed data |
-| [CLI](https://github.com/xano-sdk/sdk/blob/main/guides/cli.md) | Every command, shell completion, and what failures look like |
+| [CLI](https://github.com/xano-sdk/sdk/blob/main/guides/cli.md) | Every command, the agent skill, shell completion, and what failures look like |
 | [Warning and error codes](https://github.com/xano-sdk/sdk/blob/main/guides/codes.md) | Every code the CLI and the build emit, with what it means |
 | [Signing in & deploying](https://github.com/xano-sdk/sdk/blob/main/guides/deploying.md) | Auth, ephemerals, `--static`, releasing to production, `xanosdk preflight` |
 | [Environment & identity](https://github.com/xano-sdk/sdk/blob/main/guides/environment.md) | Every environment variable, and how `xano.lock` pins identity |

package/dist/.build-fingerprint

@@ -1 +1 @@
-0ef21e00b526b685899802e5b0d7ba1d35d8d9dc017a19dfba2c4e88953c0a6a
+a3dac9a50b7a320b81dbb028431e66025ba401dc212eea0aa3ad9293c4f52ddf

package/dist/{agent-file-refresh-KVLR7M5Y.js → agent-file-refresh-DGGSRPJ4.js}

@@ -3,26 +3,27 @@ import {
   codingAgentDetected,
   isCI,
   refreshAgentFiles
-} from "./chunk-TUEFTRC2.js";
-import "./chunk-F6IKWAIU.js";
-import "./chunk-OGUMHW2X.js";
-import "./chunk-3VX7VAQT.js";
+} from "./chunk-ZXRDD3Q2.js";
+import "./chunk-DIWF7L33.js";
+import "./chunk-D5OZRJ3T.js";
+import "./chunk-EF4MHLEW.js";
 import "./chunk-ZFDZKNGG.js";
 import "./chunk-FWD7AL6N.js";
-import "./chunk-MYLPOVX6.js";
+import "./chunk-47XT6WQL.js";
 import "./chunk-DXUICABI.js";
+import "./chunk-L6HZ67P6.js";
 import "./chunk-4KHEMC32.js";
-import "./chunk-WRBKLYSJ.js";
-import "./chunk-M7GJ6YUF.js";
-import "./chunk-HLQH3AXB.js";
+import "./chunk-DNBP4GJN.js";
+import "./chunk-CNZASQPL.js";
+import "./chunk-WAVNUTMT.js";
 import "./chunk-LLNZGEFK.js";
 import "./chunk-MF4W6FHU.js";
 import "./chunk-X2NL4KUO.js";
-import "./chunk-57HMNJGB.js";
-import "./chunk-M6ZFSTIZ.js";
-import "./chunk-DGWHAVRG.js";
-import "./chunk-XNZURZ7T.js";
-import "./chunk-GPI3OWRE.js";
+import "./chunk-BRANWM4U.js";
+import "./chunk-5GIOCDUM.js";
+import "./chunk-LJM5CIY4.js";
+import "./chunk-CH23ONYG.js";
+import "./chunk-YHB34BN6.js";
 import "./chunk-UTI5G6OJ.js";
 import "./chunk-5ZSO4T2G.js";
 import "./chunk-TFFGOFVZ.js";
@@ -35,4 +36,4 @@ export {
   isCI,
   refreshAgentFiles
 };
-//# sourceMappingURL=agent-file-refresh-KVLR7M5Y.js.map
+//# sourceMappingURL=agent-file-refresh-DGGSRPJ4.js.map