@marktiderman/genesis-cli 1.14.0 → 1.15.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
@@ -51,7 +51,9 @@ DATABASE_URL=postgres://… npx @marktiderman/genesis-cli introspect
51
51
 
52
52
  Writes `resources.genesis.ts`, a checked-in contract for the Data Studio: every table in the
53
53
  schemas, with its key, fields (type, database type, nullability, defaults, enum values, links)
54
- and a row type per table. Review it like code, and pass `contracts` to `createStudioHandler`. It
54
+ and a row type per table. Enum values come from enum types and from single-column `CHECK`s that
55
+ list values (`status in ('open', 'done')`). A view Postgres can update on its own takes its
56
+ table's key and column facts, and its table's `noun` (see `docs/RESOURCE-VIEW.md`). Review it like code, and pass `contracts` to `createStudioHandler`. It
55
57
  wins over discovery for labels, widgets and descriptions; types, keys and permissions still come
56
58
  from the live database.
57
59
 
@@ -376,6 +378,7 @@ Upgrading Genesis upgrades the checks.
376
378
  | `-c, --config <path>` | Config file. Default: `genesis.config.json`, then the `genesis` key of package.json. |
377
379
  | `-d, --dir <dir>` | The app's folder (default: cwd). |
378
380
  | `--print-genesis` | Print the components, tokens, raw tags, palette and companion packages' components read from Genesis, and exit. |
381
+ | `--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`). |
379
382
 
380
383
  Exit codes: `0` pass, `1` findings, `2` the doctor couldn't run (bad config, Genesis not installed or not built).
381
384
 
@@ -403,10 +406,17 @@ Exit codes: `0` pass, `1` findings, `2` the doctor couldn't run (bad config, Gen
403
406
  | `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. |
404
407
  | `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. |
405
408
  | `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. |
406
- | `stale-exception` | warn | An `allow` entry that no longer matches anything. |
407
-
408
- It also prints **Available but unused**: the Genesis components no file imports. Check it
409
- before building something.
409
+ | `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. |
410
+ | `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). |
411
+ | `package-rule-override` | warn | `rules` changes a package rule's level without a reason; move it to `packageRules` with one. |
412
+ | `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. |
413
+ | `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`. |
414
+ | `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. |
415
+ | `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. |
416
+
417
+ It also prints **Available but unused**: the Genesis components no file imports, and a
418
+ **Primitives** line: how many rules the installed packages declare (`genesis primitives` lists
419
+ them). Check both before building something.
410
420
 
411
421
  The route rules (`hand-rolled-sub-nav`, `resource-workspace`, `page-layout`) read the routes
412
422
  folder (`routesDir`, default the first of `src/routes`, `src/app`, `app`, `src/pages`, `pages`).
@@ -503,6 +513,7 @@ bodies blanked, so text inside a function body never matches; the one exception
503
513
  | `migration-definer-search-path` | error | A `security definer` function or procedure without `set search_path`. Functions are keyed by name and argument types, so overloads are separate; `alter function … security definer` makes one definer, `alter function … set search_path` fixes it, and renames, replaces and drops are followed. |
504
514
  | `migration-edited` | error | A `.sql` migration that already exists at the merge base with `supabase.base` (default `origin/main`) was modified, deleted or renamed. Applied migrations are never edited; add a new one. Skipped outside a git repo; a **warn** when the base ref isn't available. |
505
515
  | `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`. |
516
+ | `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. |
506
517
  | `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": "…" }`. |
507
518
 
508
519
  **Which migrations are new.** In a git repo with the base ref, a migration is new when it was
@@ -542,6 +553,7 @@ as dependencies.
542
553
  | `package-migration-test` | error | A migration without a pgTAP test: a block migration with no `test` (or a missing one), or any `migrations/NNNN_name.sql` without `migrations/tests/NNNN_name.test.sql`. |
543
554
  | `package-migration-number` | error | Two migrations in one package with the same `NNNN_` number. |
544
555
  | `package-untagged-tests` | warn | A package whose tests name no feature (`@feat:<id>`). |
556
+ | `package-doctor-declaration` | error | A published (not `private`) `@marktiderman/genesis-*` package with no `genesis.doctor` declaration, or one that doesn't validate. Declare the rules it enforces, or `{ "enforce": false, "reason": "…" }`. |
545
557
  | `package-unregistered` | warn | No feature in `features.json` lists the package's folder in `links.code`. |
546
558
  | `package-migration-edited` | warn | With a base ref: a package migration that existed at the merge base and was changed, deleted or renamed. |
547
559
  | `package-unversioned-change` | warn | With a base ref: files in the package changed but neither a higher `version` nor a new changeset naming it in its front matter did; a changeset without a `Features:` line; or blocks or exports changed without a change to `features.ts`. Run CI with `--strict` so these fail. |
@@ -550,6 +562,128 @@ Symlinks inside a package aren't followed, and a `packages/*` folder without a u
550
562
 
551
563
  Every other rule also scans local packages' source, as it does the app's.
552
564
 
565
+ ### Package rules
566
+
567
+ Every Genesis package declares what it enforces in its own package.json, under
568
+ `genesis.doctor`, and the doctor finds every installed `@marktiderman/genesis-*` package (and
569
+ every [local package](#local-packages)) and runs their rules. An app needs no config for them:
570
+ installing or upgrading a package brings its rules. Rule ids are namespaced by package
571
+ (`ui/lists-use-resource-view` for genesis-ui, `@acme/kit/<id>` for a local package), and `rules`,
572
+ `allow`, `ratchet` and `stale-exception` treat them like built-ins.
573
+
574
+ A declaration has **`prefer` rules** ("use X instead of Y") and optional **`primitives`**
575
+ (catalog rows with no rule), and may name a **`plugin`** module for checks that need code:
576
+
577
+ ```json
578
+ {
579
+ "name": "@marktiderman/genesis-widgets",
580
+ "genesis": {
581
+ "doctor": {
582
+ "prefer": [
583
+ {
584
+ "id": "lists-use-widget-view",
585
+ "need": "a list screen",
586
+ "level": "warn",
587
+ "platform": "web",
588
+ "files": ["**/*.tsx"],
589
+ "exclude": ["**/*.server.*"],
590
+ "forbid": { "jsx": ["DataTable"], "imports": ["legacy-grid", "@legacy/*"], "pattern": "\\bfetchRows\\(" },
591
+ "unless": { "renders": ["WidgetView"] },
592
+ "use": "<WidgetView>",
593
+ "import": "@marktiderman/genesis-widgets",
594
+ "docs": "https://…/WIDGETS.md",
595
+ "why": "One description per list.",
596
+ "newOnly": false
597
+ }
598
+ ],
599
+ "primitives": [{ "need": "dates", "use": "dayIn(zone)", "import": "@marktiderman/genesis-widgets/dates" }],
600
+ "plugin": "./dist/doctor-rules.js"
601
+ }
602
+ }
603
+ }
604
+ ```
605
+
606
+ | Key | |
607
+ | --- | --- |
608
+ | `id` | Lower-case words and dashes; namespaced by the doctor. |
609
+ | `need` | The need it answers, for `genesis primitives` and the agent guide. |
610
+ | `level` | `error`, `warn` (default) or `info`. |
611
+ | `platform` | `web` (off with the `native` pack) or `native` (only with it). Default both. |
612
+ | `files`, `exclude` | App-relative globs. `{routes}` is the routes folder (`routesDir`). Default: every scanned script file. |
613
+ | `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. |
614
+ | `unless` | A file is left alone when it `renders` one of these elements (it builds on the primitive) or matches `pattern`. |
615
+ | `use`, `import`, `docs`, `why` | The message: what to use, where from, why, and the link. `use` and `why` are required. |
616
+ | `newOnly` | Ratchet: under `--base`, findings in unchanged files drop to `info`. |
617
+
618
+ A forbidden element counts one level up too: an app component that renders it (`RecordTable`
619
+ around `DataTable`) is flagged in its own file, and so is every screen that renders the
620
+ wrapper. A package's rules never run on the package's own files.
621
+
622
+ A package with nothing to enforce says so, with a reason, and may still list primitives:
623
+ `"doctor": { "enforce": false, "reason": "Development tooling, not app screens." }`. In the
624
+ `packages` pack, `package-doctor-declaration` fails a published Genesis package that declares
625
+ neither, so a new package can't skip this step. `"doctor": "./doctor.json"` points at a file in
626
+ the package (list it in `files`) holding the same object. A `plugin` module is loaded like an
627
+ app plugin; its findings are namespaced like the package's other rules.
628
+
629
+ **Adding rules to a new package:** add `genesis.doctor` to its package.json, run its tests (the
630
+ genesis-cli suite validates every package's declaration), and add a changeset. Apps get the
631
+ rules when they install the release.
632
+
633
+ **In the app**, switch a package rule off, change its level or its files with a reason, never
634
+ silently. `rules` works too, but warns (`package-rule-override`) until the reason is recorded:
635
+
636
+ ```json
637
+ {
638
+ "doctor": {
639
+ "packageRules": {
640
+ "core/direct-data-access": { "files": ["src/**/*.tsx", "src/lib/**/*.ts"], "exclude": ["src/lib/server/**"], "reason": "Our data functions live in src/lib; check them too." },
641
+ "ui/record-pages-use-resource-workspace": { "level": "off", "reason": "Every record page is a builder." }
642
+ },
643
+ "allow": [{ "rule": "ui/lists-use-resource-view", "file": "src/components/data/RecordTable.tsx", "reason": "The legacy wrapper; it goes when the last screen moves." }]
644
+ }
645
+ }
646
+ ```
647
+
648
+ **The catalog.** `genesis primitives` (`--json` for data) prints, for each need, what to use,
649
+ its import, the rule that enforces it and the docs: a short static core plus every installed
650
+ package's declarations. `genesis agents` writes the same catalog as
651
+ `.claude/skills/genesis/SKILL.md` and a `<!-- genesis-primitives:start -->` block in the app's
652
+ AGENTS.md (the rest of the file is the app's), telling agents to use the primitives first, never
653
+ copy an older screen, and write a gap up for Genesis before inventing. `genesis agents --check`
654
+ writes nothing and fails when either is out of date, and the doctor's `agent-guide-stale` warns.
655
+ Both commands, and `genesis primitives`, exit 1 when a package's declaration doesn't validate,
656
+ since the catalog would leave it out. Run `genesis agents` after each Genesis upgrade.
657
+
658
+ ### The ratchet
659
+
660
+ `newOnly` rules (package rules and app patterns can declare it), and any rule the app lists in
661
+ `doctor.ratchet` (`true` for all), apply in full only to new and changed code: with
662
+ `--base <ref>`, a finding in a file unchanged since the merge base is reported as `info`, with
663
+ "ratcheted" in its message. Changed means committed on the branch, staged, edited or
664
+ untracked. Without `--base` every rule runs at its level, as before; when git can't compare,
665
+ `ratchet-skipped` says so and nothing is lowered. `allow` entries still remove findings,
666
+ ratcheted or not: they are the recorded ratchet, file by file, and under `--base` the list only
667
+ shrinks: `allow-grew` fails an entry the doctor settings at the merge base didn't have, and
668
+ `rules-weakened` fails a rule the base's settings set that this branch lowers, turns off or
669
+ excludes files from (compared with the base's settings only). Neither runs when the base had no
670
+ doctor settings. These two and
671
+ `ratchet-skipped` guard the config itself, so `rules` and `allow` can't name them (the config is
672
+ refused), and the ratchet never lowers them, nor the other rules about the config, packages or
673
+ generated files (`stale-exception`, `package-rule-override`, `package-rules-invalid`,
674
+ `package-doctor-declaration`, `plugin-error`, `build`, `agent-guide-stale`, `contracts-stale`). A
675
+ shallow CI clone has no merge base, so `ratchet-skipped` fails a config with `allow`, `rules` or
676
+ `packageRules`: check out with `fetch-depth: 0` and fetch the base ref (see
677
+ [Which migrations are new](#rule-packs)).
678
+
679
+ ```json
680
+ { "doctor": { "ratchet": ["ui/lists-use-resource-view", "core/direct-data-access"] } }
681
+ ```
682
+
683
+ ```bash
684
+ genesis doctor --strict --base origin/main
685
+ ```
686
+
553
687
  ### Config
554
688
 
555
689
  `genesis.config.json` (or `"genesis": { "doctor": { … } }` in package.json):
@@ -591,7 +725,10 @@ Every other rule also scans local packages' source, as it does the app's.
591
725
  | `localPrimitiveDirs` | `["src/components/ui"]` | |
592
726
  | `routesDir` | first of `src/routes`, `src/app`, `app`, `src/pages`, `pages` | The web routes folder the route rules read. |
593
727
  | `componentPackages` | `["@marktiderman/genesis-forms-studio"]` | Genesis packages besides `uiPackage` whose components `local-genesis-copy` and `page-layout` read (skipped when not installed). `--print-genesis` lists them under `companions`. |
594
- | `rules` | | `{ "<rule>": "error" \| "warn" \| "info" \| "off" }` for any rule, built-in or yours. `info` is reported and never fails, `--strict` included. |
728
+ | `rules` | | `{ "<rule>": "error" \| "warn" \| "info" \| "off" }` for any rule, built-in or yours. `info` is reported and never fails, `--strict` included. A package rule changed here warns until `packageRules` gives a reason. |
729
+ | `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). |
730
+ | `ratchet` | | `true`, or a list of rule ids, ratcheted under `--base`. See [The ratchet](#the-ratchet). |
731
+ | `contracts` | | `{ out?, schemas?, databaseEnv? }`: the supabase pack's `contracts-stale` check. Needs the supabase pack. |
595
732
  | `allow` | | Exceptions: `{ rule, file?, match?, reason }`. `match` is the exact tag, token, export name or import specifier. `reason` is required. |
596
733
  | `patterns` | | Declarative rules, below. |
597
734
  | `rulesDoc` | | A markdown file of declarative rules, below. |
@@ -604,7 +741,7 @@ Unknown keys are an error, so a typo can't quietly turn a check off.
604
741
 
605
742
  Keep app-specific conventions in the app. Three ways, from least to most code:
606
743
 
607
- **Patterns** (`patterns` in config): `{ id, level?, files, exclude?, forbid?, require?, path?, message? }`.
744
+ **Patterns** (`patterns` in config): `{ id, level?, files, exclude?, forbid?, require?, path?, message?, newOnly? }`.
608
745
  `forbid` must not match a file (the finding points at the line), `require` must match it, `path`
609
746
  must match its path. All are regular expressions; prefix `(?i)` for case-insensitive. `level` is
610
747
  `error` (default), `warn`, or `guide` (documentation only, never checked).
@@ -661,7 +798,8 @@ export default defineConfig({ plugins: [genesisDoctor()] });
661
798
  `vite build` fails when the doctor finds errors (`genesisDoctor({ strict: true })` fails on
662
799
  warnings too). `vite dev` logs problems and shows Vite's error overlay, re-checks on every
663
800
  change under the app (plus `genesis.config.json` and the rules doc), shows the overlay to
664
- browsers that connect later, and reloads once everything passes. Options: `root`, `configPath`,
801
+ browsers that connect later, and reloads once everything passes. Neither runs `contracts-stale`,
802
+ which reads the database; run `genesis doctor` in CI for it. Options: `root`, `configPath`,
665
803
  `strict`, `debounceMs`. `vite` is an optional peer dependency.
666
804
 
667
805
  ### Programmatic use