@marktiderman/genesis-cli 1.18.0 → 1.20.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.
Files changed (38) hide show
  1. package/README.md +147 -2
  2. package/dist/cli.js +1363 -456
  3. package/dist/cli.js.map +1 -1
  4. package/dist/{config-1jP8eCZy.d.ts → config-Dj_f9T7J.d.ts} +14 -1
  5. package/dist/doctor.d.ts +3 -3
  6. package/dist/doctor.js +402 -40
  7. package/dist/doctor.js.map +1 -1
  8. package/dist/eslint.cjs +99 -0
  9. package/dist/eslint.cjs.map +1 -0
  10. package/dist/eslint.d.cts +68 -0
  11. package/dist/eslint.d.ts +68 -0
  12. package/dist/eslint.js +72 -0
  13. package/dist/eslint.js.map +1 -0
  14. package/dist/expo.d.ts +2 -2
  15. package/dist/expo.js +18 -0
  16. package/dist/expo.js.map +1 -1
  17. package/dist/genesis-catalog.json +30 -14
  18. package/dist/index.d.ts +1 -1
  19. package/dist/index.js +410 -48
  20. package/dist/index.js.map +1 -1
  21. package/dist/starter/README.md +18 -0
  22. package/dist/starter/__tests__/components/gestures.test.tsx +64 -0
  23. package/dist/starter/__tests__/components/resolver.js +14 -2
  24. package/dist/starter/__tests__/components/setup.ts +5 -0
  25. package/dist/starter/__tests__/starter.test.ts +27 -7
  26. package/dist/starter/eslint.config.js +8 -1
  27. package/dist/starter/jest.config.js +3 -0
  28. package/dist/starter/nativewind-env.d.ts +1 -0
  29. package/dist/starter/package.json +3 -0
  30. package/dist/starter/src/lib/link-hosts.ts +7 -3
  31. package/dist/starter/supabase/functions/genesis-apple-revoke/apple.ts +7 -2
  32. package/dist/starter/supabase/migrations/20261024000700_genesis_support_findings.sql +339 -0
  33. package/dist/starter/supabase/tests/database/genesis_support.test.sql +1 -1
  34. package/dist/starter/supabase/tests/database/genesis_support_findings.test.sql +219 -0
  35. package/dist/templates/ci/genesis-upgrade.yml +1 -0
  36. package/dist/vite.js +402 -40
  37. package/dist/vite.js.map +1 -1
  38. package/package.json +18 -4
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`
@@ -400,6 +473,7 @@ doesn't fit, is a warning.
400
473
  | Codemod | Runs when | Changes |
401
474
  | --- | --- | --- |
402
475
  | `genesis-core-2-scope-names` | genesis-core crosses 2.0.0 | Genesis API usage only, never an app's own names that match (a view field means one inside `defineView(…)` or an object typed `ViewDefinition`/`ViewField`; the prop means an attribute of `<NativeResourceView>` or a key of an object typed `NativeResourceViewProps`; each with the name imported from Genesis): a view field's `timeZone: "practice"` → `"scope"`, NativeResourceView's `practiceTimeZone` (attribute or object key) → `scopeTimeZone`, `resolveZone("practice", …)` → `"scope"`, and DisplayTimeZones' `practice` (a `{ viewer, practice }` object's key, `.practice` on a value from `useDisplayTimeZones()` or typed `DisplayTimeZones`) → `scope`. `scope={{ practiceId }}` needs nothing (it is the app's own key in ResourceScope's open slot); when a file reads `scope.practiceId` and nothing declares it, the codemod prints the one-line `ResourceScope` augmentation that types it. The doctor's `removed-scope-name` rule finds what it would rewrite. |
476
+ | `genesis-cli-eslint-config` | genesis-cli crosses 1.20.0 | An ESLint flat config (`eslint.config.{js,mjs,cjs,ts,mts,cts}`) that doesn't load [`@marktiderman/genesis-cli/eslint`](#lint-rules) yet: adds the import (`require` or `import`, as the file is written) and spreads `genesis("native")` (an app with `expo` or `react-native`) or `genesis("web")` last into the array it exports, or into the array or arguments of the `defineConfig(…)` / `tseslint.config(…)` call it exports. A native app gets `eslint-plugin-testing-library` in its devDependencies when it's missing. A config that already loads the export is left alone; one it can't edit safely (built in a variable or a function, or exported twice) is left as it is, and it prints the two lines to add. A config that still inlines the starter's RNTL rules gets the spread and a note to delete the old block. Started from an older CLI, the upgrade doesn't have this codemod (see "Upgrading the CLI itself" below); the doctor's `genesis-eslint-config` then reports the app, and `genesis codemod genesis-cli-eslint-config` runs it. |
403
477
  3. Reinstalls. With pnpm, a release younger than the app's `minimumReleaseAge` is installed in
404
478
  loose mode and pnpm pins it in `minimumReleaseAgeExclude`, in the pnpm-workspace.yaml pnpm reads
405
479
  (the nearest one at or above the app, but never above the repository's top level, else beside
@@ -423,6 +497,15 @@ doesn't fit, is a warning.
423
497
  and yarn are skipped), so a Genesis package isn't left installed at two versions
424
498
  (`duplicate-genesis-package`), and commits pnpm-workspace.yaml with `--pr`.
425
499
 
500
+ With Bun, which has no dedupe, it edits `bun.lock` before the install instead: a nested copy
501
+ of a Genesis package (`<parent>/@marktiderman/genesis-…` in `packages`) at another version
502
+ than the root's goes when the root's version satisfies the parent's range, since Bun keeps it
503
+ across installs otherwise; and an overlay the upgrade deleted leaves `workspaces` (in
504
+ `bun.lock` and the root `package.json`), or `bun install` stops with "Workspace dependency not
505
+ found". If the install leaves a nested copy behind, it's dropped and the install runs once
506
+ more. The summary lists what went, and says to run `bun install` when the upgrade didn't. The
507
+ binary `bun.lockb` isn't edited.
508
+
426
509
  With `minimumReleaseAge` set in the app, pnpm runs in strict mode instead: the install fails
427
510
  with `ERR_PNPM_NO_MATURE_MATCHING_VERSION` before any tidy, and the upgrade stops and names the
428
511
  versions pnpm refused. It never loosens that setting for you: add those versions to
@@ -436,13 +519,32 @@ doesn't fit, is a warning.
436
519
  deleted stays deleted (mark its entry `"deleted": true` so the doctor's `lock-files` knows it's
437
520
  meant). A block whose `starter.config.ts` switch is off is left out: no migrations listed, no
438
521
  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`).
522
+ new package migrations are listed (run `genesis migrate`). In an app whose database files live
523
+ elsewhere, nothing under `supabase/` is refreshed or added and no migrations are listed: the
524
+ summary says to run `genesis upgrade` in that app.
440
525
  4. Runs `genesis doctor` and prints a summary; `--pr` commits to `genesis-upgrade/<version>`,
441
526
  pushes and opens a pull request with `gh`. It checks first, before writing anything, that the
442
527
  tree is clean, a branch is checked out and the branch name is free; it commits the lockfile
443
528
  (found up to the repository's root), never `.genesis-next` files. `--dry-run` changes nothing,
444
529
  and shows the refresh against the packages installed now.
445
530
 
531
+ `--version <v>` is upgrade's own option: `genesis upgrade --version 2.30.0` upgrades to 2.30.0
532
+ (the CLI's own version is `genesis --version`, before any command). Since genesis-cli 1.18.0;
533
+ 1.17.3 printed its own version instead.
534
+
535
+ **Upgrading the CLI itself.** The upgrade runs in the CLI that started it. It moves the app's
536
+ `@marktiderman/genesis-cli` dependency with the rest, but it doesn't restart in the new CLI: the
537
+ codemods, the owned-file refresh and the doctor of this run are the installed CLI's, so a
538
+ codemod the new release added doesn't run. To upgrade with the release's own CLI, start it
539
+ through npx:
540
+
541
+ ```bash
542
+ npx @marktiderman/genesis-cli@latest upgrade --version <v>
543
+ ```
544
+
545
+ The next `genesis upgrade` (and `genesis doctor`) in the app then runs the new CLI from its
546
+ dependencies.
547
+
446
548
  `genesis.lock.json` is checked like a manifest, since anyone with commit access can edit it: each
447
549
  entry may only write where its kind of source goes (a template to `eas.json`, `.eas/`, `.maestro/`
448
550
  or `.github/workflows/`, a function file to `supabase/functions/<name>/`, a pgTAP test to
@@ -450,6 +552,47 @@ or `.github/workflows/`, a function file to `supabase/functions/<name>/`, a pgTA
450
552
  substitutions may only replace the starter's own names. A pgTAP test waits while its block has
451
553
  new migrations to copy.
452
554
 
555
+ ## Lint rules
556
+
557
+ Genesis's lint rules for apps ship with the CLI, as ESLint flat-config pieces from
558
+ `@marktiderman/genesis-cli/eslint` (for `require` and `import`). An app spreads them into its
559
+ `eslint.config.js` once, and every CLI release it installs brings new and changed rules, with no
560
+ edit to the config. They ship from the CLI rather than a package of their own because every
561
+ Genesis app, web or native, already has `@marktiderman/genesis-cli` in its devDependencies (the
562
+ [genesis-upgrade workflow](../../docs/APP-CI.md) needs it), so nothing new is installed.
563
+
564
+ ```js
565
+ // eslint.config.js (CommonJS, as Expo writes it)
566
+ const { defineConfig } = require("eslint/config");
567
+ const expoConfig = require("eslint-config-expo/flat");
568
+ const { genesis } = require("@marktiderman/genesis-cli/eslint");
569
+
570
+ module.exports = defineConfig([expoConfig, ...genesis("native")]);
571
+ ```
572
+
573
+ In an ES module config: `import { genesis } from "@marktiderman/genesis-cli/eslint"`.
574
+
575
+ | Export | What it is |
576
+ | --- | --- |
577
+ | `genesis(platform, options?)` | Every Genesis piece for `"native"` or `"web"`. Spread this one, so pieces a release adds arrive too. `"native"` is `testing`; `"web"` is empty for now (Testing Library for React keeps `render` and `fireEvent` synchronous, so the RNTL await rules don't apply), and is there so web rules arrive when Genesis has some. |
578
+ | `testing(options?)` | React Native Testing Library 14's await rules, for test files (`TEST_FILES`: `**/__tests__/**` and `*.test.*`). RNTL 14 made `render`, `renderHook`, `fireEvent`, `act`, `rerender` and `unmount` async; left unawaited, a test reads the screen before React updated it. It turns on testing-library's `await-async-events` with `eventModule: ["fireEvent", "userEvent"]`, and a `no-restricted-syntax` rule for what the plugin has no rule for: `render`, `renderHook`, expo-router's `renderRouter`, the starter's `renderApp` and `act`; `rerender` and `unmount` as methods and destructured; and a chained `userEvent.setup().press(…)`. Each is flagged as a statement, a declaration or an assignment whose promise is dropped. |
579
+ | `rntlAwaitSelectors(options?)` | Those `no-restricted-syntax` entries, for an app that sets its own `no-restricted-syntax` on test files: a later setting of a rule replaces an earlier one, so spread these into yours. |
580
+
581
+ Options: `renders` (the app's own helpers that wrap `render`, checked like it:
582
+ `genesis("native", { renders: ["renderWithStore"] })`), `testFiles` (other test globs) and
583
+ `testingLibrary` (the plugin, when the config loads it itself).
584
+
585
+ `testing` needs `eslint-plugin-testing-library` (7 or later) in the app's devDependencies, an
586
+ optional peer dependency of the CLI. A flat config's plugins are objects, not names ESLint looks
587
+ up, so the piece loads the plugin itself when it's built (never on import): from the app (the
588
+ working directory, so it's the copy the app's own config would load), then from the CLI. When
589
+ it's missing, the config fails to load with a message saying to install it.
590
+
591
+ `genesis upgrade` adds the pieces to an app made before they shipped: the
592
+ `genesis-cli-eslint-config` codemod (see [genesis upgrade](#genesis-upgrade)) runs when the app's
593
+ CLI moves to 1.20.0. The doctor's `genesis-eslint-config` rule reports a native app still without
594
+ them, with the fix.
595
+
453
596
  ## Expo config plugin
454
597
 
455
598
  `withGenesis()` keeps an Expo app's `app.config.ts` to a name, ids and plugins:
@@ -619,7 +762,9 @@ Exit codes: `0` pass, `1` findings, `2` the doctor couldn't run (bad config, Gen
619
762
  | `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
763
  | `package-rule-override` | warn | `rules` changes a package rule's level without a reason; move it to `packageRules` with one. |
621
764
  | `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). |
765
+ | `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. |
766
+ | `genesis-eslint-config` | warn | A native app (with `expo` or `react-native`, or the `native` pack) whose ESLint flat config doesn't load [`@marktiderman/genesis-cli/eslint`](#lint-rules), so `genesis upgrade` can't bring Genesis's lint rules; or loads it without `eslint-plugin-testing-library` in package.json, so the config can't load. The message gives the fix: `genesis codemod genesis-cli-eslint-config`, or the two lines to add. Web apps (Genesis has no web lint rules yet) and apps without a flat config aren't checked. Ratcheted by default: under `--base`, an unchanged config reports it as `info`. |
767
+ | `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). Also `bun.lock` (at or above the app, with or without `genesis.lock.json`), **warn**: a nested copy of a Genesis package at another version than the root's, when the root's version satisfies the range of the package it's nested under. Bun keeps it across installs, so the app runs two copies; the finding names the entry to delete, then reinstall (`genesis upgrade` does both). |
623
768
  | `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
769
  | `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
770
  | `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. |