@quonfig/cli 0.0.54 → 0.0.57

package/dist/commands/cleanup/verify.js

@@ -0,0 +1,100 @@
+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());
+}
+export default class CleanupVerify extends APICommand {
+    static args = { ...nameArg };
+    static description = `Confirm zero evals for a flag in the trailing N days (default 7). Exits 0 if safe to delete, non-zero otherwise.
+
+Read-only gate intended for chaining with \`qfg delete\` after a cleanup PR
+has merged and the SDK has redeployed:
+
+  qfg cleanup verify my.flag.key && qfg delete my.flag.key
+
+The trailing window is stricter than the \`qfg cleanup remove\` 2-day gate on
+purpose — \`remove\` only writes a payload describing the flag, but \`delete\`
+permanently removes the flag definition, so we want a longer quiet period
+before chaining. Bump --days N if you want a more conservative window.`;
+    static examples = [
+        '<%= config.bin %> <%= command.id %> my.flag.key',
+        '<%= config.bin %> <%= command.id %> my.flag.key --days 14',
+        '<%= config.bin %> <%= command.id %> my.flag.key --json',
+        '<%= config.bin %> <%= command.id %> my.flag.key && <%= config.bin %> delete my.flag.key',
+    ];
+    static flags = {
+        days: Flags.integer({
+            default: 7,
+            description: 'Number of trailing calendar days that must have zero evals',
+        }),
+        json: Flags.boolean({ default: false, description: 'Return structured object for agent consumption' }),
+    };
+    async run() {
+        const { args, flags } = await this.parse(CleanupVerify);
+        const key = args.name;
+        if (!key)
+            return this.err('Key is required: `qfg cleanup verify <key>`');
+        if (flags.days <= 0)
+            return this.err('--days must be a positive integer');
+        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 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());
+        let evals = 0;
+        let mostRecentDayAgo = null;
+        for (const row of sparkResp.rows ?? []) {
+            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);
+                // --days 7 means "today (daysAgo=0) through 6 days ago" (a 7-day window).
+                // --days 1 means "today only".
+                if (daysAgo < 0 || daysAgo > flags.days - 1)
+                    continue;
+                evals += count;
+                if (mostRecentDayAgo === null || daysAgo < mostRecentDayAgo)
+                    mostRecentDayAgo = daysAgo;
+            }
+        }
+        const lastEval = mostRecentDayAgo === null ? null : new Date(todayMs - mostRecentDayAgo * 86_400_000).toISOString().slice(0, 10);
+        const safe = evals === 0;
+        const payload = {
+            key,
+            daysChecked: flags.days,
+            evals,
+            lastEval,
+            safe,
+        };
+        if (flags.json) {
+            // --json always emits the payload and exits 0; agents read `safe` to decide.
+            // Shell `verify && delete` chaining uses the text mode below where exit code
+            // matters for the shell short-circuit.
+            this.log(this.toSuccessJson(payload));
+            return payload;
+        }
+        if (safe) {
+            this.log(`${key}: safe to delete — 0 evals in the last ${flags.days} day(s).`);
+            return payload;
+        }
+        return this.err(`${key}: ${evals} eval(s) in the last ${flags.days} day(s), latest ${lastEval}. ` +
+            `Refusing to confirm safe-to-delete. Bump --days, wait for traffic to drain, or run ` +
+            `\`qfg cleanup status ${key}\` for the full per-environment breakdown.`);
+    }
+}

package/dist/commands/cleanup.d.ts

@@ -0,0 +1,6 @@
+import { BaseCommand } from '../index.js';
+export default class Cleanup extends BaseCommand {
+    static description: string;
+    static examples: string[];
+    run(): Promise<void>;
+}

package/dist/commands/cleanup.js

@@ -0,0 +1,28 @@
+import { BaseCommand } from '../index.js';
+export default class Cleanup extends BaseCommand {
+    static description = `Retire feature flags that have done their job.
+
+The cleanup workflow turns a flag's "Ready for cleanup" marker into an end-to-end
+removal flow: surface the flags that are safe to retire, hand the actual code
+removal to the qfg-flag-cleanup Claude skill, then delete the flag definition
+once the call sites are gone.
+
+Lifecycle (high-level):
+  1. Owner flips readyForCleanup=true in the UI            (already exists)
+  2. qfg cleanup list                                       see candidates + telemetry
+  3. qfg cleanup status <key>                               drill into one flag
+  4. qfg cleanup remove <key>                               handoff to the cleanup skill
+  5. PR merges, SDK redeploys, telemetry confirms 0 evals
+  6. qfg cleanup verify <key>                               (optional) confirm safe
+  7. qfg delete <key>                                       remove the flag definition`;
+    static examples = [
+        '<%= config.bin %> cleanup list',
+        '<%= config.bin %> cleanup list --json',
+        '<%= config.bin %> cleanup status my.flag.key',
+    ];
+    async run() {
+        this.log('Use one of the cleanup subcommands:');
+        this.log('  qfg cleanup list           # ready-for-cleanup flags + telemetry');
+        this.log('  qfg cleanup status <key>   # drill into one flag');
+    }
+}

package/dist/commands/config-schema.js

@@ -134,6 +134,11 @@ Weights are integers out of 100,000 (not percentages):
 
 hashByPropertyName controls the bucket assignment property (default: "user.key").
 
+────────────────────────────────────────────────────────────
+LIFECYCLE FIELDS
+────────────────────────────────────────────────────────────
+  readyForCleanup  (boolean)  Marks a feature_flag as safe to retire. See \`qfg cleanup\` for the retirement workflow.
+
 ────────────────────────────────────────────────────────────
 RELATED COMMANDS
 ────────────────────────────────────────────────────────────
@@ -143,6 +148,7 @@ RELATED COMMANDS
   qfg pull --dir ./config                         clone workspace to edit JSON directly
   qfg verify ./config                             validate all JSON files before pushing
   qfg info my.flag                                inspect current values and rules
+  qfg cleanup list                                list flags marked readyForCleanup=true
   qfg config-schema --json-schema                 print the machine-readable JSON Schema
 `.trim();
 export default class ConfigSchema extends BaseCommand {

package/dist/commands/create.js

@@ -41,7 +41,9 @@ Log levels:
   # Log-level keys must start with "${LOG_LEVEL_KEY_PREFIX}".
   # For per-logger targeting, create ONE log-level config per service and add
   # rules on the "quonfig-sdk-logging.key" context property (e.g.
-  # PROP_STARTS_WITH_ONE_OF MyPackage.) rather than one config per logger.`;
+  # PROP_STARTS_WITH_ONE_OF MyPackage.) rather than one config per logger.
+
+When this flag has done its job, mark readyForCleanup: true in the UI and run \`qfg cleanup list\` to retire it.`;
     static examples = [
         '<%= config.bin %> <%= command.id %> my.new.flag --type boolean-flag',
         '<%= config.bin %> <%= command.id %> my.new.flag --type boolean-flag --value=true',

package/dist/commands/delete.js

@@ -1,6 +1,7 @@
 import { Args, Flags } from '@oclif/core';
 import { APICommand } from '../index.js';
-import { confirmTypedSlug } from '../push/confirm.js';
+import { checkRecentEvalsSafetyNudge } from '../delete/safety-nudge.js';
+import { confirmTypedSlug, confirmYesNo } from '../push/confirm.js';
 import isInteractive from '../util/is-interactive.js';
 import { checkmark } from '../util/color.js';
 import { loadTokens } from '../util/token-storage.js';
@@ -72,6 +73,28 @@ Examples
             if (!isInteractive(flags)) {
                 return this.err(`Refusing to delete ${key} without confirmation. Pass --yes or run interactively.`);
             }
+            if (item.type === 'feature_flag') {
+                const safety = await checkRecentEvalsSafetyNudge({
+                    key,
+                    fetchSparklines: async () => {
+                        const res = await this.apiClient.post('/api/v1/analytics/configSparklines', {
+                            workspaceId: this.workspaceId,
+                            configKey: key,
+                        });
+                        if (!res.ok) {
+                            const errMsg = res.error?.error ?? `HTTP ${res.status}`;
+                            return { ok: false, error: errMsg };
+                        }
+                        const json = res.json;
+                        return { ok: true, rows: json.rows ?? [] };
+                    },
+                    prompt: (msg) => confirmYesNo(msg),
+                    warn: (msg) => this.log(`warning: ${msg}`),
+                });
+                if (!safety.proceed) {
+                    return this.err(`Aborted: ${key} still has recent evals. Run \`qfg cleanup remove ${key}\` first, then retry.`);
+                }
+            }
             this.log(`About to delete ${item.type.replaceAll('_', ' ')}: ${key}`);
             this.log('This rewrites the workspace repo and is destructive.');
             const confirmed = await confirmTypedSlug(key, `Type "${key}" to confirm: `);

package/dist/commands/info.js

@@ -65,6 +65,7 @@ Related commands:
         }
         const fullConfig = configRequest.json;
         this.verboseLog('Full config:', fullConfig);
+        const readyForCleanup = fullConfig?.readyForCleanup === true;
         // Get environments
         const environments = await getEnvironments(this);
         const appUrl = getAppUrl();
@@ -76,6 +77,9 @@ Related commands:
         this.log(url);
         this.log('');
         const json = { url };
+        if (readyForCleanup) {
+            json.readyForCleanup = true;
+        }
         json.values = this.parseConfig(fullConfig, environments, url);
         this.log('');
         // Fetch evaluation stats if needed
@@ -85,6 +89,9 @@ Related commands:
                 json.evaluations = evalStats;
             }
         }
+        if (readyForCleanup) {
+            this.log(`→ This flag is marked for cleanup. Run \`qfg cleanup status ${key}\` for telemetry, \`qfg cleanup remove ${key}\` to start the removal handoff.`);
+        }
         return { [key]: json };
     }
     displayEvaluationStats(statsPerEnv, environments) {

package/dist/delete/safety-nudge.d.ts

@@ -0,0 +1,33 @@
+export interface ConfigSparklineRow {
+    counts: number[];
+    days: string[];
+    environment: string;
+}
+interface SparklinesOk {
+    ok: true;
+    rows: ConfigSparklineRow[];
+}
+interface SparklinesErr {
+    error: string;
+    ok: false;
+}
+export type SparklinesResult = SparklinesErr | SparklinesOk;
+export interface SafetyNudgeDeps {
+    fetchSparklines: () => Promise<SparklinesResult>;
+    key: string;
+    prompt: (message: string) => Promise<boolean>;
+    warn: (message: string) => void;
+}
+export interface SafetyNudgeResult {
+    evals24h: number;
+    proceed: boolean;
+    telemetryFailed: boolean;
+}
+/**
+ * Sum the eval counts in today's UTC calendar bucket across all environment
+ * rows in a configSparklines response. Matches the `evals_24h` semantics used
+ * in `qfg cleanup remove` (today-only bucket from the daily-grouped sparkline).
+ */
+export declare function countEvalsLast24h(rows: ConfigSparklineRow[]): number;
+export declare function checkRecentEvalsSafetyNudge(deps: SafetyNudgeDeps): Promise<SafetyNudgeResult>;
+export {};

package/dist/delete/safety-nudge.js

@@ -0,0 +1,50 @@
+// Safety nudge for `qfg delete` — catches the wrong-order cleanup mistake
+// before it ships. If a flag still has eval traffic in the last 24h, we prompt
+// the user with "did you mean `qfg cleanup remove` first?" before letting
+// `qfg delete` proceed to the destructive typed-slug confirmation.
+//
+// This module is the testable core; src/commands/delete.ts wires the real
+// apiClient + confirmYesNo to it.
+function startOfDayUtcMs(date) {
+    return Date.UTC(date.getUTCFullYear(), date.getUTCMonth(), date.getUTCDate());
+}
+/**
+ * Sum the eval counts in today's UTC calendar bucket across all environment
+ * rows in a configSparklines response. Matches the `evals_24h` semantics used
+ * in `qfg cleanup remove` (today-only bucket from the daily-grouped sparkline).
+ */
+export function countEvalsLast24h(rows) {
+    const todayMs = startOfDayUtcMs(new Date());
+    let total = 0;
+    for (const row of rows) {
+        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);
+            if (daysAgo !== 0)
+                continue;
+            total += count;
+        }
+    }
+    return total;
+}
+export async function checkRecentEvalsSafetyNudge(deps) {
+    const { fetchSparklines, key, prompt, warn } = deps;
+    const sparkResult = await fetchSparklines();
+    if (!sparkResult.ok) {
+        warn(`Could not check recent evals for ${key} (${sparkResult.error}). Proceeding anyway.`);
+        return { evals24h: 0, proceed: true, telemetryFailed: true };
+    }
+    const evals24h = countEvalsLast24h(sparkResult.rows);
+    if (evals24h === 0) {
+        return { evals24h: 0, proceed: true, telemetryFailed: false };
+    }
+    const message = `This flag still has ${evals24h} eval(s) in the last 24h. ` +
+        `Did you mean \`qfg cleanup remove ${key}\` first to get the call sites out? [y/N] `;
+    const confirmed = await prompt(message);
+    return { evals24h, proceed: confirmed, telemetryFailed: false };
+}

package/dist/version.d.ts

@@ -1,2 +1,2 @@
-declare const _default: "0.0.54";
+declare const _default: "0.0.57";
 export default _default;

package/dist/version.js

@@ -1,2 +1,2 @@
 // AUTO-GENERATED from package.json by scripts/generate-version.mjs — do not edit.
-export default '0.0.54';
+export default '0.0.57';