@marktiderman/genesis-features 0.9.1 → 0.10.1

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.
Files changed (43) hide show
  1. package/README.md +14 -279
  2. package/dist/blocks.d.ts +4 -470
  3. package/dist/blocks.js +7 -5
  4. package/dist/gate-react.d.ts +4 -45
  5. package/dist/gate-react.js +7 -36
  6. package/dist/gate.d.ts +4 -15
  7. package/dist/gate.js +7 -5
  8. package/dist/index.d.ts +4 -124
  9. package/dist/index.js +7 -8
  10. package/dist/node.d.ts +4 -156
  11. package/dist/node.js +7 -486
  12. package/dist/react.d.ts +4 -57
  13. package/dist/react.js +7 -235
  14. package/dist/settings-protocol.d.ts +7 -0
  15. package/dist/settings-protocol.js +7 -0
  16. package/dist/settings-react.d.ts +7 -0
  17. package/dist/settings-react.js +8 -0
  18. package/dist/settings.d.ts +7 -0
  19. package/dist/settings.js +7 -0
  20. package/package.json +35 -51
  21. package/dist/blocks.js.map +0 -1
  22. package/dist/chunk-B6WRD3WF.js +0 -6
  23. package/dist/chunk-B6WRD3WF.js.map +0 -1
  24. package/dist/chunk-OW46SL2G.js +0 -10
  25. package/dist/chunk-OW46SL2G.js.map +0 -1
  26. package/dist/chunk-SEFG2QV6.js +0 -413
  27. package/dist/chunk-SEFG2QV6.js.map +0 -1
  28. package/dist/chunk-VYUX7VAX.js +0 -52
  29. package/dist/chunk-VYUX7VAX.js.map +0 -1
  30. package/dist/chunk-YTPGUU5F.js +0 -121
  31. package/dist/chunk-YTPGUU5F.js.map +0 -1
  32. package/dist/chunk-Z3TTDIVM.js +0 -494
  33. package/dist/chunk-Z3TTDIVM.js.map +0 -1
  34. package/dist/gate-oYFzQKyb.d.ts +0 -199
  35. package/dist/gate-react.js.map +0 -1
  36. package/dist/gate.js.map +0 -1
  37. package/dist/index.js.map +0 -1
  38. package/dist/model-sTRmrxz3.d.ts +0 -437
  39. package/dist/node.js.map +0 -1
  40. package/dist/packages-CWhdXtzS.d.ts +0 -203
  41. package/dist/platforms-NR0liM8L.d.ts +0 -10
  42. package/dist/react.js.map +0 -1
  43. package/dist/types-Bd766VxF.d.ts +0 -39
package/README.md CHANGED
@@ -1,287 +1,22 @@
1
- # @marktiderman/genesis-features
1
+ # @marktiderman/genesis-features (deprecated)
2
2
 
3
- A repo's features in one typed code file that running code imports. Every other format (the
4
- AGENTS.md pointer, `features.json`, an OpenFeature `flags.json`, the agent skill, a README
5
- section, the admin page) is generated from it, and `genesis features check` fails CI when a
6
- generated copy is stale or the registry and the code disagree.
3
+ **Renamed to [`@marktiderman/genesis-config`](../features/README.md).** This package is a thin
4
+ re-export of genesis-config with the same subpaths (`.`, `/blocks`, `/gate`, `/gate/react`,
5
+ `/settings`, `/settings/react`, `/settings-protocol`, `/node`, `/react`), kept for two minor versions (0.10 and 0.11) so apps can move at their own pace.
6
+ It goes after that.
7
7
 
8
- Phase 1 is deliberately small: one flat file per repo. No database, no sync, no hierarchy.
9
-
10
- ## The registry
11
-
12
- ```ts
13
- // src/features.ts
14
- import { defineFeatures, type FeatureIdOf } from "@marktiderman/genesis-features";
15
-
16
- export const features = defineFeatures({
17
- tasks: {
18
- name: "Tasks",
19
- summary: "Coach and client both add and check off next steps.", // internal, one sentence
20
- status: "live", // planned | building | beta | live | deprecated | retired
21
- owner: "mark",
22
- apps: ["web"],
23
- audience: ["client", "coach"],
24
- acceptance: ["A client can tick off a task their coach added."], // required on beta and live
25
- visibility: "customer", // internal | customer | public | client:<name>
26
- access: "all", // or { plan: "pro" }: the id is the entitlement's lookup key
27
- reviewedAt: "2026-10-22",
28
- links: { code: ["src/components/TasksPanel.tsx"], docs: ["docs/tasks.md"], issue: "#42" },
29
- tagline: "Never lose a next step.", // with visibility "public": marketing output
30
- category: "Coaching",
31
- },
32
- billing: { name: "Billing", summary: "…", status: "planned", horizon: "next", /* … */ },
33
- });
34
-
35
- export type FeatureId = FeatureIdOf<typeof features>;
36
- ```
37
-
38
- `defineFeatures` validates every entry with Zod and lists every problem at once:
39
-
40
- - Unknown fields, bad dates and paths that leave the repo are errors.
41
- - `planned` needs a `horizon` (now, next, later), and only planned or building features may have one. That's the roadmap, with no dates.
42
- - `beta` and `live` need `acceptance`.
43
- - `claimedBy` is only for `building`.
44
- - Ids and `aliases` are unique.
45
-
46
- It returns the same object, so code reads `features.tasks.status` directly. Name features by `FeatureId` everywhere, so a typo is a type error.
47
-
48
- Ids are permanent. `check` and `build` refuse when an id recorded in `features.json` disappears. Retire a feature with `status: "retired"`, and rename one through `aliases`.
49
-
50
- ## Flags
51
-
52
- ```ts
53
- import { defineFlags } from "@marktiderman/genesis-features";
54
- import { features } from "./features";
55
-
56
- export const flags = defineFlags(features, {
57
- "tasks.v2": { feature: "tasks", kind: "release", owner: "mark", default: false, scopes: ["platform", "user"], expires: "2026-12-01" },
58
- "tasks.kill": { feature: "tasks", kind: "ops", owner: "mark", default: true, scopes: ["platform"],
59
- runbook: "docs/runbooks/tasks.md", splitReason: "a kill switch outlives the rollout" },
60
- });
61
- ```
62
-
63
- - `feature` must be a `FeatureId`: an unknown one is a type error and a runtime error.
64
- - Flags are grouped by feature, so a feature's second flag needs a `splitReason`.
65
- - `release` and `experiment` flags need `expires`, and `ops` flags need a `runbook`.
66
- - A `permission` flag fails `check`, because paid access is `access`, not a flag.
67
- - `check` scans the code for flag reads through the accessors (default `useFlag(…)`, `getFlag(…)` and `<Flag name=…>`; set them with `flagAccessors`). It fails on:
68
- - a computed key;
69
- - a key that is read but not defined, or defined but never read;
70
- - a flag past its `expires` date.
71
-
72
- ## Generated output and the check
8
+ To move an app:
73
9
 
74
10
  ```bash
75
- genesis features build # AGENTS.md pointer, features.json, flags.json, the skill, the marketing block; @AGENTS.md in CLAUDE.md
76
- genesis features check # CI. --labels "a,b" checks a PR's feature:<id> labels; --prs reads merged PRs with gh
77
- genesis features check --summary # for a SessionStart hook: counts, stale output, expired flags, planned-but-shipped, claims
78
- genesis features find <term> # search ids, aliases, names, summaries, flags and code paths
79
- ```
80
-
81
- **Errors fail the check:**
82
-
83
- - Generated output is stale.
84
- - A `links.code` path doesn't exist.
85
- - A flag breaks one of the rules above.
86
- - An id was removed.
87
- - A feature tag names an unknown id: `@feat:<id>` in tests, `Features: <id>` in a changeset's body, or `feature:<id>` on a PR.
88
- - CLAUDE.md has no `@AGENTS.md` line.
89
-
90
- **Warnings don't fail it:**
91
-
92
- - A review is due: `reviewedAt` is over 90 days old, or missing.
93
- - A live feature has no test tagged with its `@feat:<id>`.
94
- - A feature is still `planned`, but shipped work is tagged with it: a changeset with `Features: <id>`, or (with `--prs`) a merged PR labelled `feature:<id>`. The warning names each one, e.g. "billing is still planned, but .changeset/x.md and PR #123 shipped work for it". `--prs` asks `gh pr list --state merged --label feature:<id>` for each planned id and alias; when `gh` is missing or fails, you get one warning and only changesets count. From code, pass the PRs yourself as `checkFeatureOutputs({ …, evidence: { prs: { billing: [{ number, title }] } } })`.
95
- - A route or server-function file isn't covered by any `links.code`.
96
- - A docs path is missing.
97
-
98
- The check only ever compares generated output with the generator, never two hand-written files.
99
-
100
- The AGENTS.md block is a short pointer with counts, not the list. Agents run `find` and read the skill (`.claude/skills/features/SKILL.md`, which covers finding, adding, changing and retiring features, and says to remove the code before the flag).
101
-
102
- ### Settings
103
-
104
- The CLI reads settings from the `features` block of `genesis.config.json` (the app's one Genesis config, beside `doctor`), or from `"genesisFeatures"` in `package.json`. Command-line options win, then `genesis.config.json`.
105
-
106
- ```json
107
- "genesisFeatures": {
108
- "registry": "src/features.ts",
109
- "flagsFile": "src/lib/flags/registry.ts",
110
- "command": "bun run features",
111
- "marketing": "README.md",
112
- "flagAccessors": ["useFlag", "flag", "<Flag name>"],
113
- "coverage": ["src/routes/**/*.tsx", "**/*.functions.ts"]
114
- }
115
- ```
116
-
117
- Other settings: `agents`, `claude`, `json`, `openfeature`, `skill` (each a path, or `false`), `scan`, `scanIgnore`, `tests`, `coverageIgnore`, `changesets`, `reviewDays`.
118
-
119
- The flag scan ignores comments and test files. List the flags runtime itself (the files that define the accessors and read by variable) in `scanIgnore`; setting it replaces the default test globs, so include those too.
120
-
121
- The CLI loads TypeScript itself, so the registry needs no build step. Keep its imports to packages, with no path aliases.
122
-
123
- ## The gate
124
-
125
- `featureOn(registry, context, id)` answers "is this feature on here?" the same way everywhere. Checks
126
- run in a fixed order and the first "no" wins: **status** (beta, live or deprecated), **platform**, **tenant**
127
- (switched off), **flag** (each boolean release flag must be exactly `true`) and last **entitlement** (for
128
- `access: { plan }`), so an upgrade prompt only appears when paying is the one thing missing. The answer
129
- carries the reason, and for a paid feature the plan that unlocks it.
130
-
131
- ```ts
132
- import { featureOn, gateSnapshot, isSnapshotStale, requireFeature } from "@marktiderman/genesis-features/gate";
133
-
134
- const context = { platform: "web", entitlements: ["form-webhook-delivery"], off: ["library"], flags: { "sms.release": true } };
135
- featureOn({ features, flags }, context, "library"); // { on: false, reason: "tenant" }
136
-
137
- // Server functions refuse whatever the reason: FeatureOff has status 402 (entitlement) or 403.
138
- requireFeature({ features, flags }, context, "form-webhook-delivery");
139
-
140
- // The server hands the client every shipped feature's answer: plain JSON with `at` (and `version`).
141
- const snapshot = gateSnapshot({ features, flags }, context, { version: buildVersion });
142
- // A client keeps it, and replaces it when stale, after sign-in or a tenant switch, or after a refusal.
143
- if (isSnapshotStale(snapshot, 5 * 60_000)) refresh();
11
+ npx genesis codemod genesis-features-renamed-genesis-config # genesis upgrade runs it too
144
12
  ```
145
13
 
146
- `/gate` has no zod, React, Node built-ins or DOM globals, so it ships to browsers, extension service workers,
147
- phones and edge functions. Context id sets are lists, Sets or functions (not iterators or strings). In React (web and React
148
- Native), `/gate/react` reads the server's snapshot:
149
-
150
- ```tsx
151
- import { FeatureGate, FeatureGateProvider, useFeature } from "@marktiderman/genesis-features/gate/react";
152
-
153
- <FeatureGateProvider snapshot={snapshot}>
154
- <FeatureGate feature="form-webhook-delivery" upsell={({ unlock }) => <Upgrade plan={unlock.plan} />}>
155
- <WebhookSettings />
156
- </FeatureGate>
157
- </FeatureGateProvider>;
158
- ```
159
-
160
- A feature that `requires` other features in the registry (a module's parts) is off while any of them is off,
161
- with `via` naming the one that said no, so switching a module off or not paying for it turns its parts off
162
- too. Ids outside the registry don't gate.
163
-
164
- The gate doesn't check roles: "may this person" stays with roles and row security. Why it works this
165
- way: [ADR 0001](../../docs/adr/0001-one-feature-gate.md).
166
-
167
- ## Blocks
168
-
169
- A block is a feature an app adds whole: account, push, observability, support, updates. It is
170
- declared once, by its FeatureId, with what it needs and what it contributes. The app shell, the
171
- navigation tree and Settings read the contributions by FeatureId; the app still decides where they
172
- go. `@marktiderman/genesis-features/blocks` has no zod in it, so it ships to phones (the root
173
- re-exports it).
174
-
175
- ```ts
176
- import { defineBlock, resolveBlocks } from "@marktiderman/genesis-features/blocks";
177
- import type { FeatureId } from "./features";
178
-
179
- export const supportBlock = defineBlock<FeatureId>({
180
- id: "support",
181
- requires: ["account"], // other blocks, or app features that aren't blocks
182
- platforms: ["web", "native"], // default: everywhere
183
- contributes: {
184
- nav: [{ id: "help", label: "Help", path: "/help" }],
185
- settings: [{ id: "contact-support", section: "about", title: "Contact support", href: "/support" }],
186
- routes: [{ path: "/support", signedIn: true }],
187
- slots: { fatal: SupportFatalScreen }, // fills the host shell's slots; the app's own slots win
188
- migrations: [{ package: "@acme/support", file: "migrations/0001_support.sql" }],
189
- skills: [".claude/skills/support/SKILL.md"],
190
- privacy: { collects: [{ type: "email address", purposes: ["app functionality"], linked: true, tracking: false }] },
191
- },
192
- });
193
-
194
- const blocks = resolveBlocks([accountBlock, supportBlock], enabledIds, { platform: "native", features });
195
- blocks.nav; // [{ feature: "support", id: "help", … }]: place them in your nav tree
196
- blocks.settings; // by `order`, then dependency order
197
- blocks.dropped; // with { missing: "drop" }: what was left out and why
198
- ```
199
-
200
- `defineBlock` validates one block and freezes it. `resolveBlocks(blocks, enabled?, options?)`
201
- takes the blocks that exist, the ids that are on (a list, a predicate, or every block when left
202
- out) and returns the enabled ones in dependency order with their contributions merged, each tagged
203
- with its `feature`. It throws a `BlockError` listing every problem at once:
204
-
205
- - a bad id, a block requiring itself, an unknown contribution key, a duplicate id;
206
- - a cycle through `requires` (the registry's own check, from `graph.ts`);
207
- - with `features` (the registry), a block id or requirement that isn't a feature;
208
- - an enabled block whose requirement is off, or doesn't run on `platform`. With `missing: "drop"` the
209
- block (and everything needing it) is left out instead and listed in `dropped`: for switches that
210
- change at run time, such as a tenant turning a feature off;
211
- - two enabled blocks contributing the same nav entry, Settings row, route or slot, or (with `slots`)
212
- a fill for a slot the host doesn't have.
213
-
214
- A requirement that isn't one of the blocks is a feature the app owns: it is met only when
215
- `enabled` lists it, so a block that was never passed is an error, not a silent pass. With `slots`
216
- (the host's slot names), a fill for any other slot is an error too.
217
-
218
- Blocks shipped so far: `createUpdates(…)` (`app-updates`, in `@marktiderman/genesis-native/updates`),
219
- `accountBlock` and `tenantFeaturesBlock` (in `@marktiderman/genesis-supabase`).
220
- `<GenesisNativeApp blocks={…}>` runs them; see that package's README.
221
-
222
- ## Content packs
223
-
224
- A content pack is versioned data that fills installed blocks: whatever those blocks hold (meeting types,
225
- templates, checklists, forms) plus labels. Packs are code: the publishing package exports them, and an
226
- installer copies them into a tenant's editable rows, keeping each row's source (pack, version, key) so an
227
- update can tell what someone changed.
228
-
229
- A pack's `sections` are keyed by the block that owns them. Genesis checks what every pack shares; what an
230
- item holds is the block's business, checked by the validator it registers as `contributes.contentSection`:
231
-
232
- ```ts
233
- import { contentPackProblems, defineBlock, defineContentPack } from "@marktiderman/genesis-features/blocks";
234
-
235
- export const meetingsBlock = defineBlock({
236
- id: "meetings",
237
- contributes: {
238
- // Returns every problem with this block's items in a pack.
239
- contentSection: (items) =>
240
- (items as { key: string; minutes?: number }[]).filter((m) => !((m.minutes ?? 0) > 0)).map((m) => `${m.key}: minutes must be more than 0`),
241
- },
242
- });
243
-
244
- export const weeklyTeamRhythm = defineContentPack(
245
- {
246
- id: "weekly-team-rhythm",
247
- name: "Weekly team rhythm",
248
- version: "1.0.0",
249
- publisher: "@acme/content",
250
- requires: ["meetings"],
251
- labels: { "project.phase": "Stage" },
252
- sections: { meetings: [{ key: "weekly", name: "Weekly meeting", minutes: 60 }] },
253
- },
254
- { blocks: [meetingsBlock] },
255
- );
256
-
257
- contentPackProblems(weeklyTeamRhythm, { installed: installedBlockIds, blocks: [meetingsBlock] }); // [] when it can be installed
258
- ```
259
-
260
- `defineContentPack` lists every problem at once: ids, semver versions, publisher, label keys, item keys
261
- (unique per section, stable across versions), every block validator's problems, and any section whose
262
- block `requires` doesn't list. `contentPackProblems(pack, installedBlockIds)` still takes the installed
263
- blocks alone; `{ validators: { meetings: fn } }` gives validators by block id instead of blocks.
264
-
265
- The typed sections packs had before (`sessionTypes`, `metricTemplates`, `fieldDefinitions`, `forms`,
266
- `roadmapTemplates`) still work and are checked as before, but are deprecated: put that data in `sections`
267
- under the block that owns it.
268
-
269
- ## The page
270
-
271
- ```tsx
272
- import { FeatureList } from "@marktiderman/genesis-features/react";
273
-
274
- <FeatureList features={features} flags={flags} pathHref={(p) => `https://github.com/acme/app/blob/main/${p}`} />
275
- <FeatureList features={features} variant="marketing" title="What it does" />
276
- ```
277
-
278
- The default view is a genesis-ui `ResourcePage` over static data:
279
-
280
- - A table, and in its grid view a board grouped by status (`KanbanBoard`).
281
- - Status chips (`StatusBadge`), plus filters by app, audience and visibility.
282
- - A detail panel with links, acceptance and flags.
283
- - Planned work stays off the list and shows on the roadmap (Now, Next, Later) below it.
14
+ The codemod rewrites every `@marktiderman/genesis-features` import (and subpath) to
15
+ `@marktiderman/genesis-config`, the dependency and overrides in each `package.json`, tsconfig paths
16
+ and `pnpm-workspace.yaml`, and lists what still mentions the old name. `genesis doctor` reports any
17
+ import that is left as `deprecated-import`.
284
18
 
285
- `variant="marketing"` shows public, shipped features that have a tagline, as cards: highlights first, then grouped by category.
19
+ Feature ids, `features.ts`, `features.json`, `flags.json` and the generated AGENTS.md block keep
20
+ their format.
286
21
 
287
- genesis-ui (2.7.0 or later), React and lucide-react are optional peers, needed only by `/react`. Gate the route yourself; the component shows whatever it is given.
22
+ Publishing and deprecating it: docs/RELEASING.md, "Renaming a package".