add-feature-flag

# Add a feature flag Feature flags are dynamic config entries whose resolver returns `boolean`. Completeness is enforced by TypeScript — the fixture and the Zod schema map are typed against `dynamicConfigs`, so a missing entry fails `npm run typecheck`. Reference example: `WORKFLOW_DIAGNOSTICS_ENABLED` (added in the same 4 files below). ## Naming - Key: `UPPER_SNAKE_CASE`, ending in `_ENABLED` — e.g. `WORKFLOW_DIAGNOSTICS_ENABLED` - Env var: `CADENCE_` + key — e.g. `CADENCE_WORKFLOW_DIAGNOSTICS_ENABLED` - Resolver file: kebab-case of the key — e.g. `workflow-diagnostics-enabled.ts` - Resolver function: camelCase of the key — e.g. `workflowDiagnosticsEnabled` ## Files to touch Add the new entry directly after a related existing flag in each file (not alphabetically). ### 1. Resolver — `src/config/dynamic/resolvers/<flag-name>.ts` ```ts /** * Returns whether <feature> is enabled. * * To enable, set the CADENCE_<FLAG_NAME> env variable to `true`. * For further customization, override the implementation of this resolver. * * @returns {Promise<boolean>} Whether <feature> is enabled. */ export default async function <flagName>(): Promise<boolean> { return process.env.CADENCE_<FLAG_NAME> === 'true'; } ``` - Default export, `async`, returns `Promise<boolean>`. - Off by default; forks override the resolver. - If the flag depends on another flag, import and call that resolver rather than re-reading its env var (see `workflow-diagnostics-in-history-enabled.ts`). Check the cheap env var first. - If the flag needs args (e.g. `{ cluster, domain }`), add `<flag-name>.types.ts` with a `<FlagName>ResolverParams` type (see `cron-list-enabled.types.ts`). ### 2. Register — `src/config/dynamic/dynamic.config.ts` Three edits: ```ts // import (alphabetical by file path) import <flagName> from './resolvers/<flag-name>'; // type block <FLAG_NAME>: ConfigAsyncResolverDefinition<undefined, boolean, 'request', true>; // runtime block <FLAG_NAME>: { resolver: <flagName>, evaluateOn: 'request', isPublic: true, }, ``` Replace `undefined` with the args type if the resolver takes args. `isPublic: true` is what exposes the key to the client via `/api/config`. ### 3. Zod schema — `src/config/dynamic/resolvers/schemas/resolver-schemas.ts` ```ts <FLAG_NAME>: { args: z.undefined(), // or z.object({ cluster: z.string(), domain: z.string() }) returnType: z.boolean(), }, ``` ### 4. Test fixture — `src/utils/config/__fixtures__/resolved-config-values.ts` ```ts <FLAG_NAME>: false, ``` The `getConfigValue` auto-mock reads from this, so server-side tests see the new key automatically. ### 5. Resolver test (only if the resolver has logic) Skip for a plain env-var check. If the resolver combines conditions, calls another resolver, or takes args, add `src/config/dynamic/resolvers/__tests__/<flag-name>.node.ts`. Mirror `batch-actions-ui-enabled.node.ts`: `jest.mock` the imported resolvers, save/restore the env var in `beforeEach`/`afterEach`. ## Consuming the flag Client: ```ts const { data: isEnabled } = useSuspenseConfigValue('<FLAG_NAME>'); // or non-suspense: useConfigValue('<FLAG_NAME>', args?) ``` Server (route handlers): `await getConfigValue('<FLAG_NAME>')`. Client tests mock the endpoint: ```ts render(<Component />, { endpointsMocks: [ { path: '/api/config', httpMethod: 'GET', mockOnce: false, httpResolver: async () => HttpResponse.json(true), }, ], }); ``` ## When the feature ships Once the UI lands: - Add a row to the **Feature flags** table in `README.md` - Add a commented `# CADENCE_<FLAG_NAME>=true` under `### Feature flags` in `.env` ## Verify ```bash npm run typecheck # proves fixture + schema are complete npm run test:unit:node <flag-name>.node.ts # if you added a resolver test npm run test:unit:node -- src/route-handlers/get-config src/utils/config src/config/dynamic npm run lint ``` Optional live check: `npm run dev`, then `curl 'http://localhost:8088/api/config?configKey=<FLAG_NAME>'` → `false`; rerun with `CADENCE_<FLAG_NAME>=true npm run dev` → `true`.