@marktiderman/genesis-cli 1.18.0 → 1.19.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/README.md CHANGED
@@ -132,6 +132,47 @@ by name and text. They are the app's applied baseline: its genesis.config.json g
132
132
  `doctor.supabase.since` just after the newest, so the supabase pack checks only later migrations as
133
133
  new, even before the app has a git history to compare with. `init --native` (the brand-package scaffold for an Expo app) is unchanged.
134
134
 
135
+ ### A phone app beside a web app
136
+
137
+ A phone app often has no Supabase project of its own: it signs in to, and reads from, the web app's
138
+ database, and the web app's `supabase/` is the only migrations folder. Make it with
139
+ `--beside <web-app>`:
140
+
141
+ ```sh
142
+ genesis init sample-app --template native --target mobile --beside app
143
+ ```
144
+
145
+ When the web app has a `supabase/` folder, init writes none of the starter's `supabase/` files (or
146
+ the database CI workflow), sets `"supabase": { "app": "../app" }` in the new app's
147
+ `genesis.config.json` (the web app's folder, relative to the phone app) and drops the doctor's
148
+ supabase pack there. The lock still records the blocks that are on, with no Supabase files, and the
149
+ summary's first line says what to run in the web app for the ones whose database files it lacks
150
+ (a migration it has no copy of, newer ones of a block it has included, or an Edge Function with no
151
+ folder there), in the order to run them (a block's requirements first, `notifications` before
152
+ `push`). Each is `genesis add <block> --database-only`: only the block's migrations, pgTAP tests,
153
+ Edge Functions and `config.toml` sections, and the packages they're read from. A phone block's
154
+ install, routes, skills, steps and feature entry stay the phone app's, and the web app's lock
155
+ doesn't list the block (its copies are tracked by their headers and lock entries):
156
+
157
+ ```text
158
+ In ../app (it holds this app's database), run: genesis add account --database-only && genesis add chat --database-only
159
+ ```
160
+
161
+ A web app with no `supabase/` folder gets a note instead, and the phone app keeps its own, as
162
+ without `--beside`.
163
+
164
+ The setting, on any app: `"supabase": { "app": "<folder>" }` says this app's database files live in
165
+ that app's `supabase/`; `"supabase": false` says this app has none. With either, `genesis add`,
166
+ `migrate` and `upgrade` never write or plan Supabase files here (migrations, pgTAP tests, Edge
167
+ Functions, `config.toml` sections); they say where to run them instead (`genesis add <block> --database-only`), and which of this
168
+ app's blocks' database files the other app lacks; `upgrade` still lists new package migrations,
169
+ to apply there. They don't write into the other app: its lock, its
170
+ installed package versions and its doctor are its own, so the commands run there. `upgrade` leaves
171
+ lock entries under `supabase/` alone, so an app that moves to the setting can delete its
172
+ `supabase/` folder and those entries. The doctor's supabase pack doesn't run, and
173
+ `database-elsewhere` warns when the named app has no `supabase/`, or when a `supabase/` folder is
174
+ still here (a second, unused copy).
175
+
135
176
  ## Blocks: add, migrate, upgrade
136
177
 
137
178
  A block is a feature an app adds whole (see `defineBlock` in `@marktiderman/genesis-features`).
@@ -340,6 +381,10 @@ It never overwrites a file the app has: one with other text is reported and left
340
381
  run creates and changes nothing. `--dry-run` prints the plan and writes nothing. `genesis add
341
382
  --list` lists the blocks the app can add. `genesis studio init` is unchanged.
342
383
 
384
+ In an app whose database files live elsewhere ([A phone app beside a web app](#a-phone-app-beside-a-web-app)),
385
+ `add` copies none of the block's migrations, pgTAP tests, Edge Functions or `config.toml`
386
+ sections; a step says to run `genesis add <block>` in that app, unless its lock already lists it.
387
+
343
388
  ### genesis migrate
344
389
 
345
390
  Compares the migrations of the app's blocks (`genesis.lock.json`, less any whose
@@ -354,6 +399,7 @@ installed packages with the app's copies, and every copy that carries a header:
354
399
  | `changed-upstream` | the package now ships different text than the copy was made from | reported; never rewritten |
355
400
  | `differs` | a file with the migration's name, other text and no header | treated as the app's own; never rewritten |
356
401
  | `deleted` | the app deleted a copy `genesis.lock.json` records (its `migrations` map: where each package migration was copied) | reported; never copied again |
402
+ | `provided` | not in the app, but a migration that is (or comes in the same run) provides its objects | never copied |
357
403
 
358
404
  Every file already in `supabase/migrations` counts as applied: none is ever written again, and a
359
405
  new file is created only if its name is free (otherwise it fails). A package migration is copied
@@ -367,6 +413,33 @@ runs count that copy as handled. It exits 1 when something still needs you (a de
367
413
  choice, so it doesn't). `genesis add`, `genesis migrate` and `init --template native` record each
368
414
  copy in the lock; a run on an older lock records the copies it finds.
369
415
 
416
+ A migration that creates or adopts another package migration's objects says so in its block
417
+ manifest, `provides` on the migration entry (package.json `genesis.blocks`):
418
+
419
+ ```json
420
+ {
421
+ "file": "migrations/0001_genesis_notifications.sql",
422
+ "provides": [{ "package": "@marktiderman/genesis-supabase", "file": "migrations/0005_genesis_push.sql", "functions": ["functions/genesis-push-send"] }]
423
+ }
424
+ ```
425
+
426
+ Once the providing migration is in the app (a copy, by its header or, made before headers, by
427
+ name; or the file the lock says it was copied to, while it's there), or is copied in the same run,
428
+ the provided one is `provided`, never `new`: notifications 0001 adopts the push tables of supabase
429
+ 0005, and copying 0005 after it would fail on tables that already exist.
430
+
431
+ `provides` doesn't mean the provider creates everything: 0001 creates 0005's tables and its
432
+ register and forget functions, not the sender's (`genesis_push_targets`, `_status`,
433
+ `_tickets_record`, `_receipts_claim`/`_settle`, `_devices_forget`). `functions` names the Edge
434
+ Functions of the provided migration's package that call what only it creates: where it's provided
435
+ they're superseded, so `genesis add push` neither copies nor deploys `genesis-push-send`, and its
436
+ steps point at the notifications runner (`genesis-notifications`), which sends instead. Applying
437
+ 0001 after 0005 works too (it adopts the tables); then stop calling `genesis-push-send`, as
438
+ notifications' steps say.
439
+
440
+ In an app whose database files live elsewhere ([A phone app beside a web app](#a-phone-app-beside-a-web-app)),
441
+ migrate plans nothing and says where to run it.
442
+
370
443
  With the notifications block and a named registry (`--notifications <file>`, or
371
444
  `"notifications": { "registry": "src/notifications.ts" }` in `genesis.config.json`; a relative
372
445
  path is resolved against the app's root, `--dir`), it also mirrors the app's `defineNotifications`
@@ -436,7 +509,9 @@ doesn't fit, is a warning.
436
509
  deleted stays deleted (mark its entry `"deleted": true` so the doctor's `lock-files` knows it's
437
510
  meant). A block whose `starter.config.ts` switch is off is left out: no migrations listed, no
438
511
  files refreshed or added. AGENTS.md fragments are replaced, skills a block gained are copied, and
439
- new package migrations are listed (run `genesis migrate`).
512
+ new package migrations are listed (run `genesis migrate`). In an app whose database files live
513
+ elsewhere, nothing under `supabase/` is refreshed or added and no migrations are listed: the
514
+ summary says to run `genesis upgrade` in that app.
440
515
  4. Runs `genesis doctor` and prints a summary; `--pr` commits to `genesis-upgrade/<version>`,
441
516
  pushes and opens a pull request with `gh`. It checks first, before writing anything, that the
442
517
  tree is clean, a branch is checked out and the branch name is free; it commits the lockfile
@@ -619,7 +694,8 @@ Exit codes: `0` pass, `1` findings, `2` the doctor couldn't run (bad config, Gen
619
694
  | `package-rules-invalid` | warn | An installed or local package's `genesis.doctor` declaration (or its plugin) that doesn't validate: its rules don't run; the rest of the doctor does. Read forward-compatibly, since a package can be newer than the CLI: an unknown key is ignored, and a `prefer` rule or primitive that doesn't validate is skipped on its own, each with this warning. An unknown key on a `prefer` rule itself or in its `unless` could narrow where it applies, so that rule is skipped whole rather than run wider; an unknown key in `forbid` is only dropped. It is never an error, so a package upgrade can't break an app's build. See [Package rules](#package-rules). |
620
695
  | `package-rule-override` | warn | `rules` changes a package rule's level without a reason; move it to `packageRules` with one. |
621
696
  | `agent-guide-stale` | warn | The agent guide `genesis agents` wrote (`.claude/skills/genesis/SKILL.md` and the `genesis-primitives` block in AGENTS.md) doesn't match the installed packages, one of the two is missing, or the block's markers are broken (one missing, repeated or out of order; `genesis agents` then writes nothing). An app with neither isn't checked. Line endings don't count. |
622
- | `lock-files` | warn / info | `genesis.lock.json` against the files on disk. **warn**: a file the lock owns is missing; `genesis upgrade` never brings a deleted owned file back, so a lock naming files that aren't there passes every upgrade silently. A file you deleted on purpose gets `"deleted": true` in its lock entry: the warning stops and upgrade still leaves it deleted. **info**: a locked file whose checksum differs from the lock's (an app edit, which upgrade three-way merges the next version into, or one waiting on its `.genesis-next`); a file marked deleted that is back; a locked block whose `starter.config.ts` switch is off (upgrade and migrate leave it out, and its files aren't checked). |
697
+ | `database-elsewhere` | warn | An app whose `genesis.config.json` `supabase` setting puts its database files in another app (`{ "app": "../app" }`) or nowhere (`false`): **warn** when the named app has no `supabase/` folder, and when this app still has one (`add`, `migrate` and `upgrade` never plan it, so it's a second, unused copy). The supabase pack doesn't run in such an app. |
698
+ | `lock-files` | warn / info | `genesis.lock.json` against the files on disk. **warn**: a file the lock owns is missing; `genesis upgrade` never brings a deleted owned file back, so a lock naming files that aren't there passes every upgrade silently. A file you deleted on purpose gets `"deleted": true` in its lock entry: the warning stops and upgrade still leaves it deleted. **info**: a locked file whose checksum differs from the lock's (an app edit, which upgrade three-way merges the next version into, or one waiting on its `.genesis-next`); a file marked deleted that is back; a locked block whose `starter.config.ts` switch is off (upgrade and migrate leave it out, and its files aren't checked); files under `supabase/` the lock still lists in an app whose database lives elsewhere (upgrade leaves them alone, so delete the entries). |
623
699
  | `ratchet-skipped` | warn / error | `--base` was given, but git couldn't compare (not a repository, or the ref isn't fetched). A warning when only the ratchet was skipped (every rule ran at its full level); an error when the config file holds `allow`, `rules` or `packageRules`, which then went uncompared. In CI, check out with `fetch-depth: 0`. |
624
700
  | `allow-grew` | error | Under `--base`: an `allow` entry (its rule, file and match) that the doctor settings at the merge base didn't have. The list only shrinks. Rewording a `reason` is fine. The base's settings are found as the doctor finds them (genesis.config.json's `doctor`, else package.json's `genesis.doctor`), so moving them between the two compares as usual; when the base had none (adopting the doctor), nothing is compared. |
625
701
  | `rules-weakened` | error | Under `--base`, comparing the app's settings with the base's only (never with a rule's own level, which a package upgrade may change): a rule the base's `rules` or `packageRules` set that this branch sets lower, a rule newly set to `off`, or an `exclude` glob a `packageRules` entry gained. A new entry at any other level isn't compared, so pinning a rule its package raised is fine; an entry renamed with its rule counts as new. `files` isn't compared. Not compared when the base had no doctor settings. |