@marktiderman/genesis-cli 1.24.0 → 1.26.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
 
@@ -806,7 +806,7 @@ Exit codes: `0` pass, `1` findings, `2` the doctor couldn't run (bad config, Gen
806
806
 
807
807
  | Rule | Level | What it flags |
808
808
  | --- | --- | --- |
809
- | `local-primitives` | error | A local primitive folder (`src/components/ui` by default; `localPrimitiveDirs`). |
809
+ | `local-primitives` | error | A local primitive folder (`src/components/ui` by default; `localPrimitiveDirs`): where a shadcn starter copies the primitives Genesis already has. The app's own components live in any other folder. |
810
810
  | `starter-leftover` | warn | `components.json` or `src/lib/utils.ts` from a shadcn starter. |
811
811
  | `forbidden-import` | error | `@radix-ui/*`, local `components/ui/*` (alias or relative), `@/lib/utils`, plus your `forbiddenImports`. |
812
812
  | `raw-tag` | error | A raw JSX tag Genesis has a component for: any of `button input textarea select label table dialog progress details summary` with a same-named Genesis export, plus `hr` → `Separator`. JSX files only; `rawTags` adds or removes mappings. |
@@ -826,11 +826,17 @@ Exit codes: `0` pass, `1` findings, `2` the doctor couldn't run (bad config, Gen
826
826
  | `resource-view-tree` | error | A `<ResourceView>` or `<ResourcePage>` with `tree` and `pagination="server"` or `"cursor"` (bare or in braces). A tree is built from every row on the client, so the screen throws when it renders. Leave `pagination` unset. Only the tag's own attributes count, not a `tree` inside an expression. ([Tree mode](../../docs/RESOURCE-VIEW.md#tree-mode)) |
827
827
  | `studio-server-auth-import` | warn | An import of a studio-server file the package doesn't export (`@marktiderman/genesis-studio-server/dist/…`, `/src/…`, `/lib/…`), or a CommonJS `require("@marktiderman/genesis-studio-server")` of the ESM-only root. Besides the doctor's scan it reads the app's `.cjs` and `.mjs` files (tests skipped), where a `require` usually is. Both fail at run time with `ERR_PACKAGE_PATH_NOT_EXPORTED`. Use `@marktiderman/genesis-studio-server/auth`: the token checks and `switchToUser`, for `import` and `require`. An ESM import of the root is fine. |
828
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. |
829
+ | `app-part-name` | warn | An app element's own `data-slot` that doesn't start `app-`. An app style reaches an app's own part by name, so it is `app-<name>` and never matches a Genesis part; a name the installed design system's `THEME_PARTS` already uses is called out, since every app style's rules for that part would hit the app's element. Files inside an overlay of the component package are skipped (ADR 0018). |
830
+ | `app-part-colors` | warn | In a custom view (a file that renders `<CustomView>` or calls `useCustomView`) or a file with an app part (`data-slot="app-…"`): a colour property (`color`, `backgroundColor`, `borderColor`, `fill`, …) or a Tailwind colour utility with an arbitrary value (`bg-[var(--x)]`) that reads a custom property the theme stylesheets don't declare as a colour role. Take colours from roles (`hsl(var(--primary))`, `bg-primary`), so the app brand and dark mode reach the view. Literal colours stay `raw-color`'s (ADR 0019). |
831
+ | `custom-view-states` | warn | A custom view that draws its own loading, empty or error state: a `status === "loading"`, `"empty"` or `"error"` check in a file that renders `<CustomView>` or calls `useCustomView`. `<CustomView>` draws the three states in the app's style; its `loading`, `empty` and `error` props replace one (ADR 0019). |
829
832
  | `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. |
830
833
  | `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
834
  | `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
835
  | `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
836
  | `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. |
837
+ | `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`. |
838
+ | `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. |
839
+ | `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
840
  | `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
841
  | `package-rule-override` | warn | `rules` changes a package rule's level without a reason; move it to `packageRules` with one. |
836
842
  | `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. |
@@ -1045,13 +1051,19 @@ once). A package that must stay readable by a genesis-cli before this release ke
1045
1051
  | `platform` | `web` (off with the `native` pack) or `native` (only with it). Default both. |
1046
1052
  | `files`, `exclude` | App-relative globs. `{routes}` is the routes folder (`routesDir`). Default: every scanned script file. |
1047
1053
  | `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. |
1048
- | `unless` | A file is left alone when it `renders` one of these elements (it builds on the primitive) or matches `pattern`. |
1054
+ | `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. |
1055
+ | `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). |
1049
1056
  | `use`, `import`, `docs`, `why` | The message: what to use, where from, why, and the link. `use` and `why` are required. |
1050
- | `newOnly` | Ratchet: under `--base`, findings in unchanged files drop to `info`. |
1057
+ | `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. |
1051
1058
 
1052
1059
  A forbidden element counts one level up too: an app component that renders it (`RecordTable`
1053
1060
  around `DataTable`) is flagged in its own file, and so is every screen that renders the
1054
- wrapper. A package's rules never run on the package's own files.
1061
+ wrapper. `unless.inside` follows the same level, for the elements nested in it only. A package's
1062
+ rules never run on the package's own files.
1063
+
1064
+ When two rules flag the same element on the same line (an app's own rule and a package rule,
1065
+ say), the doctor reports it once, at the higher level, with every rule id in `rules` (and in the
1066
+ report's brackets).
1055
1067
 
1056
1068
  A package with nothing to enforce says so, with a reason, and may still list primitives:
1057
1069
  `"doctor": { "enforce": false, "reason": "Development tooling, not app screens." }`. In the
@@ -1084,7 +1096,7 @@ its import, the rule that enforces it and the docs: a short static core plus eve
1084
1096
  package's declarations. `genesis agents` writes the same catalog as
1085
1097
  `.claude/skills/genesis/SKILL.md` and a `<!-- genesis-primitives:start -->` block in the app's
1086
1098
  AGENTS.md (the rest of the file is the app's), telling agents to use the primitives first, never
1087
- copy an older screen, and write a gap up for Genesis before inventing. `genesis agents --check`
1099
+ copy an older screen, extend a close Genesis piece rather than build beside it, and invent in the app when nothing fits. `genesis agents --check`
1088
1100
  writes nothing and fails when either is out of date, and the doctor's `agent-guide-stale` warns.
1089
1101
  Both commands, and `genesis catalog`, exit 1 when a package's declaration doesn't validate,
1090
1102
  since the catalog would leave it out. Run `genesis agents` after each Genesis upgrade.
@@ -1092,19 +1104,29 @@ since the catalog would leave it out. Run `genesis agents` after each Genesis up
1092
1104
  ### The ratchet
1093
1105
 
1094
1106
  `newOnly` rules (package rules and app patterns can declare it), and any rule the app lists in
1095
- `doctor.ratchet` (`true` for all), apply in full only to new and changed code: with
1096
- `--base <ref>`, a finding in a file unchanged since the merge base is reported as `info`, with
1097
- "ratcheted" in its message. Changed means committed on the branch, staged, edited or
1098
- untracked. Without `--base` every rule runs at its level, as before; when git can't compare,
1107
+ `doctor.ratchet` (`true` for all), apply in full only to new code: with `--base <ref>`, the
1108
+ doctor counts each file's findings of each ratcheted rule at the merge base and now. A finding
1109
+ keeps its level only in a file the merge base didn't have, or in a file that now has more of
1110
+ that rule's findings than it had; everything else is reported as `info`, with "ratcheted" in its
1111
+ message. So a one-line fix in a file with old debt passes, and adding to the debt doesn't.
1112
+ Counts are per rule and file, not per finding: fixing one finding and adding another of the same
1113
+ rule in the same file nets out, and the new one is reported as `info` like the rest. A renamed or
1114
+ moved file keeps its count (git's rename detection). A copy doesn't: its findings are new debt,
1115
+ even when the debt moved out of the file it was copied from.
1116
+ Changed means committed on the branch, staged, edited or untracked; the merge base's counts come
1117
+ from the changed files as git has them there: only the package rules run again on them when
1118
+ every rule being counted is one (the usual case), else every check that reads the app's files;
1119
+ never the build, the database contract or Figma. When git can't read them, a changed file keeps
1120
+ every level. Without `--base` every rule runs at its level, as before; when git can't compare,
1099
1121
  `ratchet-skipped` says so and nothing is lowered. `allow` entries still remove findings,
1100
1122
  ratcheted or not: they are the recorded ratchet, file by file, and under `--base` the list only
1101
1123
  shrinks: `allow-grew` fails an entry the doctor settings at the merge base didn't have, and
1102
1124
  `rules-weakened` fails a rule the base's settings set that this branch lowers, turns off or
1103
1125
  excludes files from (compared with the base's settings only). Neither runs when the base had no
1104
1126
  doctor settings. These two and
1105
- `ratchet-skipped` guard the config itself, so `rules` and `allow` can't name them (the config is
1127
+ `ratchet-skipped` (and `extension-invalid`) guard the config itself, so `rules` and `allow` can't name them (the config is
1106
1128
  refused), and the ratchet never lowers them, nor the other rules about the config, packages or
1107
- generated files (`stale-exception`, `package-rule-override`, `package-rules-invalid`,
1129
+ generated files (`stale-exception`, `stale-extension`, `extension-added`, `package-rule-override`, `package-rules-invalid`,
1108
1130
  `package-doctor-declaration`, `plugin-error`, `build`, `agent-guide-stale`, `contracts-stale`). A
1109
1131
  shallow CI clone has no merge base, so `ratchet-skipped` fails a config with `allow`, `rules` or
1110
1132
  `packageRules`: check out with `fetch-depth: 0` and fetch the base ref (see
@@ -1114,10 +1136,57 @@ shallow CI clone has no merge base, so `ratchet-skipped` fails a config with `al
1114
1136
  { "doctor": { "ratchet": ["ui/lists-use-resource-view", "core/direct-data-access"] } }
1115
1137
  ```
1116
1138
 
1117
- ```bash
1118
- genesis doctor --strict --base origin/main
1139
+ ### Declared extensions
1140
+
1141
+ Genesis is a trellis, not a ceiling: a rule knows the usual ways of building on a primitive, and
1142
+ an app may build on Genesis in a way the rule doesn't recognize. A package rule that allows this
1143
+ declares its extension points (`extensible`), and an app that uses one, defensibly, declares it in
1144
+ `doctor.extend` instead of hiding the finding in `allow`:
1145
+
1146
+ ```json
1147
+ {
1148
+ "doctor": {
1149
+ "extend": [
1150
+ {
1151
+ "rule": "ui/lists-use-resource-view",
1152
+ "file": "src/routes/board.tsx",
1153
+ "buildsOn": "useBoardColumns",
1154
+ "reason": "The board groups rows by a computed lane, which the view's board block can't express yet.",
1155
+ "upstream": "https://github.com/marktiderman/genesis/issues/123"
1156
+ }
1157
+ ]
1158
+ }
1159
+ }
1119
1160
  ```
1120
1161
 
1162
+ `allow` is debt and only shrinks. An extension is a reviewed decision, and it is bounded:
1163
+
1164
+ - **By the rule.** Only package rules can be extended, and only at the points they declare
1165
+ (`ui/lists-use-resource-view`: `ResourceView.slots`, `ResourceView.renderDetail`,
1166
+ `ResourceView.toolbar`, `useResourceView`, `useResourceTable`, `useBoardColumns`;
1167
+ `ui/records-use-record-view`: `BuilderLayout`). A built-in rule (`deprecated-import`,
1168
+ `removed-scope-name`, `raw-tag`, …) or a package rule without points can't be, so debt can't be
1169
+ renamed an extension.
1170
+ - **By the file, now.** It names one file (no globs) and covers the findings of its rule that the
1171
+ file has when the extension is declared. Under `--base`, once the merge base has the extension,
1172
+ a file with more of them than at the merge base reports them all at their level, as the ratchet
1173
+ would.
1174
+ - **By review.** `allow-grew` and `rules-weakened` don't count it. Under `--base` a new one is an
1175
+ `extension-added` info, and the report's summary lists every extension the branch adds with its
1176
+ reason ("Extensions added on this branch"; `extensionsAdded` in `--json`). The pull request's
1177
+ review is where it is accepted; nothing else gates it.
1178
+
1179
+ The doctor checks each one:
1180
+
1181
+ - `reason` is required, at least six words and 40 characters: why the rule's primitive doesn't
1182
+ fit this file. `upstream` links the gap's write-up for Genesis, when it is one.
1183
+ - `extension-invalid` (error, can't be lowered or allowed): the rule declares no extension points
1184
+ or `buildsOn` isn't one of them, the file doesn't import `buildsOn` from a Genesis package or
1185
+ doesn't use it (render or call it; for `X.slots` and the like, pass that prop on `<X>`),
1186
+ `buildsOn` is what a package rule replaces (`DataTable`, `DetailPage`), or the doctor flags it in
1187
+ that file (a deprecated import). The findings it would cover stay.
1188
+ - `stale-extension` (warn): the file no longer has a finding of `rule`; remove the entry.
1189
+
1121
1190
  ### Config
1122
1191
 
1123
1192
  `genesis.config.json` (or `"genesis": { "doctor": { … } }` in package.json):
@@ -1148,7 +1217,7 @@ genesis doctor --strict --base origin/main
1148
1217
  | `native` | | `{ routerRoot }` for the native pack. |
1149
1218
  | `supabase` | | `{ migrations, base, exposedSchemas, since, automaticBranching }` for the supabase pack. |
1150
1219
  | `src` | `["src"]` (`["app", "src", "components"]` with the native pack) | Folders (or files) to scan. |
1151
- | `extensions` | `.ts .tsx .js .jsx .mts .cts .css` | |
1220
+ | `extensions` | `.ts .tsx .js .jsx .mts .cts .css` | File extensions to scan (declared extensions are `extend`). |
1152
1221
  | `ignore` | | Globs to skip, added to the defaults. `*` stays in a folder, `**` crosses folders, a trailing `/` means the whole folder. |
1153
1222
  | `uiPackage` | `@marktiderman/genesis-ui` (`@marktiderman/genesis-ui-native` with the native pack) | |
1154
1223
  | `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. |
@@ -1163,7 +1232,8 @@ genesis doctor --strict --base origin/main
1163
1232
  | `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). |
1164
1233
  | `ratchet` | | `true`, or a list of rule ids, ratcheted under `--base`. See [The ratchet](#the-ratchet). |
1165
1234
  | `contracts` | | `{ out?, schemas?, databaseEnv? }`: the supabase pack's `contracts-stale` check. Needs the supabase pack. |
1166
- | `allow` | | Exceptions: `{ rule, file?, match?, reason }`. `match` is the exact tag, token, export name or import specifier. `reason` is required. |
1235
+ | `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. |
1236
+ | `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). |
1167
1237
  | `patterns` | | Declarative rules, below. |
1168
1238
  | `rulesDoc` | | A markdown file of declarative rules, below. |
1169
1239
  | `plugins` | | Rule modules, below. |
@@ -1394,6 +1464,9 @@ What an app needed from Genesis and didn't find goes in `docs/genesis-upstream.m
1394
1464
  | --- | --- | --- | --- | --- | --- | --- |
1395
1465
  | kanban-swimlanes | extension | candidate | data-views | @marktiderman/genesis-ui | src/components/lanes.tsx | Swimlanes on KanbanBoard |
1396
1466
 
1467
+ An entry is a recommendation, never a request for permission: the app builds what it needs first
1468
+ (FRAMEWORK G3) and adds an entry when it thinks Genesis should have it.
1469
+
1397
1470
  `kind` is `gap` (nothing in Genesis), `extension` (a part with no prop, variant or slot for it)
1398
1471
  or `invention` (the app built it). `status` is `candidate`, `proposed`, `promoted` or `declined`.
1399
1472
  `local` is the app's own code for it: repo-relative paths, separated by `, ` (a comma and a space)