naro-cli 0.7.0 → 0.9.0

package/README.md

@@ -86,9 +86,61 @@ naro db enable                     Create the project's database (Cloudflare D1)
 naro db info                       Status, size, table count, limits
 naro db query "select 1"           Run SQL; --file query.sql, or pipe stdin
 naro db push [--dry-run]           Apply pending ./migrations (asks first; --yes in CI)
+naro db dump --output backup.sql   SQL dump, streamed from Cloudflare (stdout without
+                                   --output); --schema-only | --data-only, --table a,b
+naro db restore --bookmark <id>    Time Travel, last 30 days (or --timestamp <time>);
+                                   asks first, prints the command that undoes it
+naro db pull                       Existing database, no migrations yet: writes its schema
+                                   as migrations/0001_remote_schema.sql, recorded as applied
+naro db reset [--dry-run]          Drop every table, view and trigger, clear the ledger and
+                                   apply ./migrations again (asks first; --yes in CI)
+naro db lint [--strict]            Check the schema for what D1 actually trips on; exits 1
+                                   on an error, and on a warning too with --strict
+naro db table create posts --column "id:integer:pk:autoincrement" --column "title:text:notnull" --column "created_at:datetime:notnull:default=current_timestamp" --owner user_id
+                                   A table without SQL (--if-not-exists too); --owner adds
+                                   user_id and an owner policy
+naro db table add-column posts --column "published:boolean:notnull:default=false"
+naro db table rename-column posts title headline | rename posts articles
+naro db table drop-column posts published | drop posts   (ask first; --yes in CI)
+naro db index create posts user_id,created_at [--unique] [--name <n>] | drop <name>
+                                   Each is one migration in d1_migrations, written to
+                                   ./migrations (--no-write skips it; --dry-run shows the SQL)
 naro migration new create_users    Creates migrations/0001_create_users.sql
 naro migration list                Local files vs the d1_migrations ledger
-naro gen types --output src/db.d.ts  TypeScript types for the schema
+naro migration repair 0001_init.sql --status applied
+                                   Fix the ledger alone — mark it applied, or --status
+                                   reverted to drop its row. Its SQL is never run
+naro gen types --output src/database.types.ts
+                                   TypeScript types for the schema, for
+                                   createClient<Database>() from @naro/sdk
+
+naro backend status                On or off, status, URL and anon key (service key hidden)
+naro backend enable                Turn the backend on: D1, sign-in and the Data API; safe
+                                   to re-run, and a failed run resumes at the step that
+                                   stopped it (provision is the same command)
+naro backend disable               Turn it off: /_naro/* answers 404; data, users and
+                                   keys are kept (asks first; --yes to skip)
+naro backend keys --reveal         Print the service key (a secret; needs database write)
+naro backend keys rotate --service Replace a key (--anon or --service); the old one stops
+                                   working at once (asks first)
+naro backend auth                  Sign-in settings: email, Google, GitHub, redirects,
+                                   and the callback URL to register for each production host
+naro backend auth email set --provider resend --from "App <no-reply@example.com>" --api-key-stdin < resend-key.txt
+                                   Confirmation and password reset emails from your Resend account
+naro backend auth oauth set github --client-id Iv1.abc --client-secret-stdin < github-secret.txt
+naro backend auth redirects add https://app.example.com/auth/
+                                   Where sign-in may send the browser back to: an
+                                   origin, or only the pages under a path
+naro backend auth redirects remove https://app.example.com/auth/
+                                   Exits 1, changing nothing, when it is not in the list
+naro backend auth require-verification on
+                                   Refuse sign-in until the email is confirmed (needs email)
+naro policy list                   Per-table rules and conditions of the Data API
+naro policy set todos --select owner --insert owner --update owner --delete owner --owner user_id
+naro policy set posts --select-when 'or(is_public.eq.true,user_id.eq.auth.uid())' --insert-when 'user_id.eq.auth.uid()'
+naro policy set posts --from-file policy.json
+                                   The policy as JSON, conditions and all
+naro policy remove todos           Back to deny (asks first)
 
 naro promote <deployment-id>       Publish a build to production
 naro rollback [deployment-id]      Back to the previous production build
@@ -108,6 +160,261 @@ An apex (`example.com`) is added as a pair by default because most registrars
 goes on `www.example.com` and the apex answers with a 308 redirect to it.
 `--no-www` registers the apex alone.
 
+`naro db dump` asks Cloudflare for the dump and streams it straight from
+Cloudflare's storage to the file — the bytes never pass through naro. While the
+export runs, Cloudflare holds every other query to the database, so dump a busy
+production database when a short pause is acceptable. It ends with the bookmark
+the dump reflects; `naro db restore --bookmark <that>` brings the database back
+to it. A restore rolls back everything written after that point — the
+`d1_migrations` ledger included — and prints the bookmark that undoes it.
+
+`naro db reset` never deletes the database itself: it drops every table, view
+and trigger the project owns, empties the `d1_migrations` ledger and applies
+the local migration files again, so the schema is what those files say. It
+reads the bookmark from just before the drops and prints it, so
+`naro db restore --bookmark <that>` puts the data back. `--dry-run` lists what
+it would drop and re-apply without touching anything.
+
+`naro db lint` reads the schema and runs the checks D1 allows. Its rules are
+the ones D1 actually trips on — orphaned rows, a failed `quick_check`, a
+missing or nullable primary key, a foreign key no index starts with, a trigger
+the REST API cannot recreate, a virtual table that makes `db dump` refuse the
+whole database. There is no "unused index" guess: D1 keeps no execution
+statistics to base one on. An error exits 1, a warning exits 0 — `--strict`
+makes warnings fail too, so CI can gate on it:
+
+```bash
+naro db lint --strict --json || exit 1
+```
+
+`db lint` changes nothing, but it needs **write** access to the database, not
+read: its two checks (`foreign_key_check`, `quick_check`) are whole-database
+scans, and naro classifies those as writes on purpose so a read-only role
+cannot start them. That is also the cost warning — both walk every row that
+has a foreign key, and `quick_check` walks the file, so on a large database
+the lint is billed rows-read and can run into the 30-second query limit. Run
+it in CI on a branch's own data, not on a busy production database.
+
+`naro db table` and `naro db index` change the schema without SQL. naro
+renders the DDL from checked input — every name quoted, types and defaults
+from a fixed list — and applies it as one migration, recorded in
+`d1_migrations` and written to `./migrations` as `NNNN_schema_<op>_<table>.sql`,
+numbered after your local files and the ledger. `naro migration list`,
+`db pull` and `db reset` see it like any other migration; with `--no-write`
+there is no file, so `db reset` will not re-apply it. `--dry-run` prints the
+SQL and changes nothing. While a local migration is not in the ledger yet, a
+change is refused — `naro db push` it first, or the change would run before it.
+
+A column is `name:type[:modifier…]`:
+
+| Part     | Values                                                                                                                                                         |
+| -------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| type     | `integer`, `real`, `text`, `blob`, `numeric`, `boolean`, `datetime`, `json` (keep JSON in `text`: a `json` column turns `'123'` into a number)                 |
+| modifier | `pk`, `autoincrement`, `notnull`, `unique`, `default=<value>`, `references=<table>.<column>`, `ondelete=cascade\|set-null\|set-default\|restrict\|no-action`   |
+| default  | `'text'` (quotes keep `:` and `''` is a quote), `null`, `true`, `false`, `current_timestamp`, `current_date`, `current_time`, a number, or a bare word as text |
+
+Every primary key but a single `integer` one is `NOT NULL`; a foreign key must
+point at its table's primary key or a unique column. `--owner user_id` adds
+`user_id TEXT NOT NULL` and, when the backend is on and ready, an owner policy for all
+four actions; any other new table is closed to the Data API until you run
+`naro policy set` (the command says so). Policies are kept by table name: a
+drop removes the table's policy whenever the project has a backend, on or off
+(the command says so), and a rename leaves the old one behind — the command
+prints what to run.
+
+SQLite cannot add a PRIMARY KEY, UNIQUE or NOT-NULL-without-default column, or
+drop a primary key, a unique or indexed column, or a table another table
+references; naro refuses those before it tries and says why. It also reads the
+SQL of your triggers and views, and refuses to drop or rename a table or
+column one of them uses (it warns when the SQL leaves that open) — drop or
+recreate the trigger or view with a migration first. Changing a
+column's type needs a new table — write that migration with
+`naro migration new` (create the new table, `INSERT … SELECT`, drop the old
+one, rename the new one) and `naro db push` it.
+
+`naro migration repair <name> --status applied|reverted` edits the
+`d1_migrations` ledger and nothing else — it never runs the migration's SQL.
+It is for a ledger that stopped matching the database: a migration whose file
+ran but whose ledger row was never written (a request that timed out between
+the two), or a `db pull` baseline you want to take back. If the ledger already
+says what you asked for, it says so and writes nothing.
+
+`naro gen types` writes TypeScript for the schema: a `…Row` interface per
+table and view, and a `Database` type that `createClient<Database>()` from
+`@naro/sdk` reads, with `Tables<"name">`, `TablesInsert<"name">` and
+`TablesUpdate<"name">` to pick one out. `--lang typescript` is the default and
+the only language.
+
+```bash
+naro gen types --output src/database.types.ts
+```
+
+```ts
+import { createClient } from "@naro/sdk";
+import type { Database } from "./database.types";
+
+const naro = createClient<Database>({ url, anonKey });
+const { data } = await naro.from("posts").select("id, title"); // { id: number; title: string }[] | null
+```
+
+`Insert` leaves out generated columns and makes a column optional when it has
+a default, allows NULL, is the `INTEGER PRIMARY KEY`, or is the `--owner`
+column of a table whose insert rule is `owner` (the backend fills it; see
+below); `Update` makes every column optional. A TEXT column also takes an array
+or object (`Json`), which the Data API stores as its `JSON.stringify` text — it
+reads back as that string, so `JSON.parse` it. A BLOB is `number[]` (what D1
+returns) and cannot be written through the Data API; a column with no type, or
+a STRICT table's `ANY`, is `number | string | number[]`. When the backend's
+policies cannot be read (no backend yet, not ready, no permission), the types
+are generated without them and one `⚠` line on stderr says why — `--json`
+carries `policies: "unavailable"` and `policiesReason`.
+Before 2026-09-24 `Database` was a flat map (`Database["users"]` was the row)
+and BLOB was `ArrayBuffer`: use `Tables<"users">` now. The `…Row` interfaces
+are unchanged.
+
+`naro backend` is the project's Naro backend: its own D1, email and password
+sign-in, and a Data API that browser code calls through `@naro/sdk` at the
+project's URL. It is off until you turn it on, one project at a time:
+`naro backend enable` (or the Database page of the dashboard). The anon key
+is public — it identifies the project and grants nothing. The service key
+skips every policy, so the CLI prints it only for
+`naro backend keys --reveal` and for a rotation that made a new one; keep it
+on a server. `naro backend enable` exits 1 with `BACKEND_PROVISION_FAILED`
+when a step stopped the run (the server still answers 200), and running it
+again picks up at that step. `naro backend status` calls a run that died
+part-way (still `provisioning`, but nothing holds its lease) stalled; the
+same `enable` picks it up. `provision`, the command's first name, still works.
+
+`naro backend disable` turns the backend off: the app's `/_naro/*` requests
+get 404 in up to about 90 seconds, as the routing cache ages out. The D1 with
+its data and users, the keys, the sign-in settings and the policies are kept,
+and `naro backend enable` brings it back with the same keys — the app needs
+no new anon key. It asks first; without a terminal it needs `--yes`, and
+exits 1 with `CONFIRMATION_REQUIRED` otherwise. `naro backend status` prints
+`Backend: off since <time>` (JSON `backend.enabled`, `backend.disabledAt`).
+`Backend: turning off` (JSON `backend.turningOff`) is a turn-off whose routes
+may still answer. While a run holds its lease (`backend.leaseExpiresAt` still
+ahead) it is in progress, and the advice says to check again in a minute;
+otherwise it stopped half-way: run `naro backend disable` again to finish it
+(the control plane retries it too). Another run holding the lease answers
+`BACKEND_BUSY` "Another change to the project backend is in progress. Try
+again in a minute." Both commands are safe to
+re-run and repair what they can: disable removes the routes again, enable
+writes them again. While it is off, key rotation and sign-in changes answer
+`409 BACKEND_OFF`; reads and policy changes still work.
+
+A rotation (`naro backend keys rotate --anon|--service`) needs a ready backend;
+a 409 (`BACKEND_NOT_READY`, `BACKEND_BUSY`, `BACKEND_OFF`) means nothing was tried. It
+installs the new key on the Naro worker first and swaps it in the database
+second, and the database decides the outcome: whenever the new key ends up
+live the answer carries it, and the CLI prints it — with a warning to run
+`naro backend enable` if a step after the swap failed. A
+`BACKEND_ROTATION_FAILED` prints no key and usually leaves the old key
+working. If you are not sure — any 5xx, a timeout, a lost connection, or the
+message that the worker may still expect the new key — run
+`naro backend keys --reveal` to see which key is live, then
+`naro backend enable`; the CLI prints that hint (JSON `hint`) and exits 1.
+For a few seconds during a rotation the worker can already refuse the old key.
+
+`naro backend auth` sets up email and social sign-in with the project's own
+accounts — Naro runs no shared sender. Email (confirmation and password reset
+links) needs a Resend API key and a `from` address; Google and GitHub need
+the project's own OAuth app. `naro backend auth` prints a callback URL for
+each production host — `https://<project>.naro.sh/_naro/v1/auth/callback/<provider>`
+and the same path on each custom domain. Register, as the app's redirect URI,
+the one for the origin your app passes to `createClient({ url })`: the
+provider sends the browser back to the host the sign-in began on, where its
+cookie is (otherwise `redirect_uri_mismatch`). A GitHub OAuth app takes one
+callback URL, so it serves one of those hosts.
+Secrets are read from stdin only — `--api-key-stdin` and
+`--client-secret-stdin` take a pipe, or ask without echo in a terminal — and
+`--api-key <value>` is refused, so a key never lands in shell history. The
+answers show a secret as its first 7 characters (the email key) or `set`.
+
+A sign-in may send the browser back only to the project's production hosts —
+its naro.sh address and its custom domains — and the entries
+`naro backend auth redirects add` allowed: an origin
+(`https://host[:port]`, every page) or an origin and a path ending in `/`
+(`https://app.example.com/auth/`, only the pages under it); `http://` only
+for localhost. The preview host (`<project>-preview.naro.sh`) runs whatever
+branch was pushed against the same accounts, so it is allowed only once it
+is added, and confirmation and reset emails always link to a production
+host. An entry for a production host narrows it too.
+`naro backend auth redirects remove` exits 1 and changes nothing when the
+entry is not in the list, naming the entries that still allow that origin;
+after a removal it names them too. The
+code or reset token rides in the URL fragment, which any script on the page
+— or an open redirect like `/logout?next=…` — can pass on: allow a path of
+sign-in pages rather than a whole origin. Each change uploads
+the Naro worker again; when that upload stops, the change is saved all the
+same and the command exits 1 with `BACKEND_PROVISION_FAILED` — run
+`naro backend enable` to finish. `require-verification on` needs email set
+up (`VERIFICATION_NEEDS_EMAIL`), and email cannot be removed while it is on.
+
+Policies are default deny: a table without one refuses every anon and
+signed-in request. Each of `--select`, `--insert`, `--update` and `--delete`
+takes `none`, `public`, `authenticated` or `owner`; `owner` lets a signed-in
+user reach only rows whose `--owner` column holds their user id, and fills
+that column in on insert. What a `policy set` leaves out keeps its stored
+value. A change is live within about 10 seconds. `naro gen types` reads the
+policies too: with `--insert owner --owner user_id`, `user_id` is optional in
+the generated `Insert` even when it is `NOT NULL` with no default — run it
+again after changing a policy.
+
+Instead of a rule, an action can hold a condition on the row, like a Supabase
+row-level security policy, written in the filter syntax of `@naro/sdk`'s
+`.or()` (commas are AND) with `auth.uid()` for the signed-in user's id —
+unquoted; `"auth.uid()"` is the text, and `auth.uid` without `()` is refused
+rather than read as text:
+
+- `--select-when` and `--delete-when`: the rows reads and deletes reach.
+- `--insert-when`: what every new row must meet.
+- `--update-when`: the rows updates reach; `--update-check`: what every updated
+  row must still meet (by default the same as `--update-when`).
+- `--signed-in`: the conditions of this command refuse anon. Without it,
+  `auth.uid()` has no value for anon: one comparison with it matches no row,
+  and neither does its `not`. Inside a group SQL's three-valued logic applies,
+  so `not(and(is_public.eq.1,user_id.eq.auth.uid()))` matches every row that is
+  not public, anon included — write what a condition lets in.
+
+When any row of an insert or an update misses its condition, nothing is
+written and the Data API answers `403 PERMISSION_DENIED` ("The new row does not
+meet the insert policy of posts."). A check reads a row as it will be stored
+and compares it with the column's collation (`COLLATE NOCASE`, `RTRIM`). So:
+
+- a number column it reads takes numbers, booleans and null, not strings, and
+  cannot be compared with `like` or `ilike`;
+- a primary key column it reads must be sent, and not as null;
+- any other column it reads may be left out only when it has no default or a
+  plain one — `NULL`, `TRUE`, `FALSE`, a number, or a quoted string on a column
+  that is not a number column; a column defaulting to `CURRENT_TIMESTAMP` or
+  another expression must be sent;
+- it cannot read a generated column or a virtual table's column.
+
+One policy's conditions use at most 50 values together (an update's check
+counts each column it reads once more), leaving 50 of D1's 100 per statement
+for the request — 48 for a write with a check, which also binds the table's
+schema to make sure it checks against the table as it is now. `--from-file`
+takes the PUT body, or a policy object from `--json`
+(`naro policy set posts --json | jq .policy > policy.json`), where
+`auth.uid()` is `{"auth":"uid"}`; its `table`, if it has one, must name the
+table being set. It cannot be combined with the other policy options.
+`naro policy list` prints each condition in filter syntax that reads back as
+the same condition, or as JSON where filter syntax cannot say it exactly
+(`deleted_at.eq.null` would be the text `"null"`, and `= NULL` is not
+`IS NULL`); `--json` gives the exact JSON.
+
+Two things a condition does not do for you. An update or delete is held to its
+own condition only, not to select's, unless it asks for rows back with
+`.select()`. With an update condition broader than select's, a caller can tell
+rows it cannot select apart without `.select()`: an update that sets a value
+the check refuses answers 403 when a hidden row matches its filters and 200
+when none does, so filter by filter it learns what those rows hold. Keep
+update and delete conditions no broader than select's. And an `--update-check`
+you give replaces the default: without `user_id.eq.auth.uid()` in it, a user
+can give a row away by changing its `user_id`. Write
+`--update-when 'user_id.eq.auth.uid()' --update-check 'user_id.eq.auth.uid(),status.eq.draft'`.
+
 ## Machine-readable output (CI / AI agents)
 
 Every command supports `--json`: stdout carries exactly one JSON object,
@@ -128,6 +435,8 @@ $ naro deploy --prod --yes --json
 Failures carry stable codes (`NOT_LOGGED_IN`, `PROJECT_NOT_LINKED`,
 `FRAMEWORK_UNSUPPORTED`, `BUILD_FAILED`, `DEPLOYMENT_NOT_FOUND`,
 `ENV_NOT_FOUND`, `DOMAIN_NOT_FOUND`, `DOMAIN_NOT_READY`,
+`BACKEND_DISABLED`, `BACKEND_NOT_READY`, `BACKEND_BUSY`,
+`BACKEND_ROTATION_FAILED`, `BACKEND_PROVISION_FAILED`, `POLICY_NOT_FOUND`,
 `VALIDATION_FAILED`, `CONFIRMATION_REQUIRED`, `CANCELED`, …). A destructive
 command run non-interactively without `--yes` fails with
 `CONFIRMATION_REQUIRED` instead of silently doing nothing:
@@ -142,8 +451,8 @@ command run non-interactively without `--yes` fails with
 ```
 
 `--yes` (or `-y`) suppresses every prompt — destructive actions
-(production rollback/promote, env/domain removal) run unconfirmed, so use it
-deliberately in automation.
+(production rollback/promote, env/domain removal, database reset, backend key
+rotation, policy removal) run unconfirmed, so use it deliberately in automation.
 
 ## CI authentication
 

package/dist/artifact-types.d.ts

@@ -33,6 +33,7 @@ export interface BuildMetadata {
     gitCommitSha?: string;
     gitCommitMessage?: string;
     artifactKey?: string;
+    framework?: string;
 }
 /** Mirrors the build observer shape from the internal build package. */
 export interface BuildObserver {

package/dist/chunk-K3NQKI34.js

@@ -0,0 +1,10 @@
+#!/usr/bin/env node
+var __defProp = Object.defineProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+
+export {
+  __export
+};