@marktiderman/genesis-cli 1.1.1 → 1.3.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
@@ -6,6 +6,12 @@ npx @marktiderman/genesis-cli init <consumer>
6
6
 
7
7
  Scaffolds a Genesis consumer: a brand package, Tailwind and tokens.
8
8
 
9
+ ```bash
10
+ npx @marktiderman/genesis-cli doctor [--strict] [--json] [--build] [--config <path>] [--dir <dir>]
11
+ ```
12
+
13
+ Checks an app against the Genesis it has installed. See [genesis doctor](#genesis-doctor).
14
+
9
15
  ```bash
10
16
  npx @marktiderman/genesis-cli studio init
11
17
  ```
@@ -45,18 +51,197 @@ from the live database.
45
51
 
46
52
  The output is deterministic: a re-run with no schema change writes the same bytes.
47
53
 
54
+ ```bash
55
+ npx @marktiderman/genesis-cli features build # or: features check (for CI)
56
+ ```
57
+
58
+ Writes the marked feature block in `AGENTS.md` (and a JSON copy with `--json <file>`) from the
59
+ repo's `src/features.ts`; `check` exits 1 when that output is stale or a feature's `links.code`
60
+ path doesn't exist. See [genesis-features](../features/README.md) for the registry and the options.
61
+
48
62
  ## Settings in comments
49
63
 
50
64
  Put labels and widgets next to the schema, in table and column comments:
51
65
 
52
66
  ```sql
53
- comment on table public.clients is
54
- 'People in a program. @genesis {"label": "Clients", "labelField": "name"}';
55
- comment on column public.clients.notes is
56
- 'Private to the coach. @genesis {"label": "Coach notes", "widget": "textarea"}';
67
+ comment on table public.customers is
68
+ 'Customers of the business. @genesis {"label": "Customers", "labelField": "name"}';
69
+ comment on column public.customers.notes is
70
+ 'Private to staff. @genesis {"label": "Internal notes", "widget": "textarea"}';
57
71
  ```
58
72
 
59
73
  The text before `@genesis` stays the description. Tables take `label`, `labelField` and
60
74
  `description`; columns take `label`, `description` and `widget`. Anything else is an error that
61
75
  names the table or column. These settings are generator input only: the checked-in file is what
62
76
  ships.
77
+
78
+ ## genesis doctor
79
+
80
+ `genesis doctor` checks that an app uses Genesis instead of working around it. Every built-in
81
+ rule is derived from what is installed, never from a list in the CLI: the components and
82
+ exports come from `@marktiderman/genesis-ui`'s type declarations (every subpath), the tokens
83
+ from the design system's theme stylesheets (`dist/themes/*.css`: `genesis.css` and the
84
+ Tailwind v4 bridge `genesis-tailwind4.css`), and the palette from the app's `tailwindcss/colors`.
85
+ Upgrading Genesis upgrades the checks.
86
+
87
+ | Option | |
88
+ | --- | --- |
89
+ | `--strict` | Fail on warnings too. |
90
+ | `--json` | Print `{ ok, genesis, errors, warnings, findings, unused }`. Build output is captured, not streamed. |
91
+ | `--build` | After the checks, run `doctor.build` commands, or the app's `typecheck` then `build` scripts. A build that itself runs the doctor doesn't recurse. |
92
+ | `-c, --config <path>` | Config file. Default: `genesis.config.json`, then the `genesis` key of package.json. |
93
+ | `-d, --dir <dir>` | The app's folder (default: cwd). |
94
+ | `--print-genesis` | Print the components, tokens, raw tags and palette read from Genesis, and exit. |
95
+
96
+ Exit codes: `0` pass, `1` findings, `2` the doctor couldn't run (bad config, Genesis not installed or not built).
97
+
98
+ ### Rules
99
+
100
+ | Rule | Level | What it flags |
101
+ | --- | --- | --- |
102
+ | `local-primitives` | error | A local primitive folder (`src/components/ui` by default; `localPrimitiveDirs`). |
103
+ | `starter-leftover` | warn | `components.json` or `src/lib/utils.ts` from a shadcn starter. |
104
+ | `forbidden-import` | error | `@radix-ui/*`, local `components/ui/*` (alias or relative), `@/lib/utils`, plus your `forbiddenImports`. |
105
+ | `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. |
106
+ | `palette-color` | error | Tailwind palette utilities (`bg-red-500`, `hover:text-slate-700/50`, `text-white`). Use semantic tokens. |
107
+ | `arbitrary-color` | error | Arbitrary color values (`bg-[#f00]`, `text-[rgb(1,2,3)]`). |
108
+ | `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. |
109
+ | `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. |
110
+ | `shadowed-export` | error | An exported value named like a Genesis export (`export function Button`). Reuse or extend it. |
111
+ | `stale-exception` | warn | An `allow` entry that no longer matches anything. |
112
+
113
+ It also prints **Available but unused**: the Genesis components no file imports. Check it
114
+ before building something.
115
+
116
+ Scanned by default: `src/**/*.{ts,tsx,js,jsx,mts,cts,css}`, skipping tests, `__fixtures__`,
117
+ `__mocks__`, `*.d.ts` and `*.gen.*`. Comments are ignored by every rule.
118
+
119
+ ### Config
120
+
121
+ `genesis.config.json` (or `"genesis": { "doctor": { … } }` in package.json):
122
+
123
+ ```json
124
+ {
125
+ "doctor": {
126
+ "src": ["src"],
127
+ "ignore": ["src/routeTree.gen.ts", "src/integrations/"],
128
+ "tokenFiles": ["src/styles.css"],
129
+ "rules": { "starter-leftover": "off", "palette-color": "warn" },
130
+ "allow": [
131
+ { "rule": "raw-color", "file": "src/lib/error-page.ts", "reason": "Static fallback page rendered before Genesis mounts." }
132
+ ],
133
+ "rulesDoc": "DESIGN_RULES.md",
134
+ "patterns": [
135
+ { "id": "no-page-chrome", "files": ["src/routes/**"], "forbid": "<AppShell\\b", "message": "The shell owns the chrome." }
136
+ ],
137
+ "plugins": ["./scripts/genesis-rules.mjs"],
138
+ "build": ["tsc --noEmit", "vite build"]
139
+ }
140
+ }
141
+ ```
142
+
143
+ | Key | Default | |
144
+ | --- | --- | --- |
145
+ | `src` | `["src"]` | Folders (or files) to scan. |
146
+ | `extensions` | `.ts .tsx .js .jsx .mts .cts .css` | |
147
+ | `ignore` | | Globs to skip, added to the defaults. `*` stays in a folder, `**` crosses folders, a trailing `/` means the whole folder. |
148
+ | `uiPackage` | `@marktiderman/genesis-ui` | |
149
+ | `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. |
150
+ | `tokenFiles` | every scanned `.css` | Globs of app files whose `--x:` declarations count as defined tokens. Files outside `src` work too. |
151
+ | `ignoreTokenPrefixes` | `["--tw-", "--radix-"]` | |
152
+ | `rawTags` | | `{ "img": "Avatar" }` adds a mapping; `{ "select": false }` stops checking a tag. |
153
+ | `forbiddenImports` | | `{ "<regexp>": "message" }`, added to the defaults. |
154
+ | `localPrimitiveDirs` | `["src/components/ui"]` | |
155
+ | `rules` | | `{ "<rule>": "error" \| "warn" \| "off" }` for any rule, built-in or yours. |
156
+ | `allow` | | Exceptions: `{ rule, file?, match?, reason }`. `match` is the exact tag, token, export name or import specifier. `reason` is required. |
157
+ | `patterns` | | Declarative rules, below. |
158
+ | `rulesDoc` | | A markdown file of declarative rules, below. |
159
+ | `plugins` | | Rule modules, below. |
160
+ | `build` | `typecheck`, `build` scripts | Commands for `--build`. |
161
+
162
+ Unknown keys are an error, so a typo can't quietly turn a check off.
163
+
164
+ ### App rules
165
+
166
+ Keep app-specific conventions in the app. Three ways, from least to most code:
167
+
168
+ **Patterns** (`patterns` in config): `{ id, level?, files, exclude?, forbid?, require?, path?, message? }`.
169
+ `forbid` must not match a file (the finding points at the line), `require` must match it, `path`
170
+ must match its path. All are regular expressions; prefix `(?i)` for case-insensitive. `level` is
171
+ `error` (default), `warn`, or `guide` (documentation only, never checked).
172
+
173
+ **A rules document** (`rulesDoc`): the same rules in markdown, next to the prose that explains
174
+ them. A `### rule-id` heading starts a rule, the `- key: value` lines under it set it (`files`
175
+ and `exclude` are comma-separated), and a `#`/`##` heading ends it:
176
+
177
+ ```md
178
+ ## Layout
179
+
180
+ ### pages-use-layouts
181
+ - level: error
182
+ - files: src/routes/_shell/*.tsx
183
+ - require: (DashboardPage|DetailPage|SettingsPage|FormPage)
184
+ - message: Signed-in pages render a Genesis page layout.
185
+ ```
186
+
187
+ **Plugins** (`plugins`): a module that default-exports a plugin, an array of them, or a factory
188
+ that receives the options from `["./path.mjs", options]`. Paths resolve from the config file.
189
+
190
+ ```js
191
+ // scripts/genesis-rules.mjs
192
+ /** @type {(options?: { max?: number }) => import("@marktiderman/genesis-cli/doctor").DoctorPlugin} */
193
+ export default function maxFileLength({ max = 400 } = {}) {
194
+ return {
195
+ name: "max-file-length",
196
+ check({ files, report }) {
197
+ for (const file of files) {
198
+ const lines = file.text.split("\n").length;
199
+ if (lines > max) report({ rule: "max-file-length", level: "warn", file: file.path, message: `has ${lines} lines; split it` });
200
+ }
201
+ },
202
+ };
203
+ }
204
+ ```
205
+
206
+ `check` gets `{ root, files, genesis, config, report }`. Each file has `path` (relative,
207
+ POSIX), `absolutePath`, `ext`, `text` and `code` (comments blanked, line numbers kept).
208
+ `genesis` has `components`, `exports`, `values`, `tokens`, `rawTags`, `palette` and the
209
+ version. `report({ rule, file, line?, level?, message, subject? })` records a finding; config
210
+ `rules` levels and `allow` entries apply to plugin rules exactly as to built-in ones. A plugin
211
+ that throws becomes a `plugin-error` finding rather than a crash. In TypeScript,
212
+ `defineDoctorPlugin` from `@marktiderman/genesis-cli/doctor` types the object.
213
+
214
+ ### Vite
215
+
216
+ ```ts
217
+ import { genesisDoctor } from "@marktiderman/genesis-cli/vite";
218
+
219
+ export default defineConfig({ plugins: [genesisDoctor()] });
220
+ ```
221
+
222
+ `vite build` fails when the doctor finds errors (`genesisDoctor({ strict: true })` fails on
223
+ warnings too). `vite dev` logs problems and shows Vite's error overlay, re-checks on every
224
+ change under the app (plus `genesis.config.json` and the rules doc), shows the overlay to
225
+ browsers that connect later, and reloads once everything passes. Options: `root`, `configPath`,
226
+ `strict`, `debounceMs`. `vite` is an optional peer dependency.
227
+
228
+ ### Programmatic use
229
+
230
+ ```ts
231
+ import { runDoctor, formatReport } from "@marktiderman/genesis-cli/doctor";
232
+
233
+ const result = await runDoctor({ root: process.cwd(), strict: true });
234
+ if (!result.ok) throw new Error(formatReport(result));
235
+ ```
236
+
237
+ ### Moving from a local verify script
238
+
239
+ 1. `npm i -D @marktiderman/genesis-cli` (or your package manager's equivalent).
240
+ 2. Move the exceptions to `genesis.config.json` under `doctor`: scan roots to `src`, ignores to
241
+ `ignore`, brand-bridge files to `tokenFiles`, theme stylesheet(s) to `themeCss` (usually not
242
+ needed; both shipped theme files are read by default), every exception to `allow` with its
243
+ reason, the rules document to `rulesDoc`.
244
+ 3. Replace the script in package.json with `genesis doctor` (and `genesis doctor --build`), and
245
+ the local Vite plugin import with `@marktiderman/genesis-cli/vite`.
246
+ 4. Run `genesis doctor`, fix or `allow` what it reports (it checks `raw-color` in code as well
247
+ as CSS, and `raw-tag` only in JSX files), then delete the old script.