naro-cli 0.19.1 → 0.21.0

package/README.md

@@ -198,6 +198,7 @@ naro policy remove todos           Drop every policy on the table: back to deny
 
 naro storage                       Naro Storage: on or off, limits, usage, today's operations, buckets
 naro storage enable                Turn it on: the project's R2 bucket, bound to the backend
+naro storage disable [--yes]       Turn it off and keep the files: Storage calls and file URLs answer 404 until enable (asks first)
 naro storage bucket create avatars --public --file-size-limit 5MiB --allowed-mime-types image/png,image/jpeg
 naro storage bucket update avatars --private | --file-size-limit none | --allowed-mime-types any
 naro storage bucket update docs --public   (asks first: anyone with an object's URL can download it)
@@ -210,7 +211,14 @@ naro storage mv naro://docs/a.pdf naro://docs/old/a.pdf         Inside one bucke
 naro storage rm naro://avatars/u1/old.png [--recursive]   (asks first)
 naro storage rm naro://avatars/u1/ --recursive   Everything under u1/; written u1, an object u1 too
 
-naro promote <deployment-id>       Publish a build to production
+naro realtime [status]             Naro Realtime: on or not, published tables, connections now
+naro realtime enable               Turn Realtime on: the project's hub, bound to its backend
+naro realtime tables [list]        The tables whose Data API writes reach subscribers
+naro realtime tables add <table>…  Publish tables' changes (within about 10 seconds)
+naro realtime tables remove <table>… [--yes]
+                                   Stop publishing tables' changes (asks first)
+
+naro promote <deployment-id> [--to <environment>]   Publish a build to production, or to an environment (0.20.0); says rebuild or reupload first, then asks
 naro rollback [deployment-id]      Back to the previous production build
 ```
 
@@ -594,8 +602,16 @@ tables: a policy on a table that does not exist
 (`relation "nope" does not exist`), a name already taken, or a 33rd policy on
 one table fails the whole request with `400 DATABASE_QUERY_FAILED`, names the
 statement, and applies nothing — not even the `CREATE TABLE` before it. Policy
-statements, and statements that create, drop or rename a table, take no
-`params` (`400 VALIDATION_FAILED`): write the values into the SQL.
+statements, statements that create, drop or rename a table, and statements
+that add a generated column take no `params` (`400 VALIDATION_FAILED`): write
+the values into the SQL.
+
+`ALTER TABLE t ADD COLUMN c … AS (…)` computes the generated column for the
+rows already in `t` right after it, as Postgres does: a row it cannot be
+computed for (`json_extract` over text that is not JSON) fails the request
+with SQLite's error (`400 DATABASE_QUERY_FAILED` `malformed JSON:
+SQLITE_ERROR`) and nothing changes. Fix those rows first, in an earlier
+statement.
 
 Policies go with their table, as in Postgres: `DROP TABLE` drops them, and a
 new table never inherits the leftovers of an earlier one with the same name
@@ -837,6 +853,164 @@ An `--update-check` you give replaces the default: without
 
 ## Release notes
 
+### 0.21.0
+
+0.20.0 went out on 2026-10-26 without these.
+
+- `naro realtime` turns on Naro Realtime for the project and chooses the
+  tables whose changes reach subscribers (Realtime 3-2d). Five commands:
+  `naro realtime [status]`, `naro realtime enable`,
+  `naro realtime tables [list]`, `naro realtime tables add <table>…` and
+  `naro realtime tables remove <table>… [--yes]`.
+  - `naro realtime` prints `Realtime: on (public channels: off)`, the
+    published tables (`Published tables: messages, gone (dropped)`, or
+    `Published tables: none — naro realtime tables add <table>`) and
+    `Connections now: 12 · channels 30 · presences 8`. When the hub does not
+    answer it says
+    `Connections now: not known — the backend is off or not ready, or the hub did not answer`.
+    Before Realtime is on it prints `Realtime: not enabled` and
+    ``Run `naro realtime enable` to turn it on (the project's backend must be on first).``
+  - `naro realtime enable` needs the backend on, and is safe to run again: it
+    picks up an upload that stopped. It prints
+    `✅ Realtime is on. Publish a table with naro realtime tables add <table>.`
+    and the state. An upload that does not answer within 2 minutes stops
+    with `TIMEOUT`
+    ``Turning Realtime on did not answer within 2 minutes. `naro realtime` shows where it got to, and `naro realtime enable` again picks up where it stopped.``
+  - `naro realtime tables add messages rooms` sends one request a table, in
+    order, and stops at the first refusal (`404 TABLE_NOT_FOUND`
+    `Table nope was not found.`): the tables before it stay published. Each
+    prints `✅ messages now publishes its changes (within about 10 seconds).`
+    and the control plane's warnings as `⚠ <warning>` — for a table with no
+    select policy,
+    `⚠ messages has no select policy: only service-key connections receive its changes.`
+    The command ends with
+    `⚠ Changes made through the Data API are published; writes your app makes with env.DB are not.`
+    once.
+  - `naro realtime tables remove` asks once for all the tables —
+    `Stop publishing messages, rooms? Subscribers stop receiving their changes within about 10 seconds.`
+    — and with `--json` or without a terminal only `--yes` answers it
+    (`CONFIRMATION_REQUIRED`). A table that is not published stops it with
+    `404 TABLE_NOT_PUBLISHED` `Table nope does not publish its changes.`
+  - A table name no URL can carry fails before its request with
+    `INVALID_PATH` `The table name is not valid.`, and a command with no
+    table with `VALIDATION_FAILED` and its usage line.
+- Until Naro Realtime is switched on for the control plane, `naro realtime enable`,
+  `tables add` and `tables remove` answer `503 REALTIME_DISABLED`
+  `Naro Realtime is not enabled on this control plane yet.` (`naro realtime`
+  still prints `Realtime: not enabled`). The tables commands on a project
+  whose Realtime is not on answer `409 REALTIME_NOT_ENABLED`
+  ``Realtime is not enabled for this project. Run `naro realtime enable` first.``
+- There is no command that turns Realtime alone off yet:
+  `naro backend disable` stops it with the rest of the backend.
+- It goes out with naro-js 0.6.0, whose `naro.channel()` is the client side
+  of Realtime (row changes, broadcast and presence, as supabase-js's
+  `channel()`). naro-js 0.6.0 is also the first published version with
+  Storage's `move()` and `copy()` (3-1i).
+
+### 0.20.0
+
+0.19.1 went out on 2026-10-24 without these.
+
+- `naro promote <deployment-id> --to <environment>` publishes a build to a
+  named environment. `--to` takes `production` (what no `--to` does) or an
+  environment's slug; an empty value, only blanks or `preview` fails before
+  any request with `VALIDATION_FAILED`
+  `--to must be production or an environment name.` The usage line is
+  `Usage: naro promote <deployment-id> [--to <environment>]`.
+  - Before it asks, it says what the promotion will do, from the control
+    plane's preview (`GET …/promote?target=`, which changes nothing):
+    `▸ rebuild: builds the same commit again with qa's variables` or
+    `▸ reupload: publishes the stored build`, then each warning as
+    `⚠ <warning>`. Without `--to` the same line is printed for production
+    (`… with production's variables`); that is one request more than 0.19.1
+    sent.
+  - A build moving between an environment and another surface (a preview or
+    production build to `qa`, a `qa` build to `staging` or to production) is
+    built again from its commit with the target's variables, and counts
+    against the plan's builds. Any other build is published as stored: one
+    promoted within its own surface, and a preview to production.
+  - The question is `Promote <id> to qa (<subdomain>--qa)?`; for production it
+    is the one it always was, `Promote <id> to production (<subdomain>)?`.
+    `--json` or no terminal without `--yes` still fails
+    `CONFIRMATION_REQUIRED`.
+  - Progress is `▸ promoting <id> to qa (rebuild)` (`(reupload)`), and the
+    result `✅ qa now serves a rebuild of <id>` or `✅ qa now serves <id>`; for
+    production `✅ Production now serves a rebuild of <id>` or, as before,
+    `✅ Production now serves <id>`. A rebuild is waited for up to 15 minutes
+    (a published build, 5 as before), and a failed one fails with its own
+    code and message. While a rebuild runs its build log lines print the way
+    `naro logs --type build --follow` prints them (`[BUILDING] next build`,
+    `[BUILDING] ✗ <error>`), on stderr with `--json` so stdout stays one
+    object; a published build prints none.
+  - `--json` adds `target` (`null` without `--to`) and `mode` (`rebuild` or
+    `reupload`): `{ deploymentId, sourceDeploymentId, projectId, target, mode, status, url }`.
+    `naro rollback`'s result gains `mode` too (as MCP's `rollback_deployment`
+    says it) and has no `target`: a rollback is always production's.
+  - `409 PROMOTE_NEEDS_GIT_SOURCE`
+    `Only deployments built from Git can be promoted to another environment. Deploy the code again with naro deploy instead.`
+    for a deployment `naro deploy` uploaded. This and every other refusal of
+    the preview (`404 ENVIRONMENT_NOT_FOUND` `Environment not found.`) stop
+    it in the control plane's words before it asks, and nothing is promoted.
+  - A rebuild checks out the pinned commit as a detached HEAD, not the
+    branch, so a build script that reads the branch name from git
+    (`git branch --show-current`, `git rev-parse --abbrev-ref HEAD`) sees
+    none.
+  - Against a control plane from before named environments 2a, which has no
+    preview (it answers 405) and whose promote ignores the target and
+    republishes to production, `--to <environment>` stops before it promotes
+    anything: `PROMOTE_TARGET_UNSUPPORTED`
+    `This control plane cannot promote to an environment yet. Deploy the latest web first, then try again.`
+    With no `--to` or `--to production` the 405 is ignored: no preview line,
+    and the promotion goes as it always did.
+- `--to` belongs to `naro promote`; `naro rollback` refuses it before any
+  request with `VALIDATION_FAILED`
+  `--to is for naro promote: naro rollback always rolls production back.`
+  (it always targets production, and ignoring `--to` would roll production
+  back for someone who named an environment).
+- Any other command given `--to` fails before any request with
+  `VALIDATION_FAILED` `--to is only for naro promote.`, so a flag a command
+  does not read is never dropped silently.
+- `naro promote` and `naro rollback` refuse `--env` and any word after the
+  deployment id before any request, with `VALIDATION_FAILED`
+  `--env is not an option of naro promote: use --to <environment>.`,
+  `--env is not an option of naro rollback: naro rollback always rolls production back.`
+  or the usage line (`Usage: naro promote <deployment-id> [--to <environment>]`,
+  `Usage: naro rollback [deployment-id]`), instead of acting on production for
+  someone who named an environment (`naro promote d1 --env qa --yes` and
+  `naro promote d1 qa --yes` promoted to production in 0.19.1).
+- A control plane with named environments 2a rebuilds a deployment of an
+  environment that is promoted to production, which it used to refuse with
+  `400 DEPLOYMENT_NOT_PROMOTABLE`. `naro promote <id>` says so before it
+  asks (`▸ rebuild: … with production's variables`) and waits up to 15
+  minutes; `naro rollback <id>` waits 15 minutes for such a rebuild too and
+  prints `✅ Production now serves a rebuild of <id>`. The build that
+  `naro rollback` picks on its own is never one.
+- `naro storage disable [--yes]` turns the project's Storage off and keeps
+  its files (Storage 3-1k). It asks first —
+  `Turn Storage off for this project? Its Storage calls and file URLs answer 404 until naro storage enable; buckets and files are kept.`
+  — and without a terminal or with `--json` only `--yes` answers it. The
+  backend is uploaded again without the bucket: the app's Storage calls and
+  file URLs answer `404 STORAGE_NOT_ENABLED` until `naro storage enable`
+  binds the same bucket again, and the buckets, the files and their storage
+  cost stay. To delete the files instead, remove the buckets with
+  `naro storage bucket remove <name> --empty` while Storage is on. Storage
+  that was never turned on prints `Storage is already off.` and changes
+  nothing; Storage that is already off is finished without asking again (a
+  turn-off whose upload stopped answers `BACKEND_PROVISION_FAILED` and says
+  to run it again).
+- `naro storage` says
+  `Storage:     off since <YYYY-MM-DD HH:MM> UTC — buckets and files are kept`
+  while it is off, with the buckets.
+- `naro storage ls`, `cp`, `mv` and `rm` read the Storage state before the
+  service key and stop with `STORAGE_OFF`
+  ``Storage is turned off for this project. Turn it on with `naro storage enable` first.``
+  while it is off. `naro storage bucket create` on Storage that is off gets
+  the control plane's `409 STORAGE_OFF`: it turns Storage on by itself only
+  when Storage was never on.
+- Published naro-cli 0.19.1 and earlier show Storage that is off as `off`
+  and pass the backend's `404 STORAGE_NOT_ENABLED` on from `ls`, `cp`,
+  `mv` and `rm`; their `bucket create` stops at `409 STORAGE_OFF` too.
+
 ### 0.19.1
 
 0.19.0 went out on 2026-10-19 without these.
@@ -996,7 +1170,7 @@ RENAME` the way the control plane now reads it: a column rename whose
   too), migration files the backend would stop at for Storage: a policy that
   reads `storage.objects` in a subquery while the backend's ledger lacks
   system migration 7 (it reads the ledger only when a file has one), and
-  any statement on `storage.objects` (CREATE POLICY, DROP POLICY without
+  a statement that needs `storage.objects` (CREATE POLICY, DROP POLICY without
   IF EXISTS, the `naro:owner` COMMENT) on a backend from before Storage or a
   project with none. It fails `BACKEND_OUTDATED`
   ``0002_b.sql needs storage.objects (statement 2 of 2), which is not available on this backend yet, so the reset would stop there with the schema already dropped. Nothing was changed. Run `naro backend enable` to update it, then try again.``
@@ -1556,7 +1730,7 @@ not fail but no strategy can ship it, `NO_DEPLOYMENT_STRATEGY`. Either way the m
 what each strategy failed at.
 
 `--yes` (or `-y`) suppresses every prompt — destructive actions
-(production rollback/promote, env/domain/environment removal, `naro env import`, turning off an environment's protection, database reset, backend key
+(production rollback, promote to production or to an environment, env/domain/environment removal, `naro env import`, turning off an environment's protection, database reset, backend key
 rotation, policy removal and drop, opening the preview with
 `naro protection disable`, replacing or removing the bypass secret) run
 unconfirmed, so use it deliberately in