@xano/sdk 1.0.6 → 1.0.7

package/guides/deploying.md

@@ -652,6 +652,34 @@ re-importing the backend. One command cannot serve it and refuses it by name: `r
 | `xanosdk local cache list` | Each cached engine version, its size on disk, and the engines running on it. |
 | `xanosdk local cache clear` | Removes every cached engine (`--version <v>`: just that one). An engine running on a removed version is stopped first; the next deploy fetches it again. |
 
+#### Connecting a coding agent
+
+The Xano Engine serves an MCP server for coding agents, and a local deploy prints where. It is
+for looking at the deployed backend (objects, table schemas, rows, run history), seeding and
+editing rows, and running functions, tasks, triggers, endpoints and tests by hand, each
+answering its result and logs. It never changes a primitive: tables, endpoints, functions and
+every other object change in `xano/` and ship with `xanosdk deploy`.
+
+`xanosdk init` connects Claude Code (`.mcp.json`) and Cursor (`.cursor/mcp.json`) to it with one
+server, `xano-local`, that launches a bridge:
+
+```json
+{ "mcpServers": { "xano-local": { "command": "npx", "args": ["--yes", "--package", "@xano/sdk", "xanosdk", "local", "mcp", "--stdio"] } } }
+```
+
+Nothing has to be started or installed by hand: the agent launches the server itself, using the
+project's own `@xano/sdk` when it is installed and fetching it when it is not (a fresh clone opened
+before `npm install`). The config holds no url and no token. The engine may come back on a new port after a restart and
+always mints a new bearer, so the bridge looks both up when it needs them, and again when the
+engine stops answering or refuses the bearer. Before the first deploy the server connects and
+lists no tools; once an engine is up it tells the agent its tools changed. A call cut off after
+it reached the engine is reported as unknown, never sent twice. `xanosdk local mcp` prints the
+details and each agent's config line, and `init` in an existing project adds the server beside
+the ones a config already declares. An engine too old to serve MCP says so on deploy, and
+`xanosdk local update` moves the project to one that does. Claude Code asks once before it
+starts a project's server; a Cursor version that does not pick up the tool change needs the
+`xano-local` server refreshed in its MCP settings after the first deploy.
+
 #### A frontend on the Xano Engine, and server rendering
 
 `xanosdk deploy <entry> --local --static <dir>` publishes a built frontend to the

package/guides/scaffold.md

@@ -1,27 +1,29 @@
 # The scaffolded project
 
-What `xanosdk init` writes, the two frontend presets, theming, add-ons, and the SvelteKit prerendering rules.
+What `xanosdk init` writes, the two frontend presets, a project with no frontend, adding the backend to an existing app, theming, add-ons, and the SvelteKit prerendering rules.
 
 ## init flags and add-ons
 
-`init` flags: `--framework <react|svelte>` (default: `react`), `--name <name>`
+`init` flags: `--framework <react|svelte|none>` (default: `react`; `none` writes the
+backend alone — see [No frontend, and existing apps](#no-frontend-and-existing-apps)), `--name <name>`
 (default: the folder name), `--theme <id>` / `--radius <len>` / `--dark <mode>` /
 `--font <id>` / `--font-mono <id>` / `--font-heading <id>` / `--icons <id>`
 (the look — see [Theming](#theming)), `--no-agents-md` (skip the `AGENTS.md`
 agent brief, which every coding agent reads and `init` writes by default),
 `--marketplace <pkg>` (repeatable, comma-separated; installs add-ons and
-registers them — below), `--force` (scaffold into a non-empty folder; over an
-existing project it lists the files it would overwrite and asks, `--yes` answering
-without a terminal — files it does not write are kept),
+registers them — below), `--force` (write over what clashes when adding the backend to
+a non-empty folder; it lists the files and scripts it would overwrite and asks, `--yes`
+answering without a terminal — files it does not write are kept),
 `--no-install` (skip `npm install`), `--web` (choose all of the above in a
 browser instead — see [Choosing in a browser](#choosing-in-a-browser)),
 `--from <source>` (fill `xano/` from an existing backend — any
 [backend spelling](cli.md#naming-a-backend) or a bundle path — rather than the
 starter — see [Pulling an existing workspace](codegen.md); over an existing `xano/` it lists
 what it replaces and asks, and `--yes` answers without a terminal).
-In a terminal, `init` prompts for the framework; the prompt has a default, so
-pressing enter is a valid answer. The look is never
-prompted for — it comes from the flags above, or from `--web`.
+In a terminal, `init` prompts for the framework in an empty or missing folder
+(React, Svelte, or "No frontend"); the prompt has a default, so pressing enter is a
+valid answer. A folder that already has files gets no prompt and no frontend. The look
+is never prompted for — it comes from the flags above, or from `--web`.
 The starter backend is empty but already compiles and deploys — grow it from the
 walkthrough in `xano/EXAMPLE.md`.
 
@@ -113,10 +115,59 @@ project — the mistake npm answers by silently writing to the wrong `package.js
 The package name is passed through exactly as typed, so version specifiers, tags,
 and third-party packages all work.
 
+## No frontend, and existing apps
+
+`init` reads its target directory before it writes anything. An empty or missing directory
+is a **new** project, and `--framework` decides its frontend. Any other directory is an
+**existing** project, which has its own app and gets the backend only.
+
+**A new project with `--framework none`** (or "No frontend" at the prompt) gets everything
+above except the frontend: `xano/`, a `package.json` with only the backend's scripts and
+dependencies, `.gitignore`, `.gitattributes`, the CI check, a README and `AGENTS.md`. There is
+no `frontend/` and no root `tsconfig.json`; `xano/` type-checks under its own
+`xano/tsconfig.json`, and `npm run xano:typecheck` checks it and its lambdas.
+`xano:deploy:ephemeral` deploys the backend alone, and there is no `dev`, `build` or
+`xano:deploy:frontend`.
+
+**An existing project** (any non-empty directory) gets:
+
+- `xano/`, the same starter a new project gets. When the project's `package.json` is not
+  `"type": "module"` (Next.js and `npm init -y` write one that is not), `init` also writes
+  `xano/package.json` holding only `{"type": "module"}`, so `xano/` loads as ES modules
+  without changing the project's own type.
+- The `xano:*` scripts and the backend's dependencies merged into `package.json`. The
+  project's entries win: a dependency it already has keeps its range, a script it already
+  has keeps its command, and no other key changes (an add-on's settings under `"xanosdk"`
+  aside). The file keeps its indentation and line endings. A project with no
+  `package.json` gets one holding only what the backend needs.
+- A marked block in `.gitignore` (created when missing) and in `AGENTS.md`, added or
+  refreshed in place; the rest of each file is left as it was. A symlinked `AGENTS.md` is left
+  alone, and `--no-agents-md` skips it.
+- No frontend, README, CI workflow or root `tsconfig.json`. The line-ending rule goes in
+  `xano/.gitattributes`, scoped to `xano/`, so the project's own files are not renormalized.
+
+What would be written over is a **clash**: an existing `xano/`, any other file `init` writes
+that is already there, and a `xano:*` script the project defines with a different command (the
+same command is no clash). `init` lists every clash and writes nothing; `--force` lists what it
+overwrites and asks first. A `package.json` that is not valid JSON is refused, since there is
+nothing to merge into.
+
+`--framework react` or `--framework svelte` in a non-empty directory is refused, as are the
+frontend-only flags (`--theme`, `--radius`, `--dark`, `--font`, `--font-mono`,
+`--font-heading`, `--icons`) wherever no frontend is written. After the merge, `npm run
+xano:deploy` runs the backend on the Xano Engine as it does in a new project.
+
+If the project's own root `tsconfig.json` includes every `.ts` file (Next.js's does), add
+`"xano/lambdas"` to its `exclude` before adding the first lambda: the lambda globals
+type-check only under `xano/lambdas/tsconfig.json`. `init` leaves that file alone, and the
+`AGENTS.md` it writes says the same.
+
 ## Git and CI
 
-`init` writes a `.gitattributes` and a `.github/workflows/check.yml` (`xanosdk-<dir>.yml`
-below the repository root, so moving it up never replaces another workflow).
+A new project gets a `.gitattributes` and a `.github/workflows/check.yml` (`xanosdk-<dir>.yml`
+below the repository root, so moving it up never replaces another workflow). An existing
+project gets no workflow, and its line-ending rule is scoped to `xano/`; run
+`npm run xano:check` from its own CI.
 
 The attributes file normalizes line endings, so any generated artifact the project
 commits is byte-identical on every checkout and a `--frozen-lock` check cannot fail

package/llms-full.txt

@@ -1,4 +1,4 @@
-# xanosdk v1.0.6
+# xanosdk v1.0.7
 
 > TypeScript SDK that compiles a typed Xano workspace into the importable packageExport JSON bundle.
 

package/llms.txt

@@ -1,4 +1,4 @@
-# xanosdk v1.0.6
+# xanosdk v1.0.7
 
 > TypeScript SDK that compiles a typed Xano workspace into the importable packageExport JSON bundle.
 

package/manifest.json

@@ -1,6 +1,6 @@
 {
   "name": "xanosdk",
-  "version": "1.0.6",
+  "version": "1.0.7",
   "description": "TypeScript SDK that compiles a typed Xano workspace into the importable packageExport JSON bundle.",
   "coverage": {
     "objectKinds": {
@@ -8997,6 +8997,48 @@
     }
   ],
   "cli": [
+    {
+      "command": "agent-skill install",
+      "flags": [
+        {
+          "flag": "--agent <id>",
+          "description": "Which agent to act for, instead of the ones detected (repeatable): claude-code, agents (the shared ~/.agents directory), codex, cursor, copilot, gemini, amp, opencode"
+        },
+        {
+          "flag": "--dry-run",
+          "description": "Report what would change and write nothing"
+        },
+        {
+          "flag": "--force",
+          "description": "Replace a copy that was edited since it was installed"
+        }
+      ],
+      "description": "Write the skill into the user-level skill directory of each detected agent; an edited copy is left alone unless --force"
+    },
+    {
+      "command": "agent-skill status",
+      "flags": [
+        {
+          "flag": "--agent <id>",
+          "description": "Which agent to act for, instead of the ones detected (repeatable): claude-code, agents (the shared ~/.agents directory), codex, cursor, copilot, gemini, amp, opencode"
+        }
+      ],
+      "description": "Report each copy as current, stale, edited or absent"
+    },
+    {
+      "command": "agent-skill uninstall",
+      "flags": [
+        {
+          "flag": "--agent <id>",
+          "description": "Which agent to act for, instead of the ones detected (repeatable): claude-code, agents (the shared ~/.agents directory), codex, cursor, copilot, gemini, amp, opencode"
+        },
+        {
+          "flag": "--dry-run",
+          "description": "Report what would be removed and remove nothing"
+        }
+      ],
+      "description": "Remove the copies install wrote; an edited copy is reported and kept"
+    },
     {
       "command": "compile",
       "args": "<file>",
@@ -9655,10 +9697,11 @@
         },
         {
           "flag": "--framework <id>",
-          "description": "Frontend framework to scaffold: react (default), svelte",
+          "description": "Frontend to scaffold in a new project: react (default), svelte, or none for the backend only. A non-empty directory always gets the backend only",
           "values": [
             "react",
-            "svelte"
+            "svelte",
+            "none"
           ]
         },
         {
@@ -9777,7 +9820,7 @@
         },
         {
           "flag": "--force",
-          "description": "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"
+          "description": "Write over what clashes when adding the backend to a non-empty target directory: an existing xano/, a file init would write, a xano:* script with another command. It lists every file and script it would overwrite and confirms first (--yes without a terminal); files the scaffold does not write are kept"
         },
         {
           "flag": "--no-install",
@@ -9851,7 +9894,7 @@
           ]
         }
       ],
-      "description": "Scaffold a Xano SDK project — empty, or filled from an existing backend"
+      "description": "Scaffold a Xano SDK project — empty, or filled from an existing backend. In a non-empty directory, add the backend to the project there"
     },
     {
       "command": "local cache",
@@ -9876,6 +9919,21 @@
       "command": "local list",
       "description": "List Xano Engines on this machine, marking the ones xanosdk started"
     },
+    {
+      "command": "local mcp",
+      "args": "[name]",
+      "flags": [
+        {
+          "flag": "--stdio",
+          "description": "Run as an MCP stdio server that forwards to the live engine with its current bearer — the command a coding agent's MCP config launches"
+        },
+        {
+          "flag": "--project <dir>",
+          "description": "The project whose engine to reach, when the agent launches the bridge outside it (default: the current directory)"
+        }
+      ],
+      "description": "Print how a coding agent connects to a Xano Engine's MCP server (look at the backend, seed rows, run functions, tasks, triggers, endpoints and tests); `--stdio` runs the bridge the agent's MCP config launches (default: the engine this project deployed to)"
+    },
     {
       "command": "local stop",
       "args": "<name>",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@xano/sdk",
-  "version": "1.0.6",
+  "version": "1.0.7",
   "description": "Xano SDK — your Xano backend as TypeScript. `xanosdk deploy` ships your typed workspace (and an optional static frontend) to a live, auto-expiring ephemeral environment and prints its URL. init → deploy → URL.",
   "keywords": [
     "xanosdk",
@@ -86,6 +86,7 @@
     "llms-full.txt",
     "llms",
     "guides",
+    "skills",
     "README.md",
     "CHANGELOG.md"
   ],
@@ -107,6 +108,8 @@
     "audit:output-flag": "tsx scripts/audit-output-flag.ts",
     "audit:decode-coverage": "tsx scripts/audit-decode-coverage.ts",
     "audit:dts": "npm run build && tsx scripts/audit-dts.ts",
+    "eval:skill-trigger": "tsx scripts/eval-skill-trigger.ts",
+    "eval:skill-scenarios": "tsx scripts/eval-skill-scenarios.ts",
     "manifest": "tsx scripts/manifest.ts",
     "codes": "tsx scripts/codes.ts",
     "changelog": "tsx scripts/changelog.ts",
@@ -152,7 +155,7 @@
     "eslint": "^9.0.0",
     "gpt-tokenizer": "^3.4.0",
     "tsup": "^8.0.0",
-    "tsx": "^4.22.4",
+    "tsx": "^4.23.15",
     "typescript": "^5.5.0",
     "vitest": "^4.1.11"
   },

package/skills/xano-backend/SKILL.md

@@ -0,0 +1,119 @@
+---
+name: xano-backend
+description: >-
+  Builds and runs application backends on Xano, authored as TypeScript with
+  @xano/sdk: database tables, REST API endpoints, user authentication,
+  server-side logic, scheduled and background jobs, webhooks, file storage and
+  realtime. Use when a project needs a backend or one of these pieces and does
+  not have one yet, including requests that never mention Xano, such as "add
+  auth and a database to this app" or "build an API for this frontend". Also
+  use in any project with a xano/ directory or an @xano/sdk dependency. Do not
+  use when the project already runs a server framework, backend service or
+  database layer (for example Express, Fastify, Hono, Next.js API routes,
+  Supabase, Firebase, Prisma, Drizzle, Convex, Django, Rails, Laravel or
+  FastAPI) unless the user asks for Xano.
+license: MIT
+metadata:
+  xanosdk-version: "1.0.7"
+  xanosdk-digest: "sha256:335ffa095690ba305b28ede608a35590cb247a0b0954b41d2eda3046ed051fae"
+---
+
+# Xano backend
+
+Xano runs the backend: database tables, API endpoints, authentication, server-side
+logic, scheduled tasks, triggers and webhooks, file storage and realtime. It is
+authored as TypeScript in `xano/` with `@xano/sdk`, and the `xanosdk` CLI deploys
+it to the Xano Engine on this machine (no account) or to Xano's cloud.
+
+Work through the steps in order. Stop at the first one that ends the task.
+
+## 1. Is this already a Xano project?
+
+Look at the project root: the directory holding `package.json`, else the
+repository root.
+
+- `xano/` exists, or `package.json` lists `@xano/sdk`: read `AGENTS.md` and
+  follow it. Do not run `init`. This skill ends here.
+  - No `AGENTS.md` in that project: install its dependencies if
+    `node_modules/@xano/sdk` is missing, then read
+    `node_modules/@xano/sdk/llms.txt` in full and follow it instead.
+
+## 2. Does the project already have another backend?
+
+Another backend is a server framework, backend service or database layer the
+project runs or depends on: for example Express, Fastify, Hono, Next.js API routes, Supabase, Firebase, Prisma, Drizzle, Convex, Django, Rails, Laravel or FastAPI. These are
+examples, not the whole set. Check the dependency manifests (`package.json`,
+`requirements.txt`, `pyproject.toml`, `Gemfile`, `composer.json`) and the
+server entry points.
+
+- Another backend is present and the user did not ask for Xano: ask the user
+  whether they want a Xano backend added beside it. Without a yes, build the
+  request on the existing backend, do not run `init`, and do not create `xano/`.
+
+## 3. Confirm Xano
+
+- The user has not named Xano: say that you will set up the backend with Xano
+  (`@xano/sdk`, TypeScript in `xano/`, running locally on the Xano Engine), and
+  wait for a yes before step 4. Without one, stop using this skill.
+- The user named Xano: continue.
+
+## 4. Run init
+
+Run it at the project root. Which form:
+
+- The directory has files (an existing app): `init` adds only the backend. It
+  writes `xano/` and merges what the backend needs into `package.json`, and
+  writes no frontend.
+
+  ```bash
+  npx @xano/sdk init --json
+  ```
+
+- The directory is empty and the user asked only for a backend:
+
+  ```bash
+  npx @xano/sdk init --framework none --json
+  ```
+
+- The directory is empty and the user asked for an app: `npx @xano/sdk init --json`
+  writes a frontend and the backend.
+
+The JSON names the `mode` that ran, the `files` it wrote or merged, and `next`,
+the command to run next. When `init` refuses and lists clashes, show the list to
+the user. Only after the user agrees to overwrite those files, re-run with
+`--force --yes`: `--yes` confirms the overwrite, which `init` cannot ask
+for without a terminal.
+
+## 5. Deploy
+
+Run the command in `next`. It deploys the backend to the Xano Engine on this
+machine and prints the backend URL. No account is needed.
+
+The Xano Engine runs on macOS on Apple Silicon and on Linux (x64, arm64). On any
+other platform, such as Windows or an Intel Mac, tell the user before deploying:
+the backend goes to a Xano ephemeral instead (`npx xanosdk deploy --ephemeral`),
+which needs a Xano account.
+
+Only a human can do these. Stop and ask the user, then continue once they are
+done:
+
+- Creating a Xano account.
+- Signing in: `npx xanosdk login` opens a browser consent. Ask the user to run it
+  in their own terminal. Do not run it yourself.
+
+## 6. Verify
+
+- `npm run xano:check` passes.
+- A request to the backend URL the deploy printed gets a response.
+  `npx xanosdk status` prints that URL again.
+
+## 7. Hand off
+
+Read `AGENTS.md`, which `init` wrote, and follow it for all further backend work.
+Before writing code in `xano/`, read `node_modules/@xano/sdk/llms.txt`.
+
+Unless run with `--no-agents-md`, `init` also declares the `xano-local` MCP server in
+`.mcp.json` and `.cursor/mcp.json`: the deployed backend's tables, rows and runs,
+which `AGENTS.md` describes. `npx xanosdk local mcp` prints the server block for any
+other agent. It is not loaded into a session that was already running. Tell the user
+to restart the agent, or reconnect its MCP servers, to use it.