@xano/sdk 1.0.3 → 1.0.5

package/guides/marketplace.md

@@ -126,15 +126,18 @@ flag that parses cleanly and then does nothing is worse than one that fails.
 `details` takes an npm package name or a slug. A miss prints the catalogue's own sentence
 plus a pointer at `search`, because a miss is usually a half-remembered name.
 
-A module that has been **removed** from the marketplace keeps its name reserved and is
-warned about before every output mode, `--prompt` included, on stderr so a piped prompt is
-unaffected. Soft-deleted modules are dropped from `list` entirely.
+A module that has been **removed** from the marketplace (`listed: false`) keeps its name
+reserved: `details` still answers it, with a warning before every output mode, `--prompt`
+included, on stderr so a piped prompt is unaffected. It is dropped from `list` and `search`
+entirely, and `install` refuses it.
 
 ### Pointing the reads somewhere else
 
 `XANOSDK_MARKETPLACE_URL` repoints all three read verbs. The catalogue host is otherwise
 hardcoded in a published package, so a move would break every installed copy of the CLI at
-once and only a release would fix it. See [Environment & identity](environment.md).
+once and only a release would fix it. A base with a path works too, so an ephemeral or a
+tenant (`https://<instance>/tenant/<name>`) can stand in for it. See
+[Environment & identity](environment.md).
 
 ## Installing
 

package/guides/project-structure.md

@@ -41,3 +41,17 @@ free to use any other layout; only `index.ts` registering the objects matters.
 Authoring is **declarative def-objects** passed to factories; there is no callback/chaining
 builder. `xano.export()` returns the importable `packageExport` bundle, and
 `xanosdk export`/`deploy` read the module's default export.
+
+## Wiring a project by hand
+
+`xanosdk init` writes all of this for you. Without it, two lines set a project up:
+
+```bash
+npm init -y && npm pkg set type=module && npm install -D @xano/sdk
+npx xanosdk upgrade     # rewrites npm's caret to the range init writes
+```
+
+Write your workspace in `xano/index.ts`; `login` and `deploy` are unchanged. `type=module`
+matters: Xano SDK defs are ESM-only, and `npm init` writes `"type": "commonjs"`. A TypeScript
+entry wants [`tsx`](https://tsx.is) (`npm i -D tsx`), which the CLI picks up — Node's type
+stripping does not remap a workspace's `./x.js` imports.

package/llms/client.md

@@ -40,11 +40,10 @@ by grepping `window.XANO_HOST` matches nothing and reads as a failed inject. Gre
 bare `XANO_HOST` token.
 **Frontend without the backend.** `xanosdk publish <dir> [--to <backend>]` uploads an
 already-built directory and nothing else — no compile, no import (scaffold script
-`npm run xano:deploy:frontend`). `publish` does not reach a local engine: after a local-engine
-deploy, pass `--to ephemeral`, or give the engine the frontend with
-`xanosdk deploy <entry> --local-engine --static <dir>` (served at `http://<prefix>.localhost:<port>`).
+`npm run xano:deploy:frontend`). A Xano Engine (`--to local`, or bare after a local
+deploy) serves it, server half included, at `http://<prefix>.localhost:<port>`.
 **Server-rendered SvelteKit.** `adapter()` from `@xano/sdk/sveltekit` (needs `esbuild`) writes
-the static half at the build's root plus a server half in `.xano-ssr/`. A local engine renders every
+the static half at the build's root plus a server half in `.xano-ssr/`. A Xano Engine renders every
 path that is not a file through it (`load` reads the engine's own URL as `XANO_HOST` from
 `$env/dynamic/private`; a rendered page gets the deploy's `window.XANO_HOST` too). Any other host
 is not sent `.xano-ssr/`: it serves the static half and answers other paths with the `404.html`

package/llms/errors.md

@@ -51,6 +51,6 @@ A failure document's `exitCode` matches.
 | 5 | `test` / `deploy --test`: the suite ran and a test failed. A deploy is not retracted. | Fix the test or the code. |
 | 6 | `test`, `deploy --test`: the suite could not be reached. | Check the backend; rerun. |
 | 7 | `upgrade --check`: an upgrade is available. | `xanosdk upgrade`. |
-| 8 | A named backend could not be addressed (or a named release, profile, branch, test, module, lock entry, `--seed` guid or local-engine version is missing): gone, expired, unreachable, a stopped local engine, or a busy import. | Retry, or redeploy. |
+| 8 | A named backend could not be addressed (or a named release, profile, branch, test, module, lock entry, `--seed` guid or Xano Engine version is missing): gone, expired, unreachable, a stopped Xano Engine, or a busy import. | Retry, or redeploy. |
 | 9 | A write whose outcome is unknown, Ctrl-C during a write included. | Read the target's state before retrying. |
 | 130 | Ctrl-C outside a write or install. | — |

package/llms/tests.md

@@ -51,9 +51,9 @@ The run is isolated in ways that make a correct test fail for reasons the failur
 
 `xanosdk test run-all` runs the unit tests AND the `workflowTest()` objects an environment carries. It takes no entry file and compiles nothing: it runs what is DEPLOYED, so deploy before testing.
 
-- `--on <backend>` picks the backend — `--on ephemeral:<name>`, `--on local-engine`, `--on tenant:<name>`, `--on workspace`; omitted, the one this project last deployed to (grammar: **Backends** in `llms.txt`). ⚠ `workspace` runs against the REAL database: safe only while every test keeps `datasource: ""`, since a stored non-empty datasource is CLONED before the run.
+- `--on <backend>` picks the backend — `--on ephemeral:<name>`, `--on local`, `--on tenant:<name>`, `--on workspace`; omitted, the one this project last deployed to (grammar: **Backends** in `llms.txt`). ⚠ `workspace` runs against the REAL database: safe only while every test keeps `datasource: ""`, since a stored non-empty datasource is CLONED before the run.
 - `xanosdk test list` shows what is there without running it; `test run "<name>"` runs one; an ambiguous name prints qualified forms (`function:math/happy path`, `workflow:<name>`) `run` accepts.
 - `--kind unit|workflow` narrows to one family. `--concurrency <n>` defaults to 1: tests share the environment database.
 - A failing suite exits 5; exit 6 when the suite could not be reached — retry it; a backend that can't be looked up exits 8 (see errors). Having no tests is success.
-- For CI: the exit code says THAT something failed, the JSON says WHICH. Progress goes to stderr; stdout carries one JSON document when not a terminal, or with `--json`. `run-all` and `run`: `{ kind, env, name, display, total, passed, failed, tests: [{ kind, name, qualified, object?, status: "pass"|"fail", message?, expectations?: [{ index, status, message? }], timing? }] }` (`message`: the first failure; `expectations`: a unit test's every expectation in order, `index` from 0; `env`: an ephemeral's or tenant's name; `name`: the backend's own, a local engine's too; null if none), same keys on an empty suite. `list` is `{ kind, env, name, display, total, tests }`; `deploy --test` nests the run under `testRun`.
+- For CI: the exit code says THAT something failed, the JSON says WHICH. Progress goes to stderr; stdout carries one JSON document when not a terminal, or with `--json`. `run-all` and `run`: `{ kind, env, name, display, total, passed, failed, tests: [{ kind, name, qualified, object?, status: "pass"|"fail", message?, expectations?: [{ index, status, message? }], timing? }] }` (`message`: the first failure; `expectations`: a unit test's every expectation in order, `index` from 0; `env`: an ephemeral's or tenant's name; `name`: the backend's own, a Xano Engine's too; null if none), same keys on an empty suite. `list` is `{ kind, env, name, display, total, tests }`; `deploy --test` nests the run under `testRun`.
 - `xanosdk deploy ./index.ts --test` deploys and then runs the suite against what it just shipped. A failure exits 5 WITHOUT retracting the deploy — the environment is live either way.

package/llms-full.txt

@@ -1,4 +1,4 @@
-# xanosdk v1.0.3
+# xanosdk v1.0.5
 
 > TypeScript SDK that compiles a typed Xano workspace into the importable packageExport JSON bundle.
 
@@ -155,19 +155,19 @@ export. Pruning, programmatic seeding, and which commands write the lock:
 `export` (honoring `xano.lock`), imports the result, and prints the URL.
 ⚠ Every deploy is a FULL REPLACE of its destination — objects AND records.
 
-**Backends** — one grammar: `workspace` | `ephemeral[:<name>]` | `local-engine[:<name>]`
+**Backends** — one grammar: `workspace` | `ephemeral[:<name>]` | `local[:<name>]`
 (no credential) | `tenant:<name>` | `release:<name>` | a bundle path where a file fits. Reads
 `--from`, writes `--to`, `test --on`; positional on `deploy`/`pull`/`generate`/`tables`/
-`impersonate`. Omitted = the ephemeral or local engine this project last deployed to, never
-workspace/tenant; bare `deploy` compiles the project onto an ephemeral instead (`--local-engine`:
-an engine on this machine), and `generate`/`init --from` need one. A refusal, typed or tracked,
-names the reason and the spellings (`publish`, `release create` refuse a local engine).
+`impersonate`. Omitted = the ephemeral or Xano Engine this project last deployed to, never
+workspace/tenant; bare `deploy` compiles onto the Xano Engine instead (`--ephemeral`: an
+ephemeral), and `generate`/`init --from` need one. A refusal, typed or tracked,
+names the reason and the spellings (`release create` refuses a Xano Engine).
 `release create --from` records a run: no bundle path, no `release:`,
 and a `tenant:` only if throwaway (`standard`/`run` refused).
 
-**Destinations** — ephemeral by default, real only when you say so:
+**Destinations** — the Xano Engine by default, real only when you say so:
 
-- `xanosdk deploy [source]` → a NAMED, auto-expiring ephemeral (~1h; `--expires-hours`
+- `xanosdk deploy [source]` → the Xano Engine on this machine (no account). `--ephemeral` → a NAMED, auto-expiring ephemeral (~1h; `--expires-hours`
   1–24), tracked in `./.xano/ephemeral.json`, so deploying again REFRESHES it at the same
   URL; if it expired or was swept, a fresh one is created and the new URL called out.
   ⚠ Only the BACKEND URL survives a refresh — the replace clears static hosting, so
@@ -670,11 +670,10 @@ by grepping `window.XANO_HOST` matches nothing and reads as a failed inject. Gre
 bare `XANO_HOST` token.
 **Frontend without the backend.** `xanosdk publish <dir> [--to <backend>]` uploads an
 already-built directory and nothing else — no compile, no import (scaffold script
-`npm run xano:deploy:frontend`). `publish` does not reach a local engine: after a local-engine
-deploy, pass `--to ephemeral`, or give the engine the frontend with
-`xanosdk deploy <entry> --local-engine --static <dir>` (served at `http://<prefix>.localhost:<port>`).
+`npm run xano:deploy:frontend`). A Xano Engine (`--to local`, or bare after a local
+deploy) serves it, server half included, at `http://<prefix>.localhost:<port>`.
 **Server-rendered SvelteKit.** `adapter()` from `@xano/sdk/sveltekit` (needs `esbuild`) writes
-the static half at the build's root plus a server half in `.xano-ssr/`. A local engine renders every
+the static half at the build's root plus a server half in `.xano-ssr/`. A Xano Engine renders every
 path that is not a file through it (`load` reads the engine's own URL as `XANO_HOST` from
 `$env/dynamic/private`; a rendered page gets the deploy's `window.XANO_HOST` too). Any other host
 is not sent `.xano-ssr/`: it serves the static half and answers other paths with the `404.html`
@@ -762,7 +761,7 @@ A failure document's `exitCode` matches.
 | 5 | `test` / `deploy --test`: the suite ran and a test failed. A deploy is not retracted. | Fix the test or the code. |
 | 6 | `test`, `deploy --test`: the suite could not be reached. | Check the backend; rerun. |
 | 7 | `upgrade --check`: an upgrade is available. | `xanosdk upgrade`. |
-| 8 | A named backend could not be addressed (or a named release, profile, branch, test, module, lock entry, `--seed` guid or local-engine version is missing): gone, expired, unreachable, a stopped local engine, or a busy import. | Retry, or redeploy. |
+| 8 | A named backend could not be addressed (or a named release, profile, branch, test, module, lock entry, `--seed` guid or Xano Engine version is missing): gone, expired, unreachable, a stopped Xano Engine, or a busy import. | Retry, or redeploy. |
 | 9 | A write whose outcome is unknown, Ctrl-C during a write included. | Read the target's state before retrying. |
 | 130 | Ctrl-C outside a write or install. | — |
 
@@ -819,11 +818,11 @@ The run is isolated in ways that make a correct test fail for reasons the failur
 
 `xanosdk test run-all` runs the unit tests AND the `workflowTest()` objects an environment carries. It takes no entry file and compiles nothing: it runs what is DEPLOYED, so deploy before testing.
 
-- `--on <backend>` picks the backend — `--on ephemeral:<name>`, `--on local-engine`, `--on tenant:<name>`, `--on workspace`; omitted, the one this project last deployed to (grammar: **Backends** in `llms.txt`). ⚠ `workspace` runs against the REAL database: safe only while every test keeps `datasource: ""`, since a stored non-empty datasource is CLONED before the run.
+- `--on <backend>` picks the backend — `--on ephemeral:<name>`, `--on local`, `--on tenant:<name>`, `--on workspace`; omitted, the one this project last deployed to (grammar: **Backends** in `llms.txt`). ⚠ `workspace` runs against the REAL database: safe only while every test keeps `datasource: ""`, since a stored non-empty datasource is CLONED before the run.
 - `xanosdk test list` shows what is there without running it; `test run "<name>"` runs one; an ambiguous name prints qualified forms (`function:math/happy path`, `workflow:<name>`) `run` accepts.
 - `--kind unit|workflow` narrows to one family. `--concurrency <n>` defaults to 1: tests share the environment database.
 - A failing suite exits 5; exit 6 when the suite could not be reached — retry it; a backend that can't be looked up exits 8 (see errors). Having no tests is success.
-- For CI: the exit code says THAT something failed, the JSON says WHICH. Progress goes to stderr; stdout carries one JSON document when not a terminal, or with `--json`. `run-all` and `run`: `{ kind, env, name, display, total, passed, failed, tests: [{ kind, name, qualified, object?, status: "pass"|"fail", message?, expectations?: [{ index, status, message? }], timing? }] }` (`message`: the first failure; `expectations`: a unit test's every expectation in order, `index` from 0; `env`: an ephemeral's or tenant's name; `name`: the backend's own, a local engine's too; null if none), same keys on an empty suite. `list` is `{ kind, env, name, display, total, tests }`; `deploy --test` nests the run under `testRun`.
+- For CI: the exit code says THAT something failed, the JSON says WHICH. Progress goes to stderr; stdout carries one JSON document when not a terminal, or with `--json`. `run-all` and `run`: `{ kind, env, name, display, total, passed, failed, tests: [{ kind, name, qualified, object?, status: "pass"|"fail", message?, expectations?: [{ index, status, message? }], timing? }] }` (`message`: the first failure; `expectations`: a unit test's every expectation in order, `index` from 0; `env`: an ephemeral's or tenant's name; `name`: the backend's own, a Xano Engine's too; null if none), same keys on an empty suite. `list` is `{ kind, env, name, display, total, tests }`; `deploy --test` nests the run under `testRun`.
 - `xanosdk deploy ./index.ts --test` deploys and then runs the suite against what it just shipped. A failure exits 5 WITHOUT retracting the deploy — the environment is live either way.
 
 # Agent and MCP def shapes

package/llms.txt

@@ -1,4 +1,4 @@
-# xanosdk v1.0.3
+# xanosdk v1.0.5
 
 > TypeScript SDK that compiles a typed Xano workspace into the importable packageExport JSON bundle.
 
@@ -155,19 +155,19 @@ export. Pruning, programmatic seeding, and which commands write the lock:
 `export` (honoring `xano.lock`), imports the result, and prints the URL.
 ⚠ Every deploy is a FULL REPLACE of its destination — objects AND records.
 
-**Backends** — one grammar: `workspace` | `ephemeral[:<name>]` | `local-engine[:<name>]`
+**Backends** — one grammar: `workspace` | `ephemeral[:<name>]` | `local[:<name>]`
 (no credential) | `tenant:<name>` | `release:<name>` | a bundle path where a file fits. Reads
 `--from`, writes `--to`, `test --on`; positional on `deploy`/`pull`/`generate`/`tables`/
-`impersonate`. Omitted = the ephemeral or local engine this project last deployed to, never
-workspace/tenant; bare `deploy` compiles the project onto an ephemeral instead (`--local-engine`:
-an engine on this machine), and `generate`/`init --from` need one. A refusal, typed or tracked,
-names the reason and the spellings (`publish`, `release create` refuse a local engine).
+`impersonate`. Omitted = the ephemeral or Xano Engine this project last deployed to, never
+workspace/tenant; bare `deploy` compiles onto the Xano Engine instead (`--ephemeral`: an
+ephemeral), and `generate`/`init --from` need one. A refusal, typed or tracked,
+names the reason and the spellings (`release create` refuses a Xano Engine).
 `release create --from` records a run: no bundle path, no `release:`,
 and a `tenant:` only if throwaway (`standard`/`run` refused).
 
-**Destinations** — ephemeral by default, real only when you say so:
+**Destinations** — the Xano Engine by default, real only when you say so:
 
-- `xanosdk deploy [source]` → a NAMED, auto-expiring ephemeral (~1h; `--expires-hours`
+- `xanosdk deploy [source]` → the Xano Engine on this machine (no account). `--ephemeral` → a NAMED, auto-expiring ephemeral (~1h; `--expires-hours`
   1–24), tracked in `./.xano/ephemeral.json`, so deploying again REFRESHES it at the same
   URL; if it expired or was swept, a fresh one is created and the new URL called out.
   ⚠ Only the BACKEND URL survives a refresh — the replace clears static hosting, so