@quonfig/cli 0.0.54 → 0.0.57

package/dist/commands/cleanup/list.js

@@ -0,0 +1,157 @@
+import { Flags } from '@oclif/core';
+import { getEnvironments } from '../../api/get-environments.js';
+import { APICommand } from '../../index.js';
+function startOfDayUtcMs(date) {
+    return Date.UTC(date.getUTCFullYear(), date.getUTCMonth(), date.getUTCDate());
+}
+function deriveWindows(daysAgoByKey, key) {
+    const buckets = daysAgoByKey.get(key) ?? new Map();
+    let evals_24h = 0;
+    let evals_2d = 0;
+    let evals_7d = 0;
+    let evals_30d = 0;
+    let mostRecentDayAgo = null;
+    for (const [daysAgo, count] of buckets) {
+        if (count <= 0)
+            continue;
+        if (daysAgo === 0)
+            evals_24h += count;
+        if (daysAgo <= 1)
+            evals_2d += count;
+        if (daysAgo <= 6)
+            evals_7d += count;
+        if (daysAgo <= 29)
+            evals_30d += count;
+        if (mostRecentDayAgo === null || daysAgo < mostRecentDayAgo) {
+            mostRecentDayAgo = daysAgo;
+        }
+    }
+    let last_eval = null;
+    if (mostRecentDayAgo !== null) {
+        const ms = startOfDayUtcMs(new Date()) - mostRecentDayAgo * 86_400_000;
+        last_eval = new Date(ms).toISOString().slice(0, 10);
+    }
+    return { evals_24h, evals_2d, evals_7d, evals_30d, last_eval };
+}
+export default class CleanupList extends APICommand {
+    static description = `List feature flags marked readyForCleanup=true, with eval volume per window.
+
+Columns:
+  KEY         the flag key
+  TYPE        the flag's valueType (bool, string, int, etc.)
+  EVALS_24H   evals counted in today's bucket (latest day)
+  EVALS_2D    evals in the last 2 calendar days
+  EVALS_7D    evals in the last 7 calendar days
+  EVALS_30D   evals in the last 30 calendar days
+  LAST_EVAL   most recent calendar day with any evals (UTC), blank if none
+  CLASS       quiet (zero evals in last 2 days) or active
+
+Default sort: quiet first, oldest LAST_EVAL at top.
+
+Pass --json for the structured object (rows[]). Each row carries the columns
+above plus the raw eval counts your agent can reason about itself.
+
+Once you've picked a candidate, run \`qfg cleanup status <key>\` for the
+drill-in or hand off the removal to the qfg-flag-cleanup Claude skill.`;
+    static examples = ['<%= config.bin %> <%= command.id %>', '<%= config.bin %> <%= command.id %> --json'];
+    static flags = {
+        json: Flags.boolean({ default: false, description: 'Return structured rows for agent consumption' }),
+    };
+    async run() {
+        const { flags } = await this.parse(CleanupList);
+        const metadataReq = await this.apiClient.post('/api/v1/metadata/list', { workspaceId: this.workspaceId });
+        if (!metadataReq.ok) {
+            const errorMsg = metadataReq.error?.error || `Failed to fetch configs: ${metadataReq.status}`;
+            return this.err(errorMsg, { serverError: metadataReq.error });
+        }
+        const metadata = metadataReq.json;
+        const readyFlags = metadata.configs.filter((c) => c.type === 'feature_flag' && c.readyForCleanup === true);
+        if (readyFlags.length === 0) {
+            this.log('No feature flags are marked readyForCleanup. Mark a flag in the UI to start the retirement workflow.');
+            if (flags.json) {
+                return { rows: [] };
+            }
+            return;
+        }
+        const environments = await getEnvironments(this);
+        // Per-env sparklines, aggregated client-side into a per-key (daysAgo → count) map.
+        const todayMs = startOfDayUtcMs(new Date());
+        const daysAgoByKey = new Map();
+        for (const env of environments) {
+            // eslint-disable-next-line no-await-in-loop
+            const req = await this.apiClient.post('/api/v1/analytics/sparklines', {
+                workspaceId: this.workspaceId,
+                environment: env.name,
+            });
+            if (!req.ok) {
+                this.verboseLog('cleanup list', `sparklines failed for env ${env.name}: ${req.status}`);
+                continue;
+            }
+            const resp = req.json;
+            for (const row of resp.rows ?? []) {
+                const bucket = daysAgoByKey.get(row.config_key) ?? new Map();
+                for (const [i, day] of row.days.entries()) {
+                    const count = row.counts[i] ?? 0;
+                    if (count <= 0)
+                        continue;
+                    // Day strings are YYYY-MM-DD in UTC (ClickHouse Date). Parsing as UTC midnight.
+                    const dayMs = Date.parse(`${day}T00:00:00Z`);
+                    if (Number.isNaN(dayMs))
+                        continue;
+                    const daysAgo = Math.round((todayMs - dayMs) / 86_400_000);
+                    bucket.set(daysAgo, (bucket.get(daysAgo) ?? 0) + count);
+                }
+                daysAgoByKey.set(row.config_key, bucket);
+            }
+        }
+        const rows = readyFlags.map((flag) => {
+            const windows = deriveWindows(daysAgoByKey, flag.key);
+            const klass = windows.evals_2d === 0 ? 'quiet' : 'active';
+            return {
+                key: flag.key,
+                type: flag.valueType,
+                ...windows,
+                class: klass,
+            };
+        });
+        // Safest-first sort: quiet before active; within each class, oldest last_eval first
+        // (null last_eval is "never seen" — sort to the top of the quiet group).
+        rows.sort((a, b) => {
+            if (a.class !== b.class)
+                return a.class === 'quiet' ? -1 : 1;
+            if (a.last_eval === b.last_eval)
+                return a.key.localeCompare(b.key);
+            if (a.last_eval === null)
+                return -1;
+            if (b.last_eval === null)
+                return 1;
+            return a.last_eval.localeCompare(b.last_eval);
+        });
+        if (flags.json) {
+            // Returning a JsonObj — the table-style printing below is skipped.
+            this.log(this.toSuccessJson({ rows }));
+            return { rows: rows };
+        }
+        // Plain-text table for human consumption.
+        const headers = ['KEY', 'TYPE', 'EVALS_24H', 'EVALS_2D', 'EVALS_7D', 'EVALS_30D', 'LAST_EVAL', 'CLASS'];
+        const cells = rows.map((r) => [
+            r.key,
+            r.type,
+            String(r.evals_24h),
+            String(r.evals_2d),
+            String(r.evals_7d),
+            String(r.evals_30d),
+            r.last_eval ?? '-',
+            r.class,
+        ]);
+        const widths = headers.map((h, i) => Math.max(h.length, ...cells.map((row) => row[i].length)));
+        const padRow = (row) => row.map((cell, i) => cell.padEnd(widths[i])).join('  ');
+        this.log(padRow(headers));
+        this.log(widths.map((w) => '-'.repeat(w)).join('  '));
+        for (const row of cells)
+            this.log(padRow(row));
+        this.log('');
+        this.log(`${rows.length} flag(s) marked readyForCleanup. Run \`qfg cleanup status <key>\` for drill-in.`);
+        return { rows: rows };
+    }
+}

package/dist/commands/cleanup/remove.d.ts

@@ -0,0 +1,13 @@
+import { APICommand } from '../../index.js';
+import { JsonObj } from '../../result.js';
+export default class CleanupRemove extends APICommand {
+    static args: {
+        name: import("@oclif/core/lib/interfaces/parser.js").Arg<string | undefined, Record<string, unknown>>;
+    };
+    static description: string;
+    static examples: string[];
+    static flags: {
+        force: import("@oclif/core/lib/interfaces/parser.js").BooleanFlag<boolean>;
+    };
+    run(): Promise<JsonObj | void>;
+}

package/dist/commands/cleanup/remove.js

@@ -0,0 +1,234 @@
+import { Flags } from '@oclif/core';
+import fs from 'node:fs';
+import path from 'node:path';
+import { APICommand } from '../../index.js';
+import { getAppUrl } from '../../util/domain-urls.js';
+import nameArg from '../../util/name-arg.js';
+const SKILL_NAME = 'qfg-flag-cleanup';
+const GITIGNORE_ENTRY = '.qf/cleanup/';
+// SDK client method names worth grepping for in the customer's codebase.
+// Based on the surfaces the official Quonfig SDKs expose (sdk-node /
+// sdk-javascript / sdk-react / sdk-go / sdk-ruby) plus the OpenFeature
+// wrappers. The skill consumes this list, the CLI doesn't run the grep
+// itself — keeping the lookup explicit lets a future SDK ship a new method
+// without breaking older payloads.
+const GREP_PATTERNS = [
+    'get',
+    'getBoolean',
+    'getString',
+    'getInt',
+    'getDouble',
+    'getStringList',
+    'getDuration',
+    'getJson',
+    'getLogLevel',
+    'isFeatureEnabled',
+    'booleanValue',
+    'stringValue',
+    'numberValue',
+    'objectValue',
+];
+function startOfDayUtcMs(date) {
+    return Date.UTC(date.getUTCFullYear(), date.getUTCMonth(), date.getUTCDate());
+}
+function summarizeSparklines(resp) {
+    const todayMs = startOfDayUtcMs(new Date());
+    // 4h is finer than the daily bucket the server returns; we approximate it
+    // as "today's bucket" (same window the UI sparkline popover shows). It will
+    // overlap evals_24h but stays distinct in the payload so the skill / agent
+    // can tell "any evals today" from "any evals in last 24 calendar hours".
+    let totalEvals4h = 0;
+    let totalEvals24h = 0;
+    let totalEvals2d = 0;
+    let totalEvals7d = 0;
+    let totalEvals30d = 0;
+    let overallLast = null;
+    const envSummaries = [];
+    for (const row of resp.rows ?? []) {
+        let envTotal = 0;
+        let envEvals4h = 0;
+        let envEvals24h = 0;
+        let envEvals2d = 0;
+        let envEvals7d = 0;
+        let envEvals30d = 0;
+        let envLastDayAgo = null;
+        for (const [i, day] of row.days.entries()) {
+            const count = row.counts[i] ?? 0;
+            if (count <= 0)
+                continue;
+            const dayMs = Date.parse(`${day}T00:00:00Z`);
+            if (Number.isNaN(dayMs))
+                continue;
+            const daysAgo = Math.round((todayMs - dayMs) / 86_400_000);
+            envTotal += count;
+            if (daysAgo === 0) {
+                envEvals4h += count;
+                envEvals24h += count;
+            }
+            if (daysAgo <= 1)
+                envEvals2d += count;
+            if (daysAgo <= 6)
+                envEvals7d += count;
+            if (daysAgo <= 29)
+                envEvals30d += count;
+            if (envLastDayAgo === null || daysAgo < envLastDayAgo)
+                envLastDayAgo = daysAgo;
+        }
+        const last_eval = envLastDayAgo === null ? null : new Date(todayMs - envLastDayAgo * 86_400_000).toISOString().slice(0, 10);
+        envSummaries.push({
+            environment: row.environment,
+            total: envTotal,
+            evals_4h: envEvals4h,
+            evals_24h: envEvals24h,
+            evals_2d: envEvals2d,
+            evals_7d: envEvals7d,
+            evals_30d: envEvals30d,
+            last_eval,
+        });
+        totalEvals4h += envEvals4h;
+        totalEvals24h += envEvals24h;
+        totalEvals2d += envEvals2d;
+        totalEvals7d += envEvals7d;
+        totalEvals30d += envEvals30d;
+        if (envLastDayAgo !== null && (overallLast === null || envLastDayAgo < overallLast)) {
+            overallLast = envLastDayAgo;
+        }
+    }
+    const last_eval = overallLast === null ? null : new Date(todayMs - overallLast * 86_400_000).toISOString().slice(0, 10);
+    return {
+        envSummaries,
+        totals: {
+            evals_4h: totalEvals4h,
+            evals_24h: totalEvals24h,
+            evals_2d: totalEvals2d,
+            evals_7d: totalEvals7d,
+            evals_30d: totalEvals30d,
+            last_eval,
+        },
+    };
+}
+function ensureGitignoreEntry(cwd) {
+    const gitignorePath = path.join(cwd, '.gitignore');
+    let existing = '';
+    if (fs.existsSync(gitignorePath)) {
+        existing = fs.readFileSync(gitignorePath, 'utf8');
+        const lines = new Set(existing.split('\n').map((l) => l.trim()));
+        if (lines.has('.qf/cleanup') || lines.has('.qf/cleanup/'))
+            return;
+    }
+    const sep = existing.length === 0 || existing.endsWith('\n') ? '' : '\n';
+    fs.writeFileSync(gitignorePath, `${existing}${sep}${GITIGNORE_ENTRY}\n`, 'utf8');
+}
+export default class CleanupRemove extends APICommand {
+    static args = { ...nameArg };
+    static description = `Write a cleanup payload for a ready-for-cleanup flag and hand off to the qfg-flag-cleanup Claude skill.
+
+Modeled on \`qfg migrate my-code\` — this command never edits source files
+itself. It validates that the flag is marked readyForCleanup=true, refuses to
+proceed if there are still evals_2d > 0 (use --force to override), writes
+\`.qf/cleanup/<key>.json\` describing the flag's current rule shape +
+telemetry, and prints instructions to invoke the qfg-flag-cleanup skill which
+asks the engineer which value should "win" and applies the inlining.
+
+The payload deliberately does NOT suggest a winning value; that's the
+engineer's call. Run \`qfg cleanup status <key>\` first if you want to inspect
+telemetry before retiring.`;
+    static examples = [
+        '<%= config.bin %> <%= command.id %> my.flag.key',
+        '<%= config.bin %> <%= command.id %> my.flag.key --force',
+        '<%= config.bin %> <%= command.id %> my.flag.key --json',
+    ];
+    static flags = {
+        force: Flags.boolean({
+            default: false,
+            description: 'Skip the evals_2d > 0 safety gate (useful when telemetry is delayed but you know the flag is dead)',
+        }),
+    };
+    async run() {
+        const { args, flags } = await this.parse(CleanupRemove);
+        const key = args.name;
+        if (!key)
+            return this.err('Key is required: `qfg cleanup remove <key>`');
+        const flagReq = await this.apiClient.post('/api/v1/metadata/getByKey', { workspaceId: this.workspaceId, key });
+        if (!flagReq.ok) {
+            const errorMsg = flagReq.error?.error || `Failed to fetch flag: ${flagReq.status}`;
+            if (flagReq.status === 404)
+                return this.err(`Flag ${key} not found`);
+            return this.err(errorMsg, { serverError: flagReq.error });
+        }
+        const flag = flagReq.json;
+        if (flag.readyForCleanup !== true) {
+            return this.err(`Flag ${key} is not marked readyForCleanup=true. ` +
+                `Flip it in the UI first (Flag detail page → mark "Ready for cleanup"), then re-run \`qfg cleanup remove ${key}\`.`);
+        }
+        const sparkReq = await this.apiClient.post('/api/v1/analytics/configSparklines', {
+            workspaceId: this.workspaceId,
+            configKey: key,
+        });
+        if (!sparkReq.ok) {
+            return this.err(sparkReq.error?.error || `Failed to fetch sparklines: ${sparkReq.status}`);
+        }
+        const sparkResp = sparkReq.json;
+        const { envSummaries, totals } = summarizeSparklines(sparkResp);
+        if (totals.evals_2d > 0 && !flags.force) {
+            return this.err(`Flag ${key} still has evals_2d=${totals.evals_2d} (evals in the last 2 days). ` +
+                `Refusing to write a cleanup payload — call sites are still hitting it. ` +
+                `Run \`qfg cleanup status ${key}\` for the full per-environment breakdown. ` +
+                `Use --force if you're sure the flag is dead and the telemetry is stale.`);
+        }
+        if (!this.workspaceId) {
+            return this.err('Workspace ID not found. Please run `qfg login`.');
+        }
+        const flagUrl = `${getAppUrl()}/workspaces/${this.workspaceId}/flags/${key}`;
+        const payload = {
+            $schema: 'https://api.quonfig.com/schemas/v1/cleanup-payload.json',
+            generatedAt: new Date().toISOString(),
+            skill: SKILL_NAME,
+            forced: flags.force && totals.evals_2d > 0,
+            key: flag.key,
+            type: flag.valueType,
+            readyForCleanup: true,
+            flagUrl,
+            default: flag.default ?? { rules: [] },
+            environments: flag.environments ?? [],
+            evals: totals,
+            environmentSparklines: envSummaries,
+            grepPatterns: GREP_PATTERNS,
+        };
+        const cwd = process.cwd();
+        const cleanupDir = path.join(cwd, '.qf', 'cleanup');
+        fs.mkdirSync(cleanupDir, { recursive: true });
+        const payloadPath = path.join(cleanupDir, `${key}.json`);
+        fs.writeFileSync(payloadPath, JSON.stringify(payload, null, 2) + '\n', 'utf8');
+        ensureGitignoreEntry(cwd);
+        const relPayloadPath = (path.relative(cwd, payloadPath) || payloadPath).split(path.sep).join('/');
+        this.log(`Skill:        ${SKILL_NAME}`);
+        this.log(`Flag:         ${flag.key} (${flag.valueType})`);
+        this.log(`Flag URL:     ${flagUrl}`);
+        this.log(`Payload:      ${relPayloadPath}`);
+        this.log(`Evals (2d):   ${totals.evals_2d}${payload.forced ? ' (--force overrode the safety gate)' : ''}`);
+        this.log('');
+        this.log(`To remove this flag's call sites, invoke Claude with the ${SKILL_NAME} skill:`);
+        this.log('');
+        this.log(`  claude "/${SKILL_NAME} ${key}"`);
+        this.log('');
+        this.log(`The skill will:`);
+        this.log(`  1. Read ${relPayloadPath}`);
+        this.log(`  2. Grep the repo for SDK call sites that reference ${flag.key}`);
+        this.log(`  3. Ask you which value should "win" (the cleanup direction)`);
+        this.log(`  4. Inline that value and delete the unreachable branches`);
+        this.log(`  5. Run your formatter / tests and open a PR`);
+        this.log('');
+        this.log(`Once the PR merges and the SDK redeploys, run \`qfg delete ${key}\` to remove the flag definition.`);
+        const output = {
+            skill: SKILL_NAME,
+            payloadPath: relPayloadPath,
+            key: flag.key,
+            type: flag.valueType,
+            flagUrl,
+            forced: payload.forced,
+            evals: totals,
+        };
+        return output;
+    }
+}

package/dist/commands/cleanup/status.d.ts

@@ -0,0 +1,13 @@
+import { APICommand } from '../../index.js';
+import { JsonObj } from '../../result.js';
+export default class CleanupStatus extends APICommand {
+    static args: {
+        name: import("@oclif/core/lib/interfaces/parser.js").Arg<string | undefined, Record<string, unknown>>;
+    };
+    static description: string;
+    static examples: string[];
+    static flags: {
+        json: import("@oclif/core/lib/interfaces/parser.js").BooleanFlag<boolean>;
+    };
+    run(): Promise<JsonObj | void>;
+}

package/dist/commands/cleanup/status.js

@@ -0,0 +1,184 @@
+import { Flags } from '@oclif/core';
+import { APICommand } from '../../index.js';
+import nameArg from '../../util/name-arg.js';
+function startOfDayUtcMs(date) {
+    return Date.UTC(date.getUTCFullYear(), date.getUTCMonth(), date.getUTCDate());
+}
+function formatRuleValue(value) {
+    if (!value)
+        return '(no value)';
+    // Old format: {type: 'bool', value: true}
+    if (typeof value.type === 'string' && value.value !== undefined) {
+        return String(value.value);
+    }
+    // New format: {bool: true} / {string: "..."} / etc.
+    for (const k of ['bool', 'string', 'int', 'double']) {
+        if (value[k] !== undefined)
+            return String(value[k]);
+    }
+    if (value.stringList !== undefined) {
+        return Array.isArray(value.stringList) ? value.stringList.join(',') : JSON.stringify(value.stringList);
+    }
+    if (value.json !== undefined)
+        return JSON.stringify(value.json);
+    return JSON.stringify(value);
+}
+function summarizeRules(rules) {
+    if (!rules || rules.length === 0)
+        return '[inherit default]';
+    const fallback = rules.find((r) => r.criteria && r.criteria.length === 1 && r.criteria[0].operator === 'ALWAYS_TRUE');
+    const overrides = rules.filter((r) => r !== fallback);
+    const fallbackStr = fallback ? formatRuleValue(fallback.value) : formatRuleValue(rules[0].value);
+    if (overrides.length === 0)
+        return fallbackStr;
+    return `${fallbackStr} (+${overrides.length} override rule${overrides.length === 1 ? '' : 's'})`;
+}
+export default class CleanupStatus extends APICommand {
+    static args = { ...nameArg };
+    static description = `Drill into one ready-for-cleanup flag — show telemetry across all environments and the current rule shape.
+
+Use this after \`qfg cleanup list\` to inspect a specific flag before handing
+removal off to the qfg-flag-cleanup Claude skill. The eval counts come from
+analytics.configSparklines (the same backing data the per-flag sparklines on
+the flag detail page use), summed into 24h/2d/7d/30d windows so you can decide
+whether it's safe to retire.
+
+Pass --json for the structured object including the full rule shape per
+environment — the cleanup skill consumes this directly.`;
+    static examples = [
+        '<%= config.bin %> <%= command.id %> my.flag.key',
+        '<%= config.bin %> <%= command.id %> my.flag.key --json',
+    ];
+    static flags = {
+        json: Flags.boolean({ default: false, description: 'Return structured object for agent consumption' }),
+    };
+    async run() {
+        const { args, flags } = await this.parse(CleanupStatus);
+        const key = args.name;
+        if (!key)
+            return this.err('Key is required: `qfg cleanup status <key>`');
+        const flagReq = await this.apiClient.post('/api/v1/metadata/getByKey', { workspaceId: this.workspaceId, key });
+        if (!flagReq.ok) {
+            const errorMsg = flagReq.error?.error || `Failed to fetch flag: ${flagReq.status}`;
+            if (flagReq.status === 404)
+                return this.err(`Flag ${key} not found`);
+            return this.err(errorMsg, { serverError: flagReq.error });
+        }
+        const flag = flagReq.json;
+        const sparkReq = await this.apiClient.post('/api/v1/analytics/configSparklines', {
+            workspaceId: this.workspaceId,
+            configKey: key,
+        });
+        if (!sparkReq.ok) {
+            return this.err(sparkReq.error?.error || `Failed to fetch sparklines: ${sparkReq.status}`);
+        }
+        const sparkResp = sparkReq.json;
+        const todayMs = startOfDayUtcMs(new Date());
+        const envSummaries = [];
+        let totalEvals24h = 0;
+        let totalEvals2d = 0;
+        let totalEvals7d = 0;
+        let totalEvals30d = 0;
+        let overallLast = null;
+        for (const row of sparkResp.rows ?? []) {
+            let envTotal = 0;
+            let envEvals24h = 0;
+            let envEvals2d = 0;
+            let envEvals7d = 0;
+            let envEvals30d = 0;
+            let envLastDayAgo = null;
+            for (const [i, day] of row.days.entries()) {
+                const count = row.counts[i] ?? 0;
+                if (count <= 0)
+                    continue;
+                const dayMs = Date.parse(`${day}T00:00:00Z`);
+                if (Number.isNaN(dayMs))
+                    continue;
+                const daysAgo = Math.round((todayMs - dayMs) / 86_400_000);
+                envTotal += count;
+                if (daysAgo === 0)
+                    envEvals24h += count;
+                if (daysAgo <= 1)
+                    envEvals2d += count;
+                if (daysAgo <= 6)
+                    envEvals7d += count;
+                if (daysAgo <= 29)
+                    envEvals30d += count;
+                if (envLastDayAgo === null || daysAgo < envLastDayAgo)
+                    envLastDayAgo = daysAgo;
+            }
+            const last_eval = envLastDayAgo === null ? null : new Date(todayMs - envLastDayAgo * 86_400_000).toISOString().slice(0, 10);
+            envSummaries.push({
+                environment: row.environment,
+                total: envTotal,
+                evals_24h: envEvals24h,
+                evals_2d: envEvals2d,
+                evals_7d: envEvals7d,
+                evals_30d: envEvals30d,
+                last_eval,
+            });
+            totalEvals24h += envEvals24h;
+            totalEvals2d += envEvals2d;
+            totalEvals7d += envEvals7d;
+            totalEvals30d += envEvals30d;
+            if (envLastDayAgo !== null && (overallLast === null || envLastDayAgo < overallLast)) {
+                overallLast = envLastDayAgo;
+            }
+        }
+        // Drop env summaries with zero evals so the human view stays terse; the
+        // --json output below includes the same array.
+        const nonEmptyEnvs = envSummaries.filter((e) => e.total > 0);
+        const overallLastEval = overallLast === null ? null : new Date(todayMs - overallLast * 86_400_000).toISOString().slice(0, 10);
+        const defaultRulesSummary = summarizeRules(flag.default?.rules);
+        const envRules = (flag.environments ?? []).map((env) => ({
+            environment: env.id,
+            rules: summarizeRules(env.rules),
+        }));
+        const payload = {
+            key: flag.key,
+            type: flag.valueType,
+            readyForCleanup: flag.readyForCleanup === true,
+            defaultRule: defaultRulesSummary,
+            environmentRules: envRules,
+            evals: {
+                evals_24h: totalEvals24h,
+                evals_2d: totalEvals2d,
+                evals_7d: totalEvals7d,
+                evals_30d: totalEvals30d,
+                last_eval: overallLastEval,
+            },
+            environments: nonEmptyEnvs,
+        };
+        if (flags.json) {
+            this.log(this.toSuccessJson(payload));
+            return payload;
+        }
+        this.log(`${flag.key} (${flag.valueType})`);
+        this.log(`  readyForCleanup: ${flag.readyForCleanup === true ? 'yes' : 'no'}`);
+        this.log(`  default rule: ${defaultRulesSummary}`);
+        if (envRules.length > 0) {
+            this.log('  per-environment rules:');
+            for (const er of envRules)
+                this.log(`    - env ${er.environment}: ${er.rules}`);
+        }
+        this.log('');
+        this.log('Evaluations:');
+        this.log(`  evals_24h: ${totalEvals24h}`);
+        this.log(`  evals_2d:  ${totalEvals2d}`);
+        this.log(`  evals_7d:  ${totalEvals7d}`);
+        this.log(`  evals_30d: ${totalEvals30d}`);
+        this.log(`  last_eval: ${overallLastEval ?? '-'}`);
+        if (nonEmptyEnvs.length > 0) {
+            this.log('');
+            this.log('Per-environment:');
+            for (const env of nonEmptyEnvs) {
+                this.log(`  ${env.environment}: total=${env.total}  24h=${env.evals_24h}  2d=${env.evals_2d}  7d=${env.evals_7d}  30d=${env.evals_30d}  last=${env.last_eval ?? '-'}`);
+            }
+        }
+        else {
+            this.log('');
+            this.log('No evaluations in the retained window — this flag looks quiet.');
+        }
+        return payload;
+    }
+}

package/dist/commands/cleanup/verify.d.ts

@@ -0,0 +1,14 @@
+import { APICommand } from '../../index.js';
+import { JsonObj } from '../../result.js';
+export default class CleanupVerify extends APICommand {
+    static args: {
+        name: import("@oclif/core/lib/interfaces/parser.js").Arg<string | undefined, Record<string, unknown>>;
+    };
+    static description: string;
+    static examples: string[];
+    static flags: {
+        days: import("@oclif/core/lib/interfaces/parser.js").OptionFlag<number, import("@oclif/core/lib/interfaces/parser.js").CustomOptions>;
+        json: import("@oclif/core/lib/interfaces/parser.js").BooleanFlag<boolean>;
+    };
+    run(): Promise<JsonObj | void>;
+}