@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
|
@@ -0,0 +1,515 @@
|
|
|
1
|
+
import { SecretStore, SettingsPreset, SettingsLayer, SettingDef, ResolvedSettings, SettingsLayerValues } from './settings.js';
|
|
2
|
+
import './gate-CNTkn-Fv.js';
|
|
3
|
+
import './types-D4hs16bJ.js';
|
|
4
|
+
import './platforms-NR0liM8L.js';
|
|
5
|
+
|
|
6
|
+
/**
|
|
7
|
+
* `@marktiderman/genesis-config/settings-protocol`: the wire between the Settings screen and the
|
|
8
|
+
* host that serves it. One UI, two hosts (config-layer §4):
|
|
9
|
+
*
|
|
10
|
+
* - the **CLI host** (`genesis setup`, the localhost wizard) reads and writes the files, and the
|
|
11
|
+
* database through the developer's linked project;
|
|
12
|
+
* - the **app host** (the platform-admin Settings screen) writes the database layer only.
|
|
13
|
+
*
|
|
14
|
+
* One endpoint, `POST`, JSON in and out, a bearer token in a header (never a cookie), every request
|
|
15
|
+
* `{ v, op, … }`. What a host can do is its {@link SettingsCapabilities}; the screen hides or
|
|
16
|
+
* disables every write the host can't do, and the host refuses it anyway.
|
|
17
|
+
*
|
|
18
|
+
* Secrets travel by name and status only: no type here has a field for a secret's value.
|
|
19
|
+
*
|
|
20
|
+
* No zod, React, Node built-ins or DOM globals beyond `fetch`'s types: it ships to browsers, the
|
|
21
|
+
* CLI and edge functions alike.
|
|
22
|
+
*
|
|
23
|
+
* @stability Beta
|
|
24
|
+
*/
|
|
25
|
+
|
|
26
|
+
/** Bumped on any incompatible change; a host rejects other versions with `version`. @stability Beta */
|
|
27
|
+
declare const SETTINGS_PROTOCOL_VERSION = 1;
|
|
28
|
+
/**
|
|
29
|
+
* What the host serving the screen can do. The screen shows a write only when its capability is
|
|
30
|
+
* true; the host checks again.
|
|
31
|
+
*
|
|
32
|
+
* - `writeFiles`: genesis.config.json and the app's files (the CLI host).
|
|
33
|
+
* - `writeDatabase`: the `genesis_settings` table (both hosts).
|
|
34
|
+
* - `setSecrets`: put a secret in its store, per store (`{ vault: true }`), or `true` for every
|
|
35
|
+
* store. The CLI host sets them through the developer's own CLIs; the app host may set and
|
|
36
|
+
* rotate Vault secrets only (`setSecret`, write-only), when it says so.
|
|
37
|
+
* - `runCli`: run `supabase`, `gh`, `eas` and the package manager (the CLI host).
|
|
38
|
+
* - `agent`: "Fix with Claude" (the CLI host, when the Agent SDK is installed).
|
|
39
|
+
* - `proposeChanges`: open a pull request for a file-layer change (`propose`). Optional; off when absent.
|
|
40
|
+
*
|
|
41
|
+
* @stability Beta
|
|
42
|
+
*/
|
|
43
|
+
interface SettingsCapabilities {
|
|
44
|
+
writeFiles: boolean;
|
|
45
|
+
writeDatabase: boolean;
|
|
46
|
+
setSecrets: boolean | SecretStoreCapabilities;
|
|
47
|
+
runCli: boolean;
|
|
48
|
+
agent: boolean;
|
|
49
|
+
proposeChanges?: boolean;
|
|
50
|
+
}
|
|
51
|
+
/** Which secret stores a host can write. A store left out can't be written. @stability Beta */
|
|
52
|
+
type SecretStoreCapabilities = {
|
|
53
|
+
readonly [S in SecretStore]?: boolean;
|
|
54
|
+
};
|
|
55
|
+
/** Whether the host can write a secret in this store. @stability Beta */
|
|
56
|
+
declare function canSetSecret(capabilities: Pick<SettingsCapabilities, "setSecrets">, store: SecretStore): boolean;
|
|
57
|
+
/** Nothing: a read-only screen. @stability Beta */
|
|
58
|
+
declare const NO_SETTINGS_CAPABILITIES: Readonly<SettingsCapabilities>;
|
|
59
|
+
/**
|
|
60
|
+
* The most the app host may do: the database layer, and Vault secrets when the host reports it can.
|
|
61
|
+
* Pass it as the screen's `capabilities` prop: it is a mask, so Vault is offered only when the host
|
|
62
|
+
* itself says `setSecrets: { vault: true }`.
|
|
63
|
+
*
|
|
64
|
+
* @stability Beta
|
|
65
|
+
*/
|
|
66
|
+
declare const APP_HOST_CAPABILITIES: Readonly<SettingsCapabilities>;
|
|
67
|
+
/**
|
|
68
|
+
* Both sets at once: a write is allowed only when both allow it. The screen narrows the host's
|
|
69
|
+
* capabilities with its own `capabilities` prop this way; a prop can never widen what the host
|
|
70
|
+
* reports. A key the prop leaves out doesn't narrow; only `false` does.
|
|
71
|
+
*
|
|
72
|
+
* @stability Beta
|
|
73
|
+
*/
|
|
74
|
+
declare function intersectCapabilities(a: SettingsCapabilities, b?: Partial<SettingsCapabilities>): SettingsCapabilities;
|
|
75
|
+
/** Which host is serving: the localhost wizard or the app's own screen. @stability Beta */
|
|
76
|
+
type SettingsHost = "cli" | "app";
|
|
77
|
+
/** What the screen shows about the app. @stability Beta */
|
|
78
|
+
interface SettingsAppFacts {
|
|
79
|
+
name: string;
|
|
80
|
+
slug?: string;
|
|
81
|
+
host: SettingsHost;
|
|
82
|
+
preset: SettingsPreset;
|
|
83
|
+
/** The installed `@marktiderman/genesis-*` release, when known. */
|
|
84
|
+
genesisVersion?: string;
|
|
85
|
+
platforms?: readonly ("web" | "ios" | "android")[];
|
|
86
|
+
}
|
|
87
|
+
/**
|
|
88
|
+
* How a finding is fixed. `auto`: planned and applied by Genesis. `guided`: a setup step the
|
|
89
|
+
* person walks through. `manual`: instructions only.
|
|
90
|
+
*
|
|
91
|
+
* @stability Beta
|
|
92
|
+
*/
|
|
93
|
+
type SettingsFixKind = "auto" | "guided" | "manual";
|
|
94
|
+
/** A finding's fix, by reference (the plan is made on request, never sent with the state). @stability Beta */
|
|
95
|
+
interface SettingsFixRef {
|
|
96
|
+
/** The fix id `plan` and `apply` take, e.g. `upgrade.release`, or `manual:<rule>`. */
|
|
97
|
+
id: string;
|
|
98
|
+
kind: SettingsFixKind;
|
|
99
|
+
title?: string;
|
|
100
|
+
/** A guided fix's setup step id (`genesis setup --step <id>`). */
|
|
101
|
+
step?: string;
|
|
102
|
+
/** Where a guided step opens, when the host has a page for it. */
|
|
103
|
+
href?: string;
|
|
104
|
+
/** A manual fix's instructions (plain text, may hold several lines). */
|
|
105
|
+
instructions?: string;
|
|
106
|
+
/**
|
|
107
|
+
* An automatic fix that writes the database layer and nothing else (no files, no commands, no
|
|
108
|
+
* secrets): the app host can apply it with `writeDatabase`.
|
|
109
|
+
*/
|
|
110
|
+
databaseOnly?: boolean;
|
|
111
|
+
}
|
|
112
|
+
/** @stability Beta */
|
|
113
|
+
type SettingsFindingLevel = "error" | "warn" | "info";
|
|
114
|
+
/** One doctor finding. @stability Beta */
|
|
115
|
+
interface SettingsFinding {
|
|
116
|
+
/** Stable within one `state`: the screen keys rows and test ids on it. */
|
|
117
|
+
id: string;
|
|
118
|
+
rule: string;
|
|
119
|
+
level: SettingsFindingLevel;
|
|
120
|
+
message: string;
|
|
121
|
+
file?: string;
|
|
122
|
+
line?: number;
|
|
123
|
+
/** The setting key or package the finding is about. */
|
|
124
|
+
subject?: string;
|
|
125
|
+
fix?: SettingsFixRef;
|
|
126
|
+
}
|
|
127
|
+
/** @stability Beta */
|
|
128
|
+
type SecretState = "set" | "missing" | "unknown";
|
|
129
|
+
/** One secret the app needs, by name: never its value. @stability Beta */
|
|
130
|
+
interface SettingsSecretStatus {
|
|
131
|
+
name: string;
|
|
132
|
+
store: SecretStore;
|
|
133
|
+
status: SecretState;
|
|
134
|
+
/** ISO time it was last set, when the store says. */
|
|
135
|
+
lastRotated?: string;
|
|
136
|
+
/** The setting keys (or block functions) that need it. */
|
|
137
|
+
neededBy: readonly string[];
|
|
138
|
+
}
|
|
139
|
+
/** How far a package is behind its latest release. @stability Beta */
|
|
140
|
+
type UpgradeDistance = "current" | "patch" | "minor" | "major" | "unknown";
|
|
141
|
+
/** @stability Beta */
|
|
142
|
+
interface SettingsPackageUpgrade {
|
|
143
|
+
name: string;
|
|
144
|
+
current: string;
|
|
145
|
+
latest?: string;
|
|
146
|
+
distance: UpgradeDistance;
|
|
147
|
+
/** An advisory affects the installed version. */
|
|
148
|
+
advisory?: boolean;
|
|
149
|
+
/** The changelog lines that matter to this app. */
|
|
150
|
+
notes?: string;
|
|
151
|
+
notesUrl?: string;
|
|
152
|
+
}
|
|
153
|
+
/** @stability Beta */
|
|
154
|
+
interface SettingsUpgrades {
|
|
155
|
+
packages: readonly SettingsPackageUpgrade[];
|
|
156
|
+
/** ISO time of the registry check. */
|
|
157
|
+
checkedAt?: string;
|
|
158
|
+
/** The check used its cache: the network was off. */
|
|
159
|
+
offline?: boolean;
|
|
160
|
+
/** The upgrade fix (`upgrade.release`), when there is something to upgrade. */
|
|
161
|
+
fix?: SettingsFixRef;
|
|
162
|
+
}
|
|
163
|
+
/** @stability Beta */
|
|
164
|
+
type SettingsAuditAction = "set" | "clear" | "fix" | "upgrade" | "secret";
|
|
165
|
+
/** One change in the history. Secrets appear by name only. @stability Beta */
|
|
166
|
+
interface SettingsAuditEntry {
|
|
167
|
+
id: string;
|
|
168
|
+
/** ISO time. */
|
|
169
|
+
at: string;
|
|
170
|
+
/** Who made it: an email, a user id or `cli`. */
|
|
171
|
+
actor?: string;
|
|
172
|
+
action: SettingsAuditAction;
|
|
173
|
+
/** The setting key, fix id, package or secret name. */
|
|
174
|
+
subject: string;
|
|
175
|
+
layer?: SettingsLayer;
|
|
176
|
+
before?: unknown;
|
|
177
|
+
after?: unknown;
|
|
178
|
+
locked?: boolean;
|
|
179
|
+
summary?: string;
|
|
180
|
+
}
|
|
181
|
+
/** A page of the history, newest first. @stability Beta */
|
|
182
|
+
interface SettingsAuditPage {
|
|
183
|
+
entries: readonly SettingsAuditEntry[];
|
|
184
|
+
/** Pass to `audit` for the next page; absent on the last. */
|
|
185
|
+
next?: string;
|
|
186
|
+
}
|
|
187
|
+
/**
|
|
188
|
+
* What `state` returns: everything the screen draws.
|
|
189
|
+
*
|
|
190
|
+
* `layers` are the raw file and database layers (what each holds for a key, and whether it is
|
|
191
|
+
* locked there), so the screen can tell "set here" from "inherited", and offer to clear a layer's
|
|
192
|
+
* own value.
|
|
193
|
+
*
|
|
194
|
+
* @stability Beta
|
|
195
|
+
*/
|
|
196
|
+
interface SettingsState {
|
|
197
|
+
app: SettingsAppFacts;
|
|
198
|
+
/** The catalogue's keys (`SettingDef`, serialised). */
|
|
199
|
+
catalogue: readonly SettingDef[];
|
|
200
|
+
resolved: ResolvedSettings;
|
|
201
|
+
layers: {
|
|
202
|
+
file?: SettingsLayerValues;
|
|
203
|
+
database?: SettingsLayerValues;
|
|
204
|
+
};
|
|
205
|
+
findings: readonly SettingsFinding[];
|
|
206
|
+
secrets: readonly SettingsSecretStatus[];
|
|
207
|
+
capabilities: SettingsCapabilities;
|
|
208
|
+
upgrades?: SettingsUpgrades;
|
|
209
|
+
audit?: SettingsAuditPage;
|
|
210
|
+
}
|
|
211
|
+
/** A file a fix writes. `diff` is unified, for the screen; the host keeps the content. @stability Beta */
|
|
212
|
+
interface SettingsPlanFile {
|
|
213
|
+
path: string;
|
|
214
|
+
why: string;
|
|
215
|
+
diff?: string;
|
|
216
|
+
/** The file is new. */
|
|
217
|
+
created?: boolean;
|
|
218
|
+
}
|
|
219
|
+
/** A command a fix runs. Secrets reach a command on stdin, never in `args`. @stability Beta */
|
|
220
|
+
interface SettingsPlanCommand {
|
|
221
|
+
tool: string;
|
|
222
|
+
args: readonly string[];
|
|
223
|
+
why: string;
|
|
224
|
+
}
|
|
225
|
+
/**
|
|
226
|
+
* A fix's plan, as the screen shows it before anything is written. `hash` goes back to `apply` as
|
|
227
|
+
* `expect`: the host re-plans and refuses (`stale_plan`) when anything changed in between.
|
|
228
|
+
*
|
|
229
|
+
* @stability Beta
|
|
230
|
+
*/
|
|
231
|
+
interface SettingsPlan {
|
|
232
|
+
fixId: string;
|
|
233
|
+
summary: string;
|
|
234
|
+
hash: string;
|
|
235
|
+
files: readonly SettingsPlanFile[];
|
|
236
|
+
commands: readonly SettingsPlanCommand[];
|
|
237
|
+
/** The secrets it needs, by name. */
|
|
238
|
+
secrets: readonly string[];
|
|
239
|
+
/** The settings layers it writes (a fix that only seeds `genesis_settings` writes `database`). */
|
|
240
|
+
layers?: readonly SettingsWriteLayer[];
|
|
241
|
+
/** Steps the person does by hand after it. */
|
|
242
|
+
manual?: string;
|
|
243
|
+
}
|
|
244
|
+
/** What `apply` returns. @stability Beta */
|
|
245
|
+
interface SettingsApplyResult {
|
|
246
|
+
fixId: string;
|
|
247
|
+
/** The fix's own check passed after it ran. */
|
|
248
|
+
verified: boolean;
|
|
249
|
+
message?: string;
|
|
250
|
+
/** A pull request it opened (the upgrade fix). */
|
|
251
|
+
pullRequestUrl?: string;
|
|
252
|
+
}
|
|
253
|
+
/** What `propose` returns: a pull request, or the change to make by hand. @stability Beta */
|
|
254
|
+
interface SettingsProposal {
|
|
255
|
+
pullRequestUrl?: string;
|
|
256
|
+
/** The genesis.config.json fragment to commit. */
|
|
257
|
+
snippet: string;
|
|
258
|
+
}
|
|
259
|
+
/** The layers a person can write from the screen. @stability Beta */
|
|
260
|
+
type SettingsWriteLayer = "file" | "database";
|
|
261
|
+
/**
|
|
262
|
+
* Every request. `audit` takes a cursor from the last page; `upgrades` with `refresh` skips the
|
|
263
|
+
* host's cache.
|
|
264
|
+
*
|
|
265
|
+
* @stability Beta
|
|
266
|
+
*/
|
|
267
|
+
type SettingsRequest = {
|
|
268
|
+
op: "state";
|
|
269
|
+
audit?: {
|
|
270
|
+
limit?: number;
|
|
271
|
+
};
|
|
272
|
+
} | {
|
|
273
|
+
op: "setValue";
|
|
274
|
+
key: string;
|
|
275
|
+
value: unknown;
|
|
276
|
+
locked?: boolean;
|
|
277
|
+
layer: SettingsWriteLayer;
|
|
278
|
+
} | {
|
|
279
|
+
op: "clearValue";
|
|
280
|
+
key: string;
|
|
281
|
+
layer: SettingsWriteLayer;
|
|
282
|
+
} | {
|
|
283
|
+
op: "plan";
|
|
284
|
+
fixId: string;
|
|
285
|
+
} | {
|
|
286
|
+
op: "apply";
|
|
287
|
+
fixId: string;
|
|
288
|
+
expect: string;
|
|
289
|
+
} | {
|
|
290
|
+
op: "upgrades";
|
|
291
|
+
refresh?: boolean;
|
|
292
|
+
} | {
|
|
293
|
+
op: "audit";
|
|
294
|
+
cursor?: string;
|
|
295
|
+
limit?: number;
|
|
296
|
+
} | {
|
|
297
|
+
op: "propose";
|
|
298
|
+
key: string;
|
|
299
|
+
value: unknown;
|
|
300
|
+
locked?: boolean;
|
|
301
|
+
} | {
|
|
302
|
+
op: "setSecret";
|
|
303
|
+
name: string;
|
|
304
|
+
store: "vault";
|
|
305
|
+
value: string;
|
|
306
|
+
};
|
|
307
|
+
/** A request on the wire. @stability Beta */
|
|
308
|
+
type SettingsWireRequest = SettingsRequest & {
|
|
309
|
+
v: number;
|
|
310
|
+
};
|
|
311
|
+
/** The ops, for a host's router. @stability Beta */
|
|
312
|
+
declare const SETTINGS_OPS: readonly ["state", "setValue", "clearValue", "plan", "apply", "upgrades", "audit", "propose", "setSecret"];
|
|
313
|
+
/** @stability Beta */
|
|
314
|
+
type SettingsOp = (typeof SETTINGS_OPS)[number];
|
|
315
|
+
/** What each op answers. @stability Beta */
|
|
316
|
+
interface SettingsResponses {
|
|
317
|
+
state: SettingsState;
|
|
318
|
+
setValue: {
|
|
319
|
+
ok: true;
|
|
320
|
+
};
|
|
321
|
+
clearValue: {
|
|
322
|
+
ok: true;
|
|
323
|
+
};
|
|
324
|
+
plan: {
|
|
325
|
+
plan: SettingsPlan;
|
|
326
|
+
};
|
|
327
|
+
apply: {
|
|
328
|
+
result: SettingsApplyResult;
|
|
329
|
+
};
|
|
330
|
+
upgrades: SettingsUpgrades;
|
|
331
|
+
audit: SettingsAuditPage;
|
|
332
|
+
propose: SettingsProposal;
|
|
333
|
+
setSecret: {
|
|
334
|
+
ok: true;
|
|
335
|
+
};
|
|
336
|
+
}
|
|
337
|
+
/**
|
|
338
|
+
* Why a request failed.
|
|
339
|
+
*
|
|
340
|
+
* - `bad_request`: the body or a value is wrong (`details` may name the key).
|
|
341
|
+
* - `unauthenticated` / `forbidden`: no token, or not a platform admin.
|
|
342
|
+
* - `unsupported`: the host can't do it (a capability it doesn't have), or doesn't know the op: a
|
|
343
|
+
* host answers an op it doesn't know (one a newer screen sends) with `unsupported`, never `bad_request`.
|
|
344
|
+
* - `locked`: a lower layer locked the key.
|
|
345
|
+
* - `stale_plan`: `apply`'s `expect` no longer matches a fresh plan; plan again.
|
|
346
|
+
* - `not_found`: no such key or fix.
|
|
347
|
+
* - `version`: a protocol version the host doesn't speak.
|
|
348
|
+
* - `error`: anything else.
|
|
349
|
+
*
|
|
350
|
+
* @stability Beta
|
|
351
|
+
*/
|
|
352
|
+
type SettingsErrorCode = "bad_request" | "unauthenticated" | "forbidden" | "unsupported" | "locked" | "stale_plan" | "not_found" | "version" | "error";
|
|
353
|
+
/** The body of a failed response. @stability Beta */
|
|
354
|
+
interface SettingsErrorResponse {
|
|
355
|
+
error: {
|
|
356
|
+
code: SettingsErrorCode;
|
|
357
|
+
message: string;
|
|
358
|
+
details?: {
|
|
359
|
+
[key: string]: unknown;
|
|
360
|
+
};
|
|
361
|
+
};
|
|
362
|
+
}
|
|
363
|
+
/** A failed request, as the client throws it. @stability Beta */
|
|
364
|
+
declare class SettingsProtocolError extends Error {
|
|
365
|
+
readonly code: SettingsErrorCode;
|
|
366
|
+
readonly status: number;
|
|
367
|
+
readonly details?: {
|
|
368
|
+
[key: string]: unknown;
|
|
369
|
+
};
|
|
370
|
+
constructor(code: SettingsErrorCode, message: string, status?: number, details?: {
|
|
371
|
+
[key: string]: unknown;
|
|
372
|
+
});
|
|
373
|
+
}
|
|
374
|
+
/** The Settings screen's view of its host. A fake one is a plain object. @stability Beta */
|
|
375
|
+
interface SettingsClient {
|
|
376
|
+
state(params?: {
|
|
377
|
+
auditLimit?: number;
|
|
378
|
+
}): Promise<SettingsState>;
|
|
379
|
+
setValue(params: {
|
|
380
|
+
key: string;
|
|
381
|
+
value: unknown;
|
|
382
|
+
locked?: boolean;
|
|
383
|
+
layer: SettingsWriteLayer;
|
|
384
|
+
}): Promise<void>;
|
|
385
|
+
clearValue(params: {
|
|
386
|
+
key: string;
|
|
387
|
+
layer: SettingsWriteLayer;
|
|
388
|
+
}): Promise<void>;
|
|
389
|
+
plan(fixId: string): Promise<SettingsPlan>;
|
|
390
|
+
apply(fixId: string, expect: string): Promise<SettingsApplyResult>;
|
|
391
|
+
upgrades(params?: {
|
|
392
|
+
refresh?: boolean;
|
|
393
|
+
}): Promise<SettingsUpgrades>;
|
|
394
|
+
audit(params?: {
|
|
395
|
+
cursor?: string;
|
|
396
|
+
limit?: number;
|
|
397
|
+
}): Promise<SettingsAuditPage>;
|
|
398
|
+
propose(params: {
|
|
399
|
+
key: string;
|
|
400
|
+
value: unknown;
|
|
401
|
+
locked?: boolean;
|
|
402
|
+
}): Promise<SettingsProposal>;
|
|
403
|
+
/**
|
|
404
|
+
* Set or rotate a Vault secret. Write-only: the host stores it and never returns it, and the
|
|
405
|
+
* screen forgets it once sent. Optional: a host without it can't set secrets from the screen.
|
|
406
|
+
*/
|
|
407
|
+
setSecret?(params: {
|
|
408
|
+
name: string;
|
|
409
|
+
store: "vault";
|
|
410
|
+
value: string;
|
|
411
|
+
}): Promise<void>;
|
|
412
|
+
}
|
|
413
|
+
/** The client's own error messages, for a translation. @stability Beta */
|
|
414
|
+
interface SettingsClientMessages {
|
|
415
|
+
signIn: string;
|
|
416
|
+
unreachable: (detail: string) => string;
|
|
417
|
+
timedOut: (seconds: number) => string;
|
|
418
|
+
notJson: (status: number) => string;
|
|
419
|
+
badJson: (status: number) => string;
|
|
420
|
+
notObject: string;
|
|
421
|
+
status: (status: number) => string;
|
|
422
|
+
badState: (what: string) => string;
|
|
423
|
+
}
|
|
424
|
+
/** @stability Beta */
|
|
425
|
+
declare const SETTINGS_CLIENT_MESSAGES: SettingsClientMessages;
|
|
426
|
+
/** @stability Beta */
|
|
427
|
+
interface SettingsClientOptions {
|
|
428
|
+
/** The endpoint the host serves, e.g. `/api/genesis/settings` or the wizard's `http://127.0.0.1:4400/api`. */
|
|
429
|
+
baseUrl: string;
|
|
430
|
+
/** The bearer token, or a function that returns it (the wizard's session token, the admin's access token). */
|
|
431
|
+
token: string | (() => string | null | Promise<string | null>);
|
|
432
|
+
/** Give up on a request after this long. Default 30 000 ms. */
|
|
433
|
+
timeoutMs?: number;
|
|
434
|
+
/** The client's error messages. */
|
|
435
|
+
messages?: Partial<SettingsClientMessages>;
|
|
436
|
+
}
|
|
437
|
+
type FetchLike = (input: string, init: {
|
|
438
|
+
method: string;
|
|
439
|
+
headers: Record<string, string>;
|
|
440
|
+
body: string;
|
|
441
|
+
signal: AbortSignal;
|
|
442
|
+
credentials: "omit";
|
|
443
|
+
}) => Promise<Pick<Response, "ok" | "status" | "headers" | "text">>;
|
|
444
|
+
/**
|
|
445
|
+
* A {@link SettingsClient} over `fetch`. JSON only: a response that isn't JSON is an error, so a
|
|
446
|
+
* login page or a proxy's HTML never reaches the screen as data.
|
|
447
|
+
*
|
|
448
|
+
* ```ts
|
|
449
|
+
* const client = createSettingsClient(fetch, { baseUrl: "/api/genesis/settings", token: () => session.access_token });
|
|
450
|
+
* ```
|
|
451
|
+
*
|
|
452
|
+
* @stability Beta
|
|
453
|
+
*/
|
|
454
|
+
declare function createSettingsClient(fetchFn: FetchLike, options: SettingsClientOptions): SettingsClient;
|
|
455
|
+
/** Why a key can't be written in a layer from this screen. @stability Beta */
|
|
456
|
+
type SettingWriteRefusal = "build" | "capability" | "locked";
|
|
457
|
+
/** Where a key can be written from this screen, or why it can't. @stability Beta */
|
|
458
|
+
interface SettingWritability {
|
|
459
|
+
/** The layers the screen may write, low to high. Empty when it can write none. */
|
|
460
|
+
layers: SettingsWriteLayer[];
|
|
461
|
+
/** Why a layer is missing: the host can't write it, the key applies at build, or a lower layer locked it. */
|
|
462
|
+
refused: Partial<Record<SettingsWriteLayer, SettingWriteRefusal>>;
|
|
463
|
+
}
|
|
464
|
+
/**
|
|
465
|
+
* The write rules, in one place, for the screen and a host's handler alike:
|
|
466
|
+
*
|
|
467
|
+
* - a key that applies at build time is written only in the file layer;
|
|
468
|
+
* - the file layer needs `writeFiles`, the database layer `writeDatabase`;
|
|
469
|
+
* - a key locked by a layer below the target can't be changed there (the lock's own layer can).
|
|
470
|
+
*
|
|
471
|
+
* The app host (`writeDatabase` only) therefore writes runtime keys in the database layer and
|
|
472
|
+
* shows build keys read-only, with "change in repo".
|
|
473
|
+
*
|
|
474
|
+
* @stability Beta
|
|
475
|
+
*/
|
|
476
|
+
declare function settingWritability(def: Pick<SettingDef, "applies">, source: {
|
|
477
|
+
lockedBy?: SettingsLayer;
|
|
478
|
+
} | undefined, capabilities: SettingsCapabilities): SettingWritability;
|
|
479
|
+
/**
|
|
480
|
+
* The genesis.config.json fragment for one key: its value, or `{ value, locked: true }`. What
|
|
481
|
+
* "change in repo" shows, and what `propose` commits.
|
|
482
|
+
*
|
|
483
|
+
* @stability Beta
|
|
484
|
+
*/
|
|
485
|
+
declare function settingFileSnippet(key: string, value: unknown, locked?: boolean): string;
|
|
486
|
+
/**
|
|
487
|
+
* The layer the screen writes by default: the database when the value already comes from there
|
|
488
|
+
* (and the screen can write it), else the file layer when it can (reviewed like code), else the
|
|
489
|
+
* database. Otherwise, writing the database from the CLI host is an explicit choice.
|
|
490
|
+
*
|
|
491
|
+
* @stability Beta
|
|
492
|
+
*/
|
|
493
|
+
declare function preferredWriteLayer(writable: Pick<SettingWritability, "layers">, source?: {
|
|
494
|
+
layer: SettingsLayer;
|
|
495
|
+
}): SettingsWriteLayer | undefined;
|
|
496
|
+
/** Every secret name the app knows: the state's secrets and each catalogue key's `needs`. @stability Beta */
|
|
497
|
+
declare function secretNames(catalogue: readonly Pick<SettingDef, "secret">[], secrets: readonly Pick<SettingsSecretStatus, "name">[]): Set<string>;
|
|
498
|
+
/**
|
|
499
|
+
* Whether an audit entry's `before` and `after` may be drawn: only for a `set` or `clear` of a
|
|
500
|
+
* catalogue key that needs no secret and isn't itself a secret's name. Everything else (a fix, an
|
|
501
|
+
* upgrade, a secret, a subject the catalogue doesn't know) shows its subject and summary only, so
|
|
502
|
+
* a value a host forgot to redact never reaches the screen through the history.
|
|
503
|
+
*
|
|
504
|
+
* @stability Beta
|
|
505
|
+
*/
|
|
506
|
+
declare function auditValuesVisible(entry: Pick<SettingsAuditEntry, "action" | "subject">, catalogue: readonly Pick<SettingDef, "key" | "secret">[], names: ReadonlySet<string>): boolean;
|
|
507
|
+
/**
|
|
508
|
+
* A link the screen may follow: `http:`, `https:` or a path on the same site (`/…`, `./…`, `../…`,
|
|
509
|
+
* `#…`, `?…`), never `javascript:`, `data:` or a protocol-relative `//host`. Undefined otherwise.
|
|
510
|
+
*
|
|
511
|
+
* @stability Beta
|
|
512
|
+
*/
|
|
513
|
+
declare function safeHref(href: string | undefined): string | undefined;
|
|
514
|
+
|
|
515
|
+
export { APP_HOST_CAPABILITIES, NO_SETTINGS_CAPABILITIES, SETTINGS_CLIENT_MESSAGES, SETTINGS_OPS, SETTINGS_PROTOCOL_VERSION, type SecretState, type SecretStoreCapabilities, type SettingWritability, type SettingWriteRefusal, type SettingsAppFacts, type SettingsApplyResult, type SettingsAuditAction, type SettingsAuditEntry, type SettingsAuditPage, type SettingsCapabilities, type SettingsClient, type SettingsClientMessages, type SettingsClientOptions, type SettingsErrorCode, type SettingsErrorResponse, type SettingsFinding, type SettingsFindingLevel, type SettingsFixKind, type SettingsFixRef, type SettingsHost, type SettingsOp, type SettingsPackageUpgrade, type SettingsPlan, type SettingsPlanCommand, type SettingsPlanFile, type SettingsProposal, SettingsProtocolError, type SettingsRequest, type SettingsResponses, type SettingsSecretStatus, type SettingsState, type SettingsUpgrades, type SettingsWireRequest, type SettingsWriteLayer, type UpgradeDistance, auditValuesVisible, canSetSecret, createSettingsClient, intersectCapabilities, preferredWriteLayer, safeHref, secretNames, settingFileSnippet, settingWritability };
|
|
@@ -0,0 +1,4 @@
|
|
|
1
|
+
export { APP_HOST_CAPABILITIES, NO_SETTINGS_CAPABILITIES, SETTINGS_CLIENT_MESSAGES, SETTINGS_OPS, SETTINGS_PROTOCOL_VERSION, SettingsProtocolError, auditValuesVisible, canSetSecret, createSettingsClient, intersectCapabilities, preferredWriteLayer, safeHref, secretNames, settingFileSnippet, settingWritability } from './chunk-HIOKZIZP.js';
|
|
2
|
+
import './chunk-UD7SPYZH.js';
|
|
3
|
+
//# sourceMappingURL=settings-protocol.js.map
|
|
4
|
+
//# sourceMappingURL=settings-protocol.js.map
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
{"version":3,"sources":[],"names":[],"mappings":"","file":"settings-protocol.js"}
|
|
@@ -0,0 +1,143 @@
|
|
|
1
|
+
import * as react from 'react';
|
|
2
|
+
import { SettingsLayer } from './settings.js';
|
|
3
|
+
import { SettingsFindingLevel, SettingsSecretStatus, UpgradeDistance, SettingsAuditEntry, SettingsClient, SettingsCapabilities } from './settings-protocol.js';
|
|
4
|
+
import './gate-CNTkn-Fv.js';
|
|
5
|
+
import './types-D4hs16bJ.js';
|
|
6
|
+
import './platforms-NR0liM8L.js';
|
|
7
|
+
|
|
8
|
+
/** The screen's tabs. @stability Beta */
|
|
9
|
+
type GenesisSettingsTab = "values" | "health" | "secrets" | "upgrades" | "audit";
|
|
10
|
+
/**
|
|
11
|
+
* Every word the screen shows. Pass a partial `copy` to change any of them (a translation, the
|
|
12
|
+
* app's own voice).
|
|
13
|
+
*
|
|
14
|
+
* @stability Beta
|
|
15
|
+
*/
|
|
16
|
+
interface GenesisSettingsCopy {
|
|
17
|
+
title: string;
|
|
18
|
+
description: string;
|
|
19
|
+
refresh: string;
|
|
20
|
+
loading: string;
|
|
21
|
+
loadFailed: string;
|
|
22
|
+
retry: string;
|
|
23
|
+
tabs: Record<GenesisSettingsTab, string>;
|
|
24
|
+
layers: Record<SettingsLayer, string>;
|
|
25
|
+
filterLabel: string;
|
|
26
|
+
filterPlaceholder: string;
|
|
27
|
+
noMatches: string;
|
|
28
|
+
notSet: string;
|
|
29
|
+
on: string;
|
|
30
|
+
off: string;
|
|
31
|
+
lockedBy: (layer: string) => string;
|
|
32
|
+
buildOnly: string;
|
|
33
|
+
edit: string;
|
|
34
|
+
/** The Edit button's accessible name. */
|
|
35
|
+
editLabel: (key: string) => string;
|
|
36
|
+
editTitle: (key: string) => string;
|
|
37
|
+
/** Shown when the layer being written sits below the one the value comes from. */
|
|
38
|
+
overriddenBy: (layer: string) => string;
|
|
39
|
+
editDescription: string;
|
|
40
|
+
writeLayer: string;
|
|
41
|
+
lock: string;
|
|
42
|
+
lockHint: string;
|
|
43
|
+
save: string;
|
|
44
|
+
cancel: string;
|
|
45
|
+
clearLayer: (layer: string) => string;
|
|
46
|
+
invalidJson: string;
|
|
47
|
+
changeInRepo: string;
|
|
48
|
+
changeInRepoLabel: (key: string) => string;
|
|
49
|
+
changeInRepoTitle: (key: string) => string;
|
|
50
|
+
changeInRepoDescription: string;
|
|
51
|
+
openPullRequest: string;
|
|
52
|
+
pullRequestOpened: string;
|
|
53
|
+
readOnly: string;
|
|
54
|
+
healthEmpty: string;
|
|
55
|
+
healthEmptyDescription: string;
|
|
56
|
+
levels: Record<SettingsFindingLevel, string>;
|
|
57
|
+
fix: string;
|
|
58
|
+
fixLabel: (rule: string) => string;
|
|
59
|
+
/** The Health tab's count, for a screen reader. */
|
|
60
|
+
findingsCount: (n: number) => string;
|
|
61
|
+
howToFix: string;
|
|
62
|
+
openStep: string;
|
|
63
|
+
runInTerminal: string;
|
|
64
|
+
planTitle: (fixId: string) => string;
|
|
65
|
+
planLoading: string;
|
|
66
|
+
planFiles: string;
|
|
67
|
+
planCommands: string;
|
|
68
|
+
planSecrets: string;
|
|
69
|
+
planManual: string;
|
|
70
|
+
planNeeds: string;
|
|
71
|
+
apply: string;
|
|
72
|
+
confirmTitle: string;
|
|
73
|
+
confirmBody: (files: number, commands: number) => string;
|
|
74
|
+
confirmApply: string;
|
|
75
|
+
applied: string;
|
|
76
|
+
appliedUnverified: string;
|
|
77
|
+
stalePlan: string;
|
|
78
|
+
planAgain: string;
|
|
79
|
+
secretsEmpty: string;
|
|
80
|
+
secretStatus: Record<SettingsSecretStatus["status"], string>;
|
|
81
|
+
secretStores: Record<SettingsSecretStatus["store"], string>;
|
|
82
|
+
neededBy: (keys: string) => string;
|
|
83
|
+
lastRotated: (when: string) => string;
|
|
84
|
+
secretHint: string;
|
|
85
|
+
setSecret: string;
|
|
86
|
+
rotateSecret: string;
|
|
87
|
+
secretLabel: (name: string) => string;
|
|
88
|
+
setSecretTitle: (name: string) => string;
|
|
89
|
+
setSecretDescription: string;
|
|
90
|
+
secretValue: string;
|
|
91
|
+
upgradesEmpty: string;
|
|
92
|
+
checkAgain: string;
|
|
93
|
+
checkedAt: (when: string) => string;
|
|
94
|
+
offline: string;
|
|
95
|
+
distance: Record<UpgradeDistance, string>;
|
|
96
|
+
advisory: string;
|
|
97
|
+
releaseNotes: string;
|
|
98
|
+
openUpgradePr: string;
|
|
99
|
+
auditEmpty: string;
|
|
100
|
+
loadMore: string;
|
|
101
|
+
auditActions: Record<SettingsAuditEntry["action"], string>;
|
|
102
|
+
/** How a time is shown. Default: the browser's locale. */
|
|
103
|
+
formatTime: (iso: string) => string;
|
|
104
|
+
}
|
|
105
|
+
/** The default copy. @stability Beta */
|
|
106
|
+
declare const GENESIS_SETTINGS_COPY: GenesisSettingsCopy;
|
|
107
|
+
/** @stability Beta */
|
|
108
|
+
interface GenesisSettingsProps {
|
|
109
|
+
client: SettingsClient;
|
|
110
|
+
/**
|
|
111
|
+
* What this mount may do. It narrows what the host reports and can never widen it: the app's
|
|
112
|
+
* platform screen passes `APP_HOST_CAPABILITIES` so a misconfigured host still shows database
|
|
113
|
+
* writes only. Default: the host's own.
|
|
114
|
+
*/
|
|
115
|
+
capabilities?: Partial<SettingsCapabilities>;
|
|
116
|
+
copy?: Partial<GenesisSettingsCopy>;
|
|
117
|
+
defaultTab?: GenesisSettingsTab;
|
|
118
|
+
/** Opens a guided fix's setup step (the wizard routes to it). Without it, a step shows its CLI command. */
|
|
119
|
+
onOpenStep?: (step: string) => void;
|
|
120
|
+
/** Audit entries per page. Default 25. */
|
|
121
|
+
auditPageSize?: number;
|
|
122
|
+
/**
|
|
123
|
+
* Draw the page header (title, description, Refresh). Default true; pass false when the host page
|
|
124
|
+
* owns the title (under `AppShellPageHeader`, say).
|
|
125
|
+
*/
|
|
126
|
+
header?: boolean;
|
|
127
|
+
/** Prefix of every test id. Default `genesis-settings`. */
|
|
128
|
+
testID?: string;
|
|
129
|
+
className?: string;
|
|
130
|
+
}
|
|
131
|
+
/**
|
|
132
|
+
* The Settings screen. See the module header.
|
|
133
|
+
*
|
|
134
|
+
* ```tsx
|
|
135
|
+
* const client = createSettingsClient(fetch, { baseUrl: "/api/genesis/settings", token: () => session.access_token });
|
|
136
|
+
* <GenesisSettings client={client} capabilities={APP_HOST_CAPABILITIES} />
|
|
137
|
+
* ```
|
|
138
|
+
*
|
|
139
|
+
* @stability Beta
|
|
140
|
+
*/
|
|
141
|
+
declare function GenesisSettings({ client, capabilities: narrow, copy: copyOverride, defaultTab, onOpenStep, auditPageSize, header, testID, className, }: GenesisSettingsProps): react.JSX.Element;
|
|
142
|
+
|
|
143
|
+
export { GENESIS_SETTINGS_COPY, GenesisSettings, type GenesisSettingsCopy, type GenesisSettingsProps, type GenesisSettingsTab };
|