@marktiderman/genesis-cli 1.23.0 → 1.25.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
@@ -798,7 +798,7 @@ Upgrading Genesis upgrades the checks.
798
798
  | `-c, --config <path>` | Config file. Default: `genesis.config.json`, then the `genesis` key of package.json. |
799
799
  | `-d, --dir <dir>` | The app's folder (default: cwd). |
800
800
  | `--print-genesis` | Print the components, tokens, raw tags, palette and companion packages' components read from Genesis, and exit. |
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`). |
801
+ | `--base <ref>` | The git ref change checks compare against: the packages pack's change gate and the [ratchet](#the-ratchet) (`newOnly` rules keep their level only in new files and in files whose count of their findings grew since the merge base; the rest are `info`). |
802
802
 
803
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.
804
804
 
@@ -831,6 +831,9 @@ Exit codes: `0` pass, `1` findings, `2` the doctor couldn't run (bad config, Gen
831
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). |
832
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. |
833
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. |
834
+ | `stale-extension` | warn | A [declared extension](#declared-extensions) whose file no longer has a finding of its rule; remove it. Not reported while the rule is `off`. |
835
+ | `extension-invalid` | error | A [declared extension](#declared-extensions) the doctor can't accept: its rule declares no extension points or `buildsOn` isn't one, its file doesn't import `buildsOn` from a Genesis package, `buildsOn` is what a package rule replaces, or something in the file flags it. The findings it would cover stay. `rules` and `allow` can't name it. |
836
+ | `extension-added` | info | Under `--base`: a declared extension the doctor settings at the merge base didn't have (every one, when the base had no doctor settings), with its reason. The report's summary lists them all, and the pull request's review is where each is accepted. Never fails. |
834
837
  | `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). |
835
838
  | `package-rule-override` | warn | `rules` changes a package rule's level without a reason; move it to `packageRules` with one. |
836
839
  | `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. |
@@ -900,7 +903,7 @@ result on its own):
900
903
  "doctor": {
901
904
  "packs": ["native", "supabase"],
902
905
  "native": { "routerRoot": "app" },
903
- "supabase": { "migrations": "supabase/migrations", "base": "origin/main", "exposedSchemas": ["public"], "since": "20260101000000" }
906
+ "supabase": { "migrations": "supabase/migrations", "base": "origin/main", "exposedSchemas": ["public"], "since": "20260101000000", "automaticBranching": false }
904
907
  }
905
908
  }
906
909
  ```
@@ -908,6 +911,8 @@ result on its own):
908
911
  Pack rule ids are built-in ids, so `rules` and `allow` work on them as on any other rule.
909
912
  Folder settings (`routerRoot`, `migrations`) are app-relative: `./app/` is read as `app`, and
910
913
  an absolute path or one leaving the app is a config error. `exposedSchemas` compares lowercased.
914
+ `automaticBranching` (true or false; unset counts as true) says whether Supabase makes a branch
915
+ per pull request; `exposed-schema-created-later` reads it.
911
916
 
912
917
  **`native`**, for Expo apps on `@marktiderman/genesis-ui-native`. With the pack on, the core
913
918
  rules read the native package (unless `uiPackage` says otherwise) and the default scan is
@@ -943,6 +948,7 @@ bodies blanked, so text inside a function body never matches; the one exception
943
948
  | `migration-testing-kit` | error | A migration that uses `genesis_testing`, genesis-supabase's pgTAP kit for test databases only (it signs in as anyone and resets roles). Keep it in `supabase/tests/database/000_genesis_testing.test.sql`. |
944
949
  | `contracts-stale` | error | With `doctor.contracts` (`{ out, schemas, databaseEnv }`, defaults `resources.genesis.ts`, the schemas the contract's own `// Source: Postgres (…)` line names (else `["public"]`), `DATABASE_URL`): the contract on disk isn't what `genesis introspect` would write from the database now (the same comparison as `introspect --check`). Without the environment variable it reports one `info` ("not checked") and never fails; a database it can't read is a warning, and a contract it can't generate (an invalid `labelField`, two tables with one name) is an error. The advice names the schemas and, when it isn't `DATABASE_URL`, `--database-env`. A contract whose `// Source:` line isn't Postgres (one written with `--openapi`) is reported as `info` ("not checked"); check it with `genesis introspect --openapi … --check`. Line endings don't count. The Vite plugin skips it in builds and the dev server, so a build never reads a live database: run it with `genesis doctor` in CI. |
945
950
  | `migration-view-rls` | error | A view in an exposed schema that runs as its owner once every migration has run: created without `with (security_invoker = true)`, replaced without it, or reset by `alter view … reset (security_invoker)`. A plain view reads past row level security on every table it selects from. `alter view … set (security_invoker = true)`, renames and drops are followed. A view that runs as its owner on purpose (it filters rows itself) takes an `allow` entry: `{ "rule": "migration-view-rls", "match": "public.profile_cards", "reason": "…" }`. |
951
+ | `exposed-schema-created-later` | warn | A schema the Data API serves (`supabase/config.toml` `[api] schemas`, beside the migrations folder, or `exposedSchemas`) that a new Supabase database doesn't have before migrations run: anything but `public`, `graphql_public` and the platform's own schemas (`auth`, `storage`, `extensions`, `graphql`, `realtime`, `vault`). A Supabase branch applies `[api]` before it runs migrations, so a fresh preview branch's Data API points at a schema that doesn't exist yet and fails its health check; the message names the migration that creates it, or says none does. The fix is the Genesis preview standard: turn automatic branching off ([APP-CI.md, "Previews"](../../docs/APP-CI.md#previews)), then record that with `"supabase": { "automaticBranching": false }`, which quiets the migration-created case (a schema no migration creates still warns). Use that, not an `allow` entry: under `--base` a new `allow` entry fails `allow-grew`. The doctor can't see the Supabase dashboard, so `automaticBranching: false` is the app's word, not a check: review a change to it as you would an `allow` entry. It doesn't cover on-demand branches, which run the same steps; check one serves the schema after it migrates. Quiet when `[api] enabled = false`. |
946
952
 
947
953
  **Which migrations are new.** In a git repo with the base ref, a migration is new when it was
948
954
  added, modified or is untracked since the merge base. `since` (a file name or timestamp prefix)
@@ -1042,13 +1048,19 @@ once). A package that must stay readable by a genesis-cli before this release ke
1042
1048
  | `platform` | `web` (off with the `native` pack) or `native` (only with it). Default both. |
1043
1049
  | `files`, `exclude` | App-relative globs. `{routes}` is the routes folder (`routesDir`). Default: every scanned script file. |
1044
1050
  | `forbid` | `jsx` element names (type arguments too: `<ResourcePage<T>`), `imports` (exact, or `prefix*`), and/or a `pattern` regular expression (every match is reported; `(?i)` for case-insensitive). Comments never count. |
1045
- | `unless` | A file is left alone when it `renders` one of these elements (it builds on the primitive) or matches `pattern`. |
1051
+ | `unless` | A file is left alone when it `renders` one of these elements (it builds on the primitive) or matches `pattern`. `inside` exempts elements, not files: a forbidden element nested inside one of these (a builder's own panels inside `BuilderLayout`), or inside an app component the file imports that renders its `{children}` inside one. Tags in strings and template literals don't count. |
1052
+ | `extensible` | The rule's extension points: the Genesis exports (or parts of one, `ResourceView.slots`) an app may build on in a way the rule doesn't recognize, and record as a [declared extension](#declared-extensions). A rule without them can't be extended. Needs genesis-cli 1.25 or later (an older one skips a rule with this key, with a `package-rules-invalid` warning). |
1046
1053
  | `use`, `import`, `docs`, `why` | The message: what to use, where from, why, and the link. `use` and `why` are required. |
1047
- | `newOnly` | Ratchet: under `--base`, findings in unchanged files drop to `info`. |
1054
+ | `newOnly` | Ratchet: under `--base`, findings drop to `info` unless they are in a new file or a file now has more of them than at the merge base. |
1048
1055
 
1049
1056
  A forbidden element counts one level up too: an app component that renders it (`RecordTable`
1050
1057
  around `DataTable`) is flagged in its own file, and so is every screen that renders the
1051
- wrapper. A package's rules never run on the package's own files.
1058
+ wrapper. `unless.inside` follows the same level, for the elements nested in it only. A package's
1059
+ rules never run on the package's own files.
1060
+
1061
+ When two rules flag the same element on the same line (an app's own rule and a package rule,
1062
+ say), the doctor reports it once, at the higher level, with every rule id in `rules` (and in the
1063
+ report's brackets).
1052
1064
 
1053
1065
  A package with nothing to enforce says so, with a reason, and may still list primitives:
1054
1066
  `"doctor": { "enforce": false, "reason": "Development tooling, not app screens." }`. In the
@@ -1089,19 +1101,29 @@ since the catalog would leave it out. Run `genesis agents` after each Genesis up
1089
1101
  ### The ratchet
1090
1102
 
1091
1103
  `newOnly` rules (package rules and app patterns can declare it), and any rule the app lists in
1092
- `doctor.ratchet` (`true` for all), apply in full only to new and changed code: with
1093
- `--base <ref>`, a finding in a file unchanged since the merge base is reported as `info`, with
1094
- "ratcheted" in its message. Changed means committed on the branch, staged, edited or
1095
- untracked. Without `--base` every rule runs at its level, as before; when git can't compare,
1104
+ `doctor.ratchet` (`true` for all), apply in full only to new code: with `--base <ref>`, the
1105
+ doctor counts each file's findings of each ratcheted rule at the merge base and now. A finding
1106
+ keeps its level only in a file the merge base didn't have, or in a file that now has more of
1107
+ that rule's findings than it had; everything else is reported as `info`, with "ratcheted" in its
1108
+ message. So a one-line fix in a file with old debt passes, and adding to the debt doesn't.
1109
+ Counts are per rule and file, not per finding: fixing one finding and adding another of the same
1110
+ rule in the same file nets out, and the new one is reported as `info` like the rest. A renamed or
1111
+ moved file keeps its count (git's rename detection). A copy doesn't: its findings are new debt,
1112
+ even when the debt moved out of the file it was copied from.
1113
+ Changed means committed on the branch, staged, edited or untracked; the merge base's counts come
1114
+ from the changed files as git has them there: only the package rules run again on them when
1115
+ every rule being counted is one (the usual case), else every check that reads the app's files;
1116
+ never the build, the database contract or Figma. When git can't read them, a changed file keeps
1117
+ every level. Without `--base` every rule runs at its level, as before; when git can't compare,
1096
1118
  `ratchet-skipped` says so and nothing is lowered. `allow` entries still remove findings,
1097
1119
  ratcheted or not: they are the recorded ratchet, file by file, and under `--base` the list only
1098
1120
  shrinks: `allow-grew` fails an entry the doctor settings at the merge base didn't have, and
1099
1121
  `rules-weakened` fails a rule the base's settings set that this branch lowers, turns off or
1100
1122
  excludes files from (compared with the base's settings only). Neither runs when the base had no
1101
1123
  doctor settings. These two and
1102
- `ratchet-skipped` guard the config itself, so `rules` and `allow` can't name them (the config is
1124
+ `ratchet-skipped` (and `extension-invalid`) guard the config itself, so `rules` and `allow` can't name them (the config is
1103
1125
  refused), and the ratchet never lowers them, nor the other rules about the config, packages or
1104
- generated files (`stale-exception`, `package-rule-override`, `package-rules-invalid`,
1126
+ generated files (`stale-exception`, `stale-extension`, `extension-added`, `package-rule-override`, `package-rules-invalid`,
1105
1127
  `package-doctor-declaration`, `plugin-error`, `build`, `agent-guide-stale`, `contracts-stale`). A
1106
1128
  shallow CI clone has no merge base, so `ratchet-skipped` fails a config with `allow`, `rules` or
1107
1129
  `packageRules`: check out with `fetch-depth: 0` and fetch the base ref (see
@@ -1111,10 +1133,57 @@ shallow CI clone has no merge base, so `ratchet-skipped` fails a config with `al
1111
1133
  { "doctor": { "ratchet": ["ui/lists-use-resource-view", "core/direct-data-access"] } }
1112
1134
  ```
1113
1135
 
1114
- ```bash
1115
- genesis doctor --strict --base origin/main
1136
+ ### Declared extensions
1137
+
1138
+ Genesis is a trellis, not a ceiling: a rule knows the usual ways of building on a primitive, and
1139
+ an app may build on Genesis in a way the rule doesn't recognize. A package rule that allows this
1140
+ declares its extension points (`extensible`), and an app that uses one, defensibly, declares it in
1141
+ `doctor.extend` instead of hiding the finding in `allow`:
1142
+
1143
+ ```json
1144
+ {
1145
+ "doctor": {
1146
+ "extend": [
1147
+ {
1148
+ "rule": "ui/lists-use-resource-view",
1149
+ "file": "src/routes/board.tsx",
1150
+ "buildsOn": "useBoardColumns",
1151
+ "reason": "The board groups rows by a computed lane, which the view's board block can't express yet.",
1152
+ "upstream": "https://github.com/marktiderman/genesis/issues/123"
1153
+ }
1154
+ ]
1155
+ }
1156
+ }
1116
1157
  ```
1117
1158
 
1159
+ `allow` is debt and only shrinks. An extension is a reviewed decision, and it is bounded:
1160
+
1161
+ - **By the rule.** Only package rules can be extended, and only at the points they declare
1162
+ (`ui/lists-use-resource-view`: `ResourceView.slots`, `ResourceView.renderDetail`,
1163
+ `ResourceView.toolbar`, `useResourceView`, `useResourceTable`, `useBoardColumns`;
1164
+ `ui/records-use-record-view`: `BuilderLayout`). A built-in rule (`deprecated-import`,
1165
+ `removed-scope-name`, `raw-tag`, …) or a package rule without points can't be, so debt can't be
1166
+ renamed an extension.
1167
+ - **By the file, now.** It names one file (no globs) and covers the findings of its rule that the
1168
+ file has when the extension is declared. Under `--base`, once the merge base has the extension,
1169
+ a file with more of them than at the merge base reports them all at their level, as the ratchet
1170
+ would.
1171
+ - **By review.** `allow-grew` and `rules-weakened` don't count it. Under `--base` a new one is an
1172
+ `extension-added` info, and the report's summary lists every extension the branch adds with its
1173
+ reason ("Extensions added on this branch"; `extensionsAdded` in `--json`). The pull request's
1174
+ review is where it is accepted; nothing else gates it.
1175
+
1176
+ The doctor checks each one:
1177
+
1178
+ - `reason` is required, at least six words and 40 characters: why the rule's primitive doesn't
1179
+ fit this file. `upstream` links the gap's write-up for Genesis, when it is one.
1180
+ - `extension-invalid` (error, can't be lowered or allowed): the rule declares no extension points
1181
+ or `buildsOn` isn't one of them, the file doesn't import `buildsOn` from a Genesis package or
1182
+ doesn't use it (render or call it; for `X.slots` and the like, pass that prop on `<X>`),
1183
+ `buildsOn` is what a package rule replaces (`DataTable`, `DetailPage`), or the doctor flags it in
1184
+ that file (a deprecated import). The findings it would cover stay.
1185
+ - `stale-extension` (warn): the file no longer has a finding of `rule`; remove the entry.
1186
+
1118
1187
  ### Config
1119
1188
 
1120
1189
  `genesis.config.json` (or `"genesis": { "doctor": { … } }` in package.json):
@@ -1143,9 +1212,9 @@ genesis doctor --strict --base origin/main
1143
1212
  | --- | --- | --- |
1144
1213
  | `packs` | | Opt-in rule packs: `"native"`, `"supabase"`. See [Rule packs](#rule-packs). |
1145
1214
  | `native` | | `{ routerRoot }` for the native pack. |
1146
- | `supabase` | | `{ migrations, base, exposedSchemas, since }` for the supabase pack. |
1215
+ | `supabase` | | `{ migrations, base, exposedSchemas, since, automaticBranching }` for the supabase pack. |
1147
1216
  | `src` | `["src"]` (`["app", "src", "components"]` with the native pack) | Folders (or files) to scan. |
1148
- | `extensions` | `.ts .tsx .js .jsx .mts .cts .css` | |
1217
+ | `extensions` | `.ts .tsx .js .jsx .mts .cts .css` | File extensions to scan (declared extensions are `extend`). |
1149
1218
  | `ignore` | | Globs to skip, added to the defaults. `*` stays in a folder, `**` crosses folders, a trailing `/` means the whole folder. |
1150
1219
  | `uiPackage` | `@marktiderman/genesis-ui` (`@marktiderman/genesis-ui-native` with the native pack) | |
1151
1220
  | `themeCss` | the design system's `dist/themes/*.css` + genesis-ui's styles | One stylesheet or a list: package paths (`@marktiderman/genesis-design-system/dist/themes/genesis.css`) or app paths. |
@@ -1160,7 +1229,8 @@ genesis doctor --strict --base origin/main
1160
1229
  | `packageRules` | | `{ "<package>/<rule>": { level?, files?, exclude?, reason } }` for the rules packages declare. `reason` is required. `files` and `exclude` apply to `prefer` rules; a package plugin decides its own files, so only `level` applies to its rules. See [Package rules](#package-rules). |
1161
1230
  | `ratchet` | | `true`, or a list of rule ids, ratcheted under `--base`. See [The ratchet](#the-ratchet). |
1162
1231
  | `contracts` | | `{ out?, schemas?, databaseEnv? }`: the supabase pack's `contracts-stale` check. Needs the supabase pack. |
1163
- | `allow` | | Exceptions: `{ rule, file?, match?, reason }`. `match` is the exact tag, token, export name or import specifier. `reason` is required. |
1232
+ | `allow` | | Exceptions: `{ rule, file?, match?, reason }`. `match` is the exact tag, token, export name or import specifier. `reason` is required. Debt: under `--base` it only shrinks. |
1233
+ | `extend` | | Declared extensions: `{ rule, file, buildsOn, reason, upstream? }`, at a package rule's declared extension points, bounded by the findings the file had when declared. See [Declared extensions](#declared-extensions). |
1164
1234
  | `patterns` | | Declarative rules, below. |
1165
1235
  | `rulesDoc` | | A markdown file of declarative rules, below. |
1166
1236
  | `plugins` | | Rule modules, below. |
@@ -1253,6 +1323,46 @@ if (!result.ok) throw new Error(formatReport(result));
1253
1323
  the local Vite plugin import with `@marktiderman/genesis-cli/vite`.
1254
1324
  4. Run `genesis doctor`, fix or `allow` what it reports (it checks `raw-color` in code as well
1255
1325
  as CSS, and `raw-tag` only in JSX files), then delete the old script.
1326
+
1327
+ ## genesis agents
1328
+
1329
+ Writes the agent guide from the installed Genesis packages, so every coding agent and reviewer in
1330
+ the app reads the same rules, matched to the versions the app has:
1331
+
1332
+ - **The AGENTS.md block** between `<!-- genesis-primitives:start -->` and
1333
+ `<!-- genesis-primitives:end -->`: the rules, the catalog of what to use for each need, and the
1334
+ path to each installed package's own `SKILL.md` at `node_modules/<package>/SKILL.md`, so it
1335
+ matches the installed version (a package reached only through the umbrella, inside pnpm's store,
1336
+ is left out: that path changes with unrelated dependency bumps). Text outside the markers is the
1337
+ app's own and is never touched.
1338
+ - **`.claude/skills/genesis/SKILL.md`**: the same rules and catalog as a skill.
1339
+ - **`CLAUDE.md`** holding `@AGENTS.md`, only when the app has no `CLAUDE.md`. Reviewers and cloud
1340
+ project threads read CLAUDE.md, not AGENTS.md.
1341
+
1342
+ `genesis agents --hooks` also writes two things into `.claude/settings.json`, keeping everything
1343
+ else there: a `SubagentStart` hook that hands Claude Code's Explore and Plan subagents the same
1344
+ rules and package guides (they start without CLAUDE.md or AGENTS.md), and `permissions.deny`
1345
+ rules for `.env` files, which apply in cloud sessions too. The hook runs
1346
+ `genesis agents --hook subagent-start`, which prints the rules and guides and never fails a
1347
+ session: with no local `genesis` binary (before an install), the subagent simply starts without
1348
+ them. Settings are written only with `--hooks`, so a plain run never touches them; an older hook
1349
+ command is flagged instead (below), and `genesis agents --hooks` updates it.
1350
+
1351
+ Package guides are listed only at paths that stay put: a local package's folder, or
1352
+ `node_modules/<package>/SKILL.md` at the app or a workspace folder above it, up to the repo root,
1353
+ and only when that copy is the one the app resolved.
1354
+ A package reached only through the umbrella lives in pnpm's store, so its guide is left out, and
1355
+ the doctor names it (an info): add the package as a direct dependency to list its guide.
1356
+
1357
+ `genesis agents --check` writes nothing and exits 1 when any of them is missing or stale (for CI);
1358
+ the doctor's `agent-guide-stale` rule warns the same way, and also for an older hook command
1359
+ (fix it with `--hooks`). A
1360
+ CLAUDE.md the app keeps without the import, or a link to AGENTS.md, passes (the doctor notes a
1361
+ missing import as info). A CLAUDE.md that's blocked, by another case of the name such as
1362
+ `claude.md`, a dangling link or a folder, fails until it's fixed by hand, since `genesis agents`
1363
+ never writes over it. `genesis agents --rules` checks the repo against the agent rules of
1364
+ engagement a script can check. Run `genesis agents` after every Genesis upgrade.
1365
+
1256
1366
  ## genesis figma:routes
1257
1367
 
1258
1368
  A read-only check that an app's Figma app file covers its routes, so CI reports the drift and an