@marktiderman/genesis-config 0.0.0-stage → 0.10.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/LICENSE +21 -0
- package/README.md +461 -2
- package/dist/blocks.d.ts +473 -0
- package/dist/blocks.js +5 -0
- package/dist/blocks.js.map +1 -0
- package/dist/chunk-B6WRD3WF.js +6 -0
- package/dist/chunk-B6WRD3WF.js.map +1 -0
- package/dist/chunk-HIOKZIZP.js +218 -0
- package/dist/chunk-HIOKZIZP.js.map +1 -0
- package/dist/chunk-M7IY6LUN.js +123 -0
- package/dist/chunk-M7IY6LUN.js.map +1 -0
- package/dist/chunk-OW46SL2G.js +10 -0
- package/dist/chunk-OW46SL2G.js.map +1 -0
- package/dist/chunk-SEFG2QV6.js +413 -0
- package/dist/chunk-SEFG2QV6.js.map +1 -0
- package/dist/chunk-UD7SPYZH.js +354 -0
- package/dist/chunk-UD7SPYZH.js.map +1 -0
- package/dist/chunk-VYUX7VAX.js +52 -0
- package/dist/chunk-VYUX7VAX.js.map +1 -0
- package/dist/chunk-Y7NUBTWA.js +494 -0
- package/dist/chunk-Y7NUBTWA.js.map +1 -0
- package/dist/gate-CNTkn-Fv.d.ts +202 -0
- package/dist/gate-react.d.ts +48 -0
- package/dist/gate-react.js +37 -0
- package/dist/gate-react.js.map +1 -0
- package/dist/gate.d.ts +18 -0
- package/dist/gate.js +5 -0
- package/dist/gate.js.map +1 -0
- package/dist/index.d.ts +128 -0
- package/dist/index.js +9 -0
- package/dist/index.js.map +1 -0
- package/dist/model-uON71G4u.d.ts +437 -0
- package/dist/node.d.ts +159 -0
- package/dist/node.js +486 -0
- package/dist/node.js.map +1 -0
- package/dist/packages-CWhdXtzS.d.ts +203 -0
- package/dist/platforms-NR0liM8L.d.ts +10 -0
- package/dist/react.d.ts +60 -0
- package/dist/react.js +236 -0
- package/dist/react.js.map +1 -0
- package/dist/settings-protocol.d.ts +515 -0
- package/dist/settings-protocol.js +4 -0
- package/dist/settings-protocol.js.map +1 -0
- package/dist/settings-react.d.ts +143 -0
- package/dist/settings-react.js +943 -0
- package/dist/settings-react.js.map +1 -0
- package/dist/settings.d.ts +373 -0
- package/dist/settings.js +3 -0
- package/dist/settings.js.map +1 -0
- package/dist/types-D4hs16bJ.d.ts +39 -0
- package/package.json +141 -4
package/LICENSE
ADDED
|
@@ -0,0 +1,21 @@
|
|
|
1
|
+
MIT License
|
|
2
|
+
|
|
3
|
+
Copyright (c) 2026 Mark Tiderman
|
|
4
|
+
|
|
5
|
+
Permission is hereby granted, free of charge, to any person obtaining a copy
|
|
6
|
+
of this software and associated documentation files (the "Software"), to deal
|
|
7
|
+
in the Software without restriction, including without limitation the rights
|
|
8
|
+
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
|
|
9
|
+
copies of the Software, and to permit persons to whom the Software is
|
|
10
|
+
furnished to do so, subject to the following conditions:
|
|
11
|
+
|
|
12
|
+
The above copyright notice and this permission notice shall be included in all
|
|
13
|
+
copies or substantial portions of the Software.
|
|
14
|
+
|
|
15
|
+
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
|
|
16
|
+
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
|
|
17
|
+
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
|
|
18
|
+
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
|
|
19
|
+
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
|
|
20
|
+
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
|
|
21
|
+
SOFTWARE.
|
package/README.md
CHANGED
|
@@ -1,3 +1,462 @@
|
|
|
1
|
-
#
|
|
1
|
+
# @marktiderman/genesis-config
|
|
2
2
|
|
|
3
|
-
|
|
3
|
+
> Formerly `@marktiderman/genesis-features`, renamed in place (same source, same subpaths, same
|
|
4
|
+
> formats). The old name is a deprecated re-export for two minor versions
|
|
5
|
+
> ([packages/features-alias](../features-alias/README.md)); `genesis upgrade` moves an app's imports.
|
|
6
|
+
|
|
7
|
+
A repo's features in one typed code file that running code imports. Every other format (the
|
|
8
|
+
AGENTS.md pointer, `features.json`, an OpenFeature `flags.json`, the agent skill, a README
|
|
9
|
+
section, the admin page) is generated from it, and `genesis features check` fails CI when a
|
|
10
|
+
generated copy is stale or the registry and the code disagree.
|
|
11
|
+
|
|
12
|
+
Phase 1 is deliberately small: one flat file per repo. No database, no sync, no hierarchy.
|
|
13
|
+
|
|
14
|
+
## The registry
|
|
15
|
+
|
|
16
|
+
```ts
|
|
17
|
+
// src/features.ts
|
|
18
|
+
import { defineFeatures, type FeatureIdOf } from "@marktiderman/genesis-config";
|
|
19
|
+
|
|
20
|
+
export const features = defineFeatures({
|
|
21
|
+
tasks: {
|
|
22
|
+
name: "Tasks",
|
|
23
|
+
summary: "Coach and client both add and check off next steps.", // internal, one sentence
|
|
24
|
+
status: "live", // planned | building | beta | live | deprecated | retired
|
|
25
|
+
owner: "mark",
|
|
26
|
+
apps: ["web"],
|
|
27
|
+
audience: ["client", "coach"],
|
|
28
|
+
acceptance: ["A client can tick off a task their coach added."], // required on beta and live
|
|
29
|
+
visibility: "customer", // internal | customer | public | client:<name>
|
|
30
|
+
access: "all", // or { plan: "pro" }: the id is the entitlement's lookup key
|
|
31
|
+
reviewedAt: "2026-10-22",
|
|
32
|
+
links: { code: ["src/components/TasksPanel.tsx"], docs: ["docs/tasks.md"], issue: "#42" },
|
|
33
|
+
tagline: "Never lose a next step.", // with visibility "public": marketing output
|
|
34
|
+
category: "Coaching",
|
|
35
|
+
},
|
|
36
|
+
billing: { name: "Billing", summary: "…", status: "planned", horizon: "next", /* … */ },
|
|
37
|
+
});
|
|
38
|
+
|
|
39
|
+
export type FeatureId = FeatureIdOf<typeof features>;
|
|
40
|
+
```
|
|
41
|
+
|
|
42
|
+
`defineFeatures` validates every entry with Zod and lists every problem at once:
|
|
43
|
+
|
|
44
|
+
- Unknown fields, bad dates and paths that leave the repo are errors.
|
|
45
|
+
- `planned` needs a `horizon` (now, next, later), and only planned or building features may have one. That's the roadmap, with no dates.
|
|
46
|
+
- `beta` and `live` need `acceptance`.
|
|
47
|
+
- `claimedBy` is only for `building`.
|
|
48
|
+
- Ids and `aliases` are unique.
|
|
49
|
+
|
|
50
|
+
It returns the same object, so code reads `features.tasks.status` directly. Name features by `FeatureId` everywhere, so a typo is a type error.
|
|
51
|
+
|
|
52
|
+
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`.
|
|
53
|
+
|
|
54
|
+
## Flags
|
|
55
|
+
|
|
56
|
+
```ts
|
|
57
|
+
import { defineFlags } from "@marktiderman/genesis-config";
|
|
58
|
+
import { features } from "./features";
|
|
59
|
+
|
|
60
|
+
export const flags = defineFlags(features, {
|
|
61
|
+
"tasks.v2": { feature: "tasks", kind: "release", owner: "mark", default: false, scopes: ["platform", "user"], expires: "2026-12-01" },
|
|
62
|
+
"tasks.kill": { feature: "tasks", kind: "ops", owner: "mark", default: true, scopes: ["platform"],
|
|
63
|
+
runbook: "docs/runbooks/tasks.md", splitReason: "a kill switch outlives the rollout" },
|
|
64
|
+
});
|
|
65
|
+
```
|
|
66
|
+
|
|
67
|
+
- `feature` must be a `FeatureId`: an unknown one is a type error and a runtime error.
|
|
68
|
+
- Flags are grouped by feature, so a feature's second flag needs a `splitReason`.
|
|
69
|
+
- `release` and `experiment` flags need `expires`, and `ops` flags need a `runbook`.
|
|
70
|
+
- A `permission` flag fails `check`, because paid access is `access`, not a flag.
|
|
71
|
+
- `check` scans the code for flag reads through the accessors (default `useFlag(…)`, `getFlag(…)` and `<Flag name=…>`; set them with `flagAccessors`). It fails on:
|
|
72
|
+
- a computed key;
|
|
73
|
+
- a key that is read but not defined, or defined but never read;
|
|
74
|
+
- a flag past its `expires` date.
|
|
75
|
+
|
|
76
|
+
## Generated output and the check
|
|
77
|
+
|
|
78
|
+
```bash
|
|
79
|
+
genesis features build # AGENTS.md pointer, features.json, flags.json, the skill, the marketing block; @AGENTS.md in CLAUDE.md
|
|
80
|
+
genesis features check # CI. --labels "a,b" checks a PR's feature:<id> labels; --prs reads merged PRs with gh
|
|
81
|
+
genesis features check --summary # for a SessionStart hook: counts, stale output, expired flags, planned-but-shipped, claims
|
|
82
|
+
genesis features find <term> # search ids, aliases, names, summaries, flags and code paths
|
|
83
|
+
```
|
|
84
|
+
|
|
85
|
+
**Errors fail the check:**
|
|
86
|
+
|
|
87
|
+
- Generated output is stale.
|
|
88
|
+
- A `links.code` path doesn't exist.
|
|
89
|
+
- A flag breaks one of the rules above.
|
|
90
|
+
- An id was removed.
|
|
91
|
+
- A feature tag names an unknown id: `@feat:<id>` in tests, `Features: <id>` in a changeset's body, or `feature:<id>` on a PR.
|
|
92
|
+
- CLAUDE.md has no `@AGENTS.md` line.
|
|
93
|
+
|
|
94
|
+
**Warnings don't fail it:**
|
|
95
|
+
|
|
96
|
+
- A review is due: `reviewedAt` is over 90 days old, or missing.
|
|
97
|
+
- A live feature has no test tagged with its `@feat:<id>`.
|
|
98
|
+
- 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 }] } } })`.
|
|
99
|
+
- A route or server-function file isn't covered by any `links.code`.
|
|
100
|
+
- A docs path is missing.
|
|
101
|
+
|
|
102
|
+
The check only ever compares generated output with the generator, never two hand-written files.
|
|
103
|
+
|
|
104
|
+
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).
|
|
105
|
+
|
|
106
|
+
### Settings
|
|
107
|
+
|
|
108
|
+
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`.
|
|
109
|
+
|
|
110
|
+
```json
|
|
111
|
+
"genesisFeatures": {
|
|
112
|
+
"registry": "src/features.ts",
|
|
113
|
+
"flagsFile": "src/lib/flags/registry.ts",
|
|
114
|
+
"command": "bun run features",
|
|
115
|
+
"marketing": "README.md",
|
|
116
|
+
"flagAccessors": ["useFlag", "flag", "<Flag name>"],
|
|
117
|
+
"coverage": ["src/routes/**/*.tsx", "**/*.functions.ts"]
|
|
118
|
+
}
|
|
119
|
+
```
|
|
120
|
+
|
|
121
|
+
Other settings: `agents`, `claude`, `json`, `openfeature`, `skill` (each a path, or `false`), `scan`, `scanIgnore`, `tests`, `coverageIgnore`, `changesets`, `reviewDays`.
|
|
122
|
+
|
|
123
|
+
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.
|
|
124
|
+
|
|
125
|
+
The CLI loads TypeScript itself, so the registry needs no build step. Keep its imports to packages, with no path aliases.
|
|
126
|
+
|
|
127
|
+
## App settings
|
|
128
|
+
|
|
129
|
+
Every package declares its settings next to its `defineBlock`, and the app resolves them through
|
|
130
|
+
one resolver on the server, the web and phones (`@marktiderman/genesis-config/settings`, free of
|
|
131
|
+
zod; also on the root).
|
|
132
|
+
|
|
133
|
+
```ts
|
|
134
|
+
import { defineSettings, resolveSettings, settingsCatalogue, withSettings } from "@marktiderman/genesis-config/settings";
|
|
135
|
+
|
|
136
|
+
export const supportSettings = defineSettings("support", {
|
|
137
|
+
messenger: { type: "boolean", default: { max: true, standard: true, min: false }, scope: "tenant", feature: "support-messenger" },
|
|
138
|
+
agentDesk: { type: "boolean", default: { max: true, standard: true, min: false }, requires: ["support.inbox"] },
|
|
139
|
+
inbox: { type: "boolean", default: true },
|
|
140
|
+
dumpRetentionDays: { type: "number", default: 90, min: 7, max: 365 },
|
|
141
|
+
githubRepo: { type: "string", default: null, needs: "secret:GITHUB_TOKEN", store: "edge", setup: "github.issues" },
|
|
142
|
+
sentryDsn: { type: "string", default: null, applies: "build" },
|
|
143
|
+
});
|
|
144
|
+
|
|
145
|
+
const catalogue = settingsCatalogue([supportSettings]);
|
|
146
|
+
const settings = resolveSettings(catalogue, { preset: "max", file, database, tenant, person });
|
|
147
|
+
settings.values["support.dumpRetentionDays"]; // 90
|
|
148
|
+
settings.sources["support.messenger"]; // { layer: "tenant" }
|
|
149
|
+
const ctx = withSettings({ platform: "web" }, catalogue, settings); // for featureOn
|
|
150
|
+
```
|
|
151
|
+
|
|
152
|
+
Each key has a `type` (`boolean`, `number`, `string`, `list`, `object`) and a `default`, or one per
|
|
153
|
+
preset (`{ max, standard, min }`). `scope` (`app`, the default, `tenant` or `person`) is the lowest
|
|
154
|
+
layer that may change it; `applies` is `runtime` (the default) or `build` (a new binary or bundle).
|
|
155
|
+
`requires` links other keys, `min`, `max` and `options` bound the value, and `needs:
|
|
156
|
+
"secret:NAME"` names the secret it needs and `store` where it lives (`vault`, `edge`, `server-env`
|
|
157
|
+
or `ci`): never its value. `feature` and `flag` link the key to the gate. A number with
|
|
158
|
+
`integer: true` takes whole numbers only (in every layer, and in the database).
|
|
159
|
+
|
|
160
|
+
**The layers**, low to high. A later layer wins unless an earlier one locked the value
|
|
161
|
+
(`{ value, locked: true }`):
|
|
162
|
+
|
|
163
|
+
1. **default**: the declared default (for a per-preset one, `max`'s);
|
|
164
|
+
2. **preset**: `max` (Genesis's default: everything on), `standard` or `min`, chosen in
|
|
165
|
+
genesis.config.json (`"preset"`) but resolved as its own layer;
|
|
166
|
+
3. **file**: genesis.config.json `settings` (`settingsLayerFromFile`), the only layer that sets a
|
|
167
|
+
build-time key;
|
|
168
|
+
4. **database**: the app's `genesis_settings` table (genesis-supabase's `settings` block);
|
|
169
|
+
5. **tenant**: only keys declared `scope: "tenant"`;
|
|
170
|
+
6. **person**: only keys declared `scope: "person"`.
|
|
171
|
+
|
|
172
|
+
Which layers may set each scope is one table, `SCOPE_LAYERS`. A lock always holds: a locked entry
|
|
173
|
+
whose own value is bad keeps the value from below and still locks it. `null` ("not set") is a value
|
|
174
|
+
only for a key whose default is `null`.
|
|
175
|
+
|
|
176
|
+
`resolveSettings` never throws: it skips a bad entry and reports it in `problems` (an unknown
|
|
177
|
+
key, a value of the wrong type or out of bounds, a tenant or person value for a key without that
|
|
178
|
+
scope, a runtime layer setting a build-time key, a change to a locked value, a key on while one it
|
|
179
|
+
requires is off, an unknown preset, which resolves on `max`). Every map it returns has no prototype,
|
|
180
|
+
so a key such as `__proto__` or `constructor` is just an unknown key. `sources` says which layer set each value and which locked it.
|
|
181
|
+
|
|
182
|
+
**Reading a result.** `values`, `sources` and the maps `settingsGateContext` returns have no
|
|
183
|
+
prototype, so they have no `hasOwnProperty` (or `toString`) of their own: `values.hasOwnProperty(k)`
|
|
184
|
+
throws. Read a key directly (`values["support.messenger"]`), test it with `k in values` or
|
|
185
|
+
`Object.prototype.hasOwnProperty.call(values, k)`, and copy one with `{ ...values }` if you need an
|
|
186
|
+
ordinary object.
|
|
187
|
+
|
|
188
|
+
**The gate.** A boolean key linked with `feature` that resolves to `false` puts the feature in
|
|
189
|
+
`GateContext.settingsOff` (`featureOn` answers `reason: "setting"`), and a key linked with `flag`
|
|
190
|
+
gives the flag its value when the context has none (`withSettings`, `settingsGateContext`). A key the
|
|
191
|
+
app locked (genesis.config.json or the database, `APP_LOCK_LAYERS`) wins over the context: the
|
|
192
|
+
tenant's switch can't turn off a feature locked on, nor the context's flag change a locked flag. A
|
|
193
|
+
tenant or person lock only stops later settings layers; it never beats a platform flag, an
|
|
194
|
+
entitlement or (for a person) the tenant's switch. It is the same gate, with one more check.
|
|
195
|
+
|
|
196
|
+
**Two keys switching one feature.** Nothing stops two keys from naming the same `feature` (say a
|
|
197
|
+
package's `messenger` and `helpCenter` both linked to its help desk). Then either key resolving to
|
|
198
|
+
`false` switches the feature off: `off` is "any linked key is false", never "the last one wins". A
|
|
199
|
+
lock on either key keeps the tenant's switch from turning the feature off. Link one key per feature
|
|
200
|
+
unless "off when any of them is off" is what you mean.
|
|
201
|
+
|
|
202
|
+
**Packages without running them.** A package also lists its declaration in package.json
|
|
203
|
+
(`genesis.settings`: `{ "namespace": …, "keys": { … } }`, read with `settingsFromManifest`), so
|
|
204
|
+
`genesis doctor` checks an app's genesis.config.json against the installed packages
|
|
205
|
+
(`invalid-setting`, `setting-requires`, and `setup-incomplete` and `secret-missing` for keys with a
|
|
206
|
+
`setup` step or a secret they `needs`, checked by name only). `catalogueManifest` is the catalogue as the database checks values against it.
|
|
207
|
+
|
|
208
|
+
### The Settings screen
|
|
209
|
+
|
|
210
|
+
One screen, two hosts: the localhost wizard (`genesis setup`) and the app's own platform-admin
|
|
211
|
+
page. `<GenesisSettings>` (`@marktiderman/genesis-config/settings/react`, Beta) draws it, and talks to its
|
|
212
|
+
host only through a `SettingsClient` (`@marktiderman/genesis-config/settings-protocol`, Beta, free of zod
|
|
213
|
+
and React).
|
|
214
|
+
|
|
215
|
+
**Beta.** The screen ships before the maintainer's design review: its look, copy keys and props may
|
|
216
|
+
change in a minor release.
|
|
217
|
+
|
|
218
|
+
```tsx
|
|
219
|
+
import { APP_HOST_CAPABILITIES, createSettingsClient } from "@marktiderman/genesis-config/settings-protocol";
|
|
220
|
+
import { GenesisSettings } from "@marktiderman/genesis-config/settings/react";
|
|
221
|
+
|
|
222
|
+
declare const accessToken: () => string | null;
|
|
223
|
+
|
|
224
|
+
const client = createSettingsClient(fetch, { baseUrl: "/api/genesis/settings", token: accessToken });
|
|
225
|
+
|
|
226
|
+
export function PlatformSettings() {
|
|
227
|
+
return <GenesisSettings client={client} capabilities={APP_HOST_CAPABILITIES} />;
|
|
228
|
+
}
|
|
229
|
+
```
|
|
230
|
+
|
|
231
|
+
**Tabs.** Values (every key grouped by package, with its value, the layer it came from and its
|
|
232
|
+
lock), Health (the doctor's findings, each with its fix), Secrets (each secret's name, store and
|
|
233
|
+
whether it is set: never its value), Upgrades (installed and latest versions, release notes) and
|
|
234
|
+
Audit (the history of changes, a page at a time).
|
|
235
|
+
|
|
236
|
+
**What it may write.** The host reports its `capabilities` (`writeFiles`, `writeDatabase`,
|
|
237
|
+
`setSecrets`, `runCli`, `agent`, and optionally `proposeChanges`), and the `capabilities` prop can
|
|
238
|
+
only narrow them: a key the prop leaves out doesn't narrow, only `false` does
|
|
239
|
+
(`intersectCapabilities`). `settingWritability` holds the rules for the screen and a host's
|
|
240
|
+
handler alike: a build-time key is written only in the file layer; the file layer needs
|
|
241
|
+
`writeFiles`, the database layer `writeDatabase`; a key a lower layer locked can't be changed above
|
|
242
|
+
it.
|
|
243
|
+
|
|
244
|
+
- **The CLI host** writes the file layer by default (`preferredWriteLayer`), since it is reviewed
|
|
245
|
+
like code; the database is an explicit choice in the edit sheet, except for a value that already
|
|
246
|
+
comes from the database, which opens on the database. Writing a layer below the one
|
|
247
|
+
the value comes from shows that the higher layer overrides it.
|
|
248
|
+
- **The app host** (`APP_HOST_CAPABILITIES`) edits runtime keys in the database layer only. A
|
|
249
|
+
build-time key, or one the file layer locked (the lock lives in the file), shows "Change in repo"
|
|
250
|
+
with the genesis.config.json change to commit (`settingFileSnippet`), or a pull request when the
|
|
251
|
+
host can open one (`proposeChanges`).
|
|
252
|
+
- **Secrets** are set per store: `setSecrets` is `true` (every store) or `{ vault?, edge?,
|
|
253
|
+
"server-env"?, ci? }` (`canSetSecret`). The app host may set and rotate Vault secrets only, when
|
|
254
|
+
the host itself reports `{ vault: true }` (`APP_HOST_CAPABILITIES` is a mask that allows it but
|
|
255
|
+
doesn't grant it): the `setSecret` op is write-only, the value is never returned, and the screen
|
|
256
|
+
drops it once sent. Other stores are set through `genesis setup`. The host side comes with the
|
|
257
|
+
app's settings handler.
|
|
258
|
+
|
|
259
|
+
**Fixes.** An automatic fix is planned first (`plan`): the screen shows the files it writes (with
|
|
260
|
+
a diff), the commands it runs, the settings layers it writes and the secrets it needs, asks to
|
|
261
|
+
confirm, then applies it with the plan's `hash` (`apply(fixId, expect)`). A host refuses a plan
|
|
262
|
+
that changed in between (`stale_plan`), and the screen offers to plan again. A plan needing more
|
|
263
|
+
than the host can do shows its `genesis fix <id>` command instead. The app host applies a fix only
|
|
264
|
+
when it writes the database layer and nothing else (`databaseOnly` on the fix, `layers` on the
|
|
265
|
+
plan). A guided fix opens its setup step (`onOpenStep`, or `genesis setup --step <id>`); a manual
|
|
266
|
+
fix shows its instructions. Links (`href`, `notesUrl`) are followed only when `http:`, `https:` or
|
|
267
|
+
on the same site (`safeHref`).
|
|
268
|
+
|
|
269
|
+
**What a host must redact.** The screen never draws a secret's value: the Secrets tab shows names
|
|
270
|
+
and status only, and the audit history draws `before` and `after` only for a `set` or `clear` of a
|
|
271
|
+
catalogue key that needs no secret (`auditValuesVisible`). Free text is drawn as given, so a host
|
|
272
|
+
redacts secrets from it: a finding's `message`, a plan's `summary`, `why`, diffs and command
|
|
273
|
+
`args`, an apply's `message`, and an audit entry's `summary`.
|
|
274
|
+
|
|
275
|
+
**Audit.** The history is drawn as rows, a page at a time through the protocol's cursor, not as a
|
|
276
|
+
`ResourceView`: a ResourceView needs a `GenesisProvider` with a data provider and pages through
|
|
277
|
+
it, and this screen has neither (the wizard host has no app around it). It moves to a ResourceView
|
|
278
|
+
over a client-side source when ResourceView can take a cursor-paged source without a provider.
|
|
279
|
+
When `state` carries no `audit`, the tab fetches the first page itself.
|
|
280
|
+
|
|
281
|
+
**The protocol.** One endpoint, `POST`, JSON only, a bearer token and no cookies
|
|
282
|
+
(`credentials: "omit"`), every request `{ v, op, … }` (`SETTINGS_PROTOCOL_VERSION`). The ops are
|
|
283
|
+
`state`, `setValue`, `clearValue`, `plan`, `apply`, `upgrades`, `audit`, `propose` and `setSecret`
|
|
284
|
+
(`SETTINGS_OPS`, answers in `SettingsResponses`). A failure is `{ error: { code, message } }`,
|
|
285
|
+
thrown by the client as a `SettingsProtocolError` whose `code` is `bad_request`, `unauthenticated`,
|
|
286
|
+
`forbidden`, `unsupported`, `locked`, `stale_plan`, `not_found`, `version` or `error`. A host
|
|
287
|
+
answers an op it doesn't know (one a newer screen sends) with `unsupported`, so the screen can tell
|
|
288
|
+
"not here" from a bad request. The client
|
|
289
|
+
gives up after `timeoutMs` (default 30 seconds), refuses a response that isn't JSON, and refuses a
|
|
290
|
+
`state` without its lists or capabilities. Its own messages are in `messages`
|
|
291
|
+
(`SETTINGS_CLIENT_MESSAGES`).
|
|
292
|
+
|
|
293
|
+
Every word on the screen is in `copy` (defaults: `GENESIS_SETTINGS_COPY`), accessible names
|
|
294
|
+
included; a host's error messages are shown as the host wrote them. Every element a test or an
|
|
295
|
+
agent drives has a `data-testid` under the `testID` prefix (default `genesis-settings`). Pass
|
|
296
|
+
`header={false}` when the host page owns the title (under `AppShellPageHeader`).
|
|
297
|
+
|
|
298
|
+
## The gate
|
|
299
|
+
|
|
300
|
+
`featureOn(registry, context, id)` answers "is this feature on here?" the same way everywhere. Checks
|
|
301
|
+
run in a fixed order and the first "no" wins: **status** (beta, live or deprecated), **platform**, **setting**
|
|
302
|
+
(a setting switched it off, through `withSettings`), **tenant** (switched off), **flag** (each boolean release flag must be exactly `true`) and last **entitlement** (for
|
|
303
|
+
`access: { plan }`), so an upgrade prompt only appears when paying is the one thing missing. The answer
|
|
304
|
+
carries the reason, and for a paid feature the plan that unlocks it.
|
|
305
|
+
|
|
306
|
+
```ts
|
|
307
|
+
import { featureOn, gateSnapshot, isSnapshotStale, requireFeature } from "@marktiderman/genesis-config/gate";
|
|
308
|
+
|
|
309
|
+
const context = { platform: "web", entitlements: ["form-webhook-delivery"], off: ["library"], flags: { "sms.release": true } };
|
|
310
|
+
featureOn({ features, flags }, context, "library"); // { on: false, reason: "tenant" }
|
|
311
|
+
|
|
312
|
+
// Server functions refuse whatever the reason: FeatureOff has status 402 (entitlement) or 403.
|
|
313
|
+
requireFeature({ features, flags }, context, "form-webhook-delivery");
|
|
314
|
+
|
|
315
|
+
// The server hands the client every shipped feature's answer: plain JSON with `at` (and `version`).
|
|
316
|
+
const snapshot = gateSnapshot({ features, flags }, context, { version: buildVersion });
|
|
317
|
+
// A client keeps it, and replaces it when stale, after sign-in or a tenant switch, or after a refusal.
|
|
318
|
+
if (isSnapshotStale(snapshot, 5 * 60_000)) refresh();
|
|
319
|
+
```
|
|
320
|
+
|
|
321
|
+
`/gate` has no zod, React, Node built-ins or DOM globals, so it ships to browsers, extension service workers,
|
|
322
|
+
phones and edge functions. Context id sets are lists, Sets or functions (not iterators or strings). In React (web and React
|
|
323
|
+
Native), `/gate/react` reads the server's snapshot:
|
|
324
|
+
|
|
325
|
+
```tsx
|
|
326
|
+
import { FeatureGate, FeatureGateProvider, useFeature } from "@marktiderman/genesis-config/gate/react";
|
|
327
|
+
|
|
328
|
+
<FeatureGateProvider snapshot={snapshot}>
|
|
329
|
+
<FeatureGate feature="form-webhook-delivery" upsell={({ unlock }) => <Upgrade plan={unlock.plan} />}>
|
|
330
|
+
<WebhookSettings />
|
|
331
|
+
</FeatureGate>
|
|
332
|
+
</FeatureGateProvider>;
|
|
333
|
+
```
|
|
334
|
+
|
|
335
|
+
A feature that `requires` other features in the registry (a module's parts) is off while any of them is off,
|
|
336
|
+
with `via` naming the one that said no, so switching a module off or not paying for it turns its parts off
|
|
337
|
+
too. Ids outside the registry don't gate.
|
|
338
|
+
|
|
339
|
+
The gate doesn't check roles: "may this person" stays with roles and row security. Why it works this
|
|
340
|
+
way: [ADR 0001](../../docs/adr/0001-one-feature-gate.md).
|
|
341
|
+
|
|
342
|
+
## Blocks
|
|
343
|
+
|
|
344
|
+
A block is a feature an app adds whole: account, push, observability, support, updates. It is
|
|
345
|
+
declared once, by its FeatureId, with what it needs and what it contributes. The app shell, the
|
|
346
|
+
navigation tree and Settings read the contributions by FeatureId; the app still decides where they
|
|
347
|
+
go. `@marktiderman/genesis-config/blocks` has no zod in it, so it ships to phones (the root
|
|
348
|
+
re-exports it).
|
|
349
|
+
|
|
350
|
+
```ts
|
|
351
|
+
import { defineBlock, resolveBlocks } from "@marktiderman/genesis-config/blocks";
|
|
352
|
+
import type { FeatureId } from "./features";
|
|
353
|
+
|
|
354
|
+
export const supportBlock = defineBlock<FeatureId>({
|
|
355
|
+
id: "support",
|
|
356
|
+
requires: ["account"], // other blocks, or app features that aren't blocks
|
|
357
|
+
platforms: ["web", "native"], // default: everywhere
|
|
358
|
+
contributes: {
|
|
359
|
+
nav: [{ id: "help", label: "Help", path: "/help" }],
|
|
360
|
+
settings: [{ id: "contact-support", section: "about", title: "Contact support", href: "/support" }],
|
|
361
|
+
routes: [{ path: "/support", signedIn: true }],
|
|
362
|
+
slots: { fatal: SupportFatalScreen }, // fills the host shell's slots; the app's own slots win
|
|
363
|
+
migrations: [{ package: "@acme/support", file: "migrations/0001_support.sql" }],
|
|
364
|
+
skills: [".claude/skills/support/SKILL.md"],
|
|
365
|
+
privacy: { collects: [{ type: "email address", purposes: ["app functionality"], linked: true, tracking: false }] },
|
|
366
|
+
},
|
|
367
|
+
});
|
|
368
|
+
|
|
369
|
+
const blocks = resolveBlocks([accountBlock, supportBlock], enabledIds, { platform: "native", features });
|
|
370
|
+
blocks.nav; // [{ feature: "support", id: "help", … }]: place them in your nav tree
|
|
371
|
+
blocks.settings; // by `order`, then dependency order
|
|
372
|
+
blocks.dropped; // with { missing: "drop" }: what was left out and why
|
|
373
|
+
```
|
|
374
|
+
|
|
375
|
+
`defineBlock` validates one block and freezes it. `resolveBlocks(blocks, enabled?, options?)`
|
|
376
|
+
takes the blocks that exist, the ids that are on (a list, a predicate, or every block when left
|
|
377
|
+
out) and returns the enabled ones in dependency order with their contributions merged, each tagged
|
|
378
|
+
with its `feature`. It throws a `BlockError` listing every problem at once:
|
|
379
|
+
|
|
380
|
+
- a bad id, a block requiring itself, an unknown contribution key, a duplicate id;
|
|
381
|
+
- a cycle through `requires` (the registry's own check, from `graph.ts`);
|
|
382
|
+
- with `features` (the registry), a block id or requirement that isn't a feature;
|
|
383
|
+
- an enabled block whose requirement is off, or doesn't run on `platform`. With `missing: "drop"` the
|
|
384
|
+
block (and everything needing it) is left out instead and listed in `dropped`: for switches that
|
|
385
|
+
change at run time, such as a tenant turning a feature off;
|
|
386
|
+
- two enabled blocks contributing the same nav entry, Settings row, route or slot, or (with `slots`)
|
|
387
|
+
a fill for a slot the host doesn't have.
|
|
388
|
+
|
|
389
|
+
A requirement that isn't one of the blocks is a feature the app owns: it is met only when
|
|
390
|
+
`enabled` lists it, so a block that was never passed is an error, not a silent pass. With `slots`
|
|
391
|
+
(the host's slot names), a fill for any other slot is an error too.
|
|
392
|
+
|
|
393
|
+
Blocks shipped so far: `createUpdates(…)` (`app-updates`, in `@marktiderman/genesis-native/updates`),
|
|
394
|
+
`accountBlock` and `tenantFeaturesBlock` (in `@marktiderman/genesis-supabase`).
|
|
395
|
+
`<GenesisNativeApp blocks={…}>` runs them; see that package's README.
|
|
396
|
+
|
|
397
|
+
## Content packs
|
|
398
|
+
|
|
399
|
+
A content pack is versioned data that fills installed blocks: whatever those blocks hold (meeting types,
|
|
400
|
+
templates, checklists, forms) plus labels. Packs are code: the publishing package exports them, and an
|
|
401
|
+
installer copies them into a tenant's editable rows, keeping each row's source (pack, version, key) so an
|
|
402
|
+
update can tell what someone changed.
|
|
403
|
+
|
|
404
|
+
A pack's `sections` are keyed by the block that owns them. Genesis checks what every pack shares; what an
|
|
405
|
+
item holds is the block's business, checked by the validator it registers as `contributes.contentSection`:
|
|
406
|
+
|
|
407
|
+
```ts
|
|
408
|
+
import { contentPackProblems, defineBlock, defineContentPack } from "@marktiderman/genesis-config/blocks";
|
|
409
|
+
|
|
410
|
+
export const meetingsBlock = defineBlock({
|
|
411
|
+
id: "meetings",
|
|
412
|
+
contributes: {
|
|
413
|
+
// Returns every problem with this block's items in a pack.
|
|
414
|
+
contentSection: (items) =>
|
|
415
|
+
(items as { key: string; minutes?: number }[]).filter((m) => !((m.minutes ?? 0) > 0)).map((m) => `${m.key}: minutes must be more than 0`),
|
|
416
|
+
},
|
|
417
|
+
});
|
|
418
|
+
|
|
419
|
+
export const weeklyTeamRhythm = defineContentPack(
|
|
420
|
+
{
|
|
421
|
+
id: "weekly-team-rhythm",
|
|
422
|
+
name: "Weekly team rhythm",
|
|
423
|
+
version: "1.0.0",
|
|
424
|
+
publisher: "@acme/content",
|
|
425
|
+
requires: ["meetings"],
|
|
426
|
+
labels: { "project.phase": "Stage" },
|
|
427
|
+
sections: { meetings: [{ key: "weekly", name: "Weekly meeting", minutes: 60 }] },
|
|
428
|
+
},
|
|
429
|
+
{ blocks: [meetingsBlock] },
|
|
430
|
+
);
|
|
431
|
+
|
|
432
|
+
contentPackProblems(weeklyTeamRhythm, { installed: installedBlockIds, blocks: [meetingsBlock] }); // [] when it can be installed
|
|
433
|
+
```
|
|
434
|
+
|
|
435
|
+
`defineContentPack` lists every problem at once: ids, semver versions, publisher, label keys, item keys
|
|
436
|
+
(unique per section, stable across versions), every block validator's problems, and any section whose
|
|
437
|
+
block `requires` doesn't list. `contentPackProblems(pack, installedBlockIds)` still takes the installed
|
|
438
|
+
blocks alone; `{ validators: { meetings: fn } }` gives validators by block id instead of blocks.
|
|
439
|
+
|
|
440
|
+
The typed sections packs had before (`sessionTypes`, `metricTemplates`, `fieldDefinitions`, `forms`,
|
|
441
|
+
`roadmapTemplates`) still work and are checked as before, but are deprecated: put that data in `sections`
|
|
442
|
+
under the block that owns it.
|
|
443
|
+
|
|
444
|
+
## The page
|
|
445
|
+
|
|
446
|
+
```tsx
|
|
447
|
+
import { FeatureList } from "@marktiderman/genesis-config/react";
|
|
448
|
+
|
|
449
|
+
<FeatureList features={features} flags={flags} pathHref={(p) => `https://github.com/acme/app/blob/main/${p}`} />
|
|
450
|
+
<FeatureList features={features} variant="marketing" title="What it does" />
|
|
451
|
+
```
|
|
452
|
+
|
|
453
|
+
The default view is a genesis-ui `ResourcePage` over static data:
|
|
454
|
+
|
|
455
|
+
- A table, and in its grid view a board grouped by status (`KanbanBoard`).
|
|
456
|
+
- Status chips (`StatusBadge`), plus filters by app, audience and visibility.
|
|
457
|
+
- A detail panel with links, acceptance and flags.
|
|
458
|
+
- Planned work stays off the list and shows on the roadmap (Now, Next, Later) below it.
|
|
459
|
+
|
|
460
|
+
`variant="marketing"` shows public, shipped features that have a tagline, as cards: highlights first, then grouped by category.
|
|
461
|
+
|
|
462
|
+
genesis-ui (3.0.0 or later), React and lucide-react are optional peers, needed only by `/react` and `/settings/react`. Gate the route yourself; the component shows whatever it is given.
|