@xanots/sdk 0.0.3 → 0.0.4

package/guides/cli.md

@@ -0,0 +1,191 @@
+# CLI
+
+Every `xanots` command, shell completion, and what the CLI prints when something fails.
+
+```bash
+xanots init my-app                         # scaffold a full project (frontend/ + xano/)
+xanots init my-app --framework svelte      # SvelteKit instead of the default React
+xanots init my-app --ai claude --no-install  # add CLAUDE.md; skip npm install
+xanots init my-app --theme zinc-blue --dark toggle --icons tabler  # the look
+xanots init my-app --marketplace @xanots/auth,@xanots/vector  # install add-ons AND register them
+
+xanots marketplace list                    # every published add-on (no login needed)
+xanots marketplace search auth             # narrow by keyword
+xanots marketplace details @xanots/auth    # what it installs + the registration to copy
+xanots marketplace details @xanots/auth --prompt  # …as a prompt for a coding agent
+xanots marketplace install @xanots/auth    # add an add-on to the project you're in
+
+xanots export ./xano/index.ts              # bundle to stdout
+xanots export ./xano/index.ts --out ws.json
+xanots compile ./xano/functions/get-user.ts  # a single function's JSON
+
+xanots export ./xano/index.ts --strict     # CI: fail the build on any warning, don't just print it
+xanots export ./xano/index.ts --lock       # opt into xano.lock (created beside the entry)
+xanots export ./xano/index.ts --frozen-lock  # CI guard: fail if the export would change the lock
+xanots lock rename --entry=xano/index.ts table users members  # move a lock entry after renaming in code
+xanots lock prune ./xano/index.ts --yes    # drop lock entries nothing exports anymore
+xanots lock prune --no-verify --entry=xano/index.ts --yes dbo:notes  # …or drop named keys without running the workspace
+xanots lock adopt live-export.json --entry=xano/index.ts --yes  # seed the lock from a live engine export
+
+xanots login                               # OAuth sign-in (once) — pick the instance + workspace at consent
+xanots workspace details                   # which instance/workspace am I bound to, and via which credential?
+xanots deploy ./xano/index.ts              # compile + import into a live ephemeral (the dev loop) → URL
+xanots deploy ./xano/index.ts --dest sandbox             # …or your throwaway singleton sandbox
+xanots deploy ./xano/index.ts --static ./frontend/dist   # also deploy a static frontend (onto the ephemeral)
+xanots deploy ./xano/index.ts --static ./frontend/dist --static-env PK=pk_live_1   # + extra public config
+xanots deploy --bundle ws.json             # deploy an already-exported bundle
+xanots deploy ./xano/index.ts --open       # …and open the deployed URL in your browser
+xanots ephemeral list                      # list your ephemeral environments (--all-workspaces spans every workspace)
+xanots ephemeral get <tenant>              # base URL, state, and expiry for one (<tenant> = the tenant name, e.g. ewap-8wz9-9e13, NOT the display name — `ephemeral list` shows it in bold)
+xanots ephemeral delete <tenant> --yes     # destroy one
+xanots ephemeral impersonate <tenant>      # open it in the builder (--guest = read-only; --url-only prints the URL instead)
+xanots release ./xano/index.ts --dry-run   # preview what promoting to your main workspace would change
+xanots release ./xano/index.ts             # promote: add + update, never delete, never touch table data
+xanots release ./xano/index.ts --prune     # …also delete objects this project released and no longer defines (needs xano.lock)
+xanots sandbox export                      # export the DEPLOYED sandbox workspace as a JSON bundle → ./sandbox.json
+xanots sandbox export --format multidoc --name backend               # …or the deployed sandbox as XanoScript → backend.xs
+xanots sandbox export --format multidoc --path -                     # …stream the multidoc to stdout (deploy first)
+xanots sandbox details                     # print the sandbox base URL + tenant details (pretty on a TTY, JSON when piped)
+
+xanots workspace details                   # which workspace your token is scoped to (instance, id, name, guid)
+xanots workspace export --path ws.json     # your REAL workspace as a JSON bundle (`--path -` streams to stdout)
+xanots workspace codegen my-app            # …or as a runnable project (the pull direction)
+xanots sandbox codegen my-app              # same, from your sandbox
+xanots ephemeral codegen <tenant> my-app   # same, from an ephemeral (tenant first, path second)
+xanots codegen ws.json my-app              # …or from a bundle already on disk (offline, no auth)
+
+xanots profile me                          # print the scoped user + instance base URL (pretty on a TTY, JSON when piped)
+xanots whoami                              # alias for `profile me`
+xanots logout                              # revoke the refresh token + clear the shared cache (--local for the project one)
+xanots version                             # print the installed @xanots/sdk version
+xanots upgrade --check                     # is a newer @xanots/sdk published? exits 7 if so, 0 if current
+xanots upgrade                             # install it (-g or -D, matching how this CLI is installed)
+xanots help                                # grouped command reference (also the no-arg default)
+xanots <command> --help                    # that command's usage, subcommands, and flags (`xanots deploy --help`)
+xanots <noun> <verb> --help                # scoped to one verb (`xanots workspace codegen --help`)
+xanots <command> --json                    # force JSON on stdout (otherwise: whenever stdout isn't a terminal)
+xanots completion zsh                      # shell completion script (also bash, fish) — see below
+
+xanots validate ./xano/index.ts            # import into a live instance, diff each object back
+xanots validate ./xano/index.ts --runtime  # also run each deployed function on the engine
+xanots validate ./xano/index.ts --capture  # write the fetched JSON as fixture candidates
+```
+
+## Bundle key names vs. the names everything else uses
+
+A bundle's `payload` arrays are keyed by the engine's **storage** name, which for five kinds
+is not the name the SDK, the CLI, or a release plan uses for the same thing. Scripting against
+a bundle means translating:
+
+| You author / the plan reports | `payload` array |
+|---|---|
+| `table` | `payload.dbo` |
+| `api_group` | `payload.app` |
+| `agent` | `payload.toolset` |
+| `mcp_server` | `payload.toolset` |
+| `toolset` | `payload.tool` |
+| `realtime_channel` | `payload.channel` |
+| `realtime_message` | `payload.message` |
+
+Everything else (`query`, `function`, `task`, `trigger`, `middleware`, `microservice`,
+`addon`, `workflow_test`, `workspace`) is keyed the same on both sides.
+
+Two traps worth naming. A release plan reports operations as `{"type": "table", …}` while the
+bundle it came from stores that object under `payload.dbo` — so a table that released
+correctly looks *missing* if you go looking for `payload.table`. And `agent` and `mcp_server`
+both land in `payload.toolset`, while the kind actually named `toolset` lands in
+`payload.tool`; matching on the word alone will pick the wrong array.
+
+This is also the format `xanots lock adopt` reads, so both directions are user-facing.
+
+
+**Build warnings, and `--strict`.** `export`/`deploy` print a `xanots:` warning for the
+shapes that ship clean and then do the wrong thing — a `bulk.update` zero-filling the columns
+an item omits, an `ignoreEmpty` on an operand that's already empty, a `ref()` no `as` binds,
+a filter name the engine can't resolve, a `s.switch` case that falls through into the next
+one, a request-time timestamp filter on a `where` operand. Each stays a warning because each
+has a legitimate use. Nothing fails on a message nobody reads, though, so pass `--strict` in CI and in
+unattended agent builds: every warning becomes a hard failure and the exit code carries it.
+The programmatic equivalents are `emitBundle(app, { strict: true })` and
+`app.export({ strict: true })`. The bundle bytes are identical either way.
+
+## Shell completion
+
+`xanots completion <bash|zsh|fish>` prints a completion script covering every command, verb, flag,
+and closed value set (`--dest ephemeral|sandbox`, `--format json|multidoc`, `--ai claude|codex|cursor|none`).
+It is generated from the CLI's own command table, so it never drifts from what the CLI accepts — but it
+is baked at generation time, so re-run it after upgrading.
+
+```bash
+# zsh
+xanots completion zsh > "${fpath[1]}/_xanots"   # then restart your shell
+
+# bash
+xanots completion bash > ~/.xanots-completion.bash
+echo 'source ~/.xanots-completion.bash' >> ~/.bashrc
+
+# fish
+xanots completion fish > ~/.config/fish/completions/xanots.fish
+```
+
+After a command succeeds the CLI checks npm (at most once an hour, cached in
+`~/.xanots/update-check.json`) and prints a one-line nudge to **stderr** when a newer
+`@xanots/sdk` is published — never to stdout, so piped bundles stay clean. The suggested
+command adapts to how you installed it (`npm i -g …` for a global install, `npm i -D …`
+when it's a project dependency). The check is best-effort and bounded (a slow or offline
+registry never delays a command), and stays silent under CI or when stderr isn't a terminal.
+Opt out with `XANOTS_NO_UPDATE_CHECK=1` (or the conventional `NO_UPDATE_NOTIFIER=1`).
+
+`xanots upgrade` is the same question asked on purpose, and it answers under all the
+conditions the nudge stays quiet for — CI, a piped stderr, the opt-out variables — reading the
+registry live rather than serving the hourly cache. `--check` reports without installing and
+exits **7** when a newer version is published, **0** when you are current, so a pipeline can
+branch on it:
+
+```bash
+xanots upgrade --check || echo "an upgrade is waiting"
+xanots upgrade --check | jq -r .latest        # piped stdout is JSON already
+```
+
+A registry it cannot reach is an error (exit 1), never a quiet "you are up to date". Without
+`--check` it installs, matching how this CLI is installed — and for a project-local install it
+then restores the `@xanots/sdk` range your project was scaffolded with (npm rewrites it to a
+caret, which on the `0.0.x` line pins you exactly) and restamps the managed block in your
+agent files so the guidance matches the version you now have. Set `XANOTS_INSTALL_MODE` to
+`global` or `local` to override the detection.
+
+## When something fails
+
+Failures are written for the person reading the terminal. A request the instance refused
+prints the server's own sentence on one line (`deploy failed (403 Forbidden): Access denied
+for this workspace.`) rather than the whole JSON envelope; a request that never arrived names
+what it could not reach and why (`workspace list could not reach https://…: fetch failed
+(ECONNRESET)`), and a request that timed out says so separately, because "slow" and
+"unreachable" call for different next steps. Set `XANOTS_DEBUG=1` to append the untouched
+response body underneath — nothing is discarded, only folded away.
+
+A malformed invocation fails before any work happens: a missing or misspelled entry file, an
+argument the command has nowhere to put (`xanots export --lock xano.lock` — that flag takes
+its value attached, as `--lock=xano.lock`), or a missing credential, each answered with the
+command's usage block instead of a stack trace. `deploy` and `release` check that you are
+signed in *before* compiling, so a lapsed session costs you a message, not a build.
+
+Emitters that write to disk (and the programmatic CLI) are Node-only — import them from
+`@xanots/sdk/node`. The string emitters (`emit`, `emitBundle`) stay on the browser-safe
+`@xanots/sdk` entry.
+
+```ts
+import { emitBundle } from "@xanots/sdk";        // pure string — browser-safe
+import { writeBundle } from "@xanots/sdk/node";  // writes a file — Node only
+```
+
+**Four entry points, and only the first is the authoring API.** `@xanots/sdk` is what you
+define a workspace with; `@xanots/sdk/node` adds the filesystem half; `@xanots/sdk/codegen`
+is what a generated tree imports; and `@xanots/sdk/internal` holds the compiler machinery —
+the per-kind encoders, the kind and statement registries, the bundle serializer, the
+`xano.lock` model. Nothing on `/internal` is needed to author anything, and it is kept off
+the root so an agent scanning the package's exports sees the surface rather than the guts.
+
+All three run the same build-time checks, including seed validation of a literal
+`seed: [...]` array. A **deferred** seed (a thunk, or `seedFile()`) needs an await or the
+filesystem, so it is materialised and checked only by `xanots export` / `xanots deploy`.

package/guides/codegen.md

@@ -0,0 +1,83 @@
+# Pulling an existing workspace
+
+What `xanots codegen` writes, how faithful the pull is, and how to read its report.
+
+## The generated tree
+
+Inside, `xano/` is shaped the way the workspace is: one directory per kind, with each
+object under its parent — queries under the API group that owns them, triggers under
+what they fire on. Each table gets its own `table/<name>.ts`, settings sit in `xano/workspace.ts`,
+`_shared.ts` holds anything else referenced from more than one file, and `xano/README.md`
+lists anything that did not translate cleanly.
+Object identities (`guid`) are preserved, so cross-references stay intact. A statement
+this SDK does not model yet round-trips verbatim rather than breaking the pull.
+
+Pulled objects are authored the same way you would write them by hand — `table({...})`,
+`query({...})`, `defineFunction({...})` — so the generated tree keeps its types. A pulled
+table's columns still check on `fieldName`/`output`/`sortBy`, `InferInput<typeof q>` still
+resolves a pulled query's payload, and a pulled agent still types `s.ai.agent.run`.
+
+A pull states what the source workspace actually holds and leaves out what the SDK would
+put back anyway. A table's `primary(id)` / `created_at` / `gin(xdo)` indexes are the
+engine's standard set, so only the indexes someone created are listed. A trigger comes back
+through the factory that built it (`tableTrigger`, `realtimeTrigger`, …) rather than a bare
+`satisfies TriggerDef`, which keeps its typed stack handle; the two realtime types that bind
+a def handle are the exception, since a stored trigger carries two guids with no way to know
+they agree. And two objects that reference each other — a pair of tables joined both ways,
+two functions that call each other — can't both be declared first, so the second reference
+is a `{name, guid}` const hoisted to the top of the file (`const OrdersRef = {…}`) instead of
+an import that would close a cycle. Only the guid is ever read, so it binds exactly.
+
+`xano/README.md` also lists objects that were **already empty in the source** — an
+endpoint someone created and never filled in pulls as a def with no `stack`, which looks
+identical to a decode that gave up. The report is what tells the two apart.
+
+A few options exist only so a pull can be *faithful*, and reading them in generated code
+is the only time you should see them: `table: null` / `fn: null` (a statement whose target
+was deleted or never bound), `merge` / `hidden` on a field, `paging: { enabled }` on a
+query, `c.blank(tag)` (the editor's unconfigured value box — **not** a zero or an
+empty collection; the engine reads `""` and `"0"` differently, so tidying one into the
+other changes what the workspace stores), and `c.null("const:obj")` (the object-typed null
+a `db.*` statement's `@meta` slot carries — different stored bytes from `c.obj(null)`,
+which is the blank object, though both evaluate to null). They describe what the source workspace actually
+stored — a pulled `table: null` is a defect to fix upstream, not a shape to copy — and
+each carries that warning at the call site. A blank binding also reports, because a
+statement wired to a table or function that no longer exists is worth seeing even though
+it round-trips exactly.
+
+## Verification, and the decode report
+
+Then it checks its own work: the project it just wrote is loaded, exported, and diffed
+against the workspace it came from. A mismatch names the object and fails the command
+(`--no-verify` opts out). So "it compiled" and "it means the same thing" are separate
+claims, and you get both.
+
+The findings above are printed either way. Verification runs after decoding is finished,
+so whether it passes, disagrees, or cannot run at all, the report describing the decode is
+rendered first — and a tree that was written but does not re-export exits **2**, distinct
+from the **1** you get when nothing was written because the bundle could not be read.
+
+**Reading the report.** It opens with a headline (`27 distinct issues across 424 findings;
+3 need your attention`) and splits into three sections, most actionable first: *problems in
+your workspace*, *things XanoTS could not model*, and the things stated only so the output
+is not ambiguous. That split is the question a reader actually has — a `raw()` passthrough
+is ours to close, a lambda reading an unbound name is theirs to fix, and an empty object is
+neither. Findings that repeat the same sentence across objects collapse to one line with a
+count and a collapsed object list, and each names the generated file it landed in.
+`--report full` prints every site instead; `--report json` prints the findings as data, and
+the same data is written into `xano/.xanots-codegen.json` on every pull, so parity is
+trackable release over release and gateable in CI without scraping output.
+
+Re-pulling is a real workflow: a second `codegen` into the same directory refreshes
+`xano/` and leaves the rest of the project — your `package.json`, your `frontend/` —
+exactly as you left it. No `--force` needed, because the tree carries a marker saying it
+was machine-written.
+
+> ⚠️ **`xano/` is a scratch surface, and there is no `xanots workspace deploy`.**
+> Regenerating rewrites it (a directory that isn't a previous pull still needs `--force`),
+> it carries schema only — no table rows — and deploying it is a *full replace* of the
+> target. Pull from your real workspace, edit, and `deploy` to a disposable ephemeral or
+> sandbox. Workspace env var **values** ride inline in `xano/workspace.ts` (that is what a
+> deploy sends), so treat a pulled tree as secret-bearing before you commit it.
+
+---

package/guides/coverage.md

@@ -0,0 +1,67 @@
+# Coverage & agent grounding
+
+What XanoTS covers against the engine catalog, what is deliberately out of scope, and the machine-readable grounding it ships for agents.
+
+## Coverage & scope
+
+XanoTS emits only (the engine imports/executes). Fidelity is proven by deep-equal against
+the real Xano engine golden fixtures, and a coverage report prints on every test run.
+
+| Surface | Coverage |
+|---|---|
+| Object kinds | **25 / 31** — counted over the engine's catalog, where each trigger type is its own kind |
+| Statements (via `s`) | **214 / 214 (100%)** — every engine statement surface has a factory |
+| Filters (via `fl`) | **226 / 226 (100%)** — every filter's signature is known: 131 carry arguments, 95 take none |
+
+The six engine kinds you cannot author here are `tablemap`, `run.job`, `run.service`, the
+superseded `realtime_channel`, and — correctly, since they are instance state rather than
+workspace source — `branch` and `market_item`. `llms.txt` names them with
+their reasons. `llms.txt` and `manifest.json` regenerate their counts from the SDK's own
+catalogs; this table is hand-written, so a test asserts every figure in it against
+`buildManifest()` (`@xanots/sdk/internal`) — the numbers here and the numbers an agent
+reads cannot disagree.
+
+The statement catalog is generated from the engine's own schemas (`npm run codegen`): 149 of
+the 214 surfaces are declarative and carry a typed field schema, and the remaining 65 —
+control flow, the `db` family, the call family — are hand-authored. **Reachable ≠ byte-verified**: every surface is
+authorable, but a structural special without a persisted golden yet emits a shape *modeled*
+on the engine schema, to be deep-equal'd against fixtures as they are captured.
+
+**Out of scope** — reimplementing the engine's XanoScript parser, executing objects at
+runtime (XanoTS only compiles), and generating engine-side numeric ids/timestamps.
+(Object guids and canonicals *are* handled — deterministically derived or frozen via
+`xano.lock`.)
+
+**Deferred (by design)** — folder auto-discovery, and the `service` / `vault` / `branch`
+payload sections. (Round-trip decompile is no longer deferred: that is
+`xanots codegen`, in the [CLI guide](cli.md); nor is `workflow_test` — it is a
+first-class kind, see `workflowTest` in [Object kinds](object-kinds.md).) `InferResponse`
+auto-derivation covers the object-literal and single-`db`-variable cases (matching the engine's
+static walk), and follows a CALL into the object it invokes (`s.function.call`/`.run`,
+`s.tool.call`, `s.api.call` given a def handle bind the target's own `InferResponse`);
+a response variable produced inside control flow or `set_var`, and addon/related-field
+keys, resolve to `unknown` — declare `responseShape` for those.
+
+## Agent grounding
+
+XanoTS ships two machine-readable descriptions of its whole authoring surface so an agent
+can learn the SDK without reading source:
+
+- **`llms.txt`** — the always-read router: the mental model, the deploy contract, control
+  flow, the non-obvious rules in `## Gotchas`, and a `## Topic files` list naming each
+  **`llms/*.md`** and when to open it. It does not document the CLI — `xanots <command>
+  --help` and the `cli` array in `manifest.json` do, from the same registry that generates
+  the shell completions. The written version is the [CLI guide](cli.md).
+- **`llms/*.md`** — one file per surface (object def shapes, statements, values, fields,
+  filters, lambda bodies, and the legacy names a pulled workspace carries), read only when
+  that surface is in play. **`llms-full.txt`** is all
+  of them concatenated, for a reader that wants one file rather than two.
+- **`manifest.json`** — the exhaustive reference tier, reached by targeted lookup (grep or
+  `jq` one entry; never read it whole). Every object kind (factory, `Xano.register*` method,
+  payload key), every statement surface (the `s.<path>` accessor, stored `mvp:` name, and a
+  typed field schema for the 149 declarative statements), the value constructors, the tag
+  catalog, the filter catalog, and every CLI command and flag — plus live coverage counts.
+
+Both derive from the SDK's own sources of truth (so they can't drift), regenerate with
+`npm run manifest`, and are available at runtime via `buildManifest()` / `renderLlmsTxt()`,
+both exported from `@xanots/sdk/internal`.