naro-cli 0.18.0 → 0.19.0

package/README.md

@@ -62,6 +62,7 @@ naro usage                         Team usage this month: requests, builds and c
 naro usage --month 2026-09 --team acme  Another UTC month, another team
 
 naro deploy [--prod]               Build locally and deploy
+naro deploy --env qa               Deploy to a named environment (<subdomain>--qa) instead of the preview; not with --prod
 naro deployments                   List deployments
 naro inspect <deployment-id>       One deployment + build logs
 naro cancel <deployment-id>        Stop a build that is still running
@@ -86,10 +87,24 @@ naro protection                    Preview protection: on or off, and whether a
 naro protection enable | disable   Protect the preview URL (members only) or open it to anyone with the link (disable asks first; --yes in CI)
 naro protection bypass [remove]    Create (shown once) or remove the secret automation sends as x-naro-protection-bypass (replacing or removing asks first; --yes in CI)
 
-naro env list [--reveal]           Secrets masked unless --reveal
+naro env list [--reveal]           Secrets masked unless --reveal; an environment's value shows its name
 naro env add DATABASE_URL production
-naro env remove DATABASE_URL
-naro env pull [.env.local]
+                                   Target: production, preview, all (the default) or an environment name (qa)
+naro env remove DATABASE_URL       The production, preview and all values; an environment's only with its name
+                                   (naro env remove DATABASE_URL qa)
+naro env pull [.env.local]         Preview's values by default; --env production, or --env qa for an environment
+                                   (its own value wins over all; an unknown name fails before anything is written)
+naro env import .env.qa qa         Upload every variable in a dotenv file to one target (all by default; asks first,
+                                   --yes in CI; invalid keys or values over 5 KB stop it before any request)
+
+naro environments                  List the project's environments: address, branch, protection, and how many the plan allows
+naro environments create qa --branch qa
+                                   A QA or staging surface served at <subdomain>--qa; --copy-env preview|production|none
+                                   picks where its variables start, --database schema|empty how its database does
+naro environments set qa --no-branch --protection off
+                                   Change the branch whose pushes deploy here (--branch <b>, or --no-branch for none)
+                                   and who can open it (--protection on|off; off asks first, --yes in CI)
+naro environments delete qa        Delete it with its worker and protection key (asks first; --yes in CI)
 
 naro domains list
 naro domains add www.example.com   Prints the CNAME to create; naro connects
@@ -310,16 +325,14 @@ point at its table's primary key or a unique column. `--owner user_id` adds
 four actions; any other new table is closed to the Data API until you give it
 a policy (`CREATE POLICY` in a migration, or `naro policy create` or
 `naro policy set`; the command says so).
-Policies are kept by table name: a drop removes the table's policies whenever
-the project has a backend, on or off (the command says so). A rename leaves
-them under the old name, where they apply to no table — the command prints
-what to run to move them. Move them then: the next time `naro db table`
-creates a table as that name or renames one to it, renaming the table back
-included, the policies stored under the name are removed first, so a new
-table never inherits an earlier one's (except, on a project without a
-backend, one changed through `naro db table`, the table editor or MCP) — and
-neither does a table made by `naro db push` or `naro db query`. Whatever a command removes it prints
-so it can be made again: as `CREATE POLICY` statements, which
+Policies go with their table, as in Postgres and as `naro db push` does it,
+in the same migration: a drop removes the table's policies, and a rename
+moves them to the new name and rewrites the policies of other tables that
+read it (the command says which). A rename such a policy cannot follow is
+refused before anything runs. A table the command creates, or renames onto a
+name, never inherits what an earlier table of that name left there: that is
+removed first. A change that fails changes no policy. Whatever a command
+removes it prints so it can be made again: as `CREATE POLICY` statements, which
 `naro policy create` takes back, and — for owner rules, whose owner column
 `CREATE POLICY` cannot say — as the `naro policy set <table> … --owner <column>`
 command that sets them again. A statement that cannot be shown as it is (a
@@ -585,8 +598,10 @@ SQLite changes a column by building the table again — `CREATE TABLE
 __new_x`, copy the rows, `DROP TABLE x`, `ALTER TABLE __new_x RENAME TO x` — so
 the drop removes `x`'s policies and the rename does not bring them back. Write
 the `CREATE POLICY` statements again after the rename, in the same migration.
-A plain `ALTER TABLE a RENAME TO b` does not move them either: they stay under
-`a`, and `b` has none until you create them again.
+A plain `ALTER TABLE a RENAME TO b` in a migration moves `a`'s policies to `b`,
+and a policy of another table that reads `a` is written to read `b` — do not
+create them again on `b`: a policy of the same name already there is refused.
+`naro db table`, the table editor and MCP do the same.
 The answer's `warnings` lists the policies a migration removed, with SQL you
 can paste; it also says when the project has no backend yet (the policies are
 saved and apply once `naro backend enable` turns it on) and when a policy was
@@ -743,7 +758,10 @@ into named policies; it also turns a backend that is off back on, so run
 `naro backend disable` again afterwards if it should stay off. `naro policy
 list` and `naro policy remove` work in the meantime. A migration or a query
 that holds a `CREATE POLICY` or `DROP POLICY` gets the same answer before
-anything runs; SQL without one runs as before.
+anything runs, and so does any change that creates, drops or renames a table —
+in SQL, `naro db table`, the table editor or MCP, with the backend on or off:
+the stored rules apply by table name, and only `naro backend enable` clears
+them. Other SQL runs as before.
 
 `naro policy set` refuses with `409 POLICY_EXISTS` when the table's `naro_<action>` policy is not one it wrote (for example one made with `naro policy create`): `Policy <name> on <table> is not one naro policy set wrote. Change it with naro policy create, or drop it first: naro policy drop <name> --table <table>.` A `naro_<action>` policy that cannot be read as stored (the table answers `500 POLICY_INVALID`) is not refused: setting a rule replaces it, and `none` drops it.
 
@@ -808,6 +826,164 @@ An `--update-check` you give replaces the default: without
 
 ## Release notes
 
+### 0.19.0
+
+- `naro environments` manages a project's named environments, QA or staging
+  surfaces served at `https://<subdomain>--<slug>.naro.sh` beside production
+  and the preview. While the control plane has them switched off, every
+  sub-command fails with the server's `404 NOT_FOUND "Not found."`.
+  - `naro environments` (also `list`, `ls`) prints
+    `slug  url  branch  protection` and one row per environment (`—` when no
+    branch deploys there, protection `on` or `off`), then
+    `2 of 3 environments`, or `2 environments` (`1 environment`) on a plan
+    with no limit. With none it prints
+    ``No environments. Create one with `naro environments create qa`.``
+    first. `--json` prints `{ projectId, environments, limit }`.
+  - `naro environments create qa [--branch qa] [--copy-env preview|production|none] [--database schema|empty]`
+    prints `✅ Created environment qa → https://<subdomain>--qa.naro.sh`. A
+    flag left out leaves the server's default: no branch, the preview's
+    variables, the database seeded with the schema. `--copy-env none` copies
+    nothing. Other values fail before any request with
+    `--copy-env must be preview, production or none.` and
+    `--database must be schema or empty.`
+  - `naro environments set qa [--branch <b> | --no-branch] [--protection on|off]`
+    prints `✅ Updated environment qa`. Before any request it refuses
+    `--branch and --no-branch cannot be used together.`,
+    `--protection must be on or off.` and
+    `Nothing to change: pass --branch, --no-branch or --protection.`
+    `--protection off` asks
+    `Turn off protection for qa? Anyone with the link can open it.` first,
+    like `naro protection disable`; with `--json` or without a terminal it
+    needs `--yes` (`CONFIRMATION_REQUIRED`).
+  - `naro environments delete qa` asks
+    `Delete environment qa? Its worker and protection key are removed.`,
+    then prints `✅ Deleted environment qa` (`--json`:
+    `{ projectId, slug, deleted: true }`).
+  - A slug the project does not have fails `ENVIRONMENT_NOT_FOUND`
+    `Environment not found.` and changes nothing. The server's refusals
+    come through with their code and message, such as `ENVIRONMENT_EXISTS`
+    `An environment with this name already exists.` and
+    `ENVIRONMENT_BRANCH_TAKEN`
+    `Another environment already deploys this branch.`
+  - New options `--no-branch`, `--copy-env <source>`, `--database <seed>`
+    and `--protection <on|off>`. `--branch <b>` is in `naro help` now, and
+    says what it does: for `naro environments create` and `set`, the branch
+    whose pushes deploy to that environment; for `naro deploy`, the default
+    branch of a project the deploy creates or updates. A deploy's own branch
+    follows where it goes.
+- `naro deploy --env qa` deploys to a named environment instead of the
+  preview. It prints `✅ Deployment ready (qa)`, and `--json` has
+  `"target": "qa"` and `"environment": "qa"` (`null` for production and
+  preview). When the server gives no URL the CLI builds
+  `https://<subdomain>--qa.<host>`. `--env production` is `--prod` (and asks
+  `Deploy to production?` in a terminal the same way); `--env preview` is a
+  plain deploy. `--env` with `--prod` fails before anything is asked or sent:
+  `VALIDATION_FAILED` `--env and --prod cannot be used together.`, and
+  `--env ""` with `--env must be production, preview or an environment name.`
+  In a linked directory the environment is looked up before a missing key is
+  read, asked for or sent, and nothing is asked, sent or built when that
+  fails: a name the project has no environment for fails
+  `ENVIRONMENT_NOT_FOUND` `Environment not found.`, and while the control
+  plane has named environments switched off the deploy fails with their
+  `404 NOT_FOUND "Not found."`. Not yet linked, an environment deploy asks
+  for no missing value and sends none (the hint names the environment), and
+  the server answers `404 ENVIRONMENT_NOT_FOUND "Environment not found."`
+  for a name the project does not have.
+- Release order: deploy web with named environments 1b-2 before relying on
+  `naro deploy --env`. The deploy route of an older control plane ignores
+  the name and deploys a preview (the result says `(preview)`), saving the
+  values sent with it for `all`, which production builds read. In a linked
+  directory the environments route's 404 stops the deploy before that, and
+  an unlinked one sends no values.
+- `deployDirectory`, the library export the MCP server uses, refuses
+  `environment: "production"` and `environment: "preview"` (without
+  `production: true`) with `VALIDATION_FAILED`
+  `Pass production: true for production; preview is the default.` With
+  `production: true` the control plane answers
+  `environment and production cannot be used together.`
+- `naro deploy` counts the env vars a deploy is missing from the values that
+  deploy gets. A production deploy now lists a key set only for preview as
+  missing, and a preview deploy one set only for production; an environment
+  deploy counts the `all` values and that environment's own. On an
+  environment deploy, the values typed at the env prompt are saved for that
+  environment alone, so a developer, who cannot change `all`, has them saved
+  instead of listed under `⚠ skipped env:`. Production and preview deploys
+  still save them for `all`. The hint names the environment too:
+  `npx naro-cli env add DATABASE_URL qa`.
+- `naro env add` and `naro env remove` take an environment's slug as the
+  target: `naro env add DATABASE_URL qa`. A target that is none of
+  `production`, `preview`, `all` or a slug fails with
+  `Target must be production, preview, all or an environment name.` (it was
+  `Environment must be production, preview or all.`), and the usage reads
+  `Usage: naro env add KEY [production|preview|all|<environment>]`.
+  `naro env list` shows an environment's value under its slug.
+- `naro env remove KEY` with no target removes the `production`, `preview`
+  and `all` values and leaves every environment's alone; remove one with
+  `naro env remove KEY qa` (`Remove KEY (qa) from this project?`). A key
+  that only environments hold fails `ENV_NOT_FOUND` `No KEY variable found.`
+  and nothing is removed.
+- `naro env pull --env qa` writes an environment's values. A surface's own
+  value now wins over the `all` one whatever order the server lists them in
+  (before, the last row won), and preview's values never reach an
+  environment, as in the deploy. An environment the project does not have
+  fails `ENVIRONMENT_NOT_FOUND` `Environment not found.` before anything is
+  written. `--env` takes `production`, `preview` or a slug; anything else,
+  `""` included, fails with
+  `--env must be production, preview or an environment name.` (it was
+  `--env must be production or preview.`, and `--env ""` pulled preview).
+  The count in `✅ Pulled N variable(s)` and `--json` is the keys written,
+  so a key held by `all` and the surface counts once.
+- `naro env import <file> [target]` uploads every variable in a dotenv file
+  to one target, `all` by default. It lists the keys on stdout (stderr with
+  `--json`), every value masked but a `NEXT_PUBLIC_` one: the others,
+  `VITE_`, `REACT_APP_` and `PUBLIC_` included, are uploaded as secrets. It
+  asks `Upload 3 variables to qa?` (`1 variable`; `--yes` in CI),
+  and prints `✅ Imported 3 variables (qa)` (`--json`:
+  `{ projectId, file, target, count }`). Before any request it fails with
+  `Cannot read <file>.`, `No variables found in <file>.`,
+  `Invalid keys in <file>: A-B, 1X.` or
+  `Values over 5 KB in <file>: BIG.` (5,120 UTF-8 bytes, the limit the
+  server keeps). It uploads 100 variables per request, so a refusal of a
+  later request leaves the earlier ones saved. A line `export KEY=value`
+  reads as `KEY`. Values with `\"` or `\\` inside double quotes are read as
+  written, not unescaped, so a file `naro env pull` wrote with such a value
+  does not import back as it was (known-issues #224).
+- `naro env add` with a value typed at the prompt no longer loses it to a
+  refusal. It reads the project first, so a `--project` of another team or
+  of a deleted project fails `404 NOT_FOUND "Project not found."` before the
+  value is asked for. For an environment target it looks the environment up
+  too: a slug the project does not have fails `ENVIRONMENT_NOT_FOUND`
+  `Environment not found.` before the value is asked for, and while
+  environments are switched off `404 NOT_FOUND "Not found."` does. When the
+  role cannot write `all` (the default, or typed out), it asks
+  `You do not have permission to change production environment variables on this project. Save KEY for preview only?`
+  and on yes saves the same value for preview (`✅ Added KEY (preview, secret)`).
+  A named `production`, `preview` or environment target is not offered
+  another. A piped value works as before.
+- `naro usage` names a project that has moved to another team
+  `Moved to another team <id>`. Before, it read `Deleted project <id>`.
+- `naro db reset` reads the migration files the way the control plane now
+  runs them: `ALTER TABLE a RENAME TO b` moves `a`'s policies to `b`
+  (known-issues #87), so a policy a renamed table took along is no longer
+  listed as gone after the reset. A file that creates one of them again on
+  `b`, as the old advice said, would now stop the re-apply, and is named
+  before the schema is dropped:
+  `⚠ <file> would be refused: statement <n> of <m> failed and the migration was rolled back: policy "<name>" for table "b" already exists`.
+- `naro db table rename` moves the table's Data API policies to the new name
+  and rewrites the policies of other tables that read it, in the same
+  migration, as `naro db push` does (known-issues #87): the command prints
+  `⚠ Moved 1 Data API policy with posts to articles: own.` and
+  `⚠ Rewrote 1 policy that read posts to read articles: docs.team.`. A rename
+  a policy cannot follow is refused before anything runs. Before, the
+  policies stayed under the old name and the table was closed. Renaming the
+  table back brings them back.
+- `naro db table create`, `drop` and `rename` no longer print policies
+  "removed before the change ran" when the change fails: a change that fails
+  changes no policy now.
+- On a backend from before named policies, creating, dropping or renaming a
+  table answers `409 BACKEND_OUTDATED` until `naro backend enable` runs —
+  through `naro db table`, `naro db push` and `naro db query` alike.
+
 ### 0.18.0
 
 - `naro usage` shows a team's usage for a UTC month from the terminal:
@@ -866,8 +1042,9 @@ An `--update-check` you give replaces the default: without
   `buildCode`, the code the dashboard shows. It is a deployment error code,
   such as `NEXT_VERSION_UNSUPPORTED`, `INSTALL_FAILED`, `BUILD_FAILED`,
   `ARTIFACT_INVALID` (static output a deploy cannot take, like a symbolic
-  link), `FRAMEWORK_DETECTION_FAILED`, or `NO_DEPLOYMENT_STRATEGY` when every
-  deployment strategy of a Next.js app failed. Before, the stage's code was
+  link), `FRAMEWORK_DETECTION_FAILED`, or `NO_DEPLOYMENT_STRATEGY` when a
+  Next.js app's own build did not fail but no deployment strategy could ship
+  it (its own `next build` failing is `BUILD_FAILED`). Before, the stage's code was
   only in the message. A failed upload still fails with its own error and no
   `buildCode`; the dashboard shows its deployment code, or `DEPLOY_FAILED`.
 - `naro storage ls naro://<bucket>[/<prefix>] --search <text>` lists only the
@@ -1186,12 +1363,13 @@ Next.js), `INSTALL_FAILED` (the dependency install), `ARTIFACT_INVALID` (static
 output a deploy cannot take, like a symbolic link), `FRAMEWORK_DETECTION_FAILED`
 (no framework found, or an Angular app without an output path) and
 `BUILD_FAILED` (the app's own build, or a failure that carried no code). A
-Next.js app is built by trying deployment strategies in turn, so when
-every one fails — the app's own build error included — `buildCode` is
-`NO_DEPLOYMENT_STRATEGY` and the message says what each strategy failed at.
+Next.js app is built by trying deployment strategies in turn: when the app's
+own `next build` fails, `buildCode` is `BUILD_FAILED`; when its own build did
+not fail but no strategy can ship it, `NO_DEPLOYMENT_STRATEGY`. Either way the message says
+what each strategy failed at.
 
 `--yes` (or `-y`) suppresses every prompt — destructive actions
-(production rollback/promote, env/domain removal, database reset, backend key
+(production rollback/promote, 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
@@ -1215,9 +1393,11 @@ credentials live in `~/.naro/credentials.json` (0600).
 
 - Values are entered via hidden prompt or stdin — never as an argument:
   `echo "$DATABASE_URL" | naro env add DATABASE_URL production --yes`
-- Targets: `production`, `preview`, `all` (default).
+- Targets: `production`, `preview`, `all` (default), or a named
+  environment's slug: `naro env add DATABASE_URL qa`.
 - `naro env pull` writes `.env.local` (preview + all vars by default,
-  `--env production` for production values).
+  `--env production` for production values, `--env <name>` for an
+  environment's).
 
 ## Configuration