@marktiderman/genesis-features 0.0.0-stage → 0.1.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 +138 -2
- package/dist/chunk-YKNISEPJ.js +318 -0
- package/dist/chunk-YKNISEPJ.js.map +1 -0
- package/dist/index.d.ts +79 -0
- package/dist/index.js +3 -0
- package/dist/index.js.map +1 -0
- package/dist/model-CW5ocPFw.d.ts +288 -0
- package/dist/node.d.ts +140 -0
- package/dist/node.js +337 -0
- package/dist/node.js.map +1 -0
- package/dist/react.d.ts +57 -0
- package/dist/react.js +231 -0
- package/dist/react.js.map +1 -0
- package/package.json +80 -3
package/dist/index.d.ts
ADDED
|
@@ -0,0 +1,79 @@
|
|
|
1
|
+
import { F as Features, a as FeatureRecord, b as Flags } from './model-CW5ocPFw.js';
|
|
2
|
+
export { c as FEATURE_HORIZONS, d as FEATURE_STATUSES, e as FLAG_KINDS, f as FeatureAccess, g as FeatureDef, h as FeatureHorizon, i as FeatureIdOf, j as FeatureLinks, k as FeatureMedia, l as FeatureRegistryError, m as FeatureStatus, n as FeatureVisibility, o as FlagDef, p as FlagKind, q as FlagValue, r as defineFeatures, s as defineFlags, t as expiredFlags, u as featureSchema, v as findFeatures, w as flagSchema, x as flagsForFeature, y as toRecords } from './model-CW5ocPFw.js';
|
|
3
|
+
import 'zod';
|
|
4
|
+
|
|
5
|
+
/** Marks the start of the generated block in AGENTS.md. */
|
|
6
|
+
declare const AGENTS_BLOCK_START = "<!-- genesis-features:start -->";
|
|
7
|
+
/** Marks the end of the generated block in AGENTS.md. */
|
|
8
|
+
declare const AGENTS_BLOCK_END = "<!-- genesis-features:end -->";
|
|
9
|
+
/** Marks the start of the generated marketing block (e.g. in README.md). */
|
|
10
|
+
declare const MARKETING_BLOCK_START = "<!-- genesis-features:marketing:start -->";
|
|
11
|
+
/** Marks the end of the generated marketing block. */
|
|
12
|
+
declare const MARKETING_BLOCK_END = "<!-- genesis-features:marketing:end -->";
|
|
13
|
+
interface GenerateOptions {
|
|
14
|
+
/** The file the registry lives in, named in the "generated from" notes. Default `src/features.ts`. */
|
|
15
|
+
source?: string;
|
|
16
|
+
/** How agents run the CLI here, e.g. `genesis features` or `bun run features`. Default `genesis features`. */
|
|
17
|
+
command?: string;
|
|
18
|
+
/** Where the skill lives, named in the AGENTS.md pointer. Default `.claude/skills/features/SKILL.md`. */
|
|
19
|
+
skill?: string | false;
|
|
20
|
+
}
|
|
21
|
+
/**
|
|
22
|
+
* The registry as JSON, for tools that can't import TypeScript. Stable: no
|
|
23
|
+
* timestamps, features in declaration order, so `check` can compare it. It is
|
|
24
|
+
* also the record of every id ever used, which keeps ids permanent.
|
|
25
|
+
*
|
|
26
|
+
* @stability Beta
|
|
27
|
+
*/
|
|
28
|
+
declare function toJson(features: Features, flags?: Flags, options?: GenerateOptions): string;
|
|
29
|
+
/** The schema an OpenFeature CLI flag manifest points at. */
|
|
30
|
+
declare const OPENFEATURE_MANIFEST_SCHEMA = "https://raw.githubusercontent.com/open-feature/cli/refs/heads/main/schema/v0/flag-manifest.json";
|
|
31
|
+
/**
|
|
32
|
+
* The flags as an OpenFeature CLI flag manifest (`flags.json`), so
|
|
33
|
+
* `openfeature generate` can make typed accessors from the same registry.
|
|
34
|
+
*
|
|
35
|
+
* @stability Beta
|
|
36
|
+
*/
|
|
37
|
+
declare function toOpenFeatureManifest(flags: Flags, features?: Features): string;
|
|
38
|
+
/**
|
|
39
|
+
* The marker-delimited block for AGENTS.md: deliberately short. It points
|
|
40
|
+
* agents at `find` and the skill and gives counts, never the whole list, so
|
|
41
|
+
* AGENTS.md stays small however many features there are.
|
|
42
|
+
*
|
|
43
|
+
* @stability Beta
|
|
44
|
+
*/
|
|
45
|
+
declare function toAgentsMarkdown(features: Features, flags?: Flags, options?: GenerateOptions): string;
|
|
46
|
+
/** The public, shipped features a marketing page shows: visibility public, a tagline, live or beta. */
|
|
47
|
+
declare function marketingRecords(features: Features): FeatureRecord[];
|
|
48
|
+
/**
|
|
49
|
+
* A benefit-led feature list for a README or a marketing page: public, shipped
|
|
50
|
+
* features with a tagline, highlights first, grouped by category.
|
|
51
|
+
*
|
|
52
|
+
* @stability Beta
|
|
53
|
+
*/
|
|
54
|
+
declare function toMarketingMarkdown(features: Features, options?: {
|
|
55
|
+
heading?: string;
|
|
56
|
+
source?: string;
|
|
57
|
+
}): string;
|
|
58
|
+
/** Thrown when a generated block's markers are broken: one is missing, repeated or out of order. */
|
|
59
|
+
declare class BrokenBlockError extends Error {
|
|
60
|
+
constructor(start: string);
|
|
61
|
+
}
|
|
62
|
+
/** The generated AGENTS.md block inside `doc`, or null. */
|
|
63
|
+
declare const readAgentsBlock: (doc: string) => string | null;
|
|
64
|
+
/**
|
|
65
|
+
* `doc` with its generated AGENTS.md block replaced by `block`, or with
|
|
66
|
+
* `block` appended when it has none yet.
|
|
67
|
+
*
|
|
68
|
+
* @stability Beta
|
|
69
|
+
*/
|
|
70
|
+
declare const replaceAgentsBlock: (doc: string, block: string) => string;
|
|
71
|
+
/**
|
|
72
|
+
* The agent skill for working with the registry, written to
|
|
73
|
+
* `.claude/skills/features/SKILL.md` by `genesis features build`.
|
|
74
|
+
*
|
|
75
|
+
* @stability Beta
|
|
76
|
+
*/
|
|
77
|
+
declare function toSkillMarkdown(options?: GenerateOptions): string;
|
|
78
|
+
|
|
79
|
+
export { AGENTS_BLOCK_END, AGENTS_BLOCK_START, BrokenBlockError, FeatureRecord, Features, Flags, type GenerateOptions, MARKETING_BLOCK_END, MARKETING_BLOCK_START, OPENFEATURE_MANIFEST_SCHEMA, marketingRecords, readAgentsBlock, replaceAgentsBlock, toAgentsMarkdown, toJson, toMarketingMarkdown, toOpenFeatureManifest, toSkillMarkdown };
|
package/dist/index.js
ADDED
|
@@ -0,0 +1,3 @@
|
|
|
1
|
+
export { AGENTS_BLOCK_END, AGENTS_BLOCK_START, BrokenBlockError, FEATURE_HORIZONS, FEATURE_STATUSES, FLAG_KINDS, FeatureRegistryError, MARKETING_BLOCK_END, MARKETING_BLOCK_START, OPENFEATURE_MANIFEST_SCHEMA, defineFeatures, defineFlags, expiredFlags, featureSchema, findFeatures, flagSchema, flagsForFeature, marketingRecords, readAgentsBlock, replaceAgentsBlock, toAgentsMarkdown, toJson, toMarketingMarkdown, toOpenFeatureManifest, toRecords, toSkillMarkdown } from './chunk-YKNISEPJ.js';
|
|
2
|
+
//# sourceMappingURL=index.js.map
|
|
3
|
+
//# sourceMappingURL=index.js.map
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
{"version":3,"sources":[],"names":[],"mappings":"","file":"index.js"}
|
|
@@ -0,0 +1,288 @@
|
|
|
1
|
+
import { z } from 'zod';
|
|
2
|
+
|
|
3
|
+
/**
|
|
4
|
+
* Where a feature is in its life. The order is the board's column order.
|
|
5
|
+
*
|
|
6
|
+
* @stability Beta
|
|
7
|
+
*/
|
|
8
|
+
declare const FEATURE_STATUSES: readonly ["planned", "building", "beta", "live", "deprecated", "retired"];
|
|
9
|
+
/** @stability Beta */
|
|
10
|
+
type FeatureStatus = (typeof FEATURE_STATUSES)[number];
|
|
11
|
+
/**
|
|
12
|
+
* When a planned or building feature is due, without dates: the roadmap's
|
|
13
|
+
* three columns.
|
|
14
|
+
*
|
|
15
|
+
* @stability Beta
|
|
16
|
+
*/
|
|
17
|
+
declare const FEATURE_HORIZONS: readonly ["now", "next", "later"];
|
|
18
|
+
/** @stability Beta */
|
|
19
|
+
type FeatureHorizon = (typeof FEATURE_HORIZONS)[number];
|
|
20
|
+
/**
|
|
21
|
+
* Who may see a feature listed. `public` features with a `tagline` go on
|
|
22
|
+
* marketing output; `client:<name>` is one customer's own feature.
|
|
23
|
+
*
|
|
24
|
+
* @stability Beta
|
|
25
|
+
*/
|
|
26
|
+
type FeatureVisibility = "internal" | "customer" | "public" | `client:${string}`;
|
|
27
|
+
/**
|
|
28
|
+
* Who gets a feature: everyone, or one paid plan. The feature id doubles as
|
|
29
|
+
* the billing entitlement's lookup key (a Stripe `lookup_key`).
|
|
30
|
+
*
|
|
31
|
+
* @stability Beta
|
|
32
|
+
*/
|
|
33
|
+
type FeatureAccess = "all" | {
|
|
34
|
+
plan: string;
|
|
35
|
+
};
|
|
36
|
+
/**
|
|
37
|
+
* Pointers from a feature to where it lives. `code` paths are relative to the
|
|
38
|
+
* repository root and `genesis features check` fails when one doesn't exist.
|
|
39
|
+
*
|
|
40
|
+
* @stability Beta
|
|
41
|
+
*/
|
|
42
|
+
interface FeatureLinks {
|
|
43
|
+
/** Files or folders that implement the feature, relative to the repo root. */
|
|
44
|
+
code?: readonly string[];
|
|
45
|
+
/** Docs: a repo-relative path or a URL. */
|
|
46
|
+
docs?: readonly string[];
|
|
47
|
+
/** The tracking issue: a URL, `#123` or `owner/repo#123`. */
|
|
48
|
+
issue?: string;
|
|
49
|
+
}
|
|
50
|
+
/** A picture or video for a marketing page. @stability Beta */
|
|
51
|
+
interface FeatureMedia {
|
|
52
|
+
image?: string;
|
|
53
|
+
video?: string;
|
|
54
|
+
alt: string;
|
|
55
|
+
}
|
|
56
|
+
/**
|
|
57
|
+
* One feature. The object key in {@link defineFeatures} is its id: permanent,
|
|
58
|
+
* never reused, and renamed only through `aliases`.
|
|
59
|
+
*
|
|
60
|
+
* @stability Beta
|
|
61
|
+
*/
|
|
62
|
+
interface FeatureDef {
|
|
63
|
+
name: string;
|
|
64
|
+
/** One sentence for the team: what it does for whom. */
|
|
65
|
+
summary: string;
|
|
66
|
+
status: FeatureStatus;
|
|
67
|
+
/** Who answers for it: a person, a team or an agent session's name. */
|
|
68
|
+
owner: string;
|
|
69
|
+
/** Which of the repo's apps or surfaces carry it, e.g. `["web"]`. */
|
|
70
|
+
apps: readonly string[];
|
|
71
|
+
/** Who it is for, e.g. `["client", "coach"]`. */
|
|
72
|
+
audience: readonly string[];
|
|
73
|
+
/** Roadmap column. Only on planned (required) or building features. */
|
|
74
|
+
horizon?: FeatureHorizon;
|
|
75
|
+
/** Default `customer`. */
|
|
76
|
+
visibility?: FeatureVisibility;
|
|
77
|
+
/** Default `all`. */
|
|
78
|
+
access?: FeatureAccess;
|
|
79
|
+
/** One testable sentence each. Required on beta and live features. */
|
|
80
|
+
acceptance?: readonly string[];
|
|
81
|
+
/** Ids this feature had before. An old id can't be reused. */
|
|
82
|
+
aliases?: readonly string[];
|
|
83
|
+
/** When someone last checked this entry against the product: `YYYY-MM-DD`. */
|
|
84
|
+
reviewedAt?: string;
|
|
85
|
+
/** Who is building it right now. Only on building features. */
|
|
86
|
+
claimedBy?: string;
|
|
87
|
+
/** When it first shipped or started: `YYYY-MM-DD` or `YYYY-MM`. */
|
|
88
|
+
since?: string;
|
|
89
|
+
links?: FeatureLinks;
|
|
90
|
+
/** One line of benefit, for customers. Needed for marketing output. */
|
|
91
|
+
tagline?: string;
|
|
92
|
+
/** A group on a marketing page. */
|
|
93
|
+
category?: string;
|
|
94
|
+
media?: FeatureMedia;
|
|
95
|
+
/** A hero item on a marketing page. */
|
|
96
|
+
highlight?: boolean;
|
|
97
|
+
}
|
|
98
|
+
/**
|
|
99
|
+
* Why a flag exists. `release` and `experiment` flags need `expires`, `ops`
|
|
100
|
+
* flags need a `runbook`, and `permission` flags fail `check`: paid access
|
|
101
|
+
* belongs in entitlements (`access`), not flags.
|
|
102
|
+
*
|
|
103
|
+
* @stability Beta
|
|
104
|
+
*/
|
|
105
|
+
declare const FLAG_KINDS: readonly ["release", "experiment", "ops", "permission"];
|
|
106
|
+
/** @stability Beta */
|
|
107
|
+
type FlagKind = (typeof FLAG_KINDS)[number];
|
|
108
|
+
/** A flag's default: anything an OpenFeature flag can hold. */
|
|
109
|
+
type FlagValue = boolean | string | number | {
|
|
110
|
+
readonly [key: string]: unknown;
|
|
111
|
+
};
|
|
112
|
+
/**
|
|
113
|
+
* One flag. `feature` names the {@link FeatureDef} it belongs to; a feature's
|
|
114
|
+
* flags are found by reverse lookup ({@link flagsForFeature}) and never
|
|
115
|
+
* written on the feature itself.
|
|
116
|
+
*
|
|
117
|
+
* @stability Beta
|
|
118
|
+
*/
|
|
119
|
+
interface FlagDef<F extends string = string> {
|
|
120
|
+
feature: F;
|
|
121
|
+
kind: FlagKind;
|
|
122
|
+
owner: string;
|
|
123
|
+
default: FlagValue;
|
|
124
|
+
/** Where it can be set, e.g. `["platform", "practice", "user"]`. */
|
|
125
|
+
scopes: readonly string[];
|
|
126
|
+
description?: string;
|
|
127
|
+
/** `YYYY-MM-DD`. Required on release and experiment flags; `check` fails after it. */
|
|
128
|
+
expires?: string;
|
|
129
|
+
/** What to do when you flip it: a repo path or a URL. Required on ops flags. */
|
|
130
|
+
runbook?: string;
|
|
131
|
+
/**
|
|
132
|
+
* Flags are grouped by feature: one flag per feature by default. Every flag
|
|
133
|
+
* after a feature's first must say why it is a separate flag.
|
|
134
|
+
*/
|
|
135
|
+
splitReason?: string;
|
|
136
|
+
}
|
|
137
|
+
/** The id type of a features object: `type FeatureId = FeatureIdOf<typeof features>`. */
|
|
138
|
+
type FeatureIdOf<T> = Extract<keyof T, string>;
|
|
139
|
+
/** A features object as {@link defineFeatures} returns it. */
|
|
140
|
+
type Features<Id extends string = string> = {
|
|
141
|
+
readonly [K in Id]: FeatureDef;
|
|
142
|
+
};
|
|
143
|
+
/** A flags object as {@link defineFlags} returns it. */
|
|
144
|
+
type Flags<F extends string = string> = {
|
|
145
|
+
readonly [name: string]: FlagDef<F>;
|
|
146
|
+
};
|
|
147
|
+
/** The Zod schema for one {@link FeatureDef}, field by field. Cross-field rules live in {@link featureProblems}. */
|
|
148
|
+
declare const featureSchema: z.ZodObject<{
|
|
149
|
+
name: z.ZodString;
|
|
150
|
+
summary: z.ZodString;
|
|
151
|
+
status: z.ZodEnum<{
|
|
152
|
+
planned: "planned";
|
|
153
|
+
building: "building";
|
|
154
|
+
beta: "beta";
|
|
155
|
+
live: "live";
|
|
156
|
+
deprecated: "deprecated";
|
|
157
|
+
retired: "retired";
|
|
158
|
+
}>;
|
|
159
|
+
owner: z.ZodString;
|
|
160
|
+
apps: z.ZodArray<z.ZodString>;
|
|
161
|
+
audience: z.ZodArray<z.ZodString>;
|
|
162
|
+
horizon: z.ZodOptional<z.ZodEnum<{
|
|
163
|
+
now: "now";
|
|
164
|
+
next: "next";
|
|
165
|
+
later: "later";
|
|
166
|
+
}>>;
|
|
167
|
+
visibility: z.ZodOptional<z.ZodUnion<readonly [z.ZodEnum<{
|
|
168
|
+
internal: "internal";
|
|
169
|
+
customer: "customer";
|
|
170
|
+
public: "public";
|
|
171
|
+
}>, z.ZodString]>>;
|
|
172
|
+
access: z.ZodOptional<z.ZodUnion<readonly [z.ZodLiteral<"all">, z.ZodObject<{
|
|
173
|
+
plan: z.ZodString;
|
|
174
|
+
}, z.core.$strict>]>>;
|
|
175
|
+
acceptance: z.ZodOptional<z.ZodArray<z.ZodString>>;
|
|
176
|
+
aliases: z.ZodOptional<z.ZodArray<z.ZodString>>;
|
|
177
|
+
reviewedAt: z.ZodOptional<z.ZodString>;
|
|
178
|
+
claimedBy: z.ZodOptional<z.ZodString>;
|
|
179
|
+
since: z.ZodOptional<z.ZodString>;
|
|
180
|
+
links: z.ZodOptional<z.ZodObject<{
|
|
181
|
+
code: z.ZodOptional<z.ZodArray<z.ZodString>>;
|
|
182
|
+
docs: z.ZodOptional<z.ZodArray<z.ZodUnion<readonly [z.ZodString, z.ZodString]>>>;
|
|
183
|
+
issue: z.ZodOptional<z.ZodString>;
|
|
184
|
+
}, z.core.$strict>>;
|
|
185
|
+
tagline: z.ZodOptional<z.ZodString>;
|
|
186
|
+
category: z.ZodOptional<z.ZodString>;
|
|
187
|
+
media: z.ZodOptional<z.ZodObject<{
|
|
188
|
+
image: z.ZodOptional<z.ZodUnion<readonly [z.ZodString, z.ZodString]>>;
|
|
189
|
+
video: z.ZodOptional<z.ZodUnion<readonly [z.ZodString, z.ZodString]>>;
|
|
190
|
+
alt: z.ZodString;
|
|
191
|
+
}, z.core.$strict>>;
|
|
192
|
+
highlight: z.ZodOptional<z.ZodBoolean>;
|
|
193
|
+
}, z.core.$strict>;
|
|
194
|
+
/** The Zod schema for one {@link FlagDef}. Cross-flag rules live in {@link defineFlags}. */
|
|
195
|
+
declare const flagSchema: z.ZodObject<{
|
|
196
|
+
feature: z.ZodString;
|
|
197
|
+
kind: z.ZodEnum<{
|
|
198
|
+
release: "release";
|
|
199
|
+
experiment: "experiment";
|
|
200
|
+
ops: "ops";
|
|
201
|
+
permission: "permission";
|
|
202
|
+
}>;
|
|
203
|
+
owner: z.ZodString;
|
|
204
|
+
default: z.ZodType<FlagValue, unknown, z.core.$ZodTypeInternals<FlagValue, unknown>>;
|
|
205
|
+
scopes: z.ZodArray<z.ZodString>;
|
|
206
|
+
description: z.ZodOptional<z.ZodString>;
|
|
207
|
+
expires: z.ZodOptional<z.ZodString>;
|
|
208
|
+
runbook: z.ZodOptional<z.ZodUnion<readonly [z.ZodString, z.ZodString]>>;
|
|
209
|
+
splitReason: z.ZodOptional<z.ZodString>;
|
|
210
|
+
}, z.core.$strict>;
|
|
211
|
+
/** Thrown by {@link defineFeatures} and {@link defineFlags}; lists every problem at once. */
|
|
212
|
+
declare class FeatureRegistryError extends Error {
|
|
213
|
+
readonly problems: string[];
|
|
214
|
+
constructor(problems: string[]);
|
|
215
|
+
}
|
|
216
|
+
/**
|
|
217
|
+
* The one source of truth for a repo's features. Validates every entry and
|
|
218
|
+
* returns the same object, so running code reads it directly and the key type
|
|
219
|
+
* becomes the repo's `FeatureId`:
|
|
220
|
+
*
|
|
221
|
+
* ```ts
|
|
222
|
+
* export const features = defineFeatures({
|
|
223
|
+
* tasks: { name: "Tasks", summary: "…", status: "live", owner: "mark", apps: ["web"], audience: ["client"],
|
|
224
|
+
* acceptance: ["A client can tick off a task their coach added."] },
|
|
225
|
+
* });
|
|
226
|
+
* export type FeatureId = FeatureIdOf<typeof features>;
|
|
227
|
+
* ```
|
|
228
|
+
*
|
|
229
|
+
* @stability Beta
|
|
230
|
+
*/
|
|
231
|
+
declare function defineFeatures<const T extends Record<string, FeatureDef>>(features: T): T;
|
|
232
|
+
/**
|
|
233
|
+
* Flags, each tied to a feature of `features`. An unknown `feature` is a type
|
|
234
|
+
* error, and at runtime:
|
|
235
|
+
* - every flag needs an `owner`, a `kind`, a `default` and its `scopes`;
|
|
236
|
+
* - `release` and `experiment` flags need an `expires` date, `ops` flags a `runbook`;
|
|
237
|
+
* - a feature's second (third, …) flag needs a `splitReason`, because flags
|
|
238
|
+
* are grouped by feature unless there's a stated reason to split.
|
|
239
|
+
*
|
|
240
|
+
* `permission` flags are accepted here so the app still runs, and refused by
|
|
241
|
+
* `genesis features check`.
|
|
242
|
+
*
|
|
243
|
+
* @stability Beta
|
|
244
|
+
*/
|
|
245
|
+
declare function defineFlags<F extends string, const T extends Record<string, FlagDef<NoInfer<F>>>>(features: {
|
|
246
|
+
readonly [K in F]: FeatureDef;
|
|
247
|
+
}, flags: T): T;
|
|
248
|
+
/**
|
|
249
|
+
* The names of the flags that belong to a feature, in declaration order.
|
|
250
|
+
*
|
|
251
|
+
* @stability Beta
|
|
252
|
+
*/
|
|
253
|
+
declare function flagsForFeature(flags: Flags | undefined, id: string): string[];
|
|
254
|
+
/**
|
|
255
|
+
* Flags whose `expires` date is before `today` (`YYYY-MM-DD`, default today in
|
|
256
|
+
* UTC): remove the code path, then the flag.
|
|
257
|
+
*
|
|
258
|
+
* @stability Beta
|
|
259
|
+
*/
|
|
260
|
+
declare function expiredFlags(flags: Flags | undefined, today?: string): string[];
|
|
261
|
+
/**
|
|
262
|
+
* A feature flattened for a list, a board or JSON: its id, its fields with
|
|
263
|
+
* defaults filled in, and the names of its flags.
|
|
264
|
+
*
|
|
265
|
+
* @stability Beta
|
|
266
|
+
*/
|
|
267
|
+
interface FeatureRecord extends FeatureDef {
|
|
268
|
+
[key: string]: unknown;
|
|
269
|
+
id: string;
|
|
270
|
+
visibility: FeatureVisibility;
|
|
271
|
+
access: FeatureAccess;
|
|
272
|
+
flags: string[];
|
|
273
|
+
}
|
|
274
|
+
/**
|
|
275
|
+
* Features as records, in declaration order, each with its flags attached.
|
|
276
|
+
*
|
|
277
|
+
* @stability Beta
|
|
278
|
+
*/
|
|
279
|
+
declare function toRecords(features: Features, flags?: Flags): FeatureRecord[];
|
|
280
|
+
/**
|
|
281
|
+
* Features matching `term` in their id, aliases, name, summary, tagline,
|
|
282
|
+
* category or code paths, best matches (id and name) first.
|
|
283
|
+
*
|
|
284
|
+
* @stability Beta
|
|
285
|
+
*/
|
|
286
|
+
declare function findFeatures(features: Features, term: string, flags?: Flags): FeatureRecord[];
|
|
287
|
+
|
|
288
|
+
export { type Features as F, type FeatureRecord as a, type Flags as b, FEATURE_HORIZONS as c, FEATURE_STATUSES as d, FLAG_KINDS as e, type FeatureAccess as f, type FeatureDef as g, type FeatureHorizon as h, type FeatureIdOf as i, type FeatureLinks as j, type FeatureMedia as k, FeatureRegistryError as l, type FeatureStatus as m, type FeatureVisibility as n, type FlagDef as o, type FlagKind as p, type FlagValue as q, defineFeatures as r, defineFlags as s, expiredFlags as t, featureSchema as u, findFeatures as v, flagSchema as w, flagsForFeature as x, toRecords as y };
|
package/dist/node.d.ts
ADDED
|
@@ -0,0 +1,140 @@
|
|
|
1
|
+
import { F as Features, b as Flags } from './model-CW5ocPFw.js';
|
|
2
|
+
import 'zod';
|
|
3
|
+
|
|
4
|
+
/**
|
|
5
|
+
* Where a repo keeps its registry's outputs and what `check` scans. Every
|
|
6
|
+
* path is relative to `root`; `false` turns an output or a scan off. The CLI
|
|
7
|
+
* reads these from `package.json` → `"genesisFeatures"`, and its options win.
|
|
8
|
+
*
|
|
9
|
+
* @stability Beta
|
|
10
|
+
*/
|
|
11
|
+
interface FeatureProjectOptions {
|
|
12
|
+
/** The repository root. */
|
|
13
|
+
root: string;
|
|
14
|
+
features: Features;
|
|
15
|
+
flags?: Flags;
|
|
16
|
+
/** The registry file, named in generated output. Default `src/features.ts`. */
|
|
17
|
+
source?: string;
|
|
18
|
+
/** How people run the CLI here, named in generated output. Default `genesis features`. */
|
|
19
|
+
command?: string;
|
|
20
|
+
/** The AGENTS.md that holds the pointer block. Default `AGENTS.md`. */
|
|
21
|
+
agents?: string | false;
|
|
22
|
+
/** The CLAUDE.md that must import AGENTS.md (`@AGENTS.md`). Default `CLAUDE.md`. */
|
|
23
|
+
claude?: string | false;
|
|
24
|
+
/** The JSON copy, which is also the record of every id ever used. Default `features.json`. */
|
|
25
|
+
json?: string | false;
|
|
26
|
+
/** The OpenFeature flag manifest, written when there are flags. Default `flags.json`. */
|
|
27
|
+
openfeature?: string | false;
|
|
28
|
+
/** The agent skill. Default `.claude/skills/features/SKILL.md`. */
|
|
29
|
+
skill?: string | false;
|
|
30
|
+
/** A file to keep the marketing block in (e.g. README.md). Default none. */
|
|
31
|
+
marketing?: string | false;
|
|
32
|
+
/** The marketing block's heading. Default `Features`. */
|
|
33
|
+
marketingHeading?: string;
|
|
34
|
+
/**
|
|
35
|
+
* How code reads a flag: a function name (`useFlag`, read as its first
|
|
36
|
+
* argument) or a JSX attribute (`<Flag name>`). Default `useFlag`, `getFlag`
|
|
37
|
+
* and `<Flag name>`.
|
|
38
|
+
*/
|
|
39
|
+
flagAccessors?: readonly string[];
|
|
40
|
+
/** Code scanned for flag reads. Default `src`, `app` and `packages/*\/src`. */
|
|
41
|
+
scan?: readonly string[] | false;
|
|
42
|
+
/** Test files scanned for `@feat:<id>` tags. */
|
|
43
|
+
tests?: readonly string[] | false;
|
|
44
|
+
/** The changesets folder, scanned for `Features: <id>` lines. Default `.changeset`. */
|
|
45
|
+
changesets?: string | false;
|
|
46
|
+
/** The PR's labels, checked for `feature:<id>`. */
|
|
47
|
+
labels?: readonly string[];
|
|
48
|
+
/** Route and server-function files every one of which some `links.code` should cover. */
|
|
49
|
+
coverage?: readonly string[] | false;
|
|
50
|
+
coverageIgnore?: readonly string[];
|
|
51
|
+
/** Warn when `reviewedAt` is older than this many days. Default 90. */
|
|
52
|
+
reviewDays?: number;
|
|
53
|
+
/** `YYYY-MM-DD`. Default today (UTC). */
|
|
54
|
+
today?: string;
|
|
55
|
+
/**
|
|
56
|
+
* Shipped work gathered elsewhere (the CLI's `--prs` reads it with `gh`).
|
|
57
|
+
* A planned feature with any of it gets a warning, as do changesets that
|
|
58
|
+
* name it.
|
|
59
|
+
*/
|
|
60
|
+
evidence?: FeatureEvidence;
|
|
61
|
+
}
|
|
62
|
+
/** A merged PR labelled `feature:<id>`. @stability Beta */
|
|
63
|
+
interface FeaturePrEvidence {
|
|
64
|
+
number: number;
|
|
65
|
+
title: string;
|
|
66
|
+
}
|
|
67
|
+
/** @stability Beta */
|
|
68
|
+
interface FeatureEvidence {
|
|
69
|
+
/** Merged PRs by the feature id (or alias) on their `feature:<id>` label. */
|
|
70
|
+
prs?: Record<string, readonly FeaturePrEvidence[]>;
|
|
71
|
+
}
|
|
72
|
+
/** A feature still marked planned that already has shipped work tagged with it. @stability Beta */
|
|
73
|
+
interface PlannedButShipped {
|
|
74
|
+
id: string;
|
|
75
|
+
/** Changeset files with a `Features: <id>` line. */
|
|
76
|
+
changesets: string[];
|
|
77
|
+
prs: FeaturePrEvidence[];
|
|
78
|
+
}
|
|
79
|
+
/** @stability Beta */
|
|
80
|
+
interface FeatureCheckResult {
|
|
81
|
+
ok: boolean;
|
|
82
|
+
/** Hard failures: stale generated output, missing code paths, flag rules, removed ids, bad tags, no `@AGENTS.md`. */
|
|
83
|
+
errors: string[];
|
|
84
|
+
/** Everything else: reviews due, untested live features, uncovered routes, missing docs. */
|
|
85
|
+
warnings: string[];
|
|
86
|
+
/** Generated files that differ from what the generator makes now. */
|
|
87
|
+
stale: string[];
|
|
88
|
+
expiredFlags: string[];
|
|
89
|
+
/** Building features with someone on them: `[id, claimedBy]`. */
|
|
90
|
+
claims: [string, string][];
|
|
91
|
+
/** Planned features with shipped work; each is also a warning. */
|
|
92
|
+
plannedButShipped: PlannedButShipped[];
|
|
93
|
+
}
|
|
94
|
+
/** A glob (`*`, `**`, `?`, `{a,b}`) as a RegExp over `/`-separated relative paths. */
|
|
95
|
+
declare function globToRegExp(glob: string): RegExp;
|
|
96
|
+
/**
|
|
97
|
+
* Flag reads in `text`: each key read through an accessor with a literal, and
|
|
98
|
+
* each read whose key isn't a literal (`dynamic`), as `path:line`.
|
|
99
|
+
*/
|
|
100
|
+
declare function scanFlagReads(path: string, text: string, accessors?: readonly string[]): {
|
|
101
|
+
keys: {
|
|
102
|
+
key: string;
|
|
103
|
+
where: string;
|
|
104
|
+
}[];
|
|
105
|
+
dynamic: string[];
|
|
106
|
+
};
|
|
107
|
+
/**
|
|
108
|
+
* Writes every generated output (the AGENTS.md block, the JSON, the flag
|
|
109
|
+
* manifest, the skill, the marketing block) and adds `@AGENTS.md` to
|
|
110
|
+
* CLAUDE.md when it's missing. Refuses, writing nothing, when an id recorded
|
|
111
|
+
* in the JSON has disappeared. Returns the paths it changed.
|
|
112
|
+
*
|
|
113
|
+
* @stability Beta
|
|
114
|
+
*/
|
|
115
|
+
declare function buildFeatureOutputs(options: FeatureProjectOptions): string[];
|
|
116
|
+
/**
|
|
117
|
+
* Checks the registry against the repo. Errors (exit 1): generated output that
|
|
118
|
+
* is stale, `links.code` paths that don't exist, the flag rules (a permission
|
|
119
|
+
* flag, an expired flag, a dynamic key, a key read but not defined or defined
|
|
120
|
+
* but never read, a missing runbook), an id that disappeared, an unknown id in
|
|
121
|
+
* a test, changeset or PR tag, and a CLAUDE.md without `@AGENTS.md`.
|
|
122
|
+
* Warnings: reviews due, live features without tagged tests, planned features
|
|
123
|
+
* with shipped work (changesets, and `evidence.prs`), route and
|
|
124
|
+
* server-function files no feature covers, missing docs.
|
|
125
|
+
*
|
|
126
|
+
* It only ever compares generated output with the generator, never two
|
|
127
|
+
* hand-written files.
|
|
128
|
+
*
|
|
129
|
+
* @stability Beta
|
|
130
|
+
*/
|
|
131
|
+
declare function checkFeatureOutputs(options: FeatureProjectOptions): FeatureCheckResult;
|
|
132
|
+
/**
|
|
133
|
+
* A few lines for a session's start: counts, stale output, expired flags,
|
|
134
|
+
* planned features with shipped work and open claims. Meant for a SessionStart hook (`genesis features check --summary`).
|
|
135
|
+
*
|
|
136
|
+
* @stability Beta
|
|
137
|
+
*/
|
|
138
|
+
declare function summarizeCheck(result: FeatureCheckResult, features: Features): string;
|
|
139
|
+
|
|
140
|
+
export { type FeatureCheckResult, type FeatureEvidence, type FeaturePrEvidence, type FeatureProjectOptions, type PlannedButShipped, buildFeatureOutputs, checkFeatureOutputs, globToRegExp, scanFlagReads, summarizeCheck };
|