@quonfig/cli 0.0.71 → 0.0.73

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.71";
+declare const _default: "0.0.73";
 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.71';
+export default '0.0.73';

package/oclif.manifest.json

@@ -2254,11 +2254,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 +2337,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 +2394,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 +2477,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 +4149,5 @@
       ]
     }
   },
-  "version": "0.0.71"
+  "version": "0.0.73"
 }

package/package.json

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