@quonfig/cli 0.2.3 → 0.3.0

package/dist/commands/cleanup/remove.js

@@ -1,10 +1,14 @@
 import { Flags } from '@oclif/core';
 import fs from 'node:fs';
 import path from 'node:path';
+import { SKILL_NAME } from '../../agent/skill-bundle.generated.js';
 import { APICommand } from '../../index.js';
 import { getAppUrl } from '../../util/domain-urls.js';
 import nameArg from '../../util/name-arg.js';
-const SKILL_NAME = 'qfg-flag-cleanup';
+// The public Quonfig agent skill (github.com/quonfig/skills, installed with
+// `qfg agent install-skill` or the Claude Code plugin). Its
+// references/retire-a-flag.md is the code-removal half of this workflow.
+const SKILL_REFERENCE = 'references/retire-a-flag.md';
 const GITIGNORE_ENTRY = '.qf/cleanup/';
 // SDK client method names worth grepping for in the customer's codebase.
 // Based on the surfaces the official Quonfig SDKs expose (sdk-node /
@@ -121,14 +125,16 @@ function ensureGitignoreEntry(cwd) {
 }
 export default class CleanupRemove extends APICommand {
     static args = { ...nameArg };
-    static description = `Write a cleanup payload for a ready-for-cleanup flag and hand off to the qfg-flag-cleanup Claude skill.
+    static description = `Write a cleanup payload for a ready-for-cleanup flag and hand off to the Quonfig agent skill.
 
 Modeled on \`qfg migrate my-code\` — this command never edits source files
 itself. It validates that the flag is marked readyForCleanup=true, refuses to
 proceed if there are still evals_2d > 0 (use --force to override), writes
 \`.qf/cleanup/<key>.json\` describing the flag's current rule shape +
-telemetry, and prints instructions to invoke the qfg-flag-cleanup skill which
-asks the engineer which value should "win" and applies the inlining.
+telemetry, and prints how to have your coding agent remove the call sites with
+the quonfig agent skill (its references/retire-a-flag.md), which asks the
+engineer which value should "win" and applies the inlining. Install the skill
+with \`qfg agent install-skill\` or \`claude plugin install quonfig@quonfig\`.
 
 The payload deliberately does NOT suggest a winning value; that's the
 engineer's call. Run \`qfg cleanup status <key>\` first if you want to inspect
@@ -208,9 +214,14 @@ telemetry before retiring.`;
         this.log(`Payload:      ${relPayloadPath}`);
         this.log(`Evals (2d):   ${totals.evals_2d}${payload.forced ? ' (--force overrode the safety gate)' : ''}`);
         this.log('');
-        this.log(`To remove this flag's call sites, invoke Claude with the ${SKILL_NAME} skill:`);
+        this.log(`To remove this flag's call sites, ask your coding agent to retire it with the quonfig agent skill`);
+        this.log(`(${SKILL_REFERENCE} covers this workflow), e.g. in Claude Code:`);
         this.log('');
-        this.log(`  claude "/${SKILL_NAME} ${key}"`);
+        this.log(`  claude "Retire the Quonfig flag ${key} using ${relPayloadPath}"`);
+        this.log('');
+        this.log(`No quonfig skill in this repo yet? Install it first:`);
+        this.log(`  qfg agent install-skill                    # writes .claude/skills/quonfig/`);
+        this.log(`  # or: claude plugin marketplace add quonfig/skills && claude plugin install quonfig@quonfig`);
         this.log('');
         this.log(`The skill will:`);
         this.log(`  1. Read ${relPayloadPath}`);

package/dist/commands/cleanup/status.js

@@ -42,13 +42,13 @@ export default class CleanupStatus extends APICommand {
     static description = `Drill into one ready-for-cleanup flag — show telemetry across all environments and the current rule shape.
 
 Use this after \`qfg cleanup list\` to inspect a specific flag before handing
-removal off to the qfg-flag-cleanup Claude skill. The eval counts come from
+removal off to the Quonfig agent skill. The eval counts come from
 analytics.configSparklines (the same backing data the per-flag sparklines on
 the flag detail page use), summed into 24h/2d/7d/30d windows so you can decide
 whether it's safe to retire.
 
 Pass --json for the structured object including the full rule shape per
-environment — the cleanup skill consumes this directly.`;
+environment — the agent skill consumes this directly.`;
     static examples = [
         '<%= config.bin %> <%= command.id %> my.flag.key',
         '<%= config.bin %> <%= command.id %> my.flag.key --json',

package/dist/commands/cleanup.js

@@ -4,14 +4,15 @@ export default class Cleanup extends BaseCommand {
 
 The cleanup workflow turns a flag's "Ready for cleanup" marker into an end-to-end
 removal flow: surface the flags that are safe to retire, hand the actual code
-removal to the qfg-flag-cleanup Claude skill, then delete the flag definition
-once the call sites are gone.
+removal to your coding agent with the Quonfig agent skill (install it with
+\`qfg agent install-skill\`), then delete the flag definition once the call
+sites are gone.
 
 Lifecycle (high-level):
   1. Owner flips readyForCleanup=true in the UI            (already exists)
   2. qfg cleanup list                                       see candidates + telemetry
   3. qfg cleanup status <key>                               drill into one flag
-  4. qfg cleanup remove <key>                               handoff to the cleanup skill
+  4. qfg cleanup remove <key>                               handoff to the agent skill
   5. PR merges, SDK redeploys, telemetry confirms 0 evals
   6. qfg cleanup verify <key>                               (optional) confirm safe
   7. qfg delete <key>                                       remove the flag definition`;

package/dist/commands/config-schema.js

@@ -89,6 +89,9 @@ 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"
+                  To target specific customers or users, match on the context KEY
+                  ("organization.key", "user.key"), not a slug, email or name.
+                  Find a key from a name with: qfg contexts search organization <name>
   valueToMatch    (required for all except ALWAYS_TRUE / IS_PRESENT / IS_NOT_PRESENT) — typed value to compare against
 
 ────────────────────────────────────────────────────────────

package/dist/commands/contexts/search.d.ts

@@ -0,0 +1,15 @@
+import type { JsonObj } from '../../result.js';
+import { APICommand } from '../../index.js';
+export default class ContextsSearch extends APICommand {
+    static args: {
+        contextType: import("@oclif/core/lib/interfaces/parser.js").Arg<string, Record<string, unknown>>;
+        query: import("@oclif/core/lib/interfaces/parser.js").Arg<string, 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>;
+        limit: import("@oclif/core/lib/interfaces/parser.js").OptionFlag<number, import("@oclif/core/lib/interfaces/parser.js").CustomOptions>;
+    };
+    run(): Promise<JsonObj | void>;
+}

package/dist/commands/contexts/search.js

@@ -0,0 +1,78 @@
+import { Args, Flags } from '@oclif/core';
+import { APICommand } from '../../index.js';
+export default class ContextsSearch extends APICommand {
+    static args = {
+        contextType: Args.string({
+            description: 'Context type to search, e.g. organization or user (the part before ".key" in a rule)',
+            required: true,
+        }),
+        query: Args.string({
+            description: 'Case-insensitive text matched against each context key and its reported properties (e.g. a name)',
+            required: true,
+        }),
+    };
+    static description = `Find a context's key from a name, to target it in a rule.
+
+Targeting rules should match a context by its KEY (<contextType>.key, e.g.
+organization.key or user.key), not by a slug, email or name. This searches the
+contexts your SDKs have reported through telemetry, matching the query against
+each context's key and properties, and prints each match's key, its name and
+its email (blank when the context reported none), most recently seen first.
+
+Only contexts your SDKs have reported are searchable. If nothing matches, the key
+is unknown: get it from whoever owns that customer rather than targeting a slug
+or email instead.
+
+Pass a key as the query to see its name and email.
+
+--json prints {contexts: [{key, name, email?}]}: name is null when the context
+reported no name, and email is present only when it reported one.`;
+    static examples = [
+        '<%= config.bin %> <%= command.id %> organization formhealth',
+        '<%= config.bin %> <%= command.id %> user barry@example.com --environment production',
+        '<%= config.bin %> <%= command.id %> organization formhealth --json',
+    ];
+    static flags = {
+        environment: Flags.string({
+            description: 'Only contexts reported from this environment (default: every environment)',
+        }),
+        limit: Flags.integer({
+            default: 20,
+            description: 'Maximum number of matches (1-100)',
+            max: 100,
+            min: 1,
+        }),
+    };
+    async run() {
+        const { args, flags } = await this.parse(ContextsSearch);
+        const request = await this.apiClient.post('/api/v1/contexts/searchKeys', {
+            contextType: args.contextType,
+            environment: flags.environment,
+            limit: flags.limit,
+            query: args.query,
+            workspaceId: this.workspaceId,
+        });
+        if (!request.ok) {
+            const serverError = request.error;
+            const errorMsg = serverError?.error || serverError?.json?.message || `Failed to search contexts: ${request.status}`;
+            return this.err(errorMsg, { serverError: request.error });
+        }
+        const contexts = (request.json?.contexts ?? []);
+        if (contexts.length === 0) {
+            this.log(`No context seen via telemetry matched "${args.query}" (type ${args.contextType}), so the key is unknown.\n` +
+                'Only contexts your SDKs have reported are searchable. Get the key from whoever owns that ' +
+                'customer; do not target a slug or email instead.');
+            return { contexts: [] };
+        }
+        const keyWidth = Math.max(...contexts.map((c) => c.key.length), 'KEY'.length);
+        const nameWidth = Math.max(...contexts.map((c) => (c.name ?? '').length), 'NAME'.length);
+        const row = (key, name, email) => `${key.padEnd(keyWidth)}  ${name.padEnd(nameWidth)}  ${email}`.trimEnd();
+        const lines = [row('KEY', 'NAME', 'EMAIL')];
+        for (const context of contexts) {
+            lines.push(row(context.key, context.name ?? '', context.email ?? ''));
+        }
+        lines.push('', `Target these in a rule with propertyName "${args.contextType}.key".`);
+        this.log(lines.join('\n'));
+        return { contexts };
+    }
+}

package/dist/commands/contexts.d.ts

@@ -0,0 +1,6 @@
+import { BaseCommand } from '../index.js';
+export default class Contexts extends BaseCommand {
+    static description: string;
+    static examples: string[];
+    run(): Promise<void>;
+}

package/dist/commands/contexts.js

@@ -0,0 +1,10 @@
+import { BaseCommand } from '../index.js';
+export default class Contexts extends BaseCommand {
+    static description = 'Look up contexts (organizations, users, ...) your SDKs have reported, to target them by key.';
+    static examples = ['<%= config.bin %> contexts search organization formhealth'];
+    async run() {
+        this.log('Use one of the contexts subcommands:');
+        this.log('  qfg contexts search CONTEXT_TYPE QUERY [--environment ENV] [--limit N] [--json]');
+        this.log('      # find a context key by name, e.g. qfg contexts search organization formhealth');
+    }
+}

package/dist/commands/set-default.js

@@ -32,7 +32,11 @@ 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`;
+  qfg info my.flag
+
+To target specific organizations or users, write rules on their KEY
+(organization.key, user.key), not a slug or email; find a key from a name with:
+  qfg contexts search organization formhealth`;
     static examples = [
         '<%= config.bin %> <%= command.id %> my.flag.name                                          # prompts for value and env',
         '<%= config.bin %> <%= command.id %> my.flag.name --value=true --environment=staging',

package/dist/init/templates.js

@@ -5,6 +5,16 @@
  * user-editable.  Each starts with a comment so users know not to
  * hand-edit them.
  */
+import { SKILL_FILES } from '../agent/skill-bundle.generated.js';
+/**
+ * The qfg-vs-MCP steering and "setting a value keeps targeting" rules are
+ * shared with the Quonfig agent skill (github.com/quonfig/skills,
+ * references/writes.md). The skill is the single source; the cli vendors it
+ * at build time (scripts/sync-agent-skill.mjs) and AGENTS.md embeds it here.
+ */
+const SHARED_WRITES_SECTION = SKILL_FILES.find((f) => f.path === 'references/writes.md')
+    .content.trim()
+    .replaceAll(/^## /gm, '### ');
 const MANAGED_HEADER = '<!-- Managed by `qfg init` — do not edit manually. Run `qfg init` to update. -->';
 // ── README.md ──────────────────────────────────────────────────────────
 export function readmeTemplate() {
@@ -196,48 +206,19 @@ This is a Quonfig workspace repository. See \`CLAUDE.md\` for the complete schem
 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?
+## Hosted workspaces: \`qfg\`, the MCP, and how writes behave
 
 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.
+${SHARED_WRITES_SECTION}
 
-**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\`.
+## Application repos
 
-\`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.
+This file covers the workspace (config) repo. In an application repo that
+*reads* these flags through a Quonfig SDK, install the Quonfig agent skill:
+\`qfg agent install-skill\` (or \`claude plugin install quonfig@quonfig\`).
+It covers SDK setup, creating and rolling out flags, and the MCP tools.
 `;
 }
 // ── Pre-commit hook ────────────────────────────────────────────────────

package/dist/util/encryption.js

@@ -33,7 +33,9 @@ export function decrypt(encryptedString, keyStringHex) {
     const encryptedBytes = forge.util.hexToBytes(encryptedDataPart);
     const ivBytes = forge.util.hexToBytes(ivPart);
     const tagBytes = forge.util.hexToBytes(authTagPart);
-    // Create decipher
+    // Create decipher. node-forge AES-GCM with the IV passed to start() below, not
+    // Node's deprecated IV-less crypto.createDecipher that this rule targets.
+    // nosemgrep: javascript.node-crypto.security.create-de-cipher-no-iv.create-de-cipher-no-iv
     const decipher = forge.cipher.createDecipher('AES-GCM', keyBytes);
     decipher.start({
         iv: ivBytes,

package/dist/verify/schema-error-reshape.d.ts

@@ -59,6 +59,11 @@ export declare function findOneOfTag(branches: unknown[], root: unknown): OneOfT
  * a single `oneOfTag` error at the union's position.
  */
 export declare function reshapeOneOfErrors<E extends SchemaErrorLike>(errors: readonly E[], rootSchema: unknown, value: unknown): (E | SchemaErrorLike)[];
+/**
+ * The two 0-based indexes a duplicate-items violation names, lower first,
+ * or undefined for any other message. Lets a caller mark both rows.
+ */
+export declare function duplicateItemIndexes(message: string): [number, number] | undefined;
 /** One error -> message. Undefined means "skip it, a nested error says why". */
 export declare function describeSchemaError(error: SchemaErrorLike): string | undefined;
 /**

package/dist/verify/schema-error-reshape.js

@@ -207,6 +207,25 @@ export function reshapeOneOfErrors(errors, rootSchema, value) {
     });
     return result;
 }
+/**
+ * `uniqueItems` wording. Ajv says `(items ## 3 and 1 are identical)`:
+ * 0-based, later item first, with a stray `##`. Lists are numbered from 1
+ * everywhere the user reads them, so name the pair by row number, lower
+ * first: `(items 2 and 4 are identical)`.
+ */
+function duplicateItemsMessage(first, second) {
+    const [a, b] = [first, second].sort((x, y) => x - y);
+    return `must NOT have duplicate items (items ${a + 1} and ${b + 1} are identical)`;
+}
+const DUPLICATE_ITEMS_MESSAGE = /^must NOT have duplicate items \(items (\d+) and (\d+) are identical\)$/;
+/**
+ * The two 0-based indexes a duplicate-items violation names, lower first,
+ * or undefined for any other message. Lets a caller mark both rows.
+ */
+export function duplicateItemIndexes(message) {
+    const match = DUPLICATE_ITEMS_MESSAGE.exec(message);
+    return match ? [Number(match[1]) - 1, Number(match[2]) - 1] : undefined;
+}
 function stringifyAllowed(entry) {
     return typeof entry === 'string' ? entry : JSON.stringify(entry);
 }
@@ -223,6 +242,10 @@ export function describeSchemaError(error) {
             return Array.isArray(params.allowedValues)
                 ? `${message}: ${params.allowedValues.map(stringifyAllowed).join(', ')}`
                 : message;
+        case 'uniqueItems':
+            return typeof params.i === 'number' && typeof params.j === 'number'
+                ? duplicateItemsMessage(params.i, params.j)
+                : message;
         case 'propertyNames':
             // The nested keyword error (which carries `propertyName`) says why.
             return undefined;

package/dist/version.d.ts

@@ -1,2 +1,2 @@
-declare const _default: "0.2.3";
+declare const _default: "0.3.0";
 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.2.3';
+export default '0.3.0';