@quonfig/cli 0.0.4 → 0.0.5

package/dist/commands/create.js

@@ -11,7 +11,26 @@ export default class Create extends APICommand {
     static args = {
         name: Args.string({ description: 'name for your new item (e.g. my.new.flag)', required: true }),
     };
-    static description = 'Create a new item in Quonfig';
+    static description = `Create a new feature flag, config value, or other item.
+
+Use --type to specify the kind of item:
+  boolean-flag  On/off feature flag (sendToClientSdk defaults to true; best for gradual rollouts)
+  string        A string configuration value
+  int           An integer configuration value
+  double        A floating-point configuration value
+  string-list   A comma-separated list of strings
+  json          An arbitrary JSON blob
+  boolean       A plain boolean (not a feature flag)
+
+This sets the global default value. Override per-environment with:
+  qfg set-default my.flag --environment production --value true
+
+For a percentage rollout (gradual rollout / A/B test / canary deploy), use:
+  qfg set-rollout my.flag --environment production --true-percent 20
+
+Or edit the JSON config file directly for complex targeting rules:
+  qfg config-schema          # full operator reference + examples
+  qfg pull --dir ./config    # clone workspace, then edit JSON and git push`;
     static examples = [
         '<%= config.bin %> <%= command.id %> my.new.flag --type boolean-flag',
         '<%= config.bin %> <%= command.id %> my.new.flag --type boolean-flag --value=true',
@@ -19,6 +38,8 @@ export default class Create extends APICommand {
         '<%= 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\\"}"',
+        '# After creating a flag, set a 20% rollout in production:',
+        '<%= config.bin %> set-rollout my.new.flag --environment production --true-percent 20',
     ];
     static flags = {
         confidential: Flags.boolean({ default: false, description: 'mark the value as confidential' }),

package/dist/commands/info.js

@@ -7,8 +7,23 @@ import isInteractive from '../util/is-interactive.js';
 import nameArg from '../util/name-arg.js';
 export default class Info extends APICommand {
     static args = { ...nameArg };
-    static description = 'Show details about the provided config/feature-flag/etc.';
-    static examples = ['<%= config.bin %> <%= command.id %> my.config.name'];
+    static description = `Show current values, rules, and evaluation stats for a flag or config.
+
+Output shows the value for each environment:
+  - A simple value (true / false / "hello") means a single unconditional rule.
+  - "[see rules]" means the environment has targeting rules or a percentage rollout.
+  - "[inherit]" means the environment falls back to the Default value.
+
+Percentage rollouts are displayed as "20.0% true, 80.0% false".
+Evaluation counts for the past 24 hours are included by default.
+
+Related commands:
+  qfg set-default my.flag --environment production --value true   # set a scalar fallback
+  qfg set-rollout my.flag --environment production --true-percent 20  # set a % rollout`;
+    static examples = [
+        '<%= config.bin %> <%= command.id %> my.config.name',
+        '<%= config.bin %> <%= command.id %> my.config.name --exclude-evaluations   # skip 24h stats',
+    ];
     static flags = {
         'exclude-evaluations': Flags.boolean({ default: false, description: 'Exclude evaluation data' }),
     };

package/dist/commands/pull.js

@@ -7,7 +7,22 @@ import { loadGiteaToken, isGiteaTokenExpired, saveGiteaToken } from '../util/git
 import { mintAndStoreGiteaReadToken, mintGiteaToken } from '../util/gitea-api.js';
 import { isGitRepo, getRemoteUrl, isWorkingTreeClean, gitFetch, gitSetRemote, canFastForward, hasDivergedFromRemote, gitMergeFfOnly, gitClone, displayUrl, } from '../util/git-ops.js';
 export default class Pull extends BaseCommand {
-    static description = 'Clone or update a local directory from the workspace Gitea repo';
+    static description = `Clone or update a local copy of your workspace config files.
+
+Use this when you need to edit flag JSON directly — for complex targeting rules,
+multi-rule configs, or anything beyond a single scalar value.
+
+For the config file format, operator reference, and examples:
+  qfg config-schema              # human-readable reference
+  qfg config-schema --json-schema  # machine-readable JSON Schema
+
+After editing files:
+  qfg verify <dir>               # validate JSON before pushing
+  git -C <dir> add -A && git -C <dir> commit -m "feat: ..." && git -C <dir> push
+
+CLI shortcuts (no JSON editing needed for simple cases):
+  qfg set-rollout my.flag --environment production --true-percent 20
+  qfg set-default my.flag --environment production --value true`;
     static examples = [
         '<%= config.bin %> pull --dir ./our-config',
         '<%= config.bin %> pull  # uses QUONFIG_DIR env var',

package/dist/commands/set-default.js

@@ -14,12 +14,29 @@ import nameArg from '../util/name-arg.js';
 import secretFlags, { parsedSecretFlags } from '../util/secret-flags.js';
 export default class SetDefault extends APICommand {
     static args = { ...nameArg };
-    static description = 'Set/update the default value for an environment (other rules still apply)';
+    static description = `Set the unconditional fallback value for a flag or config in a specific environment.
+
+This updates the catch-all rule — the value users receive when NO targeting rule matches.
+Any targeting rules or percentage rollouts you have configured are NOT affected; they
+continue to fire before this fallback is evaluated.
+
+"Other rules still apply" means: if you have rules targeting specific users, segments,
+or properties, those rules still take priority. This command only changes what everyone
+else sees.
+
+To set a percentage rollout (gradual rollout / A/B test / canary deploy) instead:
+  qfg set-rollout my.flag --environment production --true-percent 20
+
+To see all current values and rules for a flag:
+  qfg info my.flag`;
     static 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',
+        '# For a percentage rollout, use set-rollout instead:',
+        '<%= config.bin %> set-rollout my.flag.name --environment production --true-percent 20',
     ];
     static flags = {
         confidential: Flags.boolean({ default: false, description: 'mark the value as confidential' }),
@@ -123,7 +140,6 @@ export default class SetDefault extends APICommand {
                 config,
                 envVar: flags['env-var'],
                 environment,
-                environmentId: environment.id,
                 key,
                 secret,
             });
@@ -147,13 +163,12 @@ export default class SetDefault extends APICommand {
             confidential,
             config,
             environment,
-            environmentId: environment.id,
             key,
             secret,
             value,
         });
     }
-    async submitChange({ confidential, config, envVar, environment, environmentId, key, secret, value, }) {
+    async submitChange({ confidential, config, envVar, environment, key, secret, value, }) {
         /* eslint-disable camelcase */
         const typeMapping = {
             bool: 'bool',
@@ -174,7 +189,7 @@ export default class SetDefault extends APICommand {
             successMessage = `Successfully changed default to \`${value}\``;
             if (secret.selected) {
                 // Handle encrypted values using shared utility
-                const encryptedValueResult = await makeConfidentialValue(this, value, secret, environmentId);
+                const encryptedValueResult = await makeConfidentialValue(this, value, secret, environment.id);
                 if (!encryptedValueResult.ok) {
                     return this.err(encryptedValueResult.message || 'Failed to encrypt value');
                 }
@@ -244,19 +259,67 @@ export default class SetDefault extends APICommand {
             configValue.confidential = true;
             successMessage += ' (confidential)';
         }
-        const payload = {
-            configKey: key,
-            currentVersionId: config.version,
-            environmentId: environmentId ? Number.parseInt(environmentId, 10) : 0,
-            value: configValue,
-        };
-        this.verboseLog('Payload:', payload);
-        const request = await this.apiClient.post('/internal/ops/v1/set-default', payload);
+        // Fetch the current full config to get the existing environments array and commitSha.
+        const detailRequest = await this.apiClient.post('/api/v1/metadata/getByKey', {
+            workspaceId: this.workspaceId,
+            key,
+        });
+        if (!detailRequest.ok) {
+            return this.err(`Failed to fetch config details: ${detailRequest.status}`);
+        }
+        const currentConfig = detailRequest.json;
+        // Build a single catch-all rule (empty criteria = matches everything).
+        const newRule = { criteria: [], value: configValue };
+        // For [Default] (environment.id === ''), update default.rules.
+        // For a specific environment, update the environments array.
+        let updateFields;
+        if (environment.id === '') {
+            // [Default] — no environment-specific block, update the catch-all default rules.
+            updateFields = { default: { rules: [newRule] } };
+        }
+        else {
+            // environment.name is the slug stored in git files (e.g. "production").
+            // environment.id is the DB UUID — never written to git files.
+            const envKey = environment.name;
+            const existingEnvs = currentConfig.environments ?? [];
+            const hasEnv = existingEnvs.some((e) => e.id === envKey);
+            const updatedEnvironments = hasEnv
+                ? existingEnvs.map((e) => (e.id === envKey ? { ...e, rules: [newRule] } : e))
+                : [...existingEnvs, { id: envKey, rules: [newRule] }];
+            updateFields = { environments: updatedEnvironments };
+        }
+        this.verboseLog('Update fields:', JSON.stringify(updateFields, null, 2));
+        // Route to the correct update endpoint based on config type.
+        let request;
+        if (config.type === 'feature_flag') {
+            request = await this.apiClient.post('/api/v1/flags/update', {
+                workspaceId: this.workspaceId,
+                flagKey: key,
+                flag: updateFields,
+                expectedCommitSha: currentConfig.commitSha,
+            });
+        }
+        else if (config.type === 'log_level') {
+            request = await this.apiClient.post('/api/v1/logLevels/update', {
+                workspaceId: this.workspaceId,
+                logLevelKey: key,
+                logLevel: updateFields,
+                expectedCommitSha: currentConfig.commitSha,
+            });
+        }
+        else {
+            request = await this.apiClient.post('/api/v1/configs/update', {
+                workspaceId: this.workspaceId,
+                configKey: key,
+                config: updateFields,
+                expectedCommitSha: currentConfig.commitSha,
+            });
+        }
         if (request.ok) {
             this.log(`${checkmark} ${successMessage}`);
             return {
                 environment: {
-                    id: environmentId,
+                    id: environment.id,
                     name: environment.name,
                 },
                 key,

package/dist/commands/set-rollout.d.ts

@@ -0,0 +1,19 @@
+import { APICommand } from '../index.js';
+import { JsonObj } from '../result.js';
+export default class SetRollout 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: {
+        environment: import("@oclif/core/lib/interfaces/parser.js").OptionFlag<string | undefined, import("@oclif/core/lib/interfaces/parser.js").CustomOptions>;
+        'hash-by': import("@oclif/core/lib/interfaces/parser.js").OptionFlag<string, import("@oclif/core/lib/interfaces/parser.js").CustomOptions>;
+        'true-percent': import("@oclif/core/lib/interfaces/parser.js").OptionFlag<number | undefined, import("@oclif/core/lib/interfaces/parser.js").CustomOptions>;
+        weights: import("@oclif/core/lib/interfaces/parser.js").OptionFlag<string | undefined, import("@oclif/core/lib/interfaces/parser.js").CustomOptions>;
+        confirm: import("@oclif/core/lib/interfaces/parser.js").BooleanFlag<boolean>;
+    };
+    run(): Promise<JsonObj | void>;
+    private parseWeights;
+    private coerceValue;
+}

package/dist/commands/set-rollout.js

@@ -0,0 +1,260 @@
+import { Flags } from '@oclif/core';
+import { APICommand } from '../index.js';
+import getConfirmation from '../ui/get-confirmation.js';
+import getEnvironment from '../ui/get-environment.js';
+import { checkmark } from '../util/color.js';
+import isInteractive from '../util/is-interactive.js';
+import nameArg from '../util/name-arg.js';
+const WEIGHT_TOTAL = 100_000;
+export default class SetRollout extends APICommand {
+    static args = { ...nameArg };
+    static description = `Configure a percentage rollout (gradual rollout / A/B test / canary deploy) for a flag.
+
+The flag must already exist. Create it first if needed:
+  qfg create my.flag --type boolean-flag
+
+Weights are specified as whole-number percentages (0–100). They must sum to 100.
+
+For a boolean flag, use --true-percent to set the percentage of users that receive
+true (the remainder automatically receive false):
+  qfg set-rollout my.flag --environment production --true-percent 20
+  → 20% of users get true, 80% get false
+
+For multi-value flags or custom splits, use --weights with a comma-separated list:
+  qfg set-rollout my.flag --environment production --weights "red:33,green:33,blue:34"
+
+Hashing: users are bucketed by the value of hashByPropertyName (default: "user.key").
+Use --hash-by to change which property drives the bucket assignment:
+  qfg set-rollout my.flag --environment production --true-percent 10 --hash-by user.id
+
+For scripted / agent use, add --confirm to skip the interactive confirmation prompt.
+
+To combine a rollout with segment targeting (e.g. beta ON, holdout OFF, everyone else 50/50),
+you need to edit the JSON config file directly:
+  qfg config-schema           # operator reference + worked multi-rule example
+  qfg pull --dir ./config     # clone workspace to edit
+
+To revert to a single value for everyone, use:
+  qfg set-default my.flag --environment production --value false
+
+To inspect the current rollout:
+  qfg info my.flag`;
+    static 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',
+    ];
+    static flags = {
+        environment: Flags.string({ description: 'environment to update (e.g. production, staging)' }),
+        'hash-by': Flags.string({
+            default: 'user.key',
+            description: 'user property used to assign buckets (default: user.key)',
+        }),
+        'true-percent': Flags.integer({
+            description: 'percentage of users that receive true (0–100). Remaining users receive false. Boolean flags only.',
+            max: 100,
+            min: 0,
+        }),
+        weights: Flags.string({
+            description: 'comma-separated "value:percent" pairs that must sum to 100 (e.g. "true:20,false:80" or "red:33,green:33,blue:34")',
+        }),
+        confirm: Flags.boolean({ description: 'skip the interactive confirmation prompt (useful for scripts and agents)' }),
+    };
+    async run() {
+        const { args, flags } = await this.parse(SetRollout);
+        // Validate flag exclusivity
+        if (flags['true-percent'] !== undefined && flags.weights) {
+            return this.err('Use either --true-percent or --weights, not both.');
+        }
+        if (flags['true-percent'] === undefined && !flags.weights) {
+            return this.err('Either --true-percent or --weights is required.');
+        }
+        // Validate required args for non-interactive mode
+        if (!args.name && !isInteractive(flags)) {
+            return this.err("'name' argument is required when interactive mode isn't available.");
+        }
+        if (!flags.environment && !isInteractive(flags)) {
+            return this.err("'environment' is required when interactive mode isn't available.");
+        }
+        // Fetch config metadata to validate the key exists
+        const metadataRequest = await this.apiClient.post('/api/v1/metadata/list', { workspaceId: this.workspaceId });
+        if (!metadataRequest.ok) {
+            const errorMsg = metadataRequest.error?.error || `Failed to fetch configs: ${metadataRequest.status}`;
+            return this.err(errorMsg, { serverError: metadataRequest.error });
+        }
+        const metadataResponse = metadataRequest.json;
+        const configs = metadataResponse.configs;
+        let key = args.name;
+        if (!key && isInteractive(flags)) {
+            const { default: autocomplete } = await import('../util/autocomplete.js');
+            const selected = await autocomplete({
+                message: 'Which flag would you like to configure a rollout for?',
+                source: configs.map((c) => c.key),
+            });
+            if (selected)
+                key = selected;
+        }
+        if (!key) {
+            return this.err("'name' argument is required when interactive mode isn't available.");
+        }
+        const config = configs.find((c) => c.key === key);
+        if (!config) {
+            return this.err(`Could not find config named ${key}`);
+        }
+        // Get environment
+        const environment = await getEnvironment({
+            command: this,
+            flags,
+            message: 'Which environment would you like to configure the rollout for?',
+            providedEnvironment: flags.environment,
+        });
+        if (!environment)
+            return;
+        // Build weighted values
+        let weightedValues;
+        if (flags['true-percent'] !== undefined) {
+            const truePercent = flags['true-percent'];
+            const falsePercent = 100 - truePercent;
+            weightedValues = [
+                { value: { type: 'bool', value: true }, weight: truePercent * (WEIGHT_TOTAL / 100) },
+                { value: { type: 'bool', value: false }, weight: falsePercent * (WEIGHT_TOTAL / 100) },
+            ];
+        }
+        else {
+            // Parse --weights "value1:N,value2:M,..."
+            const parsed = this.parseWeights(flags.weights, config.valueType);
+            if (!parsed.ok) {
+                return this.err(parsed.error);
+            }
+            weightedValues = parsed.weights;
+        }
+        const totalWeight = weightedValues.reduce((sum, wv) => sum + wv.weight, 0);
+        if (totalWeight !== WEIGHT_TOTAL) {
+            return this.err(`Weights must sum to 100. Got: ${weightedValues.map((wv) => `${wv.weight / 1000}%`).join(' + ')} = ${totalWeight / 1000}%`);
+        }
+        const rolloutValue = {
+            type: 'weighted_values',
+            value: {
+                hashByPropertyName: flags['hash-by'],
+                weightedValues,
+            },
+        };
+        const rolloutDescription = weightedValues
+            .map((wv) => `${wv.weight / 1000}% → ${JSON.stringify(wv.value.value)}`)
+            .join(', ');
+        const message = `Confirm: set rollout for ${key} in ${environment.name} to [${rolloutDescription}]? yes/no`;
+        if (!(await getConfirmation({ flags, message }))) {
+            return;
+        }
+        // Fetch the current full config to get commitSha and existing environments
+        const detailRequest = await this.apiClient.post('/api/v1/metadata/getByKey', {
+            workspaceId: this.workspaceId,
+            key,
+        });
+        if (!detailRequest.ok) {
+            return this.err(`Failed to fetch config details: ${detailRequest.status}`);
+        }
+        const currentConfig = detailRequest.json;
+        const newRule = { criteria: [], value: rolloutValue };
+        const envKey = environment.name;
+        const existingEnvs = currentConfig.environments ?? [];
+        const hasEnv = existingEnvs.some((e) => e.id === envKey);
+        const updatedEnvironments = hasEnv
+            ? existingEnvs.map((e) => (e.id === envKey ? { ...e, rules: [newRule] } : e))
+            : [...existingEnvs, { id: envKey, rules: [newRule] }];
+        const updateFields = { environments: updatedEnvironments };
+        this.verboseLog('Update fields:', JSON.stringify(updateFields, null, 2));
+        let request;
+        if (config.type === 'feature_flag') {
+            request = await this.apiClient.post('/api/v1/flags/update', {
+                expectedCommitSha: currentConfig.commitSha,
+                flag: updateFields,
+                flagKey: key,
+                workspaceId: this.workspaceId,
+            });
+        }
+        else {
+            request = await this.apiClient.post('/api/v1/configs/update', {
+                config: updateFields,
+                configKey: key,
+                expectedCommitSha: currentConfig.commitSha,
+                workspaceId: this.workspaceId,
+            });
+        }
+        if (request.ok) {
+            this.log(`${checkmark} Rollout set: ${key} in ${environment.name} → [${rolloutDescription}]`);
+            return {
+                environment: { id: environment.id, name: environment.name },
+                hashByPropertyName: flags['hash-by'],
+                key,
+                rollout: rolloutDescription,
+                success: true,
+                weightedValues,
+            };
+        }
+        this.verboseLog(request.error);
+        return this.err(`Failed to set rollout: ${request.status} | ${JSON.stringify(request.error)}`, { key, serverError: request.error });
+    }
+    parseWeights(weightsStr, valueType) {
+        const pairs = weightsStr.split(',').map((s) => s.trim());
+        const weights = [];
+        let totalPercent = 0;
+        for (const pair of pairs) {
+            const colonIdx = pair.lastIndexOf(':');
+            if (colonIdx === -1) {
+                return {
+                    error: `Invalid weight entry "${pair}". Expected format "value:percent" (e.g. "true:20").`,
+                    ok: false,
+                };
+            }
+            const rawValue = pair.slice(0, colonIdx).trim();
+            const percentStr = pair.slice(colonIdx + 1).trim();
+            const percent = Number(percentStr);
+            if (Number.isNaN(percent) || percent < 0 || percent > 100) {
+                return { error: `Invalid percent "${percentStr}" in "${pair}". Must be 0–100.`, ok: false };
+            }
+            const typedValue = this.coerceValue(rawValue, valueType);
+            if (!typedValue.ok) {
+                return { error: typedValue.error, ok: false };
+            }
+            weights.push({ value: typedValue.typed, weight: percent * (WEIGHT_TOTAL / 100) });
+            totalPercent += percent;
+        }
+        if (Math.round(totalPercent) !== 100) {
+            return { error: `Weights must sum to 100. Got: ${totalPercent}%.`, ok: false };
+        }
+        return { ok: true, weights };
+    }
+    coerceValue(raw, valueType) {
+        const type = valueType.toLowerCase();
+        switch (type) {
+            case 'bool': {
+                if (raw !== 'true' && raw !== 'false') {
+                    return { error: `Invalid boolean value "${raw}". Must be "true" or "false".`, ok: false };
+                }
+                return { ok: true, typed: { type: 'bool', value: raw === 'true' } };
+            }
+            case 'int': {
+                const n = Number.parseInt(raw, 10);
+                if (Number.isNaN(n)) {
+                    return { error: `Invalid int value "${raw}".`, ok: false };
+                }
+                return { ok: true, typed: { type: 'int', value: n } };
+            }
+            case 'double': {
+                const n = Number.parseFloat(raw);
+                if (Number.isNaN(n)) {
+                    return { error: `Invalid double value "${raw}".`, ok: false };
+                }
+                return { ok: true, typed: { type: 'double', value: n } };
+            }
+            default: {
+                // string, json, etc — pass as-is
+                return { ok: true, typed: { type, value: raw } };
+            }
+        }
+    }
+}