@marktiderman/genesis-cli 1.16.1 → 1.17.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
@@ -49,11 +49,25 @@ function's secrets, apply the migration. Options: `--host next|supabase-function
49
49
  DATABASE_URL=postgres://… npx @marktiderman/genesis-cli introspect
50
50
  ```
51
51
 
52
- Writes `resources.genesis.ts`, a checked-in contract for the Data Studio: every table in the
52
+ With no flags it follows the app's `doctor.contracts` settings (`out`, `schemas`,
53
+ `databaseEnv`), so it rewrites the file the doctor's `contracts-stale` check reads, from the same
54
+ schemas: without `contracts.schemas`, the ones the existing contract's `// Source:` line names.
55
+ `-o`, `-s` and `--database-env` override them; paths are relative to the app's root, where you run
56
+ the command. With `--openapi`, only a single configured schema carries over (else `public`).
57
+
58
+ Writes `resources.genesis.ts` (or `contracts.out`), a checked-in contract for the Data Studio: every table in the
53
59
  schemas, with its key, fields (type, database type, nullability, defaults, enum values, links)
54
60
  and a row type per table. Enum values come from enum types and from single-column `CHECK`s that
55
61
  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
62
+ table's key and column facts, and its table's `noun` (see `docs/RESOURCE-VIEW.md`). A read-only view
63
+ that joins tables has no key the catalog can see: name it in the view's comment,
64
+ `@genesis {"key": "id"}` (or a list of columns, no repeats; one that differs from a primary key
65
+ is used, with a warning). A foreign key is a link when it's one column, or a composite key whose
66
+ other columns reference their namesakes and whose own column references a column unique on its own
67
+ (the primary key or a unique index): the tenant-safe `(gallery_id, org_id) references galleries
68
+ (id, org_id)` makes `gallery_id` a link to galleries, while `(doc_id, version) references
69
+ doc_versions (id, version)` is not a link.
70
+ PostgREST's OpenAPI notes single-column keys only, so `--openapi` links those alone. Review it like code, and pass `contracts` to `createStudioHandler`. It
57
71
  wins over discovery for labels, widgets and descriptions; types, keys and permissions still come
58
72
  from the live database.
59
73
 
@@ -160,6 +174,100 @@ Then:
160
174
  - A local package keeps package shape, so publishing it later (GitHub Packages or npm) needs no
161
175
  restructuring.
162
176
 
177
+ ### Overlays
178
+
179
+ An **overlay** is a local package that shadows a published `@marktiderman/genesis-*` package by
180
+ name: the package's source, copied into the app at a release, so the app can change it and ship
181
+ the change the same day. Put it in a package folder of its own (`packages/genesis-support`), list it
182
+ in `localPackages` like any local package, and mark it in its package.json, keeping the package's
183
+ own `genesis` key:
184
+
185
+ ```json
186
+ {
187
+ "name": "@marktiderman/genesis-support",
188
+ "version": "0.2.6+local.1",
189
+ "private": true,
190
+ "genesis": {
191
+ "doctor": { "…": "the package's own declaration" },
192
+ "overlay": {
193
+ "upstream": "@marktiderman/genesis-support@0.2.6",
194
+ "since": "2026-10-30",
195
+ "owner": "web team",
196
+ "reason": "inbox filters; to promote upstream"
197
+ }
198
+ }
199
+ }
200
+ ```
201
+
202
+ - `upstream`: the package and the exact release it was copied from (`@marktiderman/genesis-*@<semver>`,
203
+ a prerelease allowed; no build metadata and no `-local.N`, which are an overlay's own versions).
204
+ - `since`: the day the overlay was made, `YYYY-MM-DD`, not later than tomorrow.
205
+ - `private: true`: an overlay never publishes.
206
+ - `owner`, `reason`: who answers for it and why it exists.
207
+ - `version`: `<upstream version>+local.N` by convention (`N` without leading zeros). Build metadata (`+`) keeps it inside other Genesis packages' peer ranges (`^0.2.6`), which a prerelease (`-local.N`) would fall outside; the upstream version itself, or `-local.N`, are also accepted.
208
+
209
+ **Wiring it in.** Point the app's dependency at the overlay, and add a root override with the same
210
+ specifier so other Genesis packages that depend on it get the copy too, not a second published copy:
211
+
212
+ - **pnpm, Bun, Yarn**: `"@marktiderman/genesis-support": "workspace:*"`, with the same value in
213
+ `pnpm.overrides` (pnpm), `overrides` (Bun) or `resolutions` (Yarn).
214
+ - **npm** has no `workspace:` protocol: use `"@marktiderman/genesis-support": "file:./packages/genesis-support"`
215
+ in `dependencies`, and the same `file:` specifier in `overrides` (npm requires an override for a
216
+ direct dependency to match it).
217
+
218
+ **Fix the copied manifest.** A source copy keeps Genesis's own `workspace:` ranges for its
219
+ dependencies (`"@marktiderman/genesis-features": "workspace:^"`), which the app can't resolve. Replace
220
+ each with the published range the upstream release declares (read it from the package.json on npm
221
+ for that version), so the overlay installs against the same Genesis it was copied from.
222
+
223
+ An overlay can keep its build step, or point its exports straight at TypeScript source
224
+ (`"exports": { ".": "./src/index.ts" }`). For TypeScript source, the server bundle must inline
225
+ every Genesis package: otherwise a published Genesis package that the server leaves external
226
+ imports the overlay through Node, which can't load `.tsx` (a 500 in dev). In Vite, set
227
+ `ssr: { noExternal: [/^@marktiderman\/genesis-/] }` (Vite matches `noExternal` against package
228
+ names). Vitest's `server.deps.inline` matches resolved file paths instead, so use a path pattern
229
+ there: `test: { server: { deps: { inline: [/[\\/]@marktiderman[\\/]genesis-/] } } }`. The doctor reads a source overlay's
230
+ component exports from the source its exports point at when there's no `types` condition.
231
+
232
+ **What the doctor does with it.** A local package wins over an installed one of the same name, so
233
+ the overlay's own `genesis.doctor` rules run, and the [`packages` pack](#rule-packs) checks it like
234
+ any local package. Then:
235
+
236
+ | Rule | Level | What it flags |
237
+ | --- | --- | --- |
238
+ | `overlay-unmarked` | error | A local package with a `@marktiderman/genesis-*` name and no `genesis.overlay`. Mark it, or rename it. |
239
+ | `overlay-invalid` | error | A marker that doesn't validate (each problem with `upstream`, `since`, `owner`, `reason`, or an unknown key), a `since` later than tomorrow, an overlay that isn't `private: true`, or an overlay folder that holds the app's scanned source (`src`, or the app root). Such an overlay doesn't count as the package below. |
240
+ | `overlay-age` | info / warn | A marker older than 14 days is reported as info, which never fails a run; older than 30 days it warns, which fails `--strict`. An overlay never blocks a release in its first month, and must be promoted or dropped within it. |
241
+ | `overlay-version` | warn | The version isn't the upstream version, `<upstream>+local.N` or `<upstream>-local.N`. |
242
+
243
+ A marked overlay (valid marker, private, in a package folder of its own) **is** the package it
244
+ shadows, so for files inside it `shadowed-export`, `raw-tag`, `local-genesis-copy` and
245
+ `native-raw-primitive` don't flag that package's own names (an overlay of another package still may
246
+ not shadow genesis-ui). `version-skew` compares the release with the marker's `upstream` version
247
+ instead of the overlay's own (only for an overlay the app lists; a marked package that is merely
248
+ installed is compared as usual), and the packages pack's change gate (`package-unversioned-change`)
249
+ asks for no changeset or version bump. A block migration that names another package
250
+ (`{ "package": "@marktiderman/genesis-supabase", "file": "…", "test": "…" }`) has its test looked up
251
+ in that package, not in the overlay; a name that isn't valid, or a package that isn't installed or
252
+ local, is reported by `package-migration-test`.
253
+
254
+ **Promotion: manual for now.**
255
+
256
+ 1. Diff the overlay against the source of its upstream tag (`upstream` in the marker), so only the
257
+ app's own changes travel.
258
+ 2. Apply that diff onto a Genesis branch cut from the current staging batch.
259
+ 3. Add a changeset for the package.
260
+ 4. Open the Genesis PR into the batch.
261
+ 5. Before adopting, reconcile migrations: if promotion renamed a migration the overlay's app already
262
+ applied, or changed its SQL, `genesis migrate` can't match it and would copy it again. Map the
263
+ app's applied migration to the package's by hand (until the lock mapping below ships), then run
264
+ `genesis migrate --dry-run` with the release installed and check it copies nothing already applied.
265
+ 6. After the release, delete the overlay, drop the override, and pin the released version.
266
+
267
+ Planned: `genesis upstream promote <package>` (steps 1 to 4) and `genesis upstream adopt
268
+ <package>@<version>` (steps 5 and 6, checking the release matches the overlay), and a `genesis.lock.json`
269
+ mapping so a migration an overlay's app already applied is never copied a second time.
270
+
163
271
  ### genesis add
164
272
 
165
273
  `genesis add <block>` plans, prints the plan, asks (or `--yes`), then:
@@ -197,6 +305,7 @@ installed packages with the app's copies, and every copy that carries a header:
197
305
  | `edited` | the copy no longer matches the text it was copied with | reported; never rewritten |
198
306
  | `changed-upstream` | the package now ships different text than the copy was made from | reported; never rewritten |
199
307
  | `differs` | a file with the migration's name, other text and no header | treated as the app's own; never rewritten |
308
+ | `deleted` | the app deleted a copy `genesis.lock.json` records (its `migrations` map: where each package migration was copied) | reported; never copied again |
200
309
 
201
310
  Every file already in `supabase/migrations` counts as applied: none is ever written again, and a
202
311
  new file is created only if its name is free (otherwise it fails). A package migration is copied
@@ -206,7 +315,25 @@ symlink in the folder stops the command. A pgTAP test is copied only with its mi
206
315
  deleted stays deleted. `--forward` writes one forward migration stub
207
316
  (`<timestamp>_<name>_forward.sql`, with a `genesis-forward` header) for each edited or changed
208
317
  copy, holding the package's current text commented out, for you to turn into the change; later
209
- runs count that copy as handled. It exits 1 when something still needs you.
318
+ runs count that copy as handled. It exits 1 when something still needs you (a deleted copy was your
319
+ choice, so it doesn't). `genesis add`, `genesis migrate` and `init --template native` record each
320
+ copy in the lock; a run on an older lock records the copies it finds.
321
+
322
+ With the notifications block and a named registry (`--notifications <file>`, or
323
+ `"notifications": { "registry": "src/notifications.ts" }` in `genesis.config.json`; a relative
324
+ path is resolved against the app's root, `--dir`), it also mirrors the app's `defineNotifications`
325
+ types: when they differ from the newest `*_genesis_notification_types.sql` (the JSON only, not its
326
+ header), it writes a new one after this run's other migrations. That migration adds and updates
327
+ types and never retires one: each is one branch's snapshot, and two branches merged would
328
+ otherwise retire each other's types. Retiring stays with `syncNotificationTypes` on deploy. The
329
+ types are in place once every migration has run, so a trigger that fires after the migrations
330
+ meets no unknown type before the deploy; a migration that queues a notification while it runs
331
+ needs its type added earlier in that migration.
332
+
333
+ Loading the registry runs the app's code, so it happens only when the registry is named, never on
334
+ `--dry-run` (reported as not checked), and the registry module must have no side effects on
335
+ import (no network, database or writes). A registry it can't find or load, or a timestamp that
336
+ doesn't fit, is a warning.
210
337
 
211
338
  ### genesis upgrade
212
339
 
@@ -401,10 +528,13 @@ Exit codes: `0` pass, `1` findings, `2` the doctor couldn't run (bad config, Gen
401
528
  | `local-genesis-copy` | warn | An app component definition named like a component of `uiPackage` or of `componentPackages` (forms-studio's `ResourceHeader`, `SettingsSection`, `ResourceSettingsPage`, `HeadlineNumbers`, `SummaryCard`, `ShareDialog`, …): "Genesis already has X". A definition renders JSX, isn't in a file that imports the Genesis one, and is exported or lives outside the routes folder; a route's own non-exported functions and anything passed as `component` / `errorComponent` / `pendingComponent` / `notFoundComponent` (TanStack's `FormError`) are not copies. An exported genesis-ui value is `shadowed-export` instead; `const X = lazy(() => import("@marktiderman/genesis-…"))` is fine. |
402
529
  | `resource-workspace` | info | In a routes folder where a detail page (`courses.$courseId.tsx`, `[id]/page.tsx`) renders `AppShellPageHeader`, directly or through one local import, the other detail pages there that don't: one workspace header and tab row for every resource. Reported, never failing (`--strict` included); `rules` can raise it to `warn`. |
403
530
  | `page-layout` | warn | A route inside the AppShell (under the layout route that renders it) that renders no Genesis page layout (the `…Page` / `…PageShell` components `uiPackage` and `componentPackages` export, not `BreadcrumbPage`) itself, through one local import, or from a layout route around it (`my/route.tsx` supplying `DetailPage` covers `my/index.tsx`). A `…Page`, `…Screen` or `…Workspace` imported from any Genesis package counts. Routes outside the shell (sign-in, landing, public forms) aren't checked until Genesis ships layouts for them. Layout-only (`route.tsx`, `__root`, `<Outlet>`) and redirect-only routes are skipped; off with the `native` pack (see `native-screen-layout`). |
531
+ | `core/views-stay-platform-neutral` | warn | Declared by genesis-core (see [Package rules](#package-rules)). A `*.view.ts` file (a view description web and native share) that imports a platform module: a router (`react-router*`, `@tanstack/react-router`, `@tanstack/react-start`, `next`, `expo-router`), `react-dom`, `react-native` or `react-native-*`, `expo*`, icon sets (`lucide-react`, `lucide-react-native`), or Genesis UI (`genesis-ui`, `genesis-ui-native`, `genesis-native`). Direct imports only: keep what the view imports platform-neutral too. |
404
532
  | `iso-date-slice` | warn | A day cut from an ISO timestamp: `.toISOString().slice(0, 10)`, `.substring(0, 10)`, `.substr(0, 10)`, `.split("T")[0]` or `.split("T").at(0)`. That's the day in UTC, which for an evening in the Americas is already tomorrow. Use `personDay(person)` or `dayIn(zone)` from `@marktiderman/genesis-core/dates`. Test files are skipped; where UTC is what you mean (a log name, a UTC report), allow it with a reason. |
405
533
  | `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)) |
406
534
  | `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. |
407
535
  | `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. |
536
+ | `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. |
537
+ | `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. |
408
538
  | `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. |
409
539
  | `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
540
  | `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). |
@@ -415,7 +545,7 @@ Exit codes: `0` pass, `1` findings, `2` the doctor couldn't run (bad config, Gen
415
545
  | `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
546
 
417
547
  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
548
+ **Primitives** line: how many rules the installed packages declare (`genesis catalog` lists
419
549
  them). Check both before building something.
420
550
 
421
551
  The route rules (`hand-rolled-sub-nav`, `resource-workspace`, `page-layout`) read the routes
@@ -596,17 +726,20 @@ A declaration has **`prefer` rules** ("use X instead of Y") and optional **`prim
596
726
  "newOnly": false
597
727
  }
598
728
  ],
599
- "primitives": [{ "need": "dates", "use": "dayIn(zone)", "import": "@marktiderman/genesis-widgets/dates" }],
729
+ "catalog": [{ "need": "dates", "use": "dayIn(zone)", "import": "@marktiderman/genesis-widgets/dates" }],
600
730
  "plugin": "./dist/doctor-rules.js"
601
731
  }
602
732
  }
603
733
  }
604
734
  ```
605
735
 
736
+ `catalog` was called `primitives`; the old key is still read until the next major (not both at
737
+ once). A package that must stay readable by a genesis-cli before this release keeps `primitives`.
738
+
606
739
  | Key | |
607
740
  | --- | --- |
608
741
  | `id` | Lower-case words and dashes; namespaced by the doctor. |
609
- | `need` | The need it answers, for `genesis primitives` and the agent guide. |
742
+ | `need` | The need it answers, for `genesis catalog` and the agent guide. |
610
743
  | `level` | `error`, `warn` (default) or `info`. |
611
744
  | `platform` | `web` (off with the `native` pack) or `native` (only with it). Default both. |
612
745
  | `files`, `exclude` | App-relative globs. `{routes}` is the routes folder (`routesDir`). Default: every scanned script file. |
@@ -645,14 +778,14 @@ silently. `rules` works too, but warns (`package-rule-override`) until the reaso
645
778
  }
646
779
  ```
647
780
 
648
- **The catalog.** `genesis primitives` (`--json` for data) prints, for each need, what to use,
781
+ **The catalog.** `genesis catalog` (`--json` for data; `genesis primitives` is its deprecated name) prints, for each need, what to use,
649
782
  its import, the rule that enforces it and the docs: a short static core plus every installed
650
783
  package's declarations. `genesis agents` writes the same catalog as
651
784
  `.claude/skills/genesis/SKILL.md` and a `<!-- genesis-primitives:start -->` block in the app's
652
785
  AGENTS.md (the rest of the file is the app's), telling agents to use the primitives first, never
653
786
  copy an older screen, and write a gap up for Genesis before inventing. `genesis agents --check`
654
787
  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,
788
+ Both commands, and `genesis catalog`, exit 1 when a package's declaration doesn't validate,
656
789
  since the catalog would leave it out. Run `genesis agents` after each Genesis upgrade.
657
790
 
658
791
  ### The ratchet
@@ -822,3 +955,20 @@ if (!result.ok) throw new Error(formatReport(result));
822
955
  the local Vite plugin import with `@marktiderman/genesis-cli/vite`.
823
956
  4. Run `genesis doctor`, fix or `allow` what it reports (it checks `raw-color` in code as well
824
957
  as CSS, and `raw-tag` only in JSX files), then delete the old script.
958
+ ## genesis upstream
959
+
960
+ What an app needed from Genesis and didn't find goes in `docs/genesis-upstream.md`, one table:
961
+
962
+ | id | kind | status | feature | package | local | need |
963
+ | --- | --- | --- | --- | --- | --- | --- |
964
+ | kanban-swimlanes | extension | candidate | data-views | @marktiderman/genesis-ui | src/components/lanes.tsx | Swimlanes on KanbanBoard |
965
+
966
+ `kind` is `gap` (nothing in Genesis), `extension` (a part with no prop, variant or slot for it)
967
+ or `invention` (the app built it). `status` is `candidate`, `proposed`, `promoted` or `declined`.
968
+
969
+ - `genesis upstream check` validates it, and warns when a promoted entry's local code is still
970
+ there (delete your copy and use the Genesis one).
971
+ - `genesis upstream export <id>` prints the link to Genesis's gap issue form, filled in from the
972
+ entry (never the local path). It sends nothing; check the text names no app or customer, file
973
+ it, and set the entry to `proposed`.
974
+