@blotout/qinto-cli 0.1.12 → 0.1.14

package/README.md

@@ -223,6 +223,10 @@ callee's page, exactly as a site manager does on a deployed site.
 An app folder added or removed while `dev` is running is not picked up — it says so and asks for a restart. A save inside a
 mounted app rebuilds that app alone.
 
+Declared `server.schedules` fire on their own while `dev` runs — at the cron's minute, in UTC, with `scheduledTime` set to that
+instant, exactly as the deployed sweep dispatches them. Each schedule on the app's console page also has a **Run now** button,
+so you never wait for the window.
+
 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; every mounted app is listed
@@ -230,10 +234,13 @@ Three surfaces, one per side of the product:
   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.
+  install is never removable — uninstall the app instead. **Analytics → ID graph** opens the visitor's anon, alias and person
+  objects exactly as the platform's page does: paste an anon id, an email or a person id and read its keys and tables as your
+  app writes into them.
 - **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
+  activated. Its **Visitor** panel shows the browser's anon id, the one to paste into the ID graph page, and the person id
+  once `identify` links one. 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
@@ -259,11 +266,124 @@ are namespaced by its slug, so two apps declaring a `d1` called `ledger` get a d
 | `--worker-port <port>` | Port the local site worker listens on (default `4310`). |
 | `--ui-port <port>` | Port the app panels are served from (default `4302`). |
 | `--reset` | Discard this directory's local installs, variables, secrets and stored data first. |
+| `--tunnel` | Expose the site worker on a fresh `trycloudflare.com` hostname, so a vendor webhook can reach its endpoints. |
+| `--tunnel-name <name>` | Expose it through this named Cloudflare Tunnel instead, for a hostname that survives a restart. |
 | `--no-input` | Disable all interactive prompts, mounting every app found. |
 
 All four listeners bind `127.0.0.1` only.
 
-Two things behave differently from a deployed site, and `dev` says so rather than letting you discover them:
+**Reaching your endpoints from outside — `--tunnel`.** A vendor webhook cannot call `127.0.0.1`, so `--tunnel` opens a
+Cloudflare Tunnel to the site worker and prints the public origin; the console's Endpoints card then leads with the URL to
+register with the vendor and keeps the loopback one beside it for `curl`.
+
+```
+  Anyone who has this URL can:
+    · call your app’s ungated endpoints
+    · make your app code run against real vendor APIs, with your dev variables and secrets
+    · reach whatever the site worker passes through
+
+  Restrict it with Cloudflare Access on a named tunnel (--tunnel-name) if that matters here.
+
+  Opening a Cloudflare Tunnel to the site worker — this usually takes 20-40 seconds.
+    · downloading cloudflared 2026.8.3…
+    · starting cloudflared…
+    · connecting to the Cloudflare edge…
+    · publishing odd-mule-hits-yet.trycloudflare.com in DNS…
+
+  Site worker   http://127.0.0.1:4310
+  Public site   https://odd-mule-hits-yet.trycloudflare.com
+                ! anyone holding this URL reaches your dev site worker
+
+  My App (my-app) — installed and active on the seeded site
+    POST  https://odd-mule-hits-yet.trycloudflare.com/app/my-app/hook
+```
+
+`cloudflared` is downloaded and cached on first use, unless you already have one on `PATH` or at `CLOUDFLARED_PATH`.
+
+**The tunnel closes after an hour.** It is a public door onto your machine, and an `app dev` left running overnight would hold it
+open until you noticed. `dev` says how long is left every ten minutes; press `a` then Enter to add an hour, up to three hours from
+now. When it closes, the public URL stops being advertised and the loopback one carries on.
+
+**A hostname that survives a restart — `--tunnel-name <name>`.** A quick tunnel is free and needs no account, but its hostname is
+new on every run, so a vendor has to be told the new one each time. A named tunnel keeps one hostname. `dev` reads it from **your
+own Cloudflare account**, never from anything Qinto holds.
+
+Run `qinto app dev --tunnel-name <name>`. The first time, `dev` asks for the two things it needs and tells you how to make them:
+
+```
+  A named tunnel is read from your own Cloudflare account, and qinto has no credentials for it yet.
+
+  1. Open https://dash.cloudflare.com/profile/api-tokens
+  2. Select Create Token, then Create Custom Token.
+  3. Under Permissions, add:  Account > Cloudflare Tunnel > Edit
+     To let qinto create the tunnel for you, also add:  Zone > Zone > Read and Zone > DNS > Edit
+     Nothing more: the token is saved on this machine.
+     (An account-owned token lists the first row as Cloudflare One Connector: cloudflared, or Argo Tunnel (Legacy).)
+  4. Under Account Resources, select the account that holds the tunnel; under Zone Resources, the zone its hostname is on.
+  5. Create the token and copy it — Cloudflare shows it once.
+
+  Your account ID is the last part of the dashboard URL:
+  https://dash.cloudflare.com/<account-id>
+```
+
+They are saved in **`~/.qinto/cloudflare.json`**, readable only by you, and every later run uses them without asking. They are
+written only **after Cloudflare accepts them**, so a mistyped token is asked for again rather than stored and reported as a tunnel
+fault. Delete that file to enter different ones. `CLOUDFLARE_ACCOUNT_ID` and `CLOUDFLARE_API_TOKEN` in the environment override the
+saved pair and overwrite nothing — that is how CI, or a second account, runs. Set **both or neither**: one on its own is refused
+rather than paired with a credential from somewhere else. `--no-input`, and a run with no terminal, say what to set instead of
+prompting.
+
+**A tunnel that does not exist yet is created for you.** When the account has no tunnel under that name, `dev` says so and asks
+whether to create it. Say yes and it asks for the public hostname a vendor should call — a zone on that account or a name one
+level below it, such as `hooks.example.com`; Universal SSL covers no deeper name, so a deeper one is refused before anything is
+made — then makes the tunnel under the name you gave `--tunnel-name`, routes that hostname to
+`http://127.0.0.1:4310` (the port `--worker-port` sets), and adds the proxied CNAME record for it to your zone. The zone is found
+from the hostname, so nothing is created when no zone on the account holds it; a failure after the tunnel exists — a DNS record
+already on that name, or a token without the zone rows — removes the tunnel again, so a fixed token or a different hostname is a
+clean retry. `dev` never deletes a DNS record: when the record's write got no readable answer, it names the record to check in the
+dashboard instead. From then on the tunnel is found by name and nothing is asked. Say no and `dev` prints the dashboard steps
+instead:
+
+```
+  To create the tunnel "hooks" yourself:
+    1. Open https://one.dash.cloudflare.com/<account-id>/networks/tunnels and select Create a tunnel.
+    2. Choose Cloudflared and name it "hooks". Skip installing a connector — qinto runs cloudflared for you.
+    3. Under Public Hostnames, add the hostname a vendor should call, with service http://127.0.0.1:4310 (the port --worker-port sets).
+  Then run the command again.
+```
+
+`--no-input`, and a run with no terminal, print the same steps rather than creating anything: making a tunnel and a DNS record
+in your account is a question, and a run that promised no prompts cannot ask it.
+
+`dev` looks the tunnel up by name and runs it on the token it fetched. cloudflared reads ingress rules top to bottom and stops at
+the first match, so the rule that decides a hostname is often not the rule naming it — an earlier catch-all, wildcard, or
+same-hostname rule takes the request first. A hostname is advertised only when **every rule that can take it points at your worker
+port, ending in one that carries no path**. A rule with a `path` takes some requests and leaves the rest to the rules below it, and
+that path is a regex `dev` cannot evaluate, so one pointing elsewhere is refused rather than guessed at — it may be the rule that
+takes your `/app/...` URLs. Wildcards are never offered: `https://*.example.com` is not something a vendor can call, though it still
+decides the hostnames it covers. Every advertised hostname is then checked in DNS, not just the first. A tunnel that routes nothing
+usable is refused, and the message lists its rules in the order cloudflared reads them. A tunnel created locally
+with `cloudflared tunnel create` has no configuration in the dashboard, so it lands in the same message — configure it there
+instead. `CLOUDFLARE_*` and `TUNNEL_*` are both kept out of cloudflared's own environment: it is given the tunnel token and
+nothing else, so a stray variable cannot redirect the tunnel and your account token is never handed to a process with no use for
+it.
+
+**Your own cloudflared setup is left alone, and not used.** `dev` runs cloudflared against a config file of its own, because an
+existing `~/.cloudflared/config.yml` would otherwise win: its `ingress` rules override the `--url` `dev` passes, and the tunnel
+would answer that config's catch-all — a 404 on every webhook — instead of the site worker.
+
+**Why it takes 20-40 seconds.** `dev` names each thing it is waiting for, and the wait is deliberate. A fresh
+`trycloudflare.com` hostname is minted about five seconds before DNS publishes it, and `trycloudflare.com` tells resolvers to
+remember a miss for **1800 seconds** — so one lookup a moment too early makes the hostname fail for the next half hour, for you
+and for the vendor you gave it to. `dev` therefore waits for cloudflared to register a connection, then asks the zone's own
+nameservers whether the name exists yet. Those answer from zone data, so the wait itself leaves nothing behind in any cache your
+browser, `curl` or the vendor will read. By the time the URL is printed it works on the first request. The tunnel closes when
+`dev` does.
+
+**Only the site worker is exposed** — the same worker, and the same code, that faces the internet on a deployed site. The console
+is never tunneled: it installs apps and shows your variables, and it answers a loopback `Host` and nothing else.
+
+Four things behave differently from a deployed site, and `dev` says so rather than letting you discover them:
 
 - **`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
@@ -271,6 +391,15 @@ Two things behave differently from a deployed site, and `dev` says so rather tha
 - **Two mounted apps cannot bind the same hyperdrive name to different databases.** workerd names a hyperdrive connection after
   the binding — your app's own `env.DATABASE` — and keeps the first of a name, so the second app's binding is reported inert
   instead of silently reaching the first app's database. Rename the binding, or point both at one database.
+- **A `pipeline` writes to a local catalog, not to Cloudflare.** `send()` checks each record against the manifest schema, runs
+  the sink `select` on SQLite and appends the rows to `namespace.table` under `~/.qinto/dev/<hash>/catalog/`; `query.catalog`
+  reads them back with SQLite plus `to_timestamp_millis`, `date_trunc` and the `json_get_*` functions. The banner prints the
+  directory so `sqlite3` can open it, and `--reset` clears it.
+- **An `analytics_engine` dataset is a local SQLite file.** `writeDataPoint` stores the point with the columns Analytics Engine
+  gives it, and `query.analytics` reads it back through the same statement gate the platform applies, plus the documented
+  Analytics Engine functions — a name outside that list is refused locally rather than answered by SQLite, so a query that runs
+  here runs deployed. The one thing it cannot reproduce is the throw: a point that breaks a documented limit is reported on the
+  terminal and dropped, where a deployed hook would throw. The banner prints the file, and `--reset` clears it.
 
 **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); every mounted app's