@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.
- package/README.md +14 -279
- package/dist/blocks.d.ts +4 -470
- package/dist/blocks.js +7 -5
- package/dist/gate-react.d.ts +4 -45
- package/dist/gate-react.js +7 -36
- package/dist/gate.d.ts +4 -15
- package/dist/gate.js +7 -5
- package/dist/index.d.ts +4 -124
- package/dist/index.js +7 -8
- package/dist/node.d.ts +4 -156
- package/dist/node.js +7 -486
- package/dist/react.d.ts +4 -57
- package/dist/react.js +7 -235
- package/dist/settings-protocol.d.ts +7 -0
- package/dist/settings-protocol.js +7 -0
- package/dist/settings-react.d.ts +7 -0
- package/dist/settings-react.js +8 -0
- package/dist/settings.d.ts +7 -0
- package/dist/settings.js +7 -0
- package/package.json +35 -51
- package/dist/blocks.js.map +0 -1
- package/dist/chunk-B6WRD3WF.js +0 -6
- package/dist/chunk-B6WRD3WF.js.map +0 -1
- package/dist/chunk-OW46SL2G.js +0 -10
- package/dist/chunk-OW46SL2G.js.map +0 -1
- package/dist/chunk-SEFG2QV6.js +0 -413
- package/dist/chunk-SEFG2QV6.js.map +0 -1
- package/dist/chunk-VYUX7VAX.js +0 -52
- package/dist/chunk-VYUX7VAX.js.map +0 -1
- package/dist/chunk-YTPGUU5F.js +0 -121
- package/dist/chunk-YTPGUU5F.js.map +0 -1
- package/dist/chunk-Z3TTDIVM.js +0 -494
- package/dist/chunk-Z3TTDIVM.js.map +0 -1
- package/dist/gate-oYFzQKyb.d.ts +0 -199
- package/dist/gate-react.js.map +0 -1
- package/dist/gate.js.map +0 -1
- package/dist/index.js.map +0 -1
- package/dist/model-sTRmrxz3.d.ts +0 -437
- package/dist/node.js.map +0 -1
- package/dist/packages-CWhdXtzS.d.ts +0 -203
- package/dist/platforms-NR0liM8L.d.ts +0 -10
- package/dist/react.js.map +0 -1
- 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
|
-
|
|
4
|
-
|
|
5
|
-
|
|
6
|
-
|
|
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
|
-
|
|
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
|
|
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
|
-
|
|
147
|
-
|
|
148
|
-
|
|
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
|
-
|
|
19
|
+
Feature ids, `features.ts`, `features.json`, `flags.json` and the generated AGENTS.md block keep
|
|
20
|
+
their format.
|
|
286
21
|
|
|
287
|
-
|
|
22
|
+
Publishing and deprecating it: docs/RELEASING.md, "Renaming a package".
|