@quonfig/cli 0.0.2 → 0.0.5

package/oclif.manifest.json

@@ -1,5 +1,65 @@
 {
   "commands": {
+    "config-schema": {
+      "aliases": [],
+      "args": {},
+      "description": "Print the config file format reference: rules engine, operators, targeting criteria, segments, and weighted rollouts. Use --json-schema for the machine-readable JSON Schema document.",
+      "examples": [
+        "<%= config.bin %> <%= command.id %>                  # human-readable operator reference + examples",
+        "<%= config.bin %> <%= command.id %> --json-schema    # full JSON Schema document (copy into your editor)"
+      ],
+      "flags": {
+        "json": {
+          "description": "Format output as json.",
+          "helpGroup": "GLOBAL",
+          "name": "json",
+          "allowNo": false,
+          "type": "boolean"
+        },
+        "interactive": {
+          "description": "Force interactive mode",
+          "helpGroup": "GLOBAL",
+          "name": "interactive",
+          "allowNo": true,
+          "type": "boolean"
+        },
+        "no-color": {
+          "description": "Do not colorize output",
+          "env": "NO_COLOR",
+          "helpGroup": "GLOBAL",
+          "name": "no-color",
+          "allowNo": false,
+          "type": "boolean"
+        },
+        "verbose": {
+          "description": "Verbose output",
+          "helpGroup": "GLOBAL",
+          "name": "verbose",
+          "allowNo": false,
+          "type": "boolean"
+        },
+        "json-schema": {
+          "description": "Output the full JSON Schema document for config files instead of the human-readable reference",
+          "name": "json-schema",
+          "allowNo": false,
+          "type": "boolean"
+        }
+      },
+      "hasDynamicHelp": false,
+      "hiddenAliases": [],
+      "id": "config-schema",
+      "pluginAlias": "@quonfig/cli",
+      "pluginName": "@quonfig/cli",
+      "pluginType": "core",
+      "strict": true,
+      "enableJsonFlag": true,
+      "isESM": true,
+      "relativePath": [
+        "dist",
+        "commands",
+        "config-schema.js"
+      ]
+    },
     "create": {
       "aliases": [],
       "args": {
@@ -9,14 +69,16 @@
           "required": true
         }
       },
-      "description": "Create a new item in Quonfig",
+      "description": "Create a new feature flag, config value, or other item.\n\nUse --type to specify the kind of item:\n  boolean-flag  On/off feature flag (sendToClientSdk defaults to true; best for gradual rollouts)\n  string        A string configuration value\n  int           An integer configuration value\n  double        A floating-point configuration value\n  string-list   A comma-separated list of strings\n  json          An arbitrary JSON blob\n  boolean       A plain boolean (not a feature flag)\n\nThis sets the global default value. Override per-environment with:\n  qfg set-default my.flag --environment production --value true\n\nFor a percentage rollout (gradual rollout / A/B test / canary deploy), use:\n  qfg set-rollout my.flag --environment production --true-percent 20\n\nOr edit the JSON config file directly for complex targeting rules:\n  qfg config-schema          # full operator reference + examples\n  qfg pull --dir ./config    # clone workspace, then edit JSON and git push",
       "examples": [
         "<%= config.bin %> <%= command.id %> my.new.flag --type boolean-flag",
         "<%= config.bin %> <%= command.id %> my.new.flag --type boolean-flag --value=true",
         "<%= config.bin %> <%= command.id %> my.new.string --type string --value=\"hello world\"",
         "<%= config.bin %> <%= command.id %> my.new.string --type string --value=\"hello world\" --secret",
         "<%= config.bin %> <%= command.id %> my.new.string --type string --env-var=MY_ENV_VAR_NAME",
-        "<%= config.bin %> <%= command.id %> my.new.string --type json --value=\"{\\\"key\\\": \\\"value\\\"}\""
+        "<%= config.bin %> <%= command.id %> my.new.string --type json --value=\"{\\\"key\\\": \\\"value\\\"}\"",
+        "# After creating a flag, set a 20% rollout in production:",
+        "<%= config.bin %> set-rollout my.new.flag --environment production --true-percent 20"
       ],
       "flags": {
         "json": {
@@ -425,9 +487,10 @@
           "name": "name"
         }
       },
-      "description": "Show details about the provided config/feature-flag/etc.",
+      "description": "Show current values, rules, and evaluation stats for a flag or config.\n\nOutput shows the value for each environment:\n  - A simple value (true / false / \"hello\") means a single unconditional rule.\n  - \"[see rules]\" means the environment has targeting rules or a percentage rollout.\n  - \"[inherit]\" means the environment falls back to the Default value.\n\nPercentage rollouts are displayed as \"20.0% true, 80.0% false\".\nEvaluation counts for the past 24 hours are included by default.\n\nRelated commands:\n  qfg set-default my.flag --environment production --value true   # set a scalar fallback\n  qfg set-rollout my.flag --environment production --true-percent 20  # set a % rollout",
       "examples": [
-        "<%= config.bin %> <%= command.id %> my.config.name"
+        "<%= config.bin %> <%= command.id %> my.config.name",
+        "<%= config.bin %> <%= command.id %> my.config.name --exclude-evaluations   # skip 24h stats"
       ],
       "flags": {
         "json": {
@@ -834,7 +897,7 @@
       "examples": [
         "<%= config.bin %> <%= command.id %>",
         "<%= config.bin %> <%= command.id %> --editor cursor",
-        "<%= config.bin %> <%= command.id %> --url http://local-app.goatsofquonfig.com:3003/api/v1/mcp"
+        "<%= config.bin %> <%= command.id %> --url http://local-app.quonfig-staging.com:3003/api/v1/mcp"
       ],
       "flags": {
         "json": {
@@ -1044,6 +1107,74 @@
         "profile.js"
       ]
     },
+    "pull": {
+      "aliases": [],
+      "args": {},
+      "description": "Clone or update a local copy of your workspace config files.\n\nUse this when you need to edit flag JSON directly — for complex targeting rules,\nmulti-rule configs, or anything beyond a single scalar value.\n\nFor the config file format, operator reference, and examples:\n  qfg config-schema              # human-readable reference\n  qfg config-schema --json-schema  # machine-readable JSON Schema\n\nAfter editing files:\n  qfg verify <dir>               # validate JSON before pushing\n  git -C <dir> add -A && git -C <dir> commit -m \"feat: ...\" && git -C <dir> push\n\nCLI shortcuts (no JSON editing needed for simple cases):\n  qfg set-rollout my.flag --environment production --true-percent 20\n  qfg set-default my.flag --environment production --value true",
+      "examples": [
+        "<%= config.bin %> pull --dir ./our-config",
+        "<%= config.bin %> pull  # uses QUONFIG_DIR env var"
+      ],
+      "flags": {
+        "json": {
+          "description": "Format output as json.",
+          "helpGroup": "GLOBAL",
+          "name": "json",
+          "allowNo": false,
+          "type": "boolean"
+        },
+        "interactive": {
+          "description": "Force interactive mode",
+          "helpGroup": "GLOBAL",
+          "name": "interactive",
+          "allowNo": true,
+          "type": "boolean"
+        },
+        "no-color": {
+          "description": "Do not colorize output",
+          "env": "NO_COLOR",
+          "helpGroup": "GLOBAL",
+          "name": "no-color",
+          "allowNo": false,
+          "type": "boolean"
+        },
+        "verbose": {
+          "description": "Verbose output",
+          "helpGroup": "GLOBAL",
+          "name": "verbose",
+          "allowNo": false,
+          "type": "boolean"
+        },
+        "dir": {
+          "description": "Local directory to clone/update (defaults to QUONFIG_DIR env var)",
+          "name": "dir",
+          "hasDynamicHelp": false,
+          "multiple": false,
+          "type": "option"
+        },
+        "workspace": {
+          "description": "Workspace ID (defaults to active profile)",
+          "name": "workspace",
+          "hasDynamicHelp": false,
+          "multiple": false,
+          "type": "option"
+        }
+      },
+      "hasDynamicHelp": false,
+      "hiddenAliases": [],
+      "id": "pull",
+      "pluginAlias": "@quonfig/cli",
+      "pluginName": "@quonfig/cli",
+      "pluginType": "core",
+      "strict": true,
+      "enableJsonFlag": true,
+      "isESM": true,
+      "relativePath": [
+        "dist",
+        "commands",
+        "pull.js"
+      ]
+    },
     "schema": {
       "aliases": [],
       "args": {
@@ -1216,12 +1347,15 @@
           "name": "name"
         }
       },
-      "description": "Set/update the default value for an environment (other rules still apply)",
+      "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",
       "examples": [
-        "<%= config.bin %> <%= command.id %> my.flag.name # will prompt for value and env",
+        "<%= 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=true --secret",
-        "<%= config.bin %> <%= command.id %> my.config.name --env-var=MY_ENV_VAR_NAME --environment=production"
+        "<%= config.bin %> <%= command.id %> my.config.name --env-var=MY_ENV_VAR_NAME --environment=production",
+        "# For a percentage rollout, use set-rollout instead:",
+        "<%= config.bin %> set-rollout my.flag.name --environment production --true-percent 20"
       ],
       "flags": {
         "json": {
@@ -1326,6 +1460,191 @@
         "set-default.js"
       ]
     },
+    "set-rollout": {
+      "aliases": [],
+      "args": {
+        "name": {
+          "description": "config/feature-flag/etc. name",
+          "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",
+      "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)",
+        "<%= 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"
+      ],
+      "flags": {
+        "json": {
+          "description": "Format output as json.",
+          "helpGroup": "GLOBAL",
+          "name": "json",
+          "allowNo": false,
+          "type": "boolean"
+        },
+        "interactive": {
+          "description": "Force interactive mode",
+          "helpGroup": "GLOBAL",
+          "name": "interactive",
+          "allowNo": true,
+          "type": "boolean"
+        },
+        "no-color": {
+          "description": "Do not colorize output",
+          "env": "NO_COLOR",
+          "helpGroup": "GLOBAL",
+          "name": "no-color",
+          "allowNo": false,
+          "type": "boolean"
+        },
+        "verbose": {
+          "description": "Verbose output",
+          "helpGroup": "GLOBAL",
+          "name": "verbose",
+          "allowNo": false,
+          "type": "boolean"
+        },
+        "profile": {
+          "char": "p",
+          "description": "Profile to use (defaults to ENV var QUONFIG_PROFILE or \"default\")",
+          "helpGroup": "GLOBAL",
+          "name": "profile",
+          "required": false,
+          "hasDynamicHelp": false,
+          "multiple": false,
+          "type": "option"
+        },
+        "environment": {
+          "description": "environment to update (e.g. production, staging)",
+          "name": "environment",
+          "hasDynamicHelp": false,
+          "multiple": false,
+          "type": "option"
+        },
+        "hash-by": {
+          "description": "user property used to assign buckets (default: user.key)",
+          "name": "hash-by",
+          "default": "user.key",
+          "hasDynamicHelp": false,
+          "multiple": false,
+          "type": "option"
+        },
+        "true-percent": {
+          "description": "percentage of users that receive true (0–100). Remaining users receive false. Boolean flags only.",
+          "name": "true-percent",
+          "hasDynamicHelp": false,
+          "multiple": false,
+          "type": "option"
+        },
+        "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",
+          "hasDynamicHelp": false,
+          "multiple": false,
+          "type": "option"
+        },
+        "confirm": {
+          "description": "skip the interactive confirmation prompt (useful for scripts and agents)",
+          "name": "confirm",
+          "allowNo": false,
+          "type": "boolean"
+        }
+      },
+      "hasDynamicHelp": false,
+      "hiddenAliases": [],
+      "id": "set-rollout",
+      "pluginAlias": "@quonfig/cli",
+      "pluginName": "@quonfig/cli",
+      "pluginType": "core",
+      "strict": true,
+      "enableJsonFlag": true,
+      "isESM": true,
+      "relativePath": [
+        "dist",
+        "commands",
+        "set-rollout.js"
+      ]
+    },
+    "sync": {
+      "aliases": [],
+      "args": {},
+      "description": "Continuously poll for workspace config updates and apply them locally",
+      "examples": [
+        "<%= config.bin %> sync --watch",
+        "<%= config.bin %> sync --watch --interval 10",
+        "<%= config.bin %> sync --watch --dir ./our-config --interval 30"
+      ],
+      "flags": {
+        "json": {
+          "description": "Format output as json.",
+          "helpGroup": "GLOBAL",
+          "name": "json",
+          "allowNo": false,
+          "type": "boolean"
+        },
+        "interactive": {
+          "description": "Force interactive mode",
+          "helpGroup": "GLOBAL",
+          "name": "interactive",
+          "allowNo": true,
+          "type": "boolean"
+        },
+        "no-color": {
+          "description": "Do not colorize output",
+          "env": "NO_COLOR",
+          "helpGroup": "GLOBAL",
+          "name": "no-color",
+          "allowNo": false,
+          "type": "boolean"
+        },
+        "verbose": {
+          "description": "Verbose output",
+          "helpGroup": "GLOBAL",
+          "name": "verbose",
+          "allowNo": false,
+          "type": "boolean"
+        },
+        "dir": {
+          "description": "Local directory to sync (defaults to QUONFIG_DIR env var)",
+          "name": "dir",
+          "hasDynamicHelp": false,
+          "multiple": false,
+          "type": "option"
+        },
+        "interval": {
+          "description": "Poll interval in seconds",
+          "name": "interval",
+          "default": 60,
+          "hasDynamicHelp": false,
+          "multiple": false,
+          "type": "option"
+        },
+        "watch": {
+          "description": "Run as a continuous polling daemon (required)",
+          "name": "watch",
+          "required": true,
+          "allowNo": false,
+          "type": "boolean"
+        }
+      },
+      "hasDynamicHelp": false,
+      "hiddenAliases": [],
+      "id": "sync",
+      "pluginAlias": "@quonfig/cli",
+      "pluginName": "@quonfig/cli",
+      "pluginType": "core",
+      "strict": true,
+      "enableJsonFlag": true,
+      "isESM": true,
+      "relativePath": [
+        "dist",
+        "commands",
+        "sync.js"
+      ]
+    },
     "verify": {
       "aliases": [],
       "args": {
@@ -1498,7 +1817,83 @@
         "commands",
         "workspace.js"
       ]
+    },
+    "workspace:bootstrap": {
+      "aliases": [],
+      "args": {},
+      "description": "Push a local git repo to Gitea as this workspace's config repository",
+      "examples": [
+        "<%= config.bin %> workspace bootstrap --dir ./our-config",
+        "<%= config.bin %> workspace bootstrap --dir ./launch-migrator/output",
+        "<%= config.bin %> workspace bootstrap --dir ./our-config --skip-validate"
+      ],
+      "flags": {
+        "json": {
+          "description": "Format output as json.",
+          "helpGroup": "GLOBAL",
+          "name": "json",
+          "allowNo": false,
+          "type": "boolean"
+        },
+        "interactive": {
+          "description": "Force interactive mode",
+          "helpGroup": "GLOBAL",
+          "name": "interactive",
+          "allowNo": true,
+          "type": "boolean"
+        },
+        "no-color": {
+          "description": "Do not colorize output",
+          "env": "NO_COLOR",
+          "helpGroup": "GLOBAL",
+          "name": "no-color",
+          "allowNo": false,
+          "type": "boolean"
+        },
+        "verbose": {
+          "description": "Verbose output",
+          "helpGroup": "GLOBAL",
+          "name": "verbose",
+          "allowNo": false,
+          "type": "boolean"
+        },
+        "dir": {
+          "description": "Local directory to push (defaults to current directory)",
+          "name": "dir",
+          "required": false,
+          "hasDynamicHelp": false,
+          "multiple": false,
+          "type": "option"
+        },
+        "force": {
+          "description": "Force push even if remote already has commits",
+          "name": "force",
+          "allowNo": false,
+          "type": "boolean"
+        },
+        "skip-validate": {
+          "description": "Skip config validation before pushing",
+          "name": "skip-validate",
+          "allowNo": false,
+          "type": "boolean"
+        }
+      },
+      "hasDynamicHelp": false,
+      "hiddenAliases": [],
+      "id": "workspace:bootstrap",
+      "pluginAlias": "@quonfig/cli",
+      "pluginName": "@quonfig/cli",
+      "pluginType": "core",
+      "strict": true,
+      "enableJsonFlag": true,
+      "isESM": true,
+      "relativePath": [
+        "dist",
+        "commands",
+        "workspace",
+        "bootstrap.js"
+      ]
     }
   },
-  "version": "0.0.2"
+  "version": "0.0.5"
 }

package/package.json

@@ -1,7 +1,7 @@
 {
   "packageManager": "yarn@4.11.0+sha512.4e54aeace9141df2f0177c266b05ec50dc044638157dae128c471ba65994ac802122d7ab35bcd9e81641228b7dcf24867d28e750e0bcae8a05277d600008ad54",
   "name": "@quonfig/cli",
-  "version": "0.0.2",
+  "version": "0.0.5",
   "bugs": {
     "url": "https://github.com/quonfig/cli/issues"
   },
@@ -21,7 +21,7 @@
     "@oclif/core": "^3.18.2",
     "@oclif/plugin-help": "^6",
     "@oclif/plugin-plugins": "^4",
-    "@quonfig/node": "^0.0.1",
+    "@quonfig/node": "^0.0.2",
     "acorn": "^8.10.0",
     "acorn-walk": "^8.2.0",
     "chalk": "^5.4.1",