@blotout/qinto-cli 0.1.5 → 0.1.7

package/README.md

@@ -166,13 +166,19 @@ declares only its build tooling.
 
 `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`
+### Register — `qinto app register [dir]`
 
 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.
 
+The slug, name, and description come from `qinto.app.jsonc` — the one in `dir`, or the one in the current directory when you pass
+no `dir`. Pass `--slug`, `--name`, and `--description` only for an app that has no manifest yet; alongside a manifest they are
+refused, because a slug that differs from the manifest is one `qinto app publish` then rejects.
+
 ```sh
-qinto app register --slug my-app --name "My App" --org Acme --description "What it does."
+qinto app register ./my-app                 # slug, name, and description from its manifest
+qinto app register --org Acme               # the manifest in the current directory
+qinto app register --slug my-app --name "My App" --description "What it does."   # no manifest
 qinto app list           # every app across your organizations
 qinto app list --json
 ```
@@ -187,10 +193,15 @@ 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
+qinto app dev ./apps          # a folder of app directories — pick which to mount
 ```
 
+A directory holding a `qinto.app.jsonc` runs that one app. A directory that does not is scanned **one level down**, and every
+subfolder holding a manifest is offered; everything is ticked, so pressing Enter mounts them all. `--apps my-app,crm` skips the
+question, and `--no-input` mounts everything found.
+
 ```
-  My App (my-app) — local Qinto on platform 0.1.0
+  2 apps — local Qinto on platform 0.1.0
 
   Console       http://127.0.0.1:4300
   Demo site     http://127.0.0.1:4301
@@ -198,13 +209,25 @@ qinto app dev ./apps/my-app
   Dev state     ~/.qinto/dev/8f3c1a2b4d5e6f70
   Site token    qwat_dev_…
 
-  The app is not installed yet.
+  My App (my-app) — installed and active on the seeded site
+    panel  http://127.0.0.1:4302/dev-my-app/0.0.0-dev/
+  CRM (crm) — installed, but no install is active until you set API_KEY in the console
 ```
 
+**Apps mounted together share one site**, which is what makes everything that crosses apps testable: one event fans out to every
+app's hooks, `ctx.context.shared` is readable across them, a site-wide `ctx.push` reaches them all, and `ctx.apps.call` really
+goes caller → the site worker's broker → callee, each app in its own worker. Calls to a `public` function work as soon as both
+apps are mounted; a `private` one is refused with `403 forbidden` until you approve it under **App-to-app approvals** on the
+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.
+
 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
+- **The console** is the platform's side. A team and the site `dev.localhost` are seeded for you; every mounted app is listed
+  under **Site → Apps**, where you install it, 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.
@@ -223,30 +246,40 @@ backfill handlers, and workflows match the manifest — so a mismatch fails here
 `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.
+Everything the session persists — each app's installs, its variables and secrets, and every Durable Object, D1, KV and R2 the
+workers wrote — lives in `~/.qinto/dev/<directory>/`, keyed on the directory you pointed `dev` at and outside your app
+directories, so a restart resumes where you left off and the plaintext secrets file can never be committed. Each app's resources
+are namespaced by its slug, so two apps declaring a `d1` called `ledger` get a database each. `--reset` discards all of it.
 
 | Flag | What it does |
 | --- | --- |
+| `--apps <slugs>` | Comma-separated slugs to mount, instead of choosing them. |
 | `--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. |
+| `--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. |
+| `--no-input` | Disable all interactive prompts, mounting every app found. |
 
-All three listeners bind `127.0.0.1` only.
+All four 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:
+Two 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
   local URL in the console to bind it — the origin in your manifest is the *deployed* database and is never used here.
+- **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.
 
 **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.
+served under — `/<appId>/<version>/` — and serves the result on its own port (`--ui-port`, default 4302); every mounted app's
+panel is served from that one port, each under its own base path, and gets its own entry in the console's **Apps** menu. 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. One difference from a deployed site: there
+every panel gets its own `https://<slug>.appui.<zone>` origin, and here they share one, so panels are not origin-isolated from
+each other.
 
 ### Publish — `qinto app publish [dir]`