@quonfig/cli 0.0.2 → 0.0.5

package/dist/commands/config-schema.js

@@ -0,0 +1,165 @@
+import { Flags } from '@oclif/core';
+import { BaseCommand } from '../index.js';
+import { storedConfigJsonSchema } from '../init/schema.js';
+const REFERENCE = `
+────────────────────────────────────────────────────────────
+FILE LAYOUT
+────────────────────────────────────────────────────────────
+Config files live in your workspace (clone with: qfg pull --dir ./my-config):
+
+  feature-flags/   Boolean feature flags (on/off, targeting, percentage rollouts)
+  configs/         Typed config values (string, int, double, json, string-list)
+  segments/        User segments for targeting rules
+  log-levels/      Dynamic log-level configs
+
+────────────────────────────────────────────────────────────
+RULE EVALUATION
+────────────────────────────────────────────────────────────
+Rules are evaluated in ORDER — the FIRST matching rule wins.
+Put specific rules (user lists, segments) BEFORE catch-all rules.
+  criteria: []   means "match everyone" (unconditional / catch-all)
+  criteria: [..] multiple entries in one rule are ANDed together
+
+────────────────────────────────────────────────────────────
+EXAMPLE: complex targeting + rollout in production
+────────────────────────────────────────────────────────────
+Four rules in order:
+  1. Always ON  for users in an allowlist
+  2. Always ON  for users in the "beta" segment
+  3. Always OFF for users in the "holdout" segment
+  4. 50/50 split for everyone else
+
+  {
+    "key": "my.feature.flag",
+    "type": "feature_flag",
+    "valueType": "bool",
+    "default": {
+      "rules": [{ "criteria": [], "value": { "type": "bool", "value": false } }]
+    },
+    "environments": [{
+      "id": "production",
+      "rules": [
+        {
+          "criteria": [{
+            "operator": "PROP_IS_ONE_OF",
+            "propertyName": "user.key",
+            "valueToMatch": { "type": "string_list", "value": ["user-123", "user-456"] }
+          }],
+          "value": { "type": "bool", "value": true }
+        },
+        {
+          "criteria": [{
+            "operator": "IN_SEG",
+            "valueToMatch": { "type": "string", "value": "beta" }
+          }],
+          "value": { "type": "bool", "value": true }
+        },
+        {
+          "criteria": [{
+            "operator": "IN_SEG",
+            "valueToMatch": { "type": "string", "value": "holdout" }
+          }],
+          "value": { "type": "bool", "value": false }
+        },
+        {
+          "criteria": [],
+          "value": {
+            "type": "weighted_values",
+            "value": {
+              "hashByPropertyName": "user.key",
+              "weightedValues": [
+                { "value": { "type": "bool", "value": true },  "weight": 50000 },
+                { "value": { "type": "bool", "value": false }, "weight": 50000 }
+              ]
+            }
+          }
+        }
+      ]
+    }]
+  }
+
+────────────────────────────────────────────────────────────
+CRITERION FIELDS
+────────────────────────────────────────────────────────────
+Each criterion object has:
+  operator        (required) — see operator table below
+  propertyName    (required for PROP_* operators) — user property, e.g. "user.key", "user.plan"
+  valueToMatch    (required for all except ALWAYS_TRUE) — typed value to compare against
+
+────────────────────────────────────────────────────────────
+OPERATOR REFERENCE
+────────────────────────────────────────────────────────────
+  Operator                         valueToMatch type    Notes
+  ────────────────────────────────────────────────────────
+  ALWAYS_TRUE                      (none)               Unconditional match; use for catch-all rules
+  PROP_IS_ONE_OF                   string_list          propertyName value is in the list
+  PROP_IS_NOT_ONE_OF               string_list          propertyName value is NOT in the list
+  PROP_STARTS_WITH_ONE_OF          string_list          string prefix match
+  PROP_DOES_NOT_START_WITH_ONE_OF  string_list
+  PROP_ENDS_WITH_ONE_OF            string_list          string suffix match
+  PROP_DOES_NOT_END_WITH_ONE_OF    string_list
+  PROP_CONTAINS_ONE_OF             string_list          substring match
+  PROP_DOES_NOT_CONTAIN_ONE_OF     string_list
+  PROP_LESS_THAN                   int or double        numeric comparison
+  PROP_LESS_THAN_OR_EQUAL          int or double
+  PROP_GREATER_THAN                int or double
+  PROP_GREATER_THAN_OR_EQUAL       int or double
+  PROP_BEFORE                      string (ISO 8601)    date/time comparison
+  PROP_AFTER                       string (ISO 8601)
+  PROP_MATCHES                     string               regex match
+  PROP_DOES_NOT_MATCH              string
+  IN_SEG                           string               value = segment key (no propertyName needed)
+  NOT_IN_SEG                       string               value = segment key (no propertyName needed)
+  IN_INT_RANGE                     int_range            value = {min, max}
+  LOOKUP_KEY_IN                    string_list          matches if SDK lookup key is in the list
+  LOOKUP_KEY_NOT_IN                string_list
+
+valueToMatch format: { "type": "<type>", "value": <value> }
+  string_list  →  { "type": "string_list", "value": ["a", "b"] }
+  string       →  { "type": "string",      "value": "beta" }
+  int          →  { "type": "int",         "value": 42 }
+  double       →  { "type": "double",      "value": 3.14 }
+
+────────────────────────────────────────────────────────────
+PERCENTAGE ROLLOUT (weighted_values)
+────────────────────────────────────────────────────────────
+Weights are integers out of 100,000 (not percentages):
+  5%=5000  10%=10000  20%=20000  50%=50000  100%=100000
+  All weights in one rule MUST sum to exactly 100,000.
+
+hashByPropertyName controls the bucket assignment property (default: "user.key").
+
+────────────────────────────────────────────────────────────
+RELATED COMMANDS
+────────────────────────────────────────────────────────────
+  qfg create my.flag --type boolean-flag          create a new flag
+  qfg set-default my.flag --environment prod ...  set a scalar fallback value
+  qfg set-rollout my.flag --environment prod ...  set a simple percentage rollout
+  qfg pull --dir ./config                         clone workspace to edit JSON directly
+  qfg verify ./config                             validate all JSON files before pushing
+  qfg info my.flag                                inspect current values and rules
+  qfg config-schema --json-schema                 print the machine-readable JSON Schema
+`.trim();
+export default class ConfigSchema extends BaseCommand {
+    static 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.';
+    static examples = [
+        '<%= config.bin %> <%= command.id %>                  # human-readable operator reference + examples',
+        '<%= config.bin %> <%= command.id %> --json-schema    # full JSON Schema document (copy into your editor)',
+    ];
+    static flags = {
+        'json-schema': Flags.boolean({
+            default: false,
+            description: 'Output the full JSON Schema document for config files instead of the human-readable reference',
+        }),
+    };
+    async run() {
+        const { flags } = await this.parse(ConfigSchema);
+        if (flags['json-schema']) {
+            const schema = storedConfigJsonSchema();
+            this.log(JSON.stringify(schema, null, 2));
+            return schema;
+        }
+        this.log(REFERENCE);
+    }
+}

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/login.js

@@ -1,4 +1,5 @@
 import { Flags } from '@oclif/core';
+import { select } from '@inquirer/prompts';
 import { BaseCommand } from '../index.js';
 import { decodeJWT, pollForToken, requestDeviceCode } from '../util/oauth-client.js';
 import { getApiUrl } from '../util/domain-urls.js';
@@ -53,6 +54,8 @@ export default class Login extends BaseCommand {
         // Resolve org_id → workspace UUID via the API
         let workspaceId;
         let workspaceName;
+        let workspaceSlug;
+        let organizationName;
         try {
             const apiUrl = getApiUrl();
             this.verboseLog('Resolving workspace...', { apiUrl, orgId });
@@ -66,14 +69,28 @@ export default class Login extends BaseCommand {
             });
             if (res.ok) {
                 const body = await res.json();
-                const workspaces = body.json ?? body;
-                const match = Array.isArray(workspaces)
-                    ? workspaces.find((w) => w.workosOrgId === orgId) ?? workspaces[0]
-                    : undefined;
+                const allWorkspaces = (body.json ?? body);
+                const orgWorkspaces = Array.isArray(allWorkspaces)
+                    ? allWorkspaces.filter((w) => w.workosOrgId === orgId)
+                    : [];
+                const candidates = orgWorkspaces.length > 0 ? orgWorkspaces : (Array.isArray(allWorkspaces) ? allWorkspaces : []);
+                let match;
+                if (candidates.length === 1) {
+                    match = candidates[0];
+                }
+                else if (candidates.length > 1) {
+                    const chosen = await select({
+                        choices: candidates.map((w) => ({ name: w.workspaceSlug, value: w.workspaceId })),
+                        message: 'Select workspace:',
+                    });
+                    match = candidates.find((w) => w.workspaceId === chosen);
+                }
                 if (match) {
                     workspaceId = match.workspaceId;
-                    workspaceName = match.organizationName;
-                    this.verboseLog('Resolved workspace', { workspaceId, workspaceName });
+                    workspaceName = match.workspaceSlug;
+                    workspaceSlug = match.workspaceSlug;
+                    organizationName = match.organizationName;
+                    this.verboseLog('Resolved workspace', { workspaceId, workspaceName, workspaceSlug, organizationName });
                 }
             }
             else {
@@ -95,6 +112,7 @@ export default class Login extends BaseCommand {
                 [profileName]: {
                     workspace: workspaceId || orgId || 'unknown',
                     workspaceName: workspaceName || (orgId ? `org:${orgId}` : undefined),
+                    workspaceSlug,
                 },
             },
         });
@@ -108,6 +126,9 @@ export default class Login extends BaseCommand {
         }
         if (workspaceName) {
             this.log(`Workspace: ${workspaceName} (${workspaceId})`);
+            if (organizationName) {
+                this.log(`Organization: ${organizationName}`);
+            }
         }
         else if (orgId) {
             this.log(`Organization: ${orgId}`);

package/dist/commands/mcp.js

@@ -12,7 +12,7 @@ export default class Mcp extends BaseCommand {
     static 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',
     ];
     static flags = {
         ...BaseCommand.baseFlags,

package/dist/commands/pull.d.ts

@@ -0,0 +1,15 @@
+import type { JsonObj } from '../result.js';
+import { BaseCommand } from '../index.js';
+export default class Pull extends BaseCommand {
+    static description: string;
+    static examples: string[];
+    static flags: {
+        dir: import("@oclif/core/lib/interfaces/parser.js").OptionFlag<string | undefined, import("@oclif/core/lib/interfaces/parser.js").CustomOptions>;
+        workspace: import("@oclif/core/lib/interfaces/parser.js").OptionFlag<string | undefined, import("@oclif/core/lib/interfaces/parser.js").CustomOptions>;
+    };
+    run(): Promise<JsonObj | void>;
+    private resolveRepoUrl;
+    private refreshAndGetUrl;
+    private looksLike401;
+    private maybeWriteQuonfigDir;
+}

package/dist/commands/pull.js

@@ -0,0 +1,191 @@
+import * as path from 'node:path';
+import * as fs from 'node:fs';
+import { Flags } from '@oclif/core';
+import { BaseCommand } from '../index.js';
+import { getActiveProfile, loadAuthConfig } from '../util/token-storage.js';
+import { loadGiteaToken, isGiteaTokenExpired, saveGiteaToken } from '../util/gitea-token-storage.js';
+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 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',
+    ];
+    static flags = {
+        dir: Flags.string({
+            description: 'Local directory to clone/update (defaults to QUONFIG_DIR env var)',
+        }),
+        workspace: Flags.string({
+            description: 'Workspace ID (defaults to active profile)',
+        }),
+    };
+    async run() {
+        const { flags } = await this.parse(Pull);
+        // Resolve target directory
+        const dir = flags.dir || process.env.QUONFIG_DIR;
+        if (!dir) {
+            return this.err('No directory specified. Use --dir <path> or set QUONFIG_DIR.');
+        }
+        const resolvedDir = path.resolve(dir);
+        // Resolve workspace ID
+        let workspaceId = flags.workspace;
+        if (!workspaceId) {
+            const authConfig = await loadAuthConfig();
+            if (!authConfig) {
+                return this.err('Not logged in. Please run `qfg login` first.');
+            }
+            const activeProfile = getActiveProfile();
+            const profile = authConfig.profiles[activeProfile] || authConfig.profiles[authConfig.defaultProfile || 'default'];
+            if (!profile) {
+                return this.err('No active profile found. Please run `qfg login` first.');
+            }
+            workspaceId = profile.workspace;
+        }
+        this.verboseLog('Pull', { workspaceId, dir: resolvedDir });
+        // Get or mint Gitea read token
+        const repoUrl = await this.resolveRepoUrl(workspaceId);
+        // Perform git operation
+        const isRepo = await isGitRepo(resolvedDir);
+        if (!isRepo) {
+            // Clone fresh
+            this.log(`Cloning workspace into ${resolvedDir}...`);
+            try {
+                await gitClone(repoUrl, resolvedDir);
+            }
+            catch (err) {
+                // On 401, refresh token and retry once
+                if (this.looksLike401(err)) {
+                    this.verboseLog('Pull', 'Got 401, refreshing Gitea token...');
+                    const freshUrl = await this.refreshAndGetUrl(workspaceId);
+                    await gitClone(freshUrl, resolvedDir);
+                }
+                else {
+                    throw err;
+                }
+            }
+            this.log(`Cloned successfully into ${resolvedDir}`);
+        }
+        else {
+            // Existing repo — check remote
+            const existingRemote = await getRemoteUrl(resolvedDir);
+            const expectedUrlBase = stripAuth(repoUrl);
+            if (existingRemote && stripAuth(existingRemote) !== expectedUrlBase) {
+                return this.err(`Directory has a different git remote:\n  existing: ${displayUrl(existingRemote)}\n  expected: ${expectedUrlBase}\n\nResolve manually or use a different --dir.`);
+            }
+            // Update the remote URL to use current (possibly refreshed) token
+            await gitSetRemote(resolvedDir, repoUrl);
+            // Check working tree
+            const clean = await isWorkingTreeClean(resolvedDir);
+            if (!clean) {
+                return this.err('Local changes present — commit, stash, or run `git reset --hard origin/main` to discard.');
+            }
+            // Fetch
+            this.log('Fetching from remote...');
+            try {
+                await gitFetch(resolvedDir);
+            }
+            catch (err) {
+                if (this.looksLike401(err)) {
+                    this.verboseLog('Pull', 'Got 401 on fetch, refreshing Gitea token...');
+                    const freshUrl = await this.refreshAndGetUrl(workspaceId);
+                    await gitSetRemote(resolvedDir, freshUrl);
+                    await gitFetch(resolvedDir);
+                }
+                else {
+                    throw err;
+                }
+            }
+            const ff = await canFastForward(resolvedDir);
+            const diverged = !ff && (await hasDivergedFromRemote(resolvedDir));
+            if (diverged) {
+                return this.err('Local commits diverge from remote — resolve manually.');
+            }
+            if (!ff) {
+                this.log('Already up to date.');
+                return { dir: resolvedDir, newCommits: [], workspaceId };
+            }
+            // Merge
+            const newCommits = await gitMergeFfOnly(resolvedDir);
+            if (newCommits.length > 0) {
+                this.log(`Pulled ${newCommits.length} new commit(s):`);
+                for (const msg of newCommits) {
+                    this.log(`  - ${msg}`);
+                }
+            }
+            else {
+                this.log('Updated successfully.');
+            }
+        }
+        // Write QUONFIG_DIR to ~/.quonfig/config if not set
+        await this.maybeWriteQuonfigDir(resolvedDir);
+        return { dir: resolvedDir, workspaceId };
+    }
+    async resolveRepoUrl(workspaceId) {
+        let entry = await loadGiteaToken(workspaceId);
+        if (!entry || isGiteaTokenExpired(entry)) {
+            this.verboseLog('Pull', 'Minting new Gitea read token...');
+            entry = await mintAndStoreGiteaReadToken(workspaceId);
+        }
+        return entry.repoUrl;
+    }
+    async refreshAndGetUrl(workspaceId) {
+        const data = await mintGiteaToken(workspaceId, 'read', 'pull');
+        const entry = { token: data.token, repoUrl: data.repoUrl, expiresAt: data.expiresAt };
+        await saveGiteaToken(workspaceId, entry);
+        return entry.repoUrl;
+    }
+    looksLike401(err) {
+        const msg = err instanceof Error ? err.message : String(err);
+        return msg.includes('401') || msg.toLowerCase().includes('authentication failed');
+    }
+    async maybeWriteQuonfigDir(dir) {
+        if (process.env.QUONFIG_DIR)
+            return; // already set via env
+        const os = await import('node:os');
+        const pathMod = await import('node:path');
+        const configFilePath = pathMod.join(os.homedir(), '.quonfig', 'config');
+        try {
+            const existing = await fs.promises.readFile(configFilePath, 'utf8').catch(() => '');
+            if (existing.includes('QUONFIG_DIR') || existing.includes('quonfig_dir'))
+                return;
+            const line = `\nQUONFIG_DIR = ${dir}\n`;
+            await fs.promises.appendFile(configFilePath, line, 'utf8');
+            this.verboseLog('Pull', `Wrote QUONFIG_DIR to ${configFilePath}`);
+        }
+        catch {
+            // Non-fatal
+        }
+    }
+}
+/**
+ * Strip auth credentials from a git URL for comparison purposes.
+ * Converts `https://user:token@host/path` to `https://host/path`.
+ */
+function stripAuth(url) {
+    try {
+        const u = new URL(url);
+        u.username = '';
+        u.password = '';
+        return u.toString();
+    }
+    catch {
+        // Not a valid URL (e.g. SSH) — return as-is
+        return url;
+    }
+}

package/dist/commands/serve.js

@@ -47,7 +47,9 @@ export default class Serve extends BaseCommand {
         }
         catch (error_) {
             const error = error_;
-            if (/No projectEnvId found in config/.test(error.message) || /Unexpected end of JSON input/.test(error.message)) {
+            if (/No projectEnvId found in config/.test(error.message) ||
+                /is not iterable/.test(error.message) ||
+                /Unexpected end of JSON input/.test(error.message)) {
                 return this.error(`${error.message}\nYour download file seems invalid or corrupt. Please redownload your datafile.`);
             }
             return this.error(error);