@marktiderman/genesis-cli 1.27.0 → 1.29.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 +67 -1
- package/dist/cli.js +1274 -424
- package/dist/cli.js.map +1 -1
- package/dist/{config-ARs2YQ60.d.ts → config-BmMsEWU-.d.ts} +7 -0
- package/dist/doctor.d.ts +3 -3
- package/dist/doctor.js +628 -7
- package/dist/doctor.js.map +1 -1
- package/dist/expo.d.ts +2 -2
- package/dist/expo.js +11 -0
- package/dist/expo.js.map +1 -1
- package/dist/genesis-catalog.json +41 -17
- package/dist/index.d.ts +1 -1
- package/dist/index.js +636 -15
- package/dist/index.js.map +1 -1
- package/dist/starter/__tests__/starter.test.ts +8 -0
- package/dist/starter/fingerprint.config.js +18 -0
- package/dist/starter/supabase/migrations/20261025000095_genesis_support_ticket_fixes.sql +115 -0
- package/dist/starter/supabase/tests/database/genesis_support_ticket_fixes.test.sql +121 -0
- package/dist/verify.d.ts +209 -0
- package/dist/verify.js +549 -0
- package/dist/verify.js.map +1 -0
- package/dist/vite.js +628 -7
- package/dist/vite.js.map +1 -1
- package/package.json +18 -4
package/README.md
CHANGED
|
@@ -814,7 +814,7 @@ Exit codes: `0` pass, `1` findings, `2` the doctor couldn't run (bad config, Gen
|
|
|
814
814
|
| `arbitrary-color` | error | Arbitrary color values (`bg-[#f00]`, `text-[rgb(1,2,3)]`). |
|
|
815
815
|
| `raw-color` | error | Hex and `rgb()/hsl()` literals in code and CSS, via the same lexer as the repo's `check:token-usage` (comments, issue refs and `hsl(var(--x))` are fine). A brand file that defines token values needs an `allow` entry. |
|
|
816
816
|
| `undefined-token` | error | `var(--x)` where the theme doesn't define `--x`. Tokens declared in the app's CSS (or only `tokenFiles`) and inline style custom properties count as defined; `--tw-*` and `--radix-*` are ignored. |
|
|
817
|
-
| `shadowed-export` | error | An exported value named like a Genesis export (`export function Button`). Reuse or extend it. |
|
|
817
|
+
| `shadowed-export` | error | An exported value named like a Genesis export (`export function Button`). Reuse or extend it. A wrapper of that very component is fine: a file that imports it from the component package under another name and uses that name as code (`<G`, `G(`, `G.x`, or passed as a value; a comment, a string or JSX text doesn't count), as the client layer's `ResourceView` and `RecordView` do. |
|
|
818
818
|
| `duplicate-genesis-package` | warn | More than one copy of a `@marktiderman/genesis-*` package that the app can load, with each copy's path, version and the ranges that asked for it. Found by resolving the app's dependency graph the way Node does, from each package's real folder (starting from the app's own `package.json`), so npm/yarn/bun hoisted and nested trees, pnpm's `.pnpm` store (in the app, or at the workspace root above a sub-app) and bun's isolated `.bun` store all count; a store entry nothing resolves to is ignored. Two copies are two module instances: a `DataProvider` from one is invisible to hooks from the other. A copy reached only through dev tooling (the app's `devDependencies`, or anything under `@marktiderman/genesis-cli`, wherever it's listed) is `[dev only]`: every path to it from the app runs through declared tooling (test runners, `@types/*`, linters and formatters, compilers and bundlers, Storybook, release tools, or the CLI). Other devDependencies count as runtime: a bundler ships what the app imports from them. When exactly one copy is reached from a declared runtime dependency and every other copy is dev-only, the finding is `info` (it can't split the app's contexts). Anything else warns, a copy reached through an undeclared hoisted package included. An app with no runtime dependencies at all (a bundled SPA listing everything in `devDependencies`) has its devDependencies taken as runtime. A copy that only walking up the folders finds is left out: in an app with its own install inside another app's folder (a lockfile of its own, like `apps/mobile`), a peer dependency the app doesn't declare or install is unmet rather than met by the parent's copy, and the parent's CLI isn't followed unless the app declares it. A regular dependency that resolves up to the parent still counts. |
|
|
819
819
|
| `peer-range-mismatch` | warn | An installed Genesis package's `peerDependencies` range on another Genesis package that the copy it resolves (looked up from its own folder, as Node does) doesn't satisfy: the package, the range and the installed version. Missing peers and non-semver ranges (`workspace:*`) are skipped. Ranges are read with npm's grammar (`^ ~ x - ||`, prereleases only when the range names one). A mismatch inside a dev-only copy (the CLI's own tree) is `info`. |
|
|
820
820
|
| `hand-rolled-sub-nav` | warn | A route under the layout that renders `AppShell` that switches its sections with its own page-level `<TabsList>` or `<SubNavTabs>`, when the installed Genesis has `useAppShellSubNav`. Tabs inside a card, dialog, sheet, popover, accordion, panel, table or another tab's content are fine, as are pages that call the hook. Use `useAppShellSubNav(items, { mode: "tabs" })`, `AppShellPageHeader` and `AppShellSubNavEnd` from `@marktiderman/genesis-ui/layout` ([sub-navigation](../ui/SKILL.md)). |
|
|
@@ -829,6 +829,10 @@ Exit codes: `0` pass, `1` findings, `2` the doctor couldn't run (bad config, Gen
|
|
|
829
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
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
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). |
|
|
832
|
+
| `client/layer` | warn | Once the app has a client layer (a `resource-view.tsx` in `src/client/`, or genesis.config.json's `client.dir`): a screen outside it that renders Genesis's `<ResourceView>` or `<RecordView>` directly (`<RecordView>` once the layer has `record-view.tsx`). Screens render the layer's, so the app's defaults reach them (ADR 0020). |
|
|
833
|
+
| `client/one-view-per-resource` | warn | Once the app has a client layer: a second `defineView` over the same contract, told apart by where it is imported from (module and name, plus a `["…"]` key), not its spelling. Stories and tests are skipped, and so is a contract bound only locally (a name any function, method, arrow or `catch` binds as a parameter anywhere in the file, defaults and types aside: the skip is file-wide, a missed warning rather than a false one) or by destructuring (`const { tasks } = contracts`): the text can't tell those apart, so they're never counted (a missed warning, not a false one). Keep one view per resource and narrow it on the screen (`preset`, `filter`, `columns`), so its rules can't drift (ADR 0020). |
|
|
834
|
+
| `data/declared-access` | warn | A `createSupabaseProvider(…)` call without `access: "declared"` (its resources may read and write their tables with nothing saying so), and a table write in app code (`.from("t").insert/update/upsert/delete(…)`) outside tests and `supabase/`. Declared, each resource names its read (`source`: a view or a function) and its writes (`writes`: named database functions), and opts a table in only with `table: { …, why }`; a direct write that must stay is an `allow` entry with its reason ([DATA-ACCESS.md](../../docs/DATA-ACCESS.md)). |
|
|
835
|
+
| `data/access-rule-tests` | warn | An app that configures the Supabase provider (`createSupabaseProvider`) with no test calling `expectAccessRulesCover` (`@marktiderman/genesis-core/testing`). That test reads the provider's options and fails for each declared function (`writes`, `actions`, `source: { rpc }`) whose name no spec it is given carries. It compares names only, so give it the same specs the `accessRules` cases are registered from; the function holds who may call it, and its cases prove who is allowed and who is refused ([DATA-ACCESS.md](../../docs/DATA-ACCESS.md)). |
|
|
832
836
|
| `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. |
|
|
833
837
|
| `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. |
|
|
834
838
|
| `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). |
|
|
@@ -1327,6 +1331,51 @@ if (!result.ok) throw new Error(formatReport(result));
|
|
|
1327
1331
|
4. Run `genesis doctor`, fix or `allow` what it reports (it checks `raw-color` in code as well
|
|
1328
1332
|
as CSS, and `raw-tag` only in JSX files), then delete the old script.
|
|
1329
1333
|
|
|
1334
|
+
## Runtime conformance checks (`/verify`)
|
|
1335
|
+
|
|
1336
|
+
`genesis doctor` reads code; it can't see layout. `@marktiderman/genesis-cli/verify` checks a page
|
|
1337
|
+
in a real browser, the rules of `docs/RESPONSIVE.md` that a browser can measure. Genesis runs it
|
|
1338
|
+
over its sample app and every story in Chromium, WebKit and Firefox (the Conformance workflow),
|
|
1339
|
+
and an app can call it from its own Playwright tests.
|
|
1340
|
+
|
|
1341
|
+
```ts
|
|
1342
|
+
import { test, expect } from "@playwright/test";
|
|
1343
|
+
import { checkPage, widthViewport, contextOptions, formatFinding } from "@marktiderman/genesis-cli/verify";
|
|
1344
|
+
|
|
1345
|
+
const viewport = widthViewport(375);
|
|
1346
|
+
test.use(contextOptions(viewport, "webkit"));
|
|
1347
|
+
|
|
1348
|
+
test("items reflows on a phone", async ({ page }) => {
|
|
1349
|
+
await page.goto("/items");
|
|
1350
|
+
const findings = await checkPage(page, { viewport });
|
|
1351
|
+
expect(findings.map(formatFinding)).toEqual([]);
|
|
1352
|
+
});
|
|
1353
|
+
```
|
|
1354
|
+
|
|
1355
|
+
| Check | Fails when | Source |
|
|
1356
|
+
| --- | --- | --- |
|
|
1357
|
+
| `reflow` | the page or the app shell's scroller scrolls sideways, or an element runs past the viewport, unless it is wide content (a table, grid, code, a map, a tab strip, or a frame marked `data-scroll-frame`) in a frame that scrolls; content cut off by an ancestor that hides overflow counts, except a table cell clipping at its column's edge inside a table that scrolls | WCAG 1.4.10, rule 2 |
|
|
1358
|
+
| `text-clipped` | at 200% text (the `text-200` viewport), text is cut off by a box that hides its overflow (an ellipsis or line clamp is fine) | WCAG 1.4.4 |
|
|
1359
|
+
| `axe` | any axe WCAG 2.2 A/AA rule, `target-size` included (a `touchTarget` control passes on touch) | WCAG 2.5.8 and the rest |
|
|
1360
|
+
| `hit-area` | on a coarse pointer, a control (with its `<label>` and its `::before`/`::after`) is under 44×44px, or a hit test of its 44px box lands on something else (clipped or overlapped); a link in running text is exempt | rule 3 |
|
|
1361
|
+
| `focus-obscured` | a focused element is entirely hidden under a fixed or sticky element | WCAG 2.4.11 |
|
|
1362
|
+
| `floating-controls` | more than one floating control on a phone | rule 9 |
|
|
1363
|
+
| `viewport-meta` | the meta lacks `width=device-width`, `viewport-fit=cover` or `interactive-widget=resizes-content` | rules 6, 7 |
|
|
1364
|
+
| `touch-media` | touch is on but `(pointer: coarse)` and `(hover: none)` don't both match in that engine: an `info` note, and the coarse checks are skipped | the run itself |
|
|
1365
|
+
|
|
1366
|
+
`allViewports()` is the matrix: 320, 375, 768, 1024, 1280 and 1440px with touch at 768px and below;
|
|
1367
|
+
200% and 400% zoom of a 1280×1024 window (640×512 and 320×256 CSS px, with a mouse); and `text-200`,
|
|
1368
|
+
the browser's text size doubled (Chromium only, `zoomText(page)` before `goto`). Playwright's WebKit
|
|
1369
|
+
is a desktop build: safe areas, the browser toolbar and the on-screen keyboard still need a check
|
|
1370
|
+
on a device or the iOS Simulator.
|
|
1371
|
+
|
|
1372
|
+
Known findings go in an allow list shaped like the doctor's (`AllowEntry`: check, page, viewports,
|
|
1373
|
+
engines, target, reason; pages as paths or route patterns, targets with their quoted accessible
|
|
1374
|
+
name); `applyAllow` splits them, and `info` notes, from the rest. Axe runs first; the focus check
|
|
1375
|
+
runs last and restores focus and every frame's scroll. The page gets no input but `focus()` and an
|
|
1376
|
+
Escape after each (to close a tooltip it opened): the checks click and type nothing. Focus and blur
|
|
1377
|
+
handlers do run, so a page that saves on blur or marks things read on focus is changed by them.
|
|
1378
|
+
|
|
1330
1379
|
## genesis agents
|
|
1331
1380
|
|
|
1332
1381
|
Writes the agent guide from the installed Genesis packages, so every coding agent and reviewer in
|
|
@@ -1455,6 +1504,23 @@ export default function Settings() { … }
|
|
|
1455
1504
|
`12-345` (as a URL writes it) works too. The check reports a comment whose id isn't one of the
|
|
1456
1505
|
frames named for that route (the frame was replaced, or the comment was copied).
|
|
1457
1506
|
|
|
1507
|
+
## genesis client init
|
|
1508
|
+
|
|
1509
|
+
```bash
|
|
1510
|
+
npx @marktiderman/genesis-cli client init [--folder <dir>] [--type <name>] [--force]
|
|
1511
|
+
```
|
|
1512
|
+
|
|
1513
|
+
Starts the app's client layer (ADR 0020), its own layer over Genesis, in `src/client/` (or
|
|
1514
|
+
`--folder`, which it names in genesis.config.json as `client.dir`): `client-layer.tsx` (the
|
|
1515
|
+
provider with the app's list defaults, its saved-view store and its router's URL adapter),
|
|
1516
|
+
`resource-view.tsx` and `record-view.tsx` (the app's ResourceView and RecordView, which screens
|
|
1517
|
+
render), `cells/`, `components/` and `view-types/`, and with `--type tasks`, `tasks/contract.ts`
|
|
1518
|
+
(a starting contract to swap for the generated one), `tasks/view.ts` and `tasks/appearance.tsx`.
|
|
1519
|
+
Files that exist are kept unless `--force`. `--folder` takes a plain folder inside the app (no
|
|
1520
|
+
`.`, `..`, spaces or backslashes) and is written normalized; moving a folder genesis.config.json
|
|
1521
|
+
already names takes `--force`. The doctor's `client/layer` and `client/one-view-per-resource`
|
|
1522
|
+
rules keep screens on it.
|
|
1523
|
+
|
|
1458
1524
|
## genesis upstream
|
|
1459
1525
|
|
|
1460
1526
|
What an app needed from Genesis and didn't find goes in `docs/genesis-upstream.md` (or
|