@blotout/qinto-cli 0.1.13 → 0.1.15

package/README.md

@@ -234,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
@@ -265,6 +268,7 @@ are namespaced by its slug, so two apps declaring a `d1` called `ledger` get a d
 | `--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. |
+| `--tunnel-hours <hours>` | Close the tunnel after this many hours, instead of leaving it open until `app dev` stops. |
 | `--no-input` | Disable all interactive prompts, mounting every app found. |
 
 All four listeners bind `127.0.0.1` only.
@@ -297,26 +301,33 @@ register with the vendor and keeps the loopback one beside it for `curl`.
 
 `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.
+**The tunnel closes when `app dev` does.** It is a public door onto your machine, so quitting `dev` is what shuts it: there is no
+separate clock, and a session left running overnight holds the door open until you stop it. Cloudflare places no limit of its own,
+so a named tunnel will happily run for days.
+
+**`--tunnel-hours <hours>` closes it earlier.** Give it a deadline and `dev` says how long is left every ten minutes; press `a`
+then Enter to add an hour, as often as you like. When it closes, the public URL stops being advertised and the loopback one
+carries on. Fractions work, so `--tunnel-hours 0.5` is half an hour. Nothing caps the number.
+
+For a run measured in days, use `--tunnel-name`. Cloudflare gives `trycloudflare.com` no uptime guarantee and caps it at 200
+in-flight requests, so a quick tunnel is a debug aid rather than something to leave up over a weekend.
 
 **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.
 
-In the Cloudflare dashboard, create a tunnel and give it a **public hostname pointing at `http://127.0.0.1:4310`** — the port
-`--worker-port` sets. Then 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:
+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 one row:  Account > Cloudflare Tunnel > Edit
-     That is the only permission qinto needs. Do not add more.
-  4. Under Account Resources, select the account that holds the tunnel.
+  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:
@@ -330,6 +341,28 @@ saved pair and overwrite nothing — that is how CI, or a second account, runs.
 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
@@ -358,7 +391,7 @@ browser, `curl` or the vendor will read. By the time the URL is printed it works
 **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.
 
-Two things behave differently from a deployed site, and `dev` says so rather than letting you discover them:
+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
@@ -366,6 +399,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