@nebulr-group/bridge-cli 0.6.5 → 1.0.0-alpha.0

package/dist/commands/flag.command.js

@@ -1,874 +1,191 @@
-// TBP-192 / TBP-236 — Flag CLI parity for FF 2.0.
-//
-// The CLI's `flag` subcommand exposes the 2.0 mental model:
-//   - Three-state model: off | on | on-with-rule
-//   - Multi-type values: boolean | string | number | json
-//   - Inline rules (branches + conditions + rolloutPct)
-//   - Scheduling (data-only; the runner is TBP-189 — we just set/clear the field)
-//   - Local eval helper for debugging
-//
-// TBP-236: the CLI's rule format is now the canonical auth-core one. The
-// `Rule` / `Branch` / `Condition` types and the `evaluateRule` / `validateRule`
-// evaluator are imported from @nebulr-group/bridge-auth-core — there is no
-// CLI-local rule shape anymore. Conditions always carry a plural `values`
-// array on the wire, and operators come from the package's locked vocabulary
-// (`OPERATORS`: eq | neq | contains | not_contains | in | not_in | gt | lt |
-// between | regex | exists | not_exists). Legacy CLI inputs (singular
-// `value`, operator names like `equals` / `starts_with` / `gte`) are migrated
-// at parse time by `normalizeRuleInput()` below, with a deprecation warning
-// on stderr for legacy operator names.
-import { readFileSync, writeFileSync } from 'node:fs';
-import { OPERATORS, evaluateRule, isOperator, validateRule, } from '@nebulr-group/bridge-auth-core';
-import { getManagementClient } from '../config.js';
-import { warningsForFlags, withFlagWarnings } from '../flag-coherence.js';
-import { dryRunPreview } from '../preview.js';
-import { outputSuccess, outputError } from '../output.js';
-import { resolveFlag, resolveFlagId } from '../resolve.js';
-import { registerFlagInitCommand } from './flag-init.command.js';
-// Re-export the canonical validator so existing consumers/tests keep a single
-// import site for rule validation alongside the CLI parse helpers.
-export { validateRule };
-const FLAG_STATES = ['off', 'on', 'on-with-rule'];
-const FLAG_VALUE_TYPES = ['boolean', 'string', 'number', 'json'];
-// ── Public registration ─────────────────────────────────────────────────────
-export function registerFlagCommands(program) {
-    const flag = program
-        .command('flag')
-        .description([
-        'Manage feature flags (Feature Flags 2.0 mental model)',
-        '',
-        '  state   off | on | on-with-rule',
-        '  values  boolean | string | number | json (typed at flag level)',
-        '  rule    branches[] + otherwiseValue + rolloutPct (first-match-wins)',
-    ].join('\n'));
-    registerList(flag);
-    registerGet(flag);
-    registerCreate(flag);
-    registerUpdate(flag);
-    registerToggle(flag);
-    registerDelete(flag);
-    registerEval(flag);
-    registerSchedule(flag);
-    registerExport(flag);
-    registerImport(flag);
-    registerFlagInitCommand(flag);
-}
-// ── list ────────────────────────────────────────────────────────────────────
-function registerList(flag) {
-    flag
-        .command('list')
-        .description('List feature flags (shows state + value type)')
-        .action(async () => {
-        try {
-            const flags = await getManagementClient().flags.list();
-            // Normalize so callers always see the same shape even if the API
-            // returns the legacy fields only.
-            // TBP-709 — a flag that cannot mean what it looks like carries warnings.
-            const warnings = await warningsForFlags(flags.map((f) => ({ ...f, state: f.state ?? deriveState(f) })));
-            const rows = flags.map((f, i) => ({
-                id: f.id,
-                key: f.key,
-                description: f.description,
-                state: f.state ?? deriveState(f),
-                valueType: f.valueType ?? 'boolean',
-                enabled: f.enabled,
-                ...(warnings[i].length ? { warnings: warnings[i] } : {}),
-            }));
-            outputSuccess(rows);
-        }
-        catch (err) {
-            outputError(err);
-        }
-    });
-}
-// ── get ─────────────────────────────────────────────────────────────────────
-function registerGet(flag) {
-    flag
-        .command('get')
-        .argument('<key>', 'Flag key')
-        .description('Get a flag (rich 2.0 shape: state, value type, rule, observability)')
-        .action(async (key) => {
-        try {
-            const all = await getManagementClient().flags.list();
-            const found = all.find((f) => f.key === key);
-            if (!found) {
-                outputError(new Error(`Flag not found: ${key}`));
-                return;
-            }
-            outputSuccess(await withFlagWarnings({
-                id: found.id,
-                key: found.key,
-                description: found.description,
-                state: found.state ?? deriveState(found),
-                valueType: found.valueType ?? 'boolean',
-                offValue: found.offValue,
-                onValue: found.onValue,
-                rule: found.rule,
-                schedule: found.schedule,
-                observability: {
-                    evalCount: found.evalCount,
-                    lastEvalAt: found.lastEvalAt,
-                },
-                // Echo the legacy fields too — useful while 1.0 admin clients exist.
-                legacy: {
-                    enabled: found.enabled,
-                    defaultValue: found.defaultValue,
-                    targetValue: found.targetValue,
-                },
-            }));
-        }
-        catch (err) {
-            outputError(err);
-        }
-    });
-}
-// ── create ──────────────────────────────────────────────────────────────────
-function registerCreate(flag) {
-    flag
-        .command('create')
-        .description('Create a new feature flag (2.0 fields)')
-        .requiredOption('--key <key>', 'Flag key')
-        .option('--description <desc>', 'Description')
-        .option('--state <state>', `Three-state model: ${FLAG_STATES.join(' | ')} (default: off)`)
-        .option('--value-type <type>', `Flag value type: ${FLAG_VALUE_TYPES.join(' | ')} (default: boolean)`)
-        .option('--on-value <value>', 'Value returned when state=on (parsed per --value-type; JSON string for json type)')
-        .option('--off-value <value>', 'Value returned when state=off (parsed per --value-type)')
-        .option('--rule <json>', 'Rule as a JSON string: {"branches":[...],"otherwiseValue":...,"rolloutPct":100}')
-        // Legacy 1.0 fields kept so existing scripts don't break.
-        .option('--enabled', 'Legacy: enable the flag', false)
-        .option('--default-value', 'Legacy: default value when no segment matches', false)
-        .action(async (opts) => {
-        try {
-            // `--key` is a requiredOption above, so `key` is always present at
-            // runtime even though buildFlagWritePayload's generic return type
-            // can't express that. The `unknown` step is just to convince TS the
-            // intent is deliberate.
-            const payload = buildFlagWritePayload(opts);
-            const flag = await getManagementClient().flags.create(payload);
-            outputSuccess(await withFlagWarnings(flag));
-        }
-        catch (err) {
-            outputError(err);
-        }
-    });
-}
-// ── update ──────────────────────────────────────────────────────────────────
-function registerUpdate(flag) {
-    flag
-        .command('update')
-        .description('Update a feature flag by --key or --id (2.0 fields)')
-        .option('--key <key>', 'Flag key to address (alternative to --id)')
-        .option('--id <id>', 'Flag ID to address (alternative to --key)')
-        .option('--new-key <key>', 'Rename the flag to this key')
-        .option('--description <desc>', 'Description')
-        .option('--state <state>', `Three-state model: ${FLAG_STATES.join(' | ')}`)
-        .option('--value-type <type>', `Flag value type: ${FLAG_VALUE_TYPES.join(' | ')}`)
-        .option('--on-value <value>', 'Value returned when state=on (parsed per --value-type)')
-        .option('--off-value <value>', 'Value returned when state=off (parsed per --value-type)')
-        .option('--rule <json>', 'Rule as a JSON string (must validate via validateRule)')
-        .option('--clear-rule', 'Remove the existing rule')
-        // Legacy 1.0
-        .option('--enabled <bool>', 'Legacy: enable/disable', (v) => v === 'true')
-        .option('--default-value <bool>', 'Legacy: default value', (v) => v === 'true')
-        .action(async (opts) => {
-        try {
-            // TBP-586. `--key` is overloaded here for backwards compatibility:
-            // before key-addressing existed, `flag update --id X --key Y` renamed
-            // the flag to Y, and that still works. So `--key` means "address this
-            // flag" only when `--id` is absent; alongside `--id` it keeps its old
-            // rename meaning. `--new-key` renames in either addressing mode.
-            const addressedById = opts.id !== undefined;
-            const renameTo = opts.newKey !== undefined
-                ? opts.newKey
-                : (addressedById ? opts.key : undefined);
-            const id = await resolveFlagId({
-                id: opts.id,
-                key: addressedById ? undefined : opts.key,
-            });
-            const payload = buildFlagWritePayload({ ...opts, key: renameTo }, { partial: true });
-            if (opts.clearRule) {
-                payload.rule = null;
-            }
-            const flag = await getManagementClient().flags.update(id, payload);
-            outputSuccess(await withFlagWarnings(flag));
-        }
-        catch (err) {
-            outputError(err);
-        }
-    });
-}
-// ── toggle (kept from 1.0; convenience for state on/off without typing JSON) ─
-//
-// TBP-548. The command used to call `flags.toggle()`, which PUT the FF 1.0
-// `{ enabled }` boolean. FF 2.0 dropped that field from the flag document and
-// evaluates on `state` alone, and the server's write DTO strips undeclared
-// keys — so the body arrived empty, the API answered 200 with the untouched
-// flag, and the CLI printed `success: true` for a flag that had not moved.
-//
-// The mapping below is the one the MCP `toggle_feature_flag` tool settled on
-// (TBP-587), so the two surfaces over the same endpoint agree:
-//
-//   --enabled true   → state "on"    (everyone gets onValue)
-//   --enabled false  → state "off"   (everyone gets offValue)
-//
-// with one refusal: a flag already at "on-with-rule" is not turned ON here.
-// "on" stops the rule being consulted and hands onValue to every caller, which
-// widens the audience instead of flipping a switch — `flag update --state on`
-// is where you say that deliberately. Turning such a flag OFF stays allowed:
-// the rule document is preserved, so it is reversible.
-/** Error carrying a machine-readable `code` for `outputError` to report. */
-class FlagCommandError extends Error {
-    code;
-    constructor(code, message) {
-        super(message);
-        this.name = 'FlagCommandError';
-        this.code = code;
-    }
-}
-function registerToggle(flag) {
-    flag
-        .command('toggle')
-        .description('Quick toggle a flag on or off by --key or --id — sets state=on / state=off (the rule is kept)')
-        .option('--key <key>', 'Flag key to address (alternative to --id)')
-        .option('--id <id>', 'Flag ID to address (alternative to --key)')
-        .requiredOption('--enabled <bool>', 'true = state on, false = state off', (v) => v === 'true')
-        .action(async (opts) => {
-        try {
-            const enabled = opts.enabled;
-            const current = await resolveFlag({ id: opts.id, key: opts.key });
-            const currentState = current.state ?? deriveState(current);
-            if (currentState === 'on-with-rule' && enabled) {
-                throw new FlagCommandError('FLAG_HAS_TARGETING', `Flag '${current.key}' is state=on-with-rule: a targeting rule decides who gets it. ` +
-                    'Turning it fully on would give it to everyone and stop the rule being consulted, ' +
-                    'so nothing was changed. It is already on for whoever the rule matches. To widen it ' +
-                    'to everyone deliberately, run `bridge flag update --key ' +
-                    `${current.key} --state on\` (the rule is preserved and you can set it back to ` +
-                    'on-with-rule later).');
-            }
-            const wanted = enabled ? 'on' : 'off';
-            const result = await getManagementClient().flags.update(current.id, { state: wanted });
-            // Read the write back rather than trusting the 200. The original bug
-            // was invisible precisely because nobody checked that it landed.
-            const resultingState = result?.state ?? (result ? deriveState(result) : undefined);
-            if (resultingState !== wanted) {
-                throw new FlagCommandError('TOGGLE_NOT_APPLIED', `Requested state='${wanted}' for '${current.key}' but the flag came back as ` +
-                    `state='${resultingState ?? 'unknown'}'. The change did NOT take effect. ` +
-                    'Re-read it with `bridge flag get ' +
-                    `${current.key}\`, then set the state explicitly with \`bridge flag update\`.`);
-            }
-            outputSuccess(await withFlagWarnings(result));
-        }
-        catch (err) {
-            outputError(err);
-        }
-    });
-}
-// ── delete ──────────────────────────────────────────────────────────────────
-function registerDelete(flag) {
-    flag
-        .command('delete')
-        .description('Delete a feature flag by --key or --id')
-        .option('--key <key>', 'Flag key to address (alternative to --id)')
-        .option('--id <id>', 'Flag ID to address (alternative to --key)')
-        .option('--dry-run', 'Show what deleting it would do, and delete nothing')
-        .action(async (opts) => {
-        try {
-            const id = await resolveFlagId({ id: opts.id, key: opts.key });
-            if (opts.dryRun) {
-                outputSuccess(await dryRunPreview(`/v1/admin/flags/flag/${encodeURIComponent(id)}`));
-                return;
-            }
-            await getManagementClient().flags.delete(id);
-            outputSuccess({ deleted: true, id });
-        }
-        catch (err) {
-            outputError(err);
-        }
-    });
-}
-// ── eval (local SDK-style evaluation, for debugging) ────────────────────────
-function registerEval(flag) {
-    flag
-        .command('eval')
-        .argument('<key>', 'Flag key')
-        .description('Locally evaluate a flag against a synthetic context (debug helper)')
-        .option('--identity <id>', 'Eval identity (required when rolloutPct < 100)')
-        .option('--attribute <kv...>', 'One or more key=value attributes (use multiple flags or space-separate)')
-        .action(async (key, opts) => {
-        try {
-            const all = await getManagementClient().flags.list();
-            const found = all.find((f) => f.key === key);
-            if (!found) {
-                outputError(new Error(`Flag not found: ${key}`));
-                return;
-            }
-            const attributes = parseAttributes(opts.attribute ?? []);
-            const ctx = { identity: opts.identity, attributes };
-            const cached = {
-                key: found.key,
-                state: found.state ?? deriveState(found),
-                valueType: found.valueType ?? 'boolean',
-                offValue: found.offValue ?? false,
-                onValue: found.onValue ?? true,
-                // `FlagResponse.rule` is the canonical auth-core `Rule` — no
-                // bridging cast needed (TBP-236).
-                rule: found.rule ?? undefined,
-            };
-            const result = evaluateLocally(cached, ctx);
-            // TBP-709 — same coherence warnings as the MCP evaluate_feature_flag.
-            const [warnings] = await warningsForFlags([cached]);
-            outputSuccess({
-                flag: cached.key,
-                state: cached.state,
-                context: ctx,
-                result,
-                warnings,
-            });
-        }
-        catch (err) {
-            outputError(err);
-        }
-    });
-}
-// ── schedule ────────────────────────────────────────────────────────────────
-function registerSchedule(flag) {
-    const schedule = flag
-        .command('schedule')
-        .description('Manage scheduled state changes (TBP-189 — runner not yet active)');
-    schedule
-        .command('set')
-        .argument('<key>', 'Flag key')
-        .description('Schedule a state transition at an ISO timestamp')
-        .requiredOption('--at <iso>', 'ISO-8601 timestamp (e.g. 2026-05-20T09:00:00Z)')
-        .requiredOption('--state <state>', `Target state: ${FLAG_STATES.join(' | ')}`)
-        .action(async (key, opts) => {
-        try {
-            if (!FLAG_STATES.includes(opts.state)) {
-                throw new Error(`Invalid --state: ${opts.state}. Must be one of ${FLAG_STATES.join(', ')}.`);
-            }
-            const at = new Date(opts.at);
-            if (Number.isNaN(at.getTime())) {
-                throw new Error(`Invalid --at: ${opts.at} is not a valid ISO-8601 timestamp.`);
-            }
-            const id = await resolveFlagId({ key });
-            const schedule = { at: at.toISOString(), state: opts.state };
-            const update = { schedule };
-            const result = await getManagementClient().flags.update(id, update);
-            outputSuccess(result);
-        }
-        catch (err) {
-            outputError(err);
-        }
-    });
-    schedule
-        .command('clear')
-        .argument('<key>', 'Flag key')
-        .description('Clear an existing schedule')
-        .action(async (key) => {
-        try {
-            const id = await resolveFlagId({ key });
-            const update = { schedule: null };
-            const result = await getManagementClient().flags.update(id, update);
-            outputSuccess(result);
-        }
-        catch (err) {
-            outputError(err);
-        }
-    });
-}
-/** Build the canonical, portable doc from a remote flag record. Pure. */
-export function toFlagDoc(f) {
-    return {
-        key: f.key,
-        description: f.description,
-        state: f.state ?? deriveState(f),
-        valueType: f.valueType ?? 'boolean',
-        offValue: f.offValue,
-        onValue: f.onValue,
-        rule: f.rule,
-        schedule: f.schedule,
-    };
-}
-/** Build a create/update write payload from a doc. Pure. */
-export function buildWritePayloadFromDoc(doc) {
-    const payload = {
-        key: doc.key,
-        state: doc.state,
-        valueType: doc.valueType,
+import { readFile } from 'node:fs/promises';
+import { InvalidArgumentError } from 'commander';
+import { FLAG_STATES, VALUE_TYPES, flags, parseCondition, parseRule, parseValue } from '../api/flags.js';
+import { CliError } from '../core/errors.js';
+import { action, collect } from './context.js';
+function oneOf(list, what) {
+    return (value) => {
+        if (!list.includes(value))
+            throw new InvalidArgumentError(`${what} is one of ${list.join(', ')}.`);
+        return value;
     };
-    if (doc.description !== undefined)
-        payload.description = doc.description;
-    if (doc.offValue !== undefined)
-        payload.offValue = doc.offValue;
-    if (doc.onValue !== undefined)
-        payload.onValue = doc.onValue;
-    if (doc.rule !== undefined)
-        payload.rule = doc.rule;
-    if (doc.schedule !== undefined)
-        payload.schedule = doc.schedule;
-    return payload;
 }
-/** Validate + normalize a doc parsed from a file. Throws on the first problem. */
-export function validateFlagDoc(input, index) {
-    if (!input || typeof input !== 'object') {
-        throw new Error(`flags[${index}] must be an object.`);
-    }
-    const d = input;
-    if (typeof d.key !== 'string' || d.key.length === 0) {
-        throw new Error(`flags[${index}] is missing a non-empty "key".`);
-    }
-    const state = d.state ?? 'off';
-    if (!FLAG_STATES.includes(state)) {
-        throw new Error(`flags[${index}] ("${d.key}") invalid state "${String(d.state)}". One of ${FLAG_STATES.join(', ')}.`);
-    }
-    const valueType = d.valueType ?? 'boolean';
-    if (!FLAG_VALUE_TYPES.includes(valueType)) {
-        throw new Error(`flags[${index}] ("${d.key}") invalid valueType "${String(d.valueType)}". One of ${FLAG_VALUE_TYPES.join(', ')}.`);
-    }
-    let rule = d.rule;
-    if (d.rule !== undefined && d.rule !== null) {
-        let normalized;
-        try {
-            normalized = normalizeRuleInput(d.rule);
-        }
-        catch (err) {
-            throw new Error(`flags[${index}] ("${d.key}") rule failed validation:\n  - ${err instanceof Error ? err.message : String(err)}`);
-        }
-        const errs = validateRule(normalized);
-        if (errs.length > 0) {
-            throw new Error(`flags[${index}] ("${d.key}") rule failed validation:\n${errs.map((e) => `  - ${e.message}`).join('\n')}`);
-        }
-        rule = normalized;
-    }
+function percent(value) {
+    const n = Number(value);
+    if (!Number.isFinite(n) || n < 0 || n > 100)
+        throw new InvalidArgumentError('A share from 0 to 100.');
+    return n;
+}
+async function ruleFrom(opts) {
+    if (opts.rule !== undefined && opts.ruleFile !== undefined)
+        throw new CliError('invalid', 'Give the rule with --rule or --rule-file, not both.');
+    if (opts.rule !== undefined)
+        return parseRule(opts.rule);
+    if (opts.ruleFile !== undefined)
+        return parseRule(await readFile(opts.ruleFile, 'utf8'));
+    return undefined;
+}
+const withFlagOptions = (cmd) => cmd
+    .option('--description <text>', 'What the flag gates')
+    .option('--on-value <value>', 'The value while it is on (default true)')
+    .option('--off-value <value>', 'The value while it is off (default false)')
+    .option('--state <state>', `${FLAG_STATES.join(' | ')}`, oneOf(FLAG_STATES, '--state'))
+    .option('--rule <json>', 'The rule as JSON: { "branches": [...], "otherwiseValue": … }')
+    .option('--rule-file <file>', 'The rule from a JSON file')
+    .option('--when <condition>', 'A condition of a one-branch rule, "<attribute> <operator> <value>", such as "privileges contains USER_WRITE"; repeat to AND them', collect)
+    .option('--rollout <percent>', 'With --when: only this share of the people it matches', percent)
+    .option('--public', 'Visitors who are not signed in may read it');
+/** A one-branch rule from `--when` conditions: matches give the on value, everyone else the off value. */
+function whenRule(conditions, onValue, offValue, rollout) {
     return {
-        key: d.key,
-        description: d.description,
-        state,
-        valueType,
-        offValue: d.offValue,
-        onValue: d.onValue,
-        rule,
-        schedule: d.schedule,
+        branches: [{ conditions: conditions.map(parseCondition), returnValue: onValue, ...(rollout === undefined ? {} : { rolloutPct: rollout }) }],
+        otherwiseValue: offValue,
     };
 }
-const DOC_FIELDS = [
-    'description',
-    'state',
-    'valueType',
-    'offValue',
-    'onValue',
-    'rule',
-    'schedule',
-];
-function docChanges(a, b) {
-    return DOC_FIELDS.filter((f) => JSON.stringify(a[f] ?? null) !== JSON.stringify(b[f] ?? null));
-}
-/** Diff file docs against remote flags (matched by key). Pure. */
-export function diffFlags(remote, docs, opts = {}) {
-    const byKey = new Map(remote.map((f) => [f.key, f]));
-    const fileKeys = new Set(docs.map((d) => d.key));
-    const diff = { create: [], update: [], prune: [], unchanged: [] };
-    for (const doc of docs) {
-        const r = byKey.get(doc.key);
-        if (!r) {
-            diff.create.push(doc);
-            continue;
-        }
-        const changes = docChanges(toFlagDoc(r), doc);
-        if (changes.length === 0)
-            diff.unchanged.push(doc.key);
-        else
-            diff.update.push({ id: r.id, doc, changes });
-    }
-    if (opts.prune) {
-        for (const r of remote) {
-            if (!fileKeys.has(r.key)) {
-                diff.prune.push({ id: r.id, key: r.key });
-            }
-        }
-    }
-    return diff;
-}
-function registerExport(flag) {
-    flag
-        .command('export')
-        .description('Export all feature flags as code (canonical 2.0 JSON)')
-        .option('--out <file>', 'Write to a file instead of stdout')
-        .action(async (opts) => {
-        try {
-            const all = (await getManagementClient().flags.list());
-            const flags = all.map(toFlagDoc).sort((a, b) => a.key.localeCompare(b.key));
-            const bundle = { version: 1, flags };
-            if (opts.out) {
-                writeFileSync(opts.out, JSON.stringify(bundle, null, 2) + '\n', 'utf8');
-                outputSuccess({ written: opts.out, count: flags.length });
-            }
-            else {
-                outputSuccess(bundle);
-            }
-        }
-        catch (err) {
-            outputError(err);
-        }
-    });
-}
-function registerImport(flag) {
-    flag
-        .command('import')
-        .argument('<file>', 'Path to a flags JSON file (from `flag export`)')
-        .description('Apply feature flags from a file (create + update; --prune deletes extras)')
-        .option('--dry-run', 'Show the diff without applying any changes', false)
-        .option('--prune', 'Delete remote flags not present in the file', false)
-        .action(async (file, opts) => {
-        try {
-            let raw;
-            try {
-                raw = JSON.parse(readFileSync(file, 'utf8'));
-            }
-            catch (err) {
-                throw new Error(`Could not read/parse ${file}: ${err instanceof Error ? err.message : String(err)}`);
-            }
-            const list = Array.isArray(raw) ? raw : raw.flags;
-            if (!Array.isArray(list)) {
-                throw new Error('File must be an array of flags or an object with a "flags" array.');
-            }
-            const docs = list.map((d, i) => validateFlagDoc(d, i));
-            const remote = (await getManagementClient().flags.list());
-            const diff = diffFlags(remote, docs, { prune: opts.prune });
-            if (opts.dryRun) {
-                outputSuccess({
-                    dryRun: true,
-                    create: diff.create.map((d) => d.key),
-                    update: diff.update.map((u) => ({ key: u.doc.key, changes: u.changes })),
-                    prune: diff.prune.map((p) => p.key),
-                    unchanged: diff.unchanged,
-                });
-                return;
-            }
-            const mgmt = getManagementClient();
-            for (const doc of diff.create) {
-                await mgmt.flags.create(buildWritePayloadFromDoc(doc));
-            }
-            for (const u of diff.update) {
-                await mgmt.flags.update(u.id, buildWritePayloadFromDoc(u.doc));
-            }
-            for (const p of diff.prune) {
-                await mgmt.flags.delete(p.id);
-            }
-            outputSuccess({
-                created: diff.create.map((d) => d.key),
-                updated: diff.update.map((u) => u.doc.key),
-                pruned: diff.prune.map((p) => p.key),
-                unchanged: diff.unchanged,
-            });
-        }
-        catch (err) {
-            outputError(err);
-        }
-    });
-}
-export function buildFlagWritePayload(opts, { partial = false } = {}) {
-    const payload = {};
-    if (opts.key !== undefined)
-        payload.key = opts.key;
-    if (opts.description !== undefined)
-        payload.description = opts.description;
-    if (opts.state !== undefined) {
-        if (!FLAG_STATES.includes(opts.state)) {
-            throw new Error(`Invalid --state: ${opts.state}. Must be one of ${FLAG_STATES.join(', ')}.`);
-        }
-        payload.state = opts.state;
-    }
-    let valueType;
-    if (opts.valueType !== undefined) {
-        if (!FLAG_VALUE_TYPES.includes(opts.valueType)) {
-            throw new Error(`Invalid --value-type: ${opts.valueType}. Must be one of ${FLAG_VALUE_TYPES.join(', ')}.`);
-        }
-        valueType = opts.valueType;
-        payload.valueType = valueType;
-    }
-    if (opts.onValue !== undefined) {
-        payload.onValue = coerceValue(opts.onValue, valueType ?? 'boolean');
-    }
-    if (opts.offValue !== undefined) {
-        payload.offValue = coerceValue(opts.offValue, valueType ?? 'boolean');
-    }
-    if (opts.rule !== undefined) {
-        const parsed = parseRuleArg(opts.rule);
-        payload.rule = parsed;
-    }
-    // Legacy fields. In partial (update) mode, only include if explicitly set —
-    // commander returns `false` as default for boolean flags, which would
-    // otherwise clobber server state on every update.
-    if (!partial || opts.enabled !== undefined) {
-        if (opts.enabled !== undefined)
-            payload.enabled = opts.enabled;
-    }
-    if (!partial || opts.defaultValue !== undefined) {
-        if (opts.defaultValue !== undefined)
-            payload.defaultValue = opts.defaultValue;
-    }
-    return payload;
-}
-export function coerceValue(raw, type) {
-    switch (type) {
-        case 'boolean':
-            if (raw === 'true')
-                return true;
-            if (raw === 'false')
-                return false;
-            throw new Error(`Invalid boolean value "${raw}" — expected "true" or "false".`);
-        case 'number': {
-            const n = Number(raw);
-            if (!Number.isFinite(n))
-                throw new Error(`Invalid number value "${raw}".`);
-            return n;
-        }
-        case 'string':
-            return raw;
-        case 'json':
-            try {
-                return JSON.parse(raw);
-            }
-            catch (err) {
-                throw new Error(`Invalid JSON value: ${err instanceof Error ? err.message : String(err)}`);
-            }
-    }
-}
-export function parseRuleArg(raw) {
-    let parsed;
-    try {
-        parsed = JSON.parse(raw);
-    }
-    catch (err) {
-        throw new Error(`--rule must be valid JSON. Parse error: ${err instanceof Error ? err.message : String(err)}`);
-    }
-    let rule;
-    try {
-        rule = normalizeRuleInput(parsed);
-    }
-    catch (err) {
-        throw new Error(`--rule failed validation:\n  - ${err instanceof Error ? err.message : String(err)}`);
-    }
-    const errors = validateRule(rule);
-    if (errors.length > 0) {
-        throw new Error(`--rule failed validation:\n${errors.map((e) => `  - ${e.message}`).join('\n')}`);
-    }
-    return rule;
-}
-// ── Parse-time rule normalization (TBP-236) ─────────────────────────────────
-//
-// The CLI historically accepted conditions of shape { attribute, operator,
-// value } with operator names like 'equals' / 'starts_with' / 'gte'. The
-// canonical auth-core format is { attribute, operator, values: [...] } with
-// the locked operator vocabulary in `OPERATORS`. `normalizeRuleInput` migrates
-// legacy input to the canonical shape at parse time:
-//   - scalar `value` → plural `values` array (`"value": "pro"` → `values: ["pro"]`)
-//   - legacy operator names → canonical ones (deprecation warning on stderr)
-// Structurally invalid input (non-object rule, missing otherwiseValue, ...)
-// throws; unknown operators are passed through for `validateRule` to report.
-/** Legacy operator names that map 1:1 onto a canonical operator. */
-const LEGACY_OPERATOR_ALIASES = {
-    equals: 'eq',
-    equal: 'eq',
-    not_equals: 'neq',
-    not_equal: 'neq',
-    notEquals: 'neq',
-    does_not_contain: 'not_contains',
-    notContains: 'not_contains',
-    greater_than: 'gt',
-    greaterThan: 'gt',
-    less_than: 'lt',
-    lessThan: 'lt',
-    matches: 'regex',
-};
-function warnDeprecatedOperator(legacy, canonical, note) {
-    process.stderr.write(`Warning: rule operator "${legacy}" is deprecated; mapped to "${canonical}"${note ? ` (${note})` : ''}. ` +
-        `Canonical operators: ${OPERATORS.join(', ')}.\n`);
-}
-function escapeRegExp(s) {
-    return s.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
-}
-/**
- * Map a (possibly legacy) operator name + values to the canonical vocabulary.
- * Some legacy operators have no 1:1 canonical equivalent and are rewritten
- * with adjusted values:
- *   starts_with x → regex ^x        ends_with x → regex x$
- *   gte x         → between [x, Number.MAX_VALUE]
- *   lte x         → between [-Number.MAX_VALUE, x]
- * Unknown names are passed through so validateRule reports them.
- */
-function resolveOperator(op, values) {
-    if (isOperator(op))
-        return { operator: op, values };
-    const alias = LEGACY_OPERATOR_ALIASES[op];
-    if (alias) {
-        warnDeprecatedOperator(op, alias);
-        return { operator: alias, values };
-    }
-    switch (op) {
-        case 'starts_with':
-        case 'startsWith':
-        case 'begins_with':
-        case 'beginsWith':
-            warnDeprecatedOperator(op, 'regex', 'value rewritten to an anchored ^… pattern');
-            return { operator: 'regex', values: [`^${escapeRegExp(String(values[0] ?? ''))}`] };
-        case 'ends_with':
-        case 'endsWith':
-            warnDeprecatedOperator(op, 'regex', 'value rewritten to an anchored …$ pattern');
-            return { operator: 'regex', values: [`${escapeRegExp(String(values[0] ?? ''))}$`] };
-        case 'gte':
-        case 'greater_than_or_equal':
-        case 'greaterThanOrEqual':
-            warnDeprecatedOperator(op, 'between', 'rewritten to between [value, Number.MAX_VALUE]');
-            return { operator: 'between', values: [values[0] ?? null, Number.MAX_VALUE] };
-        case 'lte':
-        case 'less_than_or_equal':
-        case 'lessThanOrEqual':
-            warnDeprecatedOperator(op, 'between', 'rewritten to between [-Number.MAX_VALUE, value]');
-            return { operator: 'between', values: [-Number.MAX_VALUE, values[0] ?? null] };
-        default:
-            // Unknown operator — pass through; validateRule will flag it.
-            return { operator: op, values };
-    }
-}
-function normalizeConditionInput(input, bi, ci) {
-    if (!input || typeof input !== 'object') {
-        throw new Error(`Branch ${bi} condition ${ci} must be an object.`);
-    }
-    const c = input;
-    if (typeof c.attribute !== 'string' || c.attribute.length === 0) {
-        throw new Error(`Branch ${bi} condition ${ci} missing 'attribute'.`);
-    }
-    if (typeof c.operator !== 'string' || c.operator.length === 0) {
-        throw new Error(`Branch ${bi} condition ${ci} missing 'operator'.`);
-    }
-    let values;
-    if (c.values !== undefined) {
-        if (!Array.isArray(c.values)) {
-            throw new Error(`Branch ${bi} condition ${ci} 'values' must be an array.`);
-        }
-        values = [...c.values];
-    }
-    else if ('value' in c) {
-        // Legacy singular `value` — migrate to plural `values` at parse time.
-        const v = c.value;
-        values = Array.isArray(v) ? [...v] : [v];
-    }
-    else {
-        values = [];
-    }
-    const resolved = resolveOperator(c.operator, values);
-    return { attribute: c.attribute, operator: resolved.operator, values: resolved.values };
-}
-/**
- * Normalize untrusted rule input (from --rule JSON or a flags file) to the
- * canonical auth-core `Rule` shape. Throws on structural problems; operator
- * validity is left to `validateRule` on the returned rule.
- */
-export function normalizeRuleInput(input) {
-    if (!input || typeof input !== 'object') {
-        throw new Error('Rule must be an object.');
-    }
-    const r = input;
-    if (!('otherwiseValue' in r)) {
-        throw new Error('Rule missing otherwiseValue.');
-    }
-    const rawBranches = r.branches ?? [];
-    if (!Array.isArray(rawBranches)) {
-        throw new Error('`branches` must be an array.');
-    }
-    const branches = rawBranches.map((branch, bi) => {
-        if (!branch || typeof branch !== 'object') {
-            throw new Error(`Branch ${bi} must be an object.`);
-        }
-        const b = branch;
-        if (!('returnValue' in b)) {
-            throw new Error(`Branch ${bi} is missing returnValue.`);
-        }
-        const rawConds = b.conditions ?? [];
-        if (!Array.isArray(rawConds)) {
-            throw new Error(`Branch ${bi} 'conditions' must be an array.`);
-        }
-        return {
-            conditions: rawConds.map((c, ci) => normalizeConditionInput(c, bi, ci)),
-            returnValue: b.returnValue,
+async function ruleOption(opts, onValue, offValue) {
+    const given = await ruleFrom(opts);
+    if (opts.when !== undefined) {
+        if (given !== undefined)
+            throw new CliError('invalid', 'Give the rule with --when or with --rule / --rule-file, not both.');
+        return whenRule(opts.when, onValue, offValue, opts.rollout);
+    }
+    if (opts.rollout !== undefined)
+        throw new CliError('invalid', '--rollout goes with --when.');
+    return given;
+}
+/** The state a rule change leaves the flag in: the rule runs, unless the flag is switched off. */
+function stateWithRule(flag) {
+    return flag.state === 'off' ? 'off' : 'on-with-rule';
+}
+function noteIfOff(ctx, flag) {
+    if (flag.state === 'off')
+        ctx.io.info(`${flag.key} is off, so its rule does not run yet. \`bridge flag restore ${flag.key}\` or \`bridge flag update ${flag.key} --state on-with-rule\` turns it on.`);
+}
+export function registerFlagCommands(program, deps) {
+    const flag = program.command('flag').description('Feature flags and their rules: every gate in app code is a flag');
+    flag.command('list').description('The app\'s flags').action(action(deps, async (ctx) => {
+        const { c, appId } = await ctx.forApp();
+        ctx.io.result(await flags.list(c, appId));
+    }));
+    flag.command('get <key>').description('One flag, with its rule').action(action(deps, async (ctx, key) => {
+        const { c, appId } = await ctx.forApp();
+        ctx.io.result(await flags.get(c, appId, key));
+    }));
+    withFlagOptions(flag.command('create <key>').description('Create a flag').option('--type <type>', `The values' type: ${VALUE_TYPES.join(' | ')} (default boolean)`, oneOf(VALUE_TYPES, '--type'))).action(action(deps, async (ctx, key, opts) => {
+        const type = opts.type ?? 'boolean';
+        const onValue = opts.onValue === undefined ? (type === 'boolean' ? true : undefined) : parseValue(opts.onValue, type);
+        const offValue = opts.offValue === undefined ? (type === 'boolean' ? false : undefined) : parseValue(opts.offValue, type);
+        if (onValue === undefined || offValue === undefined)
+            throw new CliError('invalid', `A ${type} flag needs --on-value and --off-value.`);
+        const rule = await ruleOption(opts, onValue, offValue);
+        const fields = {
+            key,
+            valueType: type,
+            onValue,
+            offValue,
+            state: opts.state ?? (rule === undefined ? 'off' : 'on-with-rule'),
+            ...(rule === undefined ? {} : { rule }),
+            ...(opts.description === undefined ? {} : { description: opts.description }),
+            ...(opts.public === undefined ? {} : { public: opts.public }),
         };
-    });
-    const rule = {
-        branches,
-        otherwiseValue: r.otherwiseValue,
-        // Canonical `Rule` carries rolloutPct explicitly; default to 100 (full
-        // rollout) when the input omits it. Out-of-range values are kept so
-        // validateRule reports them.
-        rolloutPct: r.rolloutPct === undefined ? 100 : r.rolloutPct,
-    };
-    if (typeof r.groupRef === 'string' && r.groupRef.length > 0) {
-        rule.groupRef = r.groupRef;
-    }
-    return rule;
-}
-export function parseAttributes(pairs) {
-    const out = {};
-    for (const pair of pairs) {
-        const idx = pair.indexOf('=');
-        if (idx === -1)
-            throw new Error(`Invalid --attribute "${pair}" — expected key=value.`);
-        const key = pair.slice(0, idx);
-        const raw = pair.slice(idx + 1);
-        // Try to parse as JSON first (covers numbers, booleans, structured); fall
-        // back to the raw string.
-        try {
-            out[key] = JSON.parse(raw);
-        }
-        catch {
-            out[key] = raw;
-        }
-    }
-    return out;
-}
-// ── Local evaluator (delegates to auth-core's canonical evaluator) ──────────
-export function evaluateLocally(cached, ctx) {
-    switch (cached.state) {
-        case 'off':
-            return {
-                value: cached.offValue,
-                variantIndex: -1,
-                matched: false,
-                excludedByRollout: false,
+        const { c, appId } = await ctx.forApp();
+        ctx.io.result(await flags.create(c, appId, fields));
+    }));
+    withFlagOptions(flag.command('update <key>').description('Change a flag').option('--new-key <key>', 'Rename it').option('--private', 'Only signed-in people may read it')).action(action(deps, async (ctx, key, opts) => {
+        const given = await ruleFrom(opts);
+        if (opts.when !== undefined && given !== undefined)
+            throw new CliError('invalid', 'Give the rule with --when or with --rule / --rule-file, not both.');
+        if (opts.rollout !== undefined && opts.when === undefined)
+            throw new CliError('invalid', '--rollout goes with --when.');
+        const { c, appId } = await ctx.forApp();
+        const changed = await flags.update(c, appId, key, (current) => {
+            const onValue = opts.onValue === undefined ? current.onValue : parseValue(opts.onValue, current.valueType);
+            const offValue = opts.offValue === undefined ? current.offValue : parseValue(opts.offValue, current.valueType);
+            const rule = opts.when === undefined ? given : whenRule(opts.when, onValue, offValue, opts.rollout);
+            const fields = {
+                ...(opts.newKey === undefined ? {} : { key: opts.newKey }),
+                ...(opts.description === undefined ? {} : { description: opts.description }),
+                ...(opts.onValue === undefined ? {} : { onValue }),
+                ...(opts.offValue === undefined ? {} : { offValue }),
+                ...(opts.public ? { public: true } : opts.private ? { public: false } : {}),
+                ...(rule === undefined ? {} : { rule }),
             };
-        case 'on':
-            return {
-                value: cached.onValue,
-                variantIndex: 0,
-                matched: true,
-                excludedByRollout: false,
+            const state = opts.state ?? (rule === undefined ? undefined : stateWithRule(current));
+            if (state !== undefined)
+                fields.state = state;
+            if (Object.keys(fields).length === 0)
+                throw new CliError('invalid', 'Nothing to change.');
+            return fields;
+        });
+        if (given !== undefined || opts.when !== undefined)
+            noteIfOff(ctx, changed);
+        ctx.io.result(changed);
+    }));
+    flag.command('on <key>').description('Everyone gets the on value').action(action(deps, async (ctx, key) => {
+        const { c, appId } = await ctx.forApp();
+        ctx.io.result(await flags.update(c, appId, key, { state: 'on' }));
+    }));
+    flag.command('off <key>').description('Switch the flag off (the kill switch). Its rule is kept, and `restore` brings it back').action(action(deps, async (ctx, key) => {
+        const { c, appId } = await ctx.forApp();
+        ctx.io.result(await flags.kill(c, appId, key));
+    }));
+    flag.command('restore <key>').description('Undo `off`: the flag goes back to what it was').action(action(deps, async (ctx, key) => {
+        const { c, appId } = await ctx.forApp();
+        ctx.io.result(await flags.restore(c, appId, key));
+    }));
+    flag
+        .command('delete <key>')
+        .requiredOption('--yes', 'Confirm')
+        .action(action(deps, async (ctx, key) => {
+        const { c, appId } = await ctx.forApp();
+        ctx.io.result(await flags.remove(c, appId, key));
+    }));
+    const rule = flag.command('rule').description('A flag\'s rule: ordered branches of AND-ed conditions, the first match wins');
+    rule.command('show <key>').action(action(deps, async (ctx, key) => {
+        const { c, appId } = await ctx.forApp();
+        const found = await flags.get(c, appId, key);
+        ctx.io.result({ key: found.key, state: found.state, rule: found.rule });
+    }));
+    rule
+        .command('set <key>')
+        .description('Replace the rule, from --rule or --rule-file')
+        .option('--rule <json>', 'The rule as JSON')
+        .option('--rule-file <file>', 'The rule from a JSON file')
+        .action(action(deps, async (ctx, key, opts) => {
+        const given = await ruleFrom(opts);
+        if (given === undefined)
+            throw new CliError('invalid', 'Give the rule with --rule or --rule-file.');
+        const { c, appId } = await ctx.forApp();
+        const changed = await flags.update(c, appId, key, (current) => ({ rule: given, state: stateWithRule(current) }));
+        noteIfOff(ctx, changed);
+        ctx.io.result(changed);
+    }));
+    rule
+        .command('add <key>')
+        .description('Add a branch to the rule: people matching every --when condition get --value (default: the on value)')
+        .requiredOption('--when <condition>', '"<attribute> <operator> <value>", such as "bridge:billing.entitlement.analytics eq true"; repeat to AND them', collect)
+        .option('--value <value>', 'What the branch gives')
+        .option('--rollout <percent>', 'Only this share of the people it matches', percent)
+        .option('--first', 'Put the branch first instead of last')
+        .action(action(deps, async (ctx, key, opts) => {
+        const conditions = opts.when.map(parseCondition);
+        const { c, appId } = await ctx.forApp();
+        const changed = await flags.update(c, appId, key, (current) => {
+            const branch = {
+                conditions,
+                returnValue: opts.value === undefined ? current.onValue : parseValue(opts.value, current.valueType),
+                ...(opts.rollout === undefined ? {} : { rolloutPct: opts.rollout }),
             };
-        case 'on-with-rule':
-            if (!cached.rule) {
-                return {
-                    value: cached.onValue,
-                    variantIndex: -1,
-                    matched: false,
-                    excludedByRollout: false,
-                };
-            }
-            return evaluateRule(cached.rule, cached.key, ctx);
-    }
-}
-// ── Helpers ─────────────────────────────────────────────────────────────────
-/**
- * Derive a 2.0 state from a legacy 1.0 flag shape. Used so `flag list` /
- * `flag get` always show a state column, even against an older bridge-api
- * that has not yet rolled out 2.0 fields.
- */
-function deriveState(f) {
-    if (typeof f.state === 'string' && FLAG_STATES.includes(f.state)) {
-        return f.state;
-    }
-    if (f.enabled === false)
-        return 'off';
-    const segs = f.segments ?? [];
-    return segs.length > 0 ? 'on-with-rule' : 'on';
+            const existing = current.rule ?? { branches: [], otherwiseValue: current.offValue };
+            const branches = opts.first ? [branch, ...existing.branches] : [...existing.branches, branch];
+            return { rule: { ...existing, branches }, state: stateWithRule(current) };
+        });
+        noteIfOff(ctx, changed);
+        ctx.io.result(changed);
+    }));
+    rule.command('clear <key>').description('Remove the rule: while on, everyone gets the on value').action(action(deps, async (ctx, key) => {
+        const { c, appId } = await ctx.forApp();
+        ctx.io.result(await flags.update(c, appId, key, (current) => ({ rule: null, ...(current.state === 'on-with-rule' ? { state: 'on' } : {}) })));
+    }));
 }
 //# sourceMappingURL=flag.command.js.map