@quonfig/cli 0.0.72 → 0.0.74

package/dist/index.d.ts

@@ -3,6 +3,27 @@ import { Command } from '@oclif/core';
 import { Client } from '@quonfig/node';
 import type { ProjectEnvId } from '@quonfig/node';
 import { JsonObj, Result } from './result.js';
+/**
+ * The exit code oclif actually recorded on a thrown error.
+ *
+ * `Errors.CLIError` — what `this.error(msg, {exit: N})` throws — stores N on
+ * `oclif.exit` and has NO `exitCode` property at all. Reading `err.exitCode`
+ * therefore collapsed every non-default code (401 on the auth failures in
+ * `resolve-workspace.ts` / `get-client.ts`, for one) down to 1. Exported so the
+ * behaviour is unit-testable. See qfg-hzmb.
+ */
+export declare function errorExitCode(err: unknown): number;
+/**
+ * The code to actually terminate the process with.
+ *
+ * A POSIX exit status is one byte. Several call sites pass an HTTP-flavoured
+ * code — `{exit: 401}` for the auth failures in `get-client.ts` and
+ * `resolve-workspace.ts` — and `process.exit(401)` truncates to 145, which a
+ * shell reads as "killed by signal 17". Anything outside 1-255 therefore
+ * terminates with the plain failure code; the caller's real intent is still
+ * reported verbatim as `error.exitCode` in the `--json` envelope.
+ */
+export declare function processExitCode(err: unknown): number;
 export declare abstract class BaseCommand extends Command {
     static baseFlags: {
         interactive: import("@oclif/core/lib/interfaces/parser.js").BooleanFlag<boolean>;
@@ -20,6 +41,15 @@ export declare abstract class BaseCommand extends Command {
         code?: string;
     } & Error): Promise<void>;
     init(): Promise<void>;
+    /**
+     * oclif's default is `{error: err}`, but `message`, `code` and `stack` are
+     * non-enumerable on an Error, so `JSON.stringify` flattens a thrown Error all
+     * the way down to `{}`. Re-attach the useful fields explicitly and keep the
+     * caller's payload alongside them. See qfg-hzmb.
+     */
+    protected toErrorJson(err: unknown): {
+        error: JsonObj;
+    };
 }
 export declare abstract class APICommand extends BaseCommand {
     static baseFlags: {

package/dist/index.js

@@ -1,5 +1,5 @@
 export { run } from '@oclif/core';
-import { Command, Flags } from '@oclif/core';
+import { Command, Errors, Flags } from '@oclif/core';
 import rawGetClient, { unwrapRequest } from './util/get-client.js';
 const globalFlags = {
     interactive: Flags.boolean({
@@ -20,19 +20,71 @@ const globalFlags = {
         helpGroup: 'GLOBAL',
     }),
 };
+const DEFAULT_EXIT_CODE = 1;
+/**
+ * The exit code oclif actually recorded on a thrown error.
+ *
+ * `Errors.CLIError` — what `this.error(msg, {exit: N})` throws — stores N on
+ * `oclif.exit` and has NO `exitCode` property at all. Reading `err.exitCode`
+ * therefore collapsed every non-default code (401 on the auth failures in
+ * `resolve-workspace.ts` / `get-client.ts`, for one) down to 1. Exported so the
+ * behaviour is unit-testable. See qfg-hzmb.
+ */
+export function errorExitCode(err) {
+    const candidate = err;
+    if (typeof candidate?.oclif?.exit === 'number')
+        return candidate.oclif.exit;
+    if (typeof candidate?.exitCode === 'number')
+        return candidate.exitCode;
+    return DEFAULT_EXIT_CODE;
+}
+/**
+ * The code to actually terminate the process with.
+ *
+ * A POSIX exit status is one byte. Several call sites pass an HTTP-flavoured
+ * code — `{exit: 401}` for the auth failures in `get-client.ts` and
+ * `resolve-workspace.ts` — and `process.exit(401)` truncates to 145, which a
+ * shell reads as "killed by signal 17". Anything outside 1-255 therefore
+ * terminates with the plain failure code; the caller's real intent is still
+ * reported verbatim as `error.exitCode` in the `--json` envelope.
+ */
+export function processExitCode(err) {
+    const intended = errorExitCode(err);
+    return Number.isInteger(intended) && intended >= 1 && intended <= 255 ? intended : DEFAULT_EXIT_CODE;
+}
+/** Best available human-readable message for anything that can be thrown or passed to `err()`. */
+function errorMessage(error) {
+    if (typeof error === 'string')
+        return error;
+    if (error instanceof Error)
+        return error.message;
+    if (typeof error !== 'object' || error === null)
+        return String(error);
+    const record = error;
+    if (typeof record.message === 'string')
+        return record.message;
+    if (typeof record.error === 'string')
+        return record.error;
+    return JSON.stringify(error);
+}
 export class BaseCommand extends Command {
     static baseFlags = {
         ...globalFlags,
     };
     static enableJsonFlag = true;
     err = (error, json) => {
+        const message = errorMessage(error);
         if (this.jsonEnabled()) {
-            throw json ?? error;
-        }
-        if (typeof error === 'string') {
-            return this.error(error, { code: 'ERR', exit: 1 });
+            // qfg-hzmb: throw a real CLIError instead of a bare object, so the message
+            // and the exit code survive to catch() and reach stdout. The caller's
+            // structured payload is copied onto it, keeping the older contract that
+            // callers (and tests) read fields such as `missingEnvVar` straight off the
+            // thrown value.
+            const cliError = new Errors.CLIError(message, { code: 'ERR', exit: DEFAULT_EXIT_CODE });
+            Object.assign(cliError, json ?? (typeof error === 'object' && error !== null ? error : {}));
+            throw cliError;
         }
-        this.error(this.toErrorJson(error), { code: 'ERR', exit: 1 });
+        return this.error(message, { code: 'ERR', exit: DEFAULT_EXIT_CODE });
     };
     isVerbose;
     ok = (message, json) => {
@@ -67,19 +119,64 @@ export class BaseCommand extends Command {
     async catch(err) {
         // Override oclif's default error handling to suppress stack traces in production
         // but preserve error messages for tests
+        // `this.exit(n)` throws an ExitError: a control-flow signal, not a failure to
+        // report. `qfg verify --json` and `qfg migrate doctor --json` deliberately
+        // print their payload and *then* exit non-zero (qfg-ez47), so reporting the
+        // ExitError here would append a second JSON document to stdout. Hand it
+        // straight to oclif, which prints nothing and honours `oclif.exit`.
+        if (err instanceof Errors.ExitError || err.code === 'EEXIT') {
+            throw err;
+        }
+        // qfg-hzmb: `this.log()` is a documented no-op whenever jsonEnabled(), so
+        // this override used to print NOTHING for a failing `--json` run — empty
+        // stdout was indistinguishable from an empty success. Emit the structured
+        // envelope on stdout, exactly as oclif's own catch() does.
+        if (this.jsonEnabled()) {
+            this.logJson(this.toErrorJson(err));
+        }
         // In test environment, just re-throw the error
         if (process.env.NODE_ENV === 'test') {
             throw err;
         }
         // In production, log the error message without stack trace
-        this.log(err.message);
-        this.exit(err.exitCode || 1);
+        if (!this.jsonEnabled()) {
+            this.log(err.message);
+        }
+        this.exit(processExitCode(err));
     }
     async init() {
         await super.init();
         const { flags } = await this.parse();
         this.isVerbose = flags.verbose;
     }
+    /**
+     * oclif's default is `{error: err}`, but `message`, `code` and `stack` are
+     * non-enumerable on an Error, so `JSON.stringify` flattens a thrown Error all
+     * the way down to `{}`. Re-attach the useful fields explicitly and keep the
+     * caller's payload alongside them. See qfg-hzmb.
+     */
+    toErrorJson(err) {
+        if (typeof err !== 'object' || err === null) {
+            return { error: { code: 'ERR', exitCode: errorExitCode(err), message: errorMessage(err) } };
+        }
+        // An Error's own *enumerable* properties are the structured payload handed
+        // to `err()` — keep those. `oclif` is internal bookkeeping (surfaced as
+        // `exitCode`), and `stack` is dropped on purpose (oclif.stacktrace=false).
+        const payload = {};
+        for (const [key, value] of Object.entries(err)) {
+            if (key !== 'oclif' && key !== 'stack')
+                payload[key] = value;
+        }
+        const { code } = err;
+        return {
+            error: {
+                ...payload,
+                code: typeof code === 'string' ? code : 'ERR',
+                exitCode: errorExitCode(err),
+                message: errorMessage(err),
+            },
+        };
+    }
 }
 export class APICommand extends BaseCommand {
     static baseFlags = {

package/dist/init/templates.js

@@ -195,6 +195,49 @@ This is a Quonfig workspace repository. See \`CLAUDE.md\` for the complete schem
 4. Filename must match the \`key\` field (e.g. \`my.flag.json\` has \`"key": "my.flag"\`).
 5. Files must be in the correct directory for their \`type\`.
 6. See \`CLAUDE.md\` for the full list of value types, operators, and constraints.
+
+## \`qfg\` or the Quonfig MCP?
+
+Only relevant if this workspace is *also* hosted on a Quonfig account. On the
+fully-local path, editing the JSON in this repo is the whole story.
+
+- **This repo is checked out and you have a shell** -> use \`qfg\`. The files are
+  already on disk, so reading them costs nothing.
+- **Slack, claude.ai, or anywhere without a checkout** -> use the Quonfig MCP
+  server. It reads and writes the hosted workspace directly. Do not try to shell
+  out to \`qfg\` from a surface that has no repo.
+
+Both surfaces cover the same everyday loop — create a flag or config, change what
+an environment serves, set a log level. (\`qfg\` has all of it today; the MCP's
+create/config/log-level verbs land with its v2 write surface.)
+
+## Setting a value KEEPS that environment's targeting rules
+
+Both surfaces write the same way, so learn it once:
+
+\`qfg set-default\` (alias \`toggle\`), \`qfg set-rollout\`, and the MCP
+\`set_flag\`/\`set_config\` verbs replace exactly ONE rule — the environment's
+**fallback**, the unconditional rule at the end of its rule list that decides
+what users receive when no targeting rule matches. Every targeting rule above
+it is kept, and both surfaces report how many. An environment with no rules of
+its own has them copied from default first, so inherited targeting is kept too.
+
+| Surface | By default | To set the value for EVERYONE |
+|---------|------------|-------------------------------|
+| \`qfg set-default\` / \`qfg set-rollout\` | Keeps targeting; reports "Kept N targeting rule(s)" | add \`--replace-targeting\` |
+| MCP \`set_flag\` / \`set_config\` | Keeps targeting; reports the kept count in its result | send \`replaceTargeting: true\` |
+
+Setting the value for everyone DELETES that environment's targeting rules. They
+stay in git history, and the write returns a \`previousCommitSha\` to restore from.
+
+**Still read before you write.** \`qfg info <key>\` (or MCP \`get_flag\`) shows the
+rules your value is about to sit next to. For anything a fallback cannot express —
+multi-rule targeting, reordering, editing one targeting rule — edit the JSON
+directly or use MCP \`set_document\`.
+
+\`qfg log-level --target ...\` and MCP \`set_log_level\` are **surgical** in the same
+way: they upsert the level for the loggers you name and leave every other rule in
+place.
 `;
 }
 // ── Pre-commit hook ────────────────────────────────────────────────────

package/dist/util/rules.d.ts

@@ -0,0 +1,98 @@
+/**
+ * Rule helpers shared by the CLI's writers (`set-default`, `set-rollout`,
+ * `log-level`) and readers (`info`, `cleanup status`) — beads qfg-qjdm and
+ * qfg-9kr8.
+ *
+ * The CLI cannot import app-quonfig code, so this file is a deliberate,
+ * small mirror of the server's rulebook. Keep the semantics byte-identical
+ * with:
+ *   - app-quonfig src/lib/domain/rule-display.ts  → isCatchAllRule
+ *   - app-quonfig src/lib/public-api/write-scope.ts → countTargetingRules
+ *   - app-quonfig src/lib/public-api/log-level-write.ts → upsertFallbackRule
+ * Both surfaces write the same documents; a second, subtly different
+ * rulebook is a correctness hazard, not a style problem.
+ */
+export type Criterion = {
+    operator?: unknown;
+    [key: string]: unknown;
+};
+export type Rule = {
+    criteria?: Criterion[];
+    value?: unknown;
+    [key: string]: unknown;
+};
+export type EnvRules = {
+    id: string;
+    rules?: Rule[];
+};
+export type ScopedDocument = {
+    default?: {
+        rules?: Rule[];
+    };
+    environments?: EnvRules[];
+};
+/** A fresh unconditional rule carrying `value`. */
+export declare function catchAllRule(value: unknown): Rule;
+/**
+ * THE ONE DEFINITION of "is this rule unconditional" (qfg-gv54).
+ *
+ * A catch-all — the base-case rule that serves everyone in its scope — has
+ * two live JSON spellings, and every SDK evaluator treats them identically:
+ *
+ *   {criteria: [{operator: 'ALWAYS_TRUE'}]}  ← UI, API, MCP, `qfg create`
+ *   {criteria: []}                           ← older `qfg set-default` writes
+ *
+ * Both are in production data and neither is being backfilled (Jeff,
+ * 2026-09-02), so every READER accepts both. Criteria are ANDed, so one
+ * conditional criterion makes the whole rule conditional.
+ *
+ * Fails CLOSED: anything unreadable as a rule (no `criteria` key, not an
+ * object) is NOT a catch-all — the same choice app-quonfig's
+ * `isCatchAllRuleUnknown` makes for raw parsed JSON. On the write path that
+ * means a malformed rule is left alone and a fresh fallback is appended,
+ * rather than a malformed rule being silently overwritten.
+ */
+export declare function isCatchAllRule(rule: unknown): boolean;
+/**
+ * How many real TARGETING rules a scope holds.
+ *
+ * A targeted scope is conventionally `[…targeting rules, catch-all]`: the
+ * trailing unconditional rule is the scope's fallback, not a rule that
+ * targets anyone, so it is discounted. ONLY a trailing catch-all is — an
+ * unconditional rule anywhere earlier shadows every rule after it, which is
+ * a targeting decision in its own right and stays counted.
+ */
+export declare function countTargetingRules(rules: Rule[]): number;
+/**
+ * Set the scope's fallback value WITHOUT disturbing its targeting rules:
+ * the first catch-all's value is replaced in place (criteria untouched — an
+ * existing bare `criteria: []` fallback keeps its spelling, exactly as the
+ * server does), and if the scope has no catch-all at all a fresh
+ * ALWAYS_TRUE rule is appended at the end. Never mutates `rules`.
+ */
+export declare function upsertFallbackRule(rules: Rule[], value: unknown): Rule[];
+/**
+ * The rules a write should start from for one scope.
+ *
+ * `envName` undefined (or empty) means the document's `default` block, which
+ * always exists and is never seeded. A named environment with no block of
+ * its own inherits `default.rules` at evaluation time, so writing it starts
+ * from a DEEP CLONE of those rules — the same shape the UI produces when an
+ * environment stops inheriting. Starting from `[]` instead would silently
+ * drop the inherited targeting for that environment.
+ *
+ * `seeded` is true only when rules were actually copied, so callers do not
+ * report a copy that moved nothing.
+ */
+export declare function seedScopeRules(config: ScopedDocument, envName?: string): {
+    rules: Rule[];
+    seeded: boolean;
+};
+/** The environments array with `envName`'s rules replaced, appending the entry when it has none. */
+export declare function upsertEnvRules(envs: EnvRules[], envName: string, rules: Rule[]): EnvRules[];
+/** '<env> had no rules of its own; copied them from default.' */
+export declare function seededFromDefaultNote(envName: string): string;
+/** What a surgical write kept. Empty when the scope held no targeting rules. */
+export declare function keptTargetingNote(count: number): string;
+/** What a --replace-targeting write destroyed, and where to find it again. */
+export declare function replacedTargetingNote(count: number, previousCommitSha: string): string;

package/dist/util/rules.js

@@ -0,0 +1,131 @@
+/**
+ * Rule helpers shared by the CLI's writers (`set-default`, `set-rollout`,
+ * `log-level`) and readers (`info`, `cleanup status`) — beads qfg-qjdm and
+ * qfg-9kr8.
+ *
+ * The CLI cannot import app-quonfig code, so this file is a deliberate,
+ * small mirror of the server's rulebook. Keep the semantics byte-identical
+ * with:
+ *   - app-quonfig src/lib/domain/rule-display.ts  → isCatchAllRule
+ *   - app-quonfig src/lib/public-api/write-scope.ts → countTargetingRules
+ *   - app-quonfig src/lib/public-api/log-level-write.ts → upsertFallbackRule
+ * Both surfaces write the same documents; a second, subtly different
+ * rulebook is a correctness hazard, not a style problem.
+ */
+/** A fresh unconditional rule carrying `value`. */
+export function catchAllRule(value) {
+    return { criteria: [{ operator: 'ALWAYS_TRUE' }], value };
+}
+/**
+ * THE ONE DEFINITION of "is this rule unconditional" (qfg-gv54).
+ *
+ * A catch-all — the base-case rule that serves everyone in its scope — has
+ * two live JSON spellings, and every SDK evaluator treats them identically:
+ *
+ *   {criteria: [{operator: 'ALWAYS_TRUE'}]}  ← UI, API, MCP, `qfg create`
+ *   {criteria: []}                           ← older `qfg set-default` writes
+ *
+ * Both are in production data and neither is being backfilled (Jeff,
+ * 2026-09-02), so every READER accepts both. Criteria are ANDed, so one
+ * conditional criterion makes the whole rule conditional.
+ *
+ * Fails CLOSED: anything unreadable as a rule (no `criteria` key, not an
+ * object) is NOT a catch-all — the same choice app-quonfig's
+ * `isCatchAllRuleUnknown` makes for raw parsed JSON. On the write path that
+ * means a malformed rule is left alone and a fresh fallback is appended,
+ * rather than a malformed rule being silently overwritten.
+ */
+export function isCatchAllRule(rule) {
+    if (typeof rule !== 'object' || rule === null || Array.isArray(rule))
+        return false;
+    const { criteria } = rule;
+    if (!Array.isArray(criteria))
+        return false;
+    // An empty list satisfies `every` vacuously — that IS the `criteria: []`
+    // spelling — so this one expression covers both shapes.
+    return criteria.every((criterion) => typeof criterion === 'object' &&
+        criterion !== null &&
+        criterion.operator === 'ALWAYS_TRUE');
+}
+/**
+ * How many real TARGETING rules a scope holds.
+ *
+ * A targeted scope is conventionally `[…targeting rules, catch-all]`: the
+ * trailing unconditional rule is the scope's fallback, not a rule that
+ * targets anyone, so it is discounted. ONLY a trailing catch-all is — an
+ * unconditional rule anywhere earlier shadows every rule after it, which is
+ * a targeting decision in its own right and stays counted.
+ */
+export function countTargetingRules(rules) {
+    const last = rules.at(-1);
+    return last !== undefined && isCatchAllRule(last) ? rules.length - 1 : rules.length;
+}
+/**
+ * Set the scope's fallback value WITHOUT disturbing its targeting rules:
+ * the first catch-all's value is replaced in place (criteria untouched — an
+ * existing bare `criteria: []` fallback keeps its spelling, exactly as the
+ * server does), and if the scope has no catch-all at all a fresh
+ * ALWAYS_TRUE rule is appended at the end. Never mutates `rules`.
+ */
+export function upsertFallbackRule(rules, value) {
+    const index = rules.findIndex((rule) => isCatchAllRule(rule));
+    if (index === -1)
+        return [...rules, catchAllRule(value)];
+    const next = [...rules];
+    next[index] = { ...next[index], value };
+    return next;
+}
+/**
+ * The rules a write should start from for one scope.
+ *
+ * `envName` undefined (or empty) means the document's `default` block, which
+ * always exists and is never seeded. A named environment with no block of
+ * its own inherits `default.rules` at evaluation time, so writing it starts
+ * from a DEEP CLONE of those rules — the same shape the UI produces when an
+ * environment stops inheriting. Starting from `[]` instead would silently
+ * drop the inherited targeting for that environment.
+ *
+ * `seeded` is true only when rules were actually copied, so callers do not
+ * report a copy that moved nothing.
+ */
+export function seedScopeRules(config, envName) {
+    const defaultRules = config.default?.rules ?? [];
+    if (!envName)
+        return { rules: defaultRules, seeded: false };
+    const env = (config.environments ?? []).find((e) => e.id === envName);
+    if (env)
+        return { rules: env.rules ?? [], seeded: false };
+    const cloned = structuredClone(defaultRules);
+    return { rules: cloned, seeded: cloned.length > 0 };
+}
+/** The environments array with `envName`'s rules replaced, appending the entry when it has none. */
+export function upsertEnvRules(envs, envName, rules) {
+    const index = envs.findIndex((e) => e.id === envName);
+    if (index === -1)
+        return [...envs, { id: envName, rules }];
+    const next = [...envs];
+    next[index] = { ...next[index], rules };
+    return next;
+}
+// ── Reporting ────────────────────────────────────────────────────────
+//
+// One wording, used by every verb that writes a fallback, so `set-default`,
+// `set-rollout` and the public API cannot drift apart in what they claim to
+// have done.
+/** '<env> had no rules of its own; copied them from default.' */
+export function seededFromDefaultNote(envName) {
+    return `${envName} had no rules of its own; copied them from default.`;
+}
+/** What a surgical write kept. Empty when the scope held no targeting rules. */
+export function keptTargetingNote(count) {
+    if (count === 0)
+        return '';
+    return (`Kept ${count} targeting rule(s); matched users still receive their targeted value. ` +
+        `To set for everyone, add --replace-targeting.`);
+}
+/** What a --replace-targeting write destroyed, and where to find it again. */
+export function replacedTargetingNote(count, previousCommitSha) {
+    if (count === 0)
+        return `Previous version ${previousCommitSha}.`;
+    return `Replaced ${count} targeting rule(s); previous version ${previousCommitSha}.`;
+}

package/dist/version.d.ts

@@ -1,2 +1,2 @@
-declare const _default: "0.0.72";
+declare const _default: "0.0.74";
 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.72';
+export default '0.0.74';

package/oclif.manifest.json

@@ -1600,7 +1600,7 @@
           "type": "boolean"
         },
         "env": {
-          "description": "environment to operate in (default: $QUONFIG_ENVIRONMENT)",
+          "description": "environment to operate in (required; QUONFIG_ENVIRONMENT is never read)",
           "name": "env",
           "hasDynamicHelp": false,
           "multiple": false,
@@ -2176,7 +2176,8 @@
           "type": "option"
         },
         "environment": {
-          "description": "Which environment slug to evaluate. Honors QUONFIG_ENVIRONMENT.",
+          "description": "Which environment slug to evaluate. Flag wins, then QUONFIG_ENVIRONMENT (serve hosts a service, so the var is its identity), then development.",
+          "env": "QUONFIG_ENVIRONMENT",
           "name": "environment",
           "default": "development",
           "hasDynamicHelp": false,
@@ -2254,11 +2255,11 @@
           "name": "name"
         }
       },
-      "description": "Set the unconditional fallback value for a flag or config in a specific environment.\n\nThis updates the catch-all rule — the value users receive when NO targeting rule matches.\nAny targeting rules or percentage rollouts you have configured are NOT affected; they\ncontinue to fire before this fallback is evaluated.\n\n\"Other rules still apply\" means: if you have rules targeting specific users, segments,\nor properties, those rules still take priority. This command only changes what everyone\nelse sees.\n\nTo set a percentage rollout (gradual rollout / A/B test / canary deploy) instead:\n  qfg set-rollout my.flag --environment production --true-percent 20\n\nTo see all current values and rules for a flag:\n  qfg info my.flag",
+      "description": "Set the fallback value for a flag or config in one environment.\n\nThe fallback is the unconditional rule at the end of the environment's rule\nlist: what users receive when no targeting rule matches. Targeting rules and\npercentage rollouts above it are kept, and the command tells you how many.\nIf the environment has no rules of its own yet, they are copied from the\nflag's default rules first, so inherited targeting is kept too.\n\nTo turn a flag on or off for EVERYONE, including users matched by targeting\nrules, add --replace-targeting. This deletes the environment's targeting\nrules (they stay in git history).\n\nTo set a percentage rollout (gradual rollout / A/B test / canary deploy) instead:\n  qfg set-rollout my.flag --environment production --true-percent 20\n\nTo see all current values and rules for a flag:\n  qfg info my.flag",
       "examples": [
         "<%= config.bin %> <%= command.id %> my.flag.name                                          # prompts for value and env",
         "<%= config.bin %> <%= command.id %> my.flag.name --value=true --environment=staging",
-        "<%= config.bin %> <%= command.id %> my.flag.name --value=false --environment=production   # kill-switch: turn off for everyone",
+        "<%= config.bin %> <%= command.id %> my.flag.name --value=false --environment=production --replace-targeting   # kill-switch: off for everyone",
         "<%= config.bin %> <%= command.id %> my.flag.name --value=true --secret",
         "<%= config.bin %> <%= command.id %> my.config.name --env-var=MY_ENV_VAR_NAME --environment=production",
         "# For a percentage rollout, use set-rollout instead:",
@@ -2337,6 +2338,12 @@
           "multiple": false,
           "type": "option"
         },
+        "replace-targeting": {
+          "description": "set the value for EVERYONE: delete this environment's targeting rules instead of keeping them (they stay in git history)",
+          "name": "replace-targeting",
+          "allowNo": false,
+          "type": "boolean"
+        },
         "value": {
           "description": "new default value",
           "name": "value",
@@ -2388,12 +2395,13 @@
           "name": "name"
         }
       },
-      "description": "Configure a percentage rollout (gradual rollout / A/B test / canary deploy) for a flag.\n\nThe flag must already exist. Create it first if needed:\n  qfg create my.flag --type boolean-flag\n\nWeights are specified as whole-number percentages (0–100). They must sum to 100.\n\nFor a boolean flag, use --true-percent to set the percentage of users that receive\ntrue (the remainder automatically receive false):\n  qfg set-rollout my.flag --environment production --true-percent 20\n  → 20% of users get true, 80% get false\n\nFor multi-value flags or custom splits, use --weights with a comma-separated list:\n  qfg set-rollout my.flag --environment production --weights \"red:33,green:33,blue:34\"\n\nHashing: users are bucketed by the value of hashByPropertyName (default: \"user.key\").\nUse --hash-by to change which property drives the bucket assignment:\n  qfg set-rollout my.flag --environment production --true-percent 10 --hash-by user.id\n\nFor scripted / agent use, add --confirm to skip the interactive confirmation prompt.\n\nTo combine a rollout with segment targeting (e.g. beta ON, holdout OFF, everyone else 50/50),\nyou need to edit the JSON config file directly:\n  qfg config-schema           # operator reference + worked multi-rule example\n  qfg pull --dir ./config     # clone workspace to edit\n\nTo revert to a single value for everyone, use:\n  qfg set-default my.flag --environment production --value false\n\nTo inspect the current rollout:\n  qfg info my.flag",
+      "description": "Configure a percentage rollout (gradual rollout / A/B test / canary deploy) for a flag.\n\nThe flag must already exist. Create it first if needed:\n  qfg create my.flag --type boolean-flag\n\nWeights are specified as whole-number percentages (0–100). They must sum to 100.\n\nFor a boolean flag, use --true-percent to set the percentage of users that receive\ntrue (the remainder automatically receive false):\n  qfg set-rollout my.flag --environment production --true-percent 20\n  → 20% of users get true, 80% get false\n\nFor multi-value flags or custom splits, use --weights with a comma-separated list:\n  qfg set-rollout my.flag --environment production --weights \"red:33,green:33,blue:34\"\n\nHashing: users are bucketed by the value of hashByPropertyName (default: \"user.key\").\nUse --hash-by to change which property drives the bucket assignment:\n  qfg set-rollout my.flag --environment production --true-percent 10 --hash-by user.id\n\nThe rollout becomes the environment's fallback: the unconditional rule at the end\nof its rule list, what users receive when no targeting rule matches. Targeting\nrules above it are kept, and the command tells you how many. If the environment\nhas no rules of its own yet, they are copied from the flag's default rules first,\nso inherited targeting is kept too.\n\nTo roll out to EVERYONE, including users matched by targeting rules, add\n--replace-targeting. This deletes the environment's targeting rules (they stay in\ngit history).\n\nFor scripted / agent use, add --confirm to skip the interactive confirmation prompt.\n\nTo combine a rollout with segment targeting (e.g. beta ON, holdout OFF, everyone else 50/50),\nyou need to edit the JSON config file directly:\n  qfg config-schema           # operator reference + worked multi-rule example\n  qfg pull --dir ./config     # clone workspace to edit\n\nTo revert to a single value for everyone, use:\n  qfg set-default my.flag --environment production --value false --replace-targeting\n\nTo inspect the current rollout:\n  qfg info my.flag",
       "examples": [
         "<%= config.bin %> <%= command.id %> my.feature.flag --environment production --true-percent 20",
         "<%= config.bin %> <%= command.id %> my.feature.flag --environment staging --true-percent 50",
         "<%= config.bin %> <%= command.id %> my.feature.flag --environment production --true-percent 100  # full rollout",
-        "<%= config.bin %> <%= command.id %> my.feature.flag --environment production --true-percent 0    # kill switch (all false)",
+        "# For a kill switch — false for EVERYONE, including targeted users — use set-default:",
+        "<%= config.bin %> set-default my.feature.flag --value=false --environment=production --replace-targeting",
         "<%= config.bin %> <%= command.id %> my.variant.flag --environment production --weights \"control:50,treatment:50\"",
         "<%= config.bin %> <%= command.id %> my.variant.flag --environment production --weights \"a:33,b:33,c:34\" --hash-by user.id"
       ],
@@ -2470,6 +2478,12 @@
           "multiple": false,
           "type": "option"
         },
+        "replace-targeting": {
+          "description": "roll out to EVERYONE: delete this environment's targeting rules instead of keeping them (they stay in git history)",
+          "name": "replace-targeting",
+          "allowNo": false,
+          "type": "boolean"
+        },
         "weights": {
           "description": "comma-separated \"value:percent\" pairs that must sum to 100 (e.g. \"true:20,false:80\" or \"red:33,green:33,blue:34\")",
           "name": "weights",
@@ -4136,5 +4150,5 @@
       ]
     }
   },
-  "version": "0.0.72"
+  "version": "0.0.74"
 }

package/package.json

@@ -1,7 +1,7 @@
 {
   "packageManager": "yarn@4.11.0+sha512.4e54aeace9141df2f0177c266b05ec50dc044638157dae128c471ba65994ac802122d7ab35bcd9e81641228b7dcf24867d28e750e0bcae8a05277d600008ad54",
   "name": "@quonfig/cli",
-  "version": "0.0.72",
+  "version": "0.0.74",
   "bugs": {
     "url": "https://github.com/quonfig/cli/issues"
   },