@marktiderman/genesis-cli 1.21.0 → 1.22.1

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
@@ -494,14 +494,20 @@ doesn't fit, is a warning.
494
494
  downgraded.
495
495
  2. Runs a codemod only when a release declares a breaking change it fixes: the registry in
496
496
  `src/upgrade/codemods.ts` names the package and the first version that breaks, and a codemod
497
- runs when a package moves across it. A major move (or a 0.x minor) without one is listed so you
498
- read its changelog. `genesis codemod` lists them and `genesis codemod <id> [--dry-run]` runs
497
+ runs when a package moves across it. A major move (or a 0.x minor) without one is listed with
498
+ a link to its changelog (read from the Genesis repository) and the major changes in it, or a
499
+ note that it lists none of its own and moved with its dependencies (a peer's break can still
500
+ reach you). When the changelog can't be read, or doesn't reach that version, the link alone. A
501
+ codemod covers a major only when it was declared for that major. `genesis codemod` lists them and `genesis codemod <id> [--dry-run]` runs
499
502
  one by hand, for an app that moved its versions some other way:
500
503
 
501
504
  | Codemod | Runs when | Changes |
502
505
  | --- | --- | --- |
503
506
  | `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. |
504
507
  | `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. |
508
+ | `genesis-ui-native-3-8-composer-has-content` | genesis-ui-native crosses 3.8.0 | Inside each `<NativeComposerBar …>` tag: `empty={false}` → `hasContent`, `empty` and `empty={true}` → `hasContent={false}`, and `empty={expr}` → `hasContent={!(expr)}`. A spread can't be read, so its `empty` is left to the type error. |
509
+ | `genesis-ui-overlays-fit-the-phone` | genesis-ui crosses 2.31.0 | The doctor's `ui/overlays-fit-the-phone`: in files that import genesis-ui, drops a `max-h-[…vh]` of 80 or more from `DialogContent`, `AlertDialogContent` and `SheetContent` when the tag has no other cap, no height of its own and isn't a bottom sheet, and moves anything else in `vh` to `dvh`. See [the migration guide](https://github.com/marktiderman/genesis/blob/main/docs/MIGRATION.md). |
510
+ | `genesis-ui-native-haptics` | genesis-ui-native crosses 3.7.0 | The doctor's `haptics-use-genesis`: turns calls on `import * as Haptics from "expo-haptics"` into `playHaptic(Haptics, "light")`, and prints the files with calls it can't name. See [the migration guide](https://github.com/marktiderman/genesis/blob/main/docs/MIGRATION.md). |
505
511
  3. Reinstalls. With pnpm, a release younger than the app's `minimumReleaseAge` is installed in
506
512
  loose mode and pnpm pins it in `minimumReleaseAgeExclude`, in the pnpm-workspace.yaml pnpm reads
507
513
  (the nearest one at or above the app, but never above the repository's top level, else beside
@@ -550,20 +556,55 @@ doesn't fit, is a warning.
550
556
  new package migrations are listed (run `genesis migrate`). In an app whose database files live
551
557
  elsewhere, nothing under `supabase/` is refreshed or added and no migrations are listed: the
552
558
  summary says to run `genesis upgrade` in that app.
553
- 4. Runs `genesis doctor` and prints a summary; `--pr` commits to `genesis-upgrade/<version>`,
559
+ 4. Regenerates what comes from the installed packages, and the pull request carries it: the agent
560
+ guide (`genesis agents`), when the app has it, and `features build`, when it has a registry.
561
+ `--no-agents` and `--no-features-build` turn them off; a failure is a warning in the summary.
562
+ And names each export the release added that the app builds by hand, with the swap to make,
563
+ before the doctor's `shadowed-export` reports it. That swap isn't mechanical, so it's named and
564
+ not made.
565
+ 5. Runs `genesis doctor` and prints a summary (a changed file the repository ignores stays out of
566
+ the `--pr` commit, and the summary names it); `--pr` commits to `genesis-upgrade/<version>`,
554
567
  pushes and opens a pull request with `gh`. It checks first, before writing anything, that the
555
568
  tree is clean, a branch is checked out and the branch name is free; it commits the lockfile
556
569
  (found up to the repository's root), never `.genesis-next` files. `--dry-run` changes nothing,
557
570
  and shows the refresh against the packages installed now.
558
571
 
572
+ It starts only with the app's dependencies installed, when it needs them: an app with owned files
573
+ merges your edits against the installed versions, so without them it stops, changes nothing and
574
+ gives the install command. (With no owned files, the upgrade's own install is enough, unless you
575
+ pass `--no-install` or `--dry-run` and the doctor is on.)
576
+
577
+ **An app in a sub-folder of its repository.** Set `"appFolder"` at the top of
578
+ `genesis.config.json` to the app's folder from the repository root:
579
+
580
+ ```json
581
+ { "appFolder": "mobile" }
582
+ ```
583
+
584
+ - `.eas/workflows/*.yml` are written with their `paths` from the repository root (`mobile/src/**`,
585
+ `mobile/app.json`), which is how EAS reads them. Otherwise that's an edit on every line of the
586
+ list, which conflicts with each template change and leaves a `.genesis-next` each release. A
587
+ lock with no `REPLACE_WITH_APP_FOLDER` substitution gets `src` as the code folder. Turning the
588
+ setting on keeps the edits you have, but can't move them: a file with other edits and paths
589
+ still from the app's folder merges with those paths as they were, and the summary warns and
590
+ names them, to prefix by hand. A lockfile above the app stays an edit of yours, and an
591
+ unprefixed line for it is right, so it's never named.
592
+ - `.github/workflows` is left to the repository: GitHub reads only the root's, a file that holds
593
+ the rest of its CI too, so nothing is written, merged or left beside it. A template's change is
594
+ named once in the summary (your copy passes `working-directory: mobile`; see docs/APP-CI.md),
595
+ and the doctor's `lock-files` doesn't ask for the file here.
596
+
597
+ A conflict in a workflow in an app below its repository's root says to set it.
598
+
559
599
  `--version <v>` is upgrade's own option: `genesis upgrade --version 2.30.0` upgrades to 2.30.0
560
600
  (the CLI's own version is `genesis --version`, before any command). Since genesis-cli 1.18.0;
561
601
  1.17.3 printed its own version instead.
562
602
 
563
603
  **Upgrading the CLI itself.** The upgrade runs in the CLI that started it. It moves the app's
564
604
  `@marktiderman/genesis-cli` dependency with the rest, but it doesn't restart in the new CLI: the
565
- codemods, the owned-file refresh and the doctor of this run are the installed CLI's, so a
566
- codemod the new release added doesn't run. To upgrade with the release's own CLI, start it
605
+ codemods, the owned-file refresh, the agent guide and the doctor of this run are the installed
606
+ CLI's, so a codemod the new release added doesn't run, and the new CLI's doctor can report
607
+ `agent-guide-stale` until you run `genesis agents`. To upgrade with the release's own CLI, start it
567
608
  through npx:
568
609
 
569
610
  ```bash
@@ -577,7 +618,8 @@ dependencies.
577
618
  entry may only write where its kind of source goes (a template to `eas.json`, `.eas/`, `.maestro/`
578
619
  or `.github/workflows/`, a function file to `supabase/functions/<name>/`, a pgTAP test to
579
620
  `supabase/tests/database/`, a skill to `.claude/skills/`), never a migration and never `.git`;
580
- substitutions may only replace the starter's own names. A pgTAP test waits while its block has
621
+ substitutions may only replace the starter's own names, each with a plain name, and
622
+ `REPLACE_WITH_APP_FOLDER`, with a plain relative folder (`src`, `apps/web`). A pgTAP test waits while its block has
581
623
  new migrations to copy.
582
624
 
583
625
  ## Lint rules
@@ -750,6 +792,7 @@ Upgrading Genesis upgrades the checks.
750
792
  | Option | |
751
793
  | --- | --- |
752
794
  | `--strict` | Fail on warnings too. `info` findings never fail. |
795
+ | `--verbose` | List the Genesis components no file imports, not only their count. |
753
796
  | `--json` | Print `{ ok, genesis, errors, warnings, infos, findings, unused }`; each finding has its `level` (`error`, `warn` or `info`). Build output is captured, not streamed. |
754
797
  | `--build` | After the checks, run `doctor.build` commands, or the app's `typecheck` then `build` scripts. A build that itself runs the doctor doesn't recurse. |
755
798
  | `-c, --config <path>` | Config file. Default: `genesis.config.json`, then the `genesis` key of package.json. |
@@ -757,7 +800,7 @@ Upgrading Genesis upgrades the checks.
757
800
  | `--print-genesis` | Print the components, tokens, raw tags, palette and companion packages' components read from Genesis, and exit. |
758
801
  | `--base <ref>` | The git ref change checks compare against: the packages pack's change gate and the [ratchet](#the-ratchet) (`newOnly` rules report files unchanged since the merge base as `info`). |
759
802
 
760
- Exit codes: `0` pass, `1` findings, `2` the doctor couldn't run (bad config, Genesis not installed or not built).
803
+ Exit codes: `0` pass, `1` findings, `2` the doctor couldn't run (bad config, Genesis not installed or not built). With the app's dependencies not installed, the message gives the install command.
761
804
 
762
805
  ### Rules
763
806
 
@@ -785,6 +828,7 @@ Exit codes: `0` pass, `1` findings, `2` the doctor couldn't run (bad config, Gen
785
828
  | `removed-scope-name` | error | A "practice" name genesis-core 2 removed, in a file that imports a Genesis package: a view field's `timeZone: "practice"` (a string value in a view definition), NativeResourceView's `practiceTimeZone`, `resolveZone("practice", …)`, or DisplayTimeZones' `practice`. `defineView` refuses the first when the view loads and the rest are type errors; this lists them in CI. `genesis codemod genesis-core-2-scope-names` rewrites every one. It reads only Genesis API usage, the same shapes the codemod rewrites (see its row above); comments and an app's own `practice` settings, props and `resolveZone` are skipped. |
786
829
  | `deprecated-import` | warn | A named import of a Genesis export tagged `@deprecated` (or `@stability Deprecated`) in its published declarations. It goes at the next major; the message carries the tag's advice. Ratcheted by default: under `--base`, files that didn't change report it as `info`, so an upgrade never fails strict CI on untouched files. |
787
830
  | `beta-import` | info | A named import of an export tagged `@stability Beta` or `Experimental`, which may still change in a minor. Info by default since most of Genesis is beta; set it to `warn` in `rules` to see it in CI. |
831
+ | `figma-routes` | info | Runs only when genesis.config.json has a `figma` block: [genesis figma:routes](#genesis-figmaroutes) as findings. A configured page the file doesn't have, a route with no frame, navigation with no hotspot and a `// figma:` id that isn't the route's frame are `info`, `warn` under `--strict`; frames with no route, hotspots to them and navigation that isn't a string literal are always `info`, by design. Never `error`. Invalid JSON or a bad `figma` block in genesis.config.json is one `warn` naming the file. Without `FIGMA_ACCESS_TOKEN`, or when the API can't be read or doesn't answer within 30 seconds, one `info` notice. The Vite plugin and `genesis upgrade` skip it (it reads the network). |
788
832
  | `scope-practice-id` | info | `scope.practiceId` read with no `ResourceScope` augmentation in the app (declaration files included). It still works, as the app's own key in the open slot, but reads as `unknown`; the message gives the one-line augmentation. Never fails, `--strict` included. |
789
833
  | `stale-exception` | warn | An `allow` entry that no longer matches anything, or a `packageRules` entry that names no rule an installed package declares (a typo there would change nothing). An id in the namespace of a package with a `plugin` isn't checked, since a plugin's ids aren't known until it reports. |
790
834
  | `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). |
@@ -797,8 +841,8 @@ Exit codes: `0` pass, `1` findings, `2` the doctor couldn't run (bad config, Gen
797
841
  | `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. |
798
842
  | `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. |
799
843
 
800
- It also prints **Available but unused**: the Genesis components no file imports, and a
801
- **Primitives** line: how many rules the installed packages declare (`genesis catalog` lists
844
+ It also prints **Available but unused**: how many Genesis components no file imports (`--verbose`
845
+ lists them, `--json` always does), and a **Primitives** line: how many rules the installed packages declare (`genesis catalog` lists
802
846
  them). Check both before building something.
803
847
 
804
848
  The route rules (`hand-rolled-sub-nav`, `resource-workspace`, `page-layout`) read the routes
@@ -1209,6 +1253,95 @@ if (!result.ok) throw new Error(formatReport(result));
1209
1253
  the local Vite plugin import with `@marktiderman/genesis-cli/vite`.
1210
1254
  4. Run `genesis doctor`, fix or `allow` what it reports (it checks `raw-color` in code as well
1211
1255
  as CSS, and `raw-tag` only in JSX files), then delete the old script.
1256
+ ## genesis figma:routes
1257
+
1258
+ A read-only check that an app's Figma app file covers its routes, so CI reports the drift and an
1259
+ agent closes it (through the Figma MCP; this command never writes to Figma). The file layout it
1260
+ expects is in [docs/FIGMA-GUIDELINES.md](../../docs/FIGMA-GUIDELINES.md): frames named by route,
1261
+ `<route> · <state>` for a state, and proposals in `Proposal · <status> · <slug>` sections on
1262
+ their route page (an older `Proposals` page is still read).
1263
+
1264
+ ```json
1265
+ { "figma": { "file": "<file key>", "pages": { "web": "<page name>", "native": "<page name>" }, "proposalsPage": "Proposals" } }
1266
+ ```
1267
+
1268
+ `figma` goes at the top of genesis.config.json. `file` is the key from the file's URL; `pages`
1269
+ names the page holding each platform's route frames (one or both); `proposalsPage` defaults to
1270
+ `Proposals`. The token comes from `FIGMA_ACCESS_TOKEN` (a personal access token with read access
1271
+ to the file). It is sent only as the `X-Figma-Token` header, never printed or written; nothing is
1272
+ cached.
1273
+
1274
+ | Option | |
1275
+ | --- | --- |
1276
+ | `--json` | Print the report as JSON. |
1277
+ | `--strict` | Exit 1 when anything is missing: a page the config names that the file doesn't have, a route with no frame, navigation with no hotspot, a mismatched `// figma:` id. Frames with no route, hotspots to them and navigation the check can't read are reported but never fail it, by design: they are drift for a designer to sort, not gaps in what the app ships. |
1278
+ | `-d, --dir <dir>` | The app's folder (default: cwd). |
1279
+
1280
+ Exit codes: `0` reported, `1` gaps under `--strict`, `2` the check couldn't run (no `figma` block,
1281
+ genesis.config.json isn't valid JSON, no token, the API refused or didn't answer within 30 seconds).
1282
+ The same check runs in `genesis doctor` as the `figma-routes` rule.
1283
+
1284
+ **Routes.** Expo Router under `src/app`, else `app` (platform `native`): a file is its route,
1285
+ `(group)` folders kept as written, `index` naming its folder (`(tabs)/index.tsx` is `(tabs)`), and
1286
+ `_layout` and `+`-files (`+not-found`, `+native-intent`, `+html`, `+api`) left out. TanStack
1287
+ Router file routes under `src/routes` (platform `web`): dots and folders are segments, `$id`
1288
+ params and `{-$section}` optional segments kept as written, `.lazy` files folded into their
1289
+ route, `__root`, `route.tsx` and `-private` files left out. The root page is `index`.
1290
+
1291
+ **Navigation.** String literals only: `router.push("…")`, `router.replace("…")`,
1292
+ `router.navigate("…")`, `<Link href="…">`, `<Link to="…">` and `navigate({ to: "…" })`, in
1293
+ `src/` and `app/`. A target is matched to a route by URL: groups and pathless `_x` segments
1294
+ dropped, params match any segment, an Expo catch-all `[...rest]` (and a TanStack `$` splat)
1295
+ matches the rest of the path, optional segments may be absent. Only navigation in a route file
1296
+ is checked against that route's frame. A template literal with `${…}` or a `{ pathname, params }`
1297
+ object can't be resolved to a route, so in a route file it is listed as not checked (`info`)
1298
+ rather than matched.
1299
+
1300
+ **Figma.** `GET /v1/files/:key?depth=2` gives the pages and their top-level frames;
1301
+ sections on those pages are read with `GET /v1/files/:key/nodes?ids=…&depth=1` for the frames
1302
+ inside them. Each route frame's tree is then read with `GET /v1/files/:key/nodes?ids=…`, and a
1303
+ hotspot is any node in it with `interactions[].actions[]` of `type: "NODE"` and a
1304
+ `destinationId` (any `navigation` except `CHANGE_TO`, which swaps a variant), or with the older
1305
+ `transitionNodeID`. A frame matches a route when its name before ` · ` is the route as written
1306
+ (`(tabs)/settings`) or names the same URL (`settings`).
1307
+
1308
+ **The report.** A summary (routes, route frames, covered routes and percent, hotspots, missing),
1309
+ then: routes with no frame; frames on a route page with no route, outside a proposal section (put
1310
+ them in one, or add the route); proposals by section, from the route pages' `Proposal ·`
1311
+ sections and the Proposals page; navigation in a route file whose screen has a
1312
+ frame but no hotspot to the target's frame; hotspots whose destination frame has no route;
1313
+ `// figma:` ids that don't match; and navigation that isn't a string literal (not checked).
1314
+
1315
+ ```text
1316
+ Figma route coverage (file FAKEfileKEY123): 7 routes, 6 frames, 4 covered (57%), 3 hotspots, 6 missing
1317
+
1318
+ Routes with no frame (3)
1319
+ platform route file
1320
+ -------- ---------------- -------------------------------
1321
+ native items/[id] src/app/items/[id].tsx
1322
+ web admin/decks src/routes/admin/decks.tsx
1323
+ web docs/{-$section} src/routes/docs.{-$section}.tsx
1324
+
1325
+ Navigation with no hotspot (2)
1326
+ from to at
1327
+ ------ ---------------------- --------------------------
1328
+ (tabs) items/[id] (no frame) src/app/(tabs)/index.tsx:6
1329
+ index admin/decks (no frame) src/routes/index.tsx:6
1330
+ ```
1331
+
1332
+ ### Linking a route to its frame
1333
+
1334
+ A route file may name its frame's node id in a comment on one of its first five lines, so an
1335
+ agent can jump from the route to the frame:
1336
+
1337
+ ```tsx
1338
+ // figma: 12:345
1339
+ export default function Settings() { … }
1340
+ ```
1341
+
1342
+ `12-345` (as a URL writes it) works too. The check reports a comment whose id isn't one of the
1343
+ frames named for that route (the frame was replaced, or the comment was copied).
1344
+
1212
1345
  ## genesis upstream
1213
1346
 
1214
1347
  What an app needed from Genesis and didn't find goes in `docs/genesis-upstream.md` (or