@blotout/qinto-cli 0.1.0

package/README.md

@@ -0,0 +1,373 @@
+# @blotout/qinto-cli
+
+The Qinto platform CLI. Authenticate against the Qinto platform and operate it from the terminal — or from an AI agent.
+
+## Install
+
+```sh
+npm i -g @blotout/qinto-cli
+```
+
+Needs Node.js 24 or newer. The command is `qinto`.
+
+## Log in
+
+```sh
+qinto login
+```
+
+`login` opens your browser on the Qinto consent screen. Authorize one, several, or all of your current teams; each team receives
+the strongest access your role allows there. By default the CLI requests full access (every scope the platform supports, plus
+`offline_access` for silent renewal and `profile` for your account identity); pass `--scopes` to narrow the request.
+
+```sh
+qinto whoami          # who am I, with my teams, organizations, and scopes
+qinto whoami --json   # the same identity as JSON
+qinto env             # choose which Qinto every command talks to
+qinto team            # list authorized teams and mark the active one
+qinto team active     # choose the local default team
+qinto team active <teamId>
+qinto logout          # revoke the session on the server, then clear local credentials
+```
+
+The active team is a local default, not an authorization boundary. Use `--team <teamId>` on a command for a one-off override.
+`qinto login --team <teamId>` preselects that team during consent and prefers it as the active team afterward; use
+`--reauthorize` to force the consent screen. A plain login preserves the active team while it remains authorized. The CLI
+revokes the login it replaces; if that revocation fails, it is remembered and retried on the next login or logout.
+
+## Onboard a domain
+
+```sh
+qinto domain onboard example.com
+qinto domain dns shop.example.com
+```
+
+`domain onboard` guides a human through team confirmation, managed or self-hosted infrastructure, advanced placement settings,
+DNS records, optional email sharing, delivery, deployment, and the final integration snippet. Switching teams in this flow also
+updates the saved active team. DNS can remain pending without making onboarding fail; resume with the secret-free command printed
+by the CLI, or force a fresh check later with `qinto domain dns [siteId-or-hostname]`.
+
+Every prompt has a flag, so a full onboarding can be supplied up front. `qinto describe domain onboard` prints the same list as a
+machine-readable spec.
+
+| Flag | What it does |
+| --- | --- |
+| `--team <teamId>` | Use this authorized team without changing the active team. |
+| `--mode <mode>` | Choose the infrastructure: `managed` or `self`. |
+| `--name <name>` | Site display name. |
+| `--subdomain <subdomain>` | Site subdomain; also matched against existing sites to detect a resumable one. |
+| `--jurisdiction <jurisdiction>` | Choose the EU (`eu`) or US (`us`) data jurisdiction. |
+| `--location-hint <locationHint>` | Place site state near a Cloudflare region: `wnam`, `enam`, `weur`, `eeur`, `apac`, or `oc`. |
+| `--delivery <delivery>` | Serve from the customer domain (`domain`) or a development URL (`development-url`), even while DNS is pending. |
+| `--site <siteId>` | Resume onboarding an existing site instead of creating one. |
+| `--share-dns <emails>` | Email DNS instructions to 1–10 comma-separated recipients. |
+| `--share-submission-id <submissionId>` | UUID used to retry DNS sharing idempotently. |
+| `--host-id <hostId>` | Use an existing self-host (requires `--mode self`). |
+| `--host-name <name>` | Display name for a new self-host (requires `--mode self`). |
+| `--cloudflare-account-id <accountId>` | Cloudflare account ID for a new self-host (requires `--mode self`). |
+| `--host-zone <zone>` | Cloudflare zone to use for the self-host. |
+| `--workers-for-platforms` | Enable Workers for Platforms on a new self-host. |
+| `--no-input` | Disable all interactive prompts. |
+| `--json` | Print a structured onboarding state as JSON. |
+
+Re-running onboarding after an abort tries not to create a duplicate site. The CLI canonicalizes the given domain the way the
+server does (`https://www.example.com/` and `example.com` name the same site) and looks for existing sites on it: interactively
+it offers to resume one or create a new site, and in machine mode it fails with the candidate ids so a script passes `--site
+<siteId>` to resume or `--subdomain` to force a new site. Detection is best-effort — it needs `team:read` to list the team's
+sites, so a credential that only carries `domain:write` skips the check and creates a new site on every run. Resume by id
+instead: right after a site is created the CLI prints its id and a resume command to stderr, and if onboarding fails after that
+the error names the site and the same command. A resume command is `qinto domain onboard --site <siteId> --team <teamId>`,
+followed by whatever names the environment it ran against (`--env sandbox`, or `--api-url <origin>`, and nothing for
+production); when it is produced for a machine it also carries `--no-input --json`.
+
+For automation or an AI agent, use `--json`, `--no-input`, or a non-interactive terminal. Supply every conditional input up front:
+
+```sh
+qinto domain onboard example.com --mode managed --team <teamId> --no-input --json
+qinto domain onboard example.com \
+  --mode self \
+  --host-name production \
+  --cloudflare-account-id <accountId> \
+  --workers-for-platforms \
+  --no-input \
+  --json
+qinto domain dns <siteId> --team <teamId> --json
+```
+
+Set `QINTO_CLOUDFLARE_API_TOKEN` when connecting a new self-host non-interactively. The token has no command-line flag and is never
+included in JSON, output, or resume commands. Structured onboarding results use `host_setup_pending`, `dns_pending`, or `complete`;
+all obtained pending states exit `0`, operational failures exit `1`, and invalid or incomplete invocations exit `2`.
+
+## Build an app
+
+An app is code you write that runs on the Qinto platform: a **transform** rewrites, enriches, or drops events before destinations
+see them, and a **destination** receives events after transforms ran and forwards them onward. An app belongs to an
+**organization** and is published as immutable **versions**; a team then installs a version on one of its **sites**.
+
+The whole loop is a handful of commands:
+
+```sh
+qinto app create my-app                       # scaffold, install, and offer to register
+qinto app dev                                 # run it against a local Qinto
+qinto app publish                             # build, upload, and publish a version
+qinto app publish --site example.com          # …and install it on a site
+qinto app status my-app --site example.com    # desired vs deployed state
+```
+
+### Scaffold — `qinto app create [dir]`
+
+Asks for the app name, proposes a slug derived from it that you confirm or replace, and asks which template to start from. It
+then writes the scaffold, installs its dependencies, and offers to register the app under one of your organizations so you do
+not have to call `qinto app register` yourself; answer no, or pass `--no-register`, to scaffold only. In machine mode nothing is
+registered unless you pass `--register`.
+
+Two templates:
+
+| Template | What you get |
+| --- | --- |
+| `minimal` | `qinto.app.jsonc`, `package.json`, `tsconfig.json`, and a `src/server.ts` with one `track` hook. |
+| `full` | The same, plus a `transform` hook, a `src/browser.ts` bundle, a D1 database that records every `Purchase` (order id, value, and the SHA-256 of the visitor's email), three install variables, and the Astro UI panel under `ui/`, wired to the platform through `@blotout/qinto-sdk-app/ui`. |
+
+The `full` app forwards events to an endpoint the site manager supplies. Both that endpoint and its API key are `required`
+variables, so the install stays inactive — and the app sends nothing anywhere — until they are filled in.
+
+The install runs `npm install` in the app directory — and in `ui/` when a panel was scaffolded. A failed install keeps the
+scaffold and names the command to rerun, but exits `1`, so a script does not publish an app with no dependencies.
+`--no-install` skips the install and exits `0`.
+
+The panel imports `@blotout/qinto-sdk-app/ui` and resolves it from the app's own dependency one directory up, so `ui/package.json`
+declares only its build tooling.
+
+| Flag | What it does |
+| --- | --- |
+| `--name <name>` | App display name. |
+| `--slug <slug>` | Immutable app slug: 3–30 lowercase letters, digits, and hyphens, starting with a letter. Derived from the name when omitted. |
+| `--template <template>` | `minimal` or `full`. Prompted when omitted; `minimal` without prompts. |
+| `--ui` | Also scaffold the Astro UI panel under `ui/` and wire `ui` into the manifest. The `full` template always has one. |
+| `--no-install` | Skip installing the scaffold dependencies. |
+| `--register` / `--no-register` | Register the app after scaffolding, or skip the offer entirely. |
+| `--org <organization>` | Owning organization id or name when registering (prompted when ambiguous). |
+| `--no-input` | Disable all interactive prompts. |
+| `--json` | Print the scaffolded files — and the registered app, when one was created — as JSON. |
+
+`qinto app add ui [dir]` adds the same UI panel to an app that was scaffolded without one, and installs it.
+
+### Register — `qinto app register`
+
+Registers the slug under an organization. `create --register` calls it for you; run it directly to register an app you scaffolded
+earlier or wrote by hand. The slug is immutable and unique inside the organization.
+
+```sh
+qinto app register --slug my-app --name "My App" --org Acme --description "What it does."
+qinto app list           # every app across your organizations
+qinto app list --json
+```
+
+### Develop locally — `qinto app dev [dir]`
+
+`dev` runs your app against a local Qinto. It boots the **released site worker and app runtime** — the same bundles a deploy
+uploads — inside workerd, so the transform chain, the consent gate, the fan-out envelope, the app runtime and `/q.js` assembly are
+the real ones rather than a simulation. Nothing is uploaded, no Cloudflare account is involved, and no login is needed: the CLI
+ships the platform bundles and prints the version it is running.
+
+```sh
+qinto app dev                 # from inside the app directory
+qinto app dev ./apps/my-app
+```
+
+```
+  My App (my-app) — local Qinto on platform 0.1.0
+
+  Console       http://127.0.0.1:4300
+  Demo site     http://127.0.0.1:4301
+  Site worker   http://127.0.0.1:4310
+  Dev state     ~/.qinto/dev/8f3c1a2b4d5e6f70
+  Site token    qwat_dev_…
+
+  The app is not installed yet.
+```
+
+Three surfaces, one per side of the product:
+
+- **The console** is the platform's side. A team and the site `dev.localhost` are seeded for you; install the app there, turn it
+  on and off, manage its installs, and fill in the variables the manifest declares. It renders the same form the Qinto platform
+  does — text, toggle, and write-only secrets — and an install stays `inactive`, receiving nothing, until every `required`
+  variable is filled in. Adding an install is offered only for an app whose manifest sets `install.multiple`, and the last
+  install is never removable — uninstall the app instead.
+- **The demo site** is the customer's page. It loads `q.js` from the local site worker and drives every method the tag exposes —
+  `track`, `identify`, `consent`, `alias`, `getSession` — then shows which app bundles `q.js` carried and which installs
+  activated. Its **Events** panel has a button for each of the eleven standard events in
+  [the standard events reference](https://docs.qinto.io): selecting one loads its documented payload into an editable box,
+  and **Track it** sends whatever is in it, so you can fire the real shape or your own. Every event reaches your hooks;
+  only one carrying a numeric `value` and a non-empty `orderId` — `Purchase`, among the standard ones — is also recorded as a
+  conversion in the identity graph.
+- **The terminal** streams the trace of every request, your app's own `ctx.observability` lines included: they arrive in the same
+  trace as the site worker's spans, exactly as they do in the Qinto platform's real-time logs.
+
+`dev` builds the app the way `publish` does — the same esbuild bundles, and the same cross-check that event/lifecycle hooks,
+backfill handlers, and workflows match the manifest — so a mismatch fails here instead of at dispatch. A `d1` resource's phased
+`migrations` use the same statement ledger and backfill checkpoints as a deployed app: rerunning `dev` applies only what is new,
+and an entry changed after it was applied is refused by id and checksum.
+
+Everything the session persists — the install, its variables and secrets, and every Durable Object, D1, KV and R2 the two workers
+wrote — lives in `~/.qinto/dev/<project>/`, outside your app directory, so a restart resumes where you left off and the plaintext
+secrets file can never be committed. `--reset` discards all of it.
+
+| Flag | What it does |
+| --- | --- |
+| `--console-port <port>` | Port the console is served from (default `4300`). |
+| `--demo-port <port>` | Port the demo site is served from (default `4301`). |
+| `--worker-port <port>` | Port the local site worker listens on (default `4310`). |
+| `--reset` | Discard this project's local install, variables, secrets and stored data first. |
+
+All three listeners bind `127.0.0.1` only.
+
+One thing behaves differently from a deployed site, and `dev` says so rather than letting you discover it:
+
+- **`ai`, `vectorize`, and a `hyperdrive` with no local database URL are not bound.** Each needs a Cloudflare account or a
+  database only you can name, so the app boots without those bindings and the start-up banner lists them. Give a hyperdrive its
+  local URL in the console to bind it — the origin in your manifest is the *deployed* database and is never used here.
+
+**The UI panel.** When your manifest declares a `ui` block, `dev` runs its build with the same base path a published panel is
+served under — `/<appId>/<version>/` — and serves the result on its own port (`--ui-port`, default 4302). **Apps → Panel** in
+the console frames it there. That port is deliberately not the console's: the panel is cross-origin, exactly as it is in
+production, so the `postMessage` origin and `event.source` checks on both sides are the real ones. The console mints a real
+app-UI token, so the panel's calls to `${ctx.siteOrigin}/apps/<slug>/ui/*` go through the site worker's own claim checks.
+
+### Publish — `qinto app publish [dir]`
+
+`publish` reads `qinto.app.jsonc`, allocates a draft version, builds, uploads, and finalizes it. Each step is recorded in
+`.qinto/publish.json`, so an interrupted publish resumes where it stopped when you rerun it with the same arguments; `--restart`
+discards that state. A directory-level lock (`.qinto/publish.lock`) stops two publishes racing in the same checkout.
+
+What a publish does, in order:
+
+1. **Allocate** a version — `--bump patch|minor|major` (default `patch`) from the highest ready version, or `--version x.y.z`.
+2. **Build** `server.entry` with esbuild, and `browser.entry` too when the manifest declares one. The built server bundle is
+   imported; its event/lifecycle hooks, backfill handlers, and workflows are compared against the manifest before anything is
+   uploaded.
+3. **Build the UI panel**, when `ui` is declared, with the panel's own base path injected, then check that no asset in the
+   built HTML points outside that prefix.
+4. **Declare and upload** the artifacts. Each upload is presigned against the declared SHA-256, so what lands in storage is
+   exactly what was built. Redeclaring replaces the previous declaration, so a failed upload is fixed by publishing again.
+5. **Finalize** the version. `artifacts_stale` means the manifest changed after the build; the CLI rebuilds and redeclares once
+   by itself.
+6. **Install**, when `--site` is given.
+
+| Flag | What it does |
+| --- | --- |
+| `--bump <level>` | `patch` (default), `minor`, or `major`, from the highest ready version. |
+| `--version <version>` | Allocate this exact `x.y.z` instead of bumping. |
+| `--org <organization>` | Owning organization id or name, when the slug exists in several. |
+| `--site <site>` | Install the finalized version on this site (hostname or domain id). |
+| `--team <teamId>` | Authorized team to resolve `--site` in. |
+| `--accept-capabilities` | Accept the extra capabilities a newer version asks for. |
+| `--acknowledge-necessary` | Record that this app runs without visitor consent. |
+| `--dry-run` | Build and validate locally; allocate nothing and upload nothing. |
+| `--restart` | Discard `.qinto/publish.json` and start a fresh publish. |
+| `--no-input` | Disable all interactive prompts. |
+| `--json` | Print the published version, and the install when `--site` was given, as JSON. |
+
+Installing a version the visitor's consent or the capability set does not already cover fails until you accept it. Interactively
+the CLI asks; in machine mode it exits `2` and names the flag to pass.
+
+### Inspect — `status`, `versions`, `version cancel`
+
+```sh
+qinto app status my-app --site example.com     # desired vs deployed version, installs, endpoints, grants
+qinto app versions my-app                      # every version, drafts included
+qinto app versions my-app --limit 20 --json
+qinto app version cancel my-app 1.4.0          # release a draft this checkout holds
+```
+
+`status` is the one command that answers "did my publish land": `desired` is what you published and installed, `deployed` is what
+the site's worker is actually running, and an install is `inactive` until every required variable is filled in. A **draft** is a
+version that was allocated but never finalized; cancelling one frees its version number. Only the checkout that holds the draft
+can cancel it — an organization owner unwedges an abandoned draft with `--force`.
+
+### The manifest — `qinto.app.jsonc`
+
+`qinto.app.jsonc` is the app: it is JSONC (comments and trailing commas allowed), it is validated before every publish, and its
+digest is what the version is finalized against. Every field and option is documented in
+[the manifest reference](https://docs.qinto.io); the summary:
+
+| Field | What it declares |
+| --- | --- |
+| `$schema` | The JSON Schema your editor completes and validates the file against. The scaffold points it at `./node_modules/@blotout/qinto-sdk-app/app.schema.json`, which the SDK ships, so completion works offline and matches the SDK version you installed. |
+| `slug`, `name`, `description` | Identity. `slug` is immutable and must match the registered app. |
+| `flows` | `transform`, `destination`, or both. |
+| `consent` | The single consent category a visitor must have granted before events reach the app. |
+| `legal` | `termsUrl` and `privacyUrl` — HTTPS, and your own documents, never a `qinto.io` URL. |
+| `server` | `entry` plus the event and advisory lifecycle hooks the entry exports. |
+| `browser` | `entry` for the bundle inside the site's `q.js`, optional capture names, and action types whose browser handlers return a same-event server result. |
+| `capabilities` | The platform `api` calls and the event `data` the app is allowed to read. |
+| `resources` | Cloudflare bindings the app worker gets: KV, D1, R2, Durable Objects, Vectorize, Hyperdrive, and more. D1 uses immutable named `expand`, resumable `backfill`, and post-convergence `contract` entries. |
+| `variables` | Up to 32 per-install settings a team fills in — `plain` or `secret`, `text`/`password`/`toggle`. |
+| `appVariables` | Up to 16 settings you fill in once for the whole app with `qinto app var set` / `qinto app secret set`. |
+| `endpoints` | Up to 16 HTTP routes served at `https://<site>/app/<slug><path>`. |
+| `rpc` | Functions this app `exposes` to other apps, and the ones it `calls` on them. |
+| `events` | The push topics this app broadcasts to every app on the site. |
+| `ui` | `dir` holding the built panel, and the `build` command that produces it. |
+| `install` | `multiple: true` to let a site install the app more than once, plus a `labelHint`. |
+
+Limits worth knowing before a publish: the server bundle is capped at 10 MB, the browser bundle at 2 MB (and 3 MB for all apps on
+one site together), the UI panel at 200 files and 25 MB, and an app at 15 installs per site. A variable value is capped at 256
+serialized bytes, and one variable's values across every install of that app on a site must fit in 5 KB. Every other cap — the
+manifest, the publish, the install, and the runtime envelope — is listed in
+[Qinto app limits](https://docs.qinto.io).
+
+## Built for humans and agents alike
+
+Every interactive path has a non-interactive equivalent. This is a standing rule for every current and future command:
+
+| Surface | What it does |
+| --- | --- |
+| `qinto describe [command ...]` | Prints a versioned, machine-readable manifest of nested command paths, flags, environment inputs, and structured result states. |
+| `--json` | On data and onboarding commands, prints the typed result as JSON on stdout — nothing else lands on stdout. |
+| `--no-browser` | `login` prints the authorize URL instead of opening a browser; open it in a browser on the same host so its loopback callback reaches the CLI. |
+| `QINTO_API_TOKEN` | A bearer token that takes precedence over stored logins. Works with team API tokens (`qapi_`, from Team → API tokens in the Qinto platform) and OAuth access tokens (`qoa_`). No browser needed. |
+| `QINTO_ENV` | `production` or `sandbox` for every command in the shell — the non-interactive stand-in for `qinto env`, which stores the same choice. |
+| Exit codes | `0` success, `1` operational failure, `2` usage error, `130` aborted prompt (Ctrl-C). Errors go to stderr; with `--json` they are printed as `{"error": "…"}`. |
+
+## Environments
+
+Qinto runs in two environments, and every command talks to exactly one of them:
+
+| Environment | API origin | Platform |
+| --- | --- | --- |
+| `production` | `https://api.qinto.io` | `https://portal.qinto.io` |
+| `sandbox` | `https://api.qinto.tech` | `https://portal.qinto.tech` |
+
+`qinto env` picks one and remembers it, so nothing after it needs a flag:
+
+```sh
+qinto env             # pick from a list; prints the current one when nothing can be prompted
+qinto env sandbox     # the same choice, non-interactively
+qinto env --json      # {"environment":"sandbox","apiOrigin":"https://api.qinto.tech"}
+```
+
+The choice is written to `~/.qinto/settings.json` and applies to every later command, `login` included — so the usual flow is
+`qinto env sandbox`, then `qinto login`, then work as normal.
+
+**Each environment keeps its own login.** Sessions are stored per API origin, so switching does not log you out of anywhere:
+log in to production and to sandbox once each, and from then on `qinto env` moves between them with no further login. Each
+environment also remembers its own active team, and renews its own access token from its own refresh token. `qinto env` says so
+when you land on an environment you have no session on; `qinto logout` clears one environment — the one it is pointed at.
+
+Four things override it, strongest first:
+
+| Override | Scope |
+| --- | --- |
+| `--api-url <origin>` | One command, any origin — a local stack. |
+| `QINTO_API_URL` | Every command in that shell, any origin. |
+| `--env <name>` | One command. |
+| `QINTO_ENV` | Every command in that shell. |
+
+With nothing saved and nothing overriding, commands talk to production.
+
+Credentials are stored per API origin in `~/.qinto/credentials.json` (file mode 0600), so logins to different environments
+coexist and each keeps its own active team. When a command finds no login for the environment it was pointed at, its error names
+the login command for that same environment. Access tokens renew themselves through the refresh token; when a session can no
+longer be renewed the CLI asks you to log in again. `qinto logout`
+clears local credentials only after the server confirms the revocation — if the API is unreachable, nothing is cleared, so a
+retry can still revoke the session (or revoke it under User → Authorized apps in the Qinto platform).

package/bin/qinto.js

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+import '../dist/index.js'