@quonfig/cli 0.0.1 → 0.0.4

package/dist/init/init-workspace.js

@@ -0,0 +1,162 @@
+/**
+ * Core logic for `qfg init`.
+ *
+ * Uses a plan/execute pattern so --dry-run can show what *would* happen
+ * without writing anything.
+ */
+import { execSync } from 'node:child_process';
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+import { SAMPLE_FILES } from './samples.js';
+import { storedConfigJsonSchema } from './schema.js';
+import { PRE_COMMIT_MARKER, agentsMdTemplate, claudeMdTemplate, preCommitHookContent, readmeTemplate, } from './templates.js';
+// ── Directories that define a workspace ────────────────────────────────
+const WORKSPACE_DIRS = [
+    'configs',
+    'feature-flags',
+    'segments',
+    'log-levels',
+    'schemas',
+];
+// ── Plan ───────────────────────────────────────────────────────────────
+export function planInit(options) {
+    const { dir } = options;
+    const actions = [];
+    // Detect first-time vs update: do any workspace dirs already exist?
+    const isFirstTime = !WORKSPACE_DIRS.some((d) => fs.existsSync(path.join(dir, d)));
+    // Resolve samples flag: first-time → default on, update → default off
+    const includeSamples = options.samples ?? isFirstTime;
+    // 0. Ensure it's a git repo
+    const gitDir = path.join(dir, '.git');
+    const needsGitInit = !fs.existsSync(gitDir);
+    if (needsGitInit) {
+        actions.push({ kind: 'git-init', path: '.git', description: 'Initialize git repository' });
+    }
+    // 1. Ensure directories exist
+    for (const d of WORKSPACE_DIRS) {
+        const dirPath = path.join(dir, d);
+        if (fs.existsSync(dirPath)) {
+            // directory already exists, nothing to do
+        }
+        else {
+            actions.push({ kind: 'create-dir', path: d, description: `Create ${d}/` });
+        }
+    }
+    // 2. Managed files — always overwrite
+    const managedFiles = [
+        { file: 'quonfig.schema.json', content: JSON.stringify(storedConfigJsonSchema(), null, 2) + '\n' },
+        { file: 'README.md', content: readmeTemplate() },
+        { file: 'CLAUDE.md', content: claudeMdTemplate() },
+        { file: 'AGENTS.md', content: agentsMdTemplate() },
+    ];
+    for (const { file, content: _content } of managedFiles) {
+        const filePath = path.join(dir, file);
+        const verb = fs.existsSync(filePath) ? 'Update' : 'Create';
+        actions.push({ kind: 'write-file', path: file, description: `${verb} ${file}` });
+    }
+    // 3. quonfig.json — create if missing
+    const envsPath = path.join(dir, 'quonfig.json');
+    if (fs.existsSync(envsPath)) {
+        // leave it alone
+    }
+    else {
+        actions.push({ kind: 'write-file', path: 'quonfig.json', description: 'Create quonfig.json' });
+    }
+    // 4. Sample data
+    if (includeSamples) {
+        for (const sample of SAMPLE_FILES) {
+            const samplePath = path.join(dir, sample.path);
+            if (fs.existsSync(samplePath)) {
+                actions.push({ kind: 'skip-file', path: sample.path, description: `Skip ${sample.path} (already exists)` });
+            }
+            else {
+                actions.push({ kind: 'write-file', path: sample.path, description: `Create ${sample.path}` });
+            }
+        }
+    }
+    // 5. Git pre-commit hook (always runs — git repo guaranteed by step 0)
+    if (needsGitInit) {
+        // Fresh git init — hook will be created
+        actions.push({ kind: 'create-hook', path: '.git/hooks/pre-commit', description: 'Install pre-commit hook (qfg verify)' });
+    }
+    else {
+        const hooksDir = path.join(gitDir, 'hooks');
+        const hookPath = path.join(hooksDir, 'pre-commit');
+        if (fs.existsSync(hookPath)) {
+            const existing = fs.readFileSync(hookPath, 'utf-8');
+            if (existing.includes(PRE_COMMIT_MARKER)) {
+                actions.push({ kind: 'skip-hook', path: '.git/hooks/pre-commit', description: 'Pre-commit hook already installed' });
+            }
+            else if (existing.includes('qfg verify')) {
+                actions.push({ kind: 'skip-hook', path: '.git/hooks/pre-commit', description: 'Pre-commit hook already runs qfg verify' });
+            }
+            else {
+                actions.push({ kind: 'update-hook', path: '.git/hooks/pre-commit', description: 'Append qfg verify to existing pre-commit hook' });
+            }
+        }
+        else {
+            actions.push({ kind: 'create-hook', path: '.git/hooks/pre-commit', description: 'Install pre-commit hook (qfg verify)' });
+        }
+    }
+    return { actions, isFirstTime, samplesIncluded: includeSamples };
+}
+// ── Execute ────────────────────────────────────────────────────────────
+export function executeInit(plan, dir) {
+    // Build a lookup for managed file content
+    const managedContent = {
+        'quonfig.schema.json': JSON.stringify(storedConfigJsonSchema(), null, 2) + '\n',
+        'README.md': readmeTemplate(),
+        'CLAUDE.md': claudeMdTemplate(),
+        'AGENTS.md': agentsMdTemplate(),
+        'quonfig.json': JSON.stringify({ environments: [] }, null, 2) + '\n',
+    };
+    // Build a lookup for sample content
+    const sampleContent = {};
+    for (const sample of SAMPLE_FILES) {
+        sampleContent[sample.path] = JSON.stringify(sample.content, null, 2) + '\n';
+    }
+    for (const action of plan.actions) {
+        const fullPath = path.join(dir, action.path);
+        switch (action.kind) {
+            case 'git-init': {
+                execSync('git init', { cwd: dir, stdio: 'pipe' });
+                break;
+            }
+            case 'create-dir': {
+                fs.mkdirSync(fullPath, { recursive: true });
+                break;
+            }
+            case 'write-file': {
+                // Ensure parent directory exists
+                const parentDir = path.dirname(fullPath);
+                if (!fs.existsSync(parentDir)) {
+                    fs.mkdirSync(parentDir, { recursive: true });
+                }
+                const content = managedContent[action.path] ?? sampleContent[action.path];
+                if (content) {
+                    fs.writeFileSync(fullPath, content, 'utf-8');
+                }
+                break;
+            }
+            case 'create-hook': {
+                const hooksDir = path.dirname(fullPath);
+                if (!fs.existsSync(hooksDir)) {
+                    fs.mkdirSync(hooksDir, { recursive: true });
+                }
+                fs.writeFileSync(fullPath, preCommitHookContent(), 'utf-8');
+                fs.chmodSync(fullPath, 0o755);
+                break;
+            }
+            case 'update-hook': {
+                const existing = fs.readFileSync(fullPath, 'utf-8');
+                const appended = existing.trimEnd() + '\n\n' + preCommitHookContent().split('\n').slice(1).join('\n');
+                fs.writeFileSync(fullPath, appended, 'utf-8');
+                break;
+            }
+            case 'skip-file':
+            case 'skip-hook':
+                // Nothing to do
+                break;
+        }
+    }
+}

package/dist/init/samples.d.ts

@@ -0,0 +1,11 @@
+/**
+ * Sample config data for `qfg init --samples`.
+ *
+ * Each entry maps a relative path (e.g. "configs/example.greeting.json")
+ * to the JSON object that should be written there.
+ */
+export interface SampleFile {
+    path: string;
+    content: object;
+}
+export declare const SAMPLE_FILES: SampleFile[];

package/dist/init/samples.js

@@ -0,0 +1,118 @@
+/**
+ * Sample config data for `qfg init --samples`.
+ *
+ * Each entry maps a relative path (e.g. "configs/example.greeting.json")
+ * to the JSON object that should be written there.
+ */
+export const SAMPLE_FILES = [
+    {
+        path: 'configs/example.greeting.json',
+        content: {
+            key: 'example.greeting',
+            type: 'config',
+            valueType: 'string',
+            sendToClientSdk: true,
+            description: 'A greeting message shown to users.',
+            default: {
+                rules: [
+                    {
+                        criteria: [{ operator: 'ALWAYS_TRUE' }],
+                        value: { type: 'string', value: 'Hello, world!' },
+                    },
+                ],
+            },
+            environments: [
+                {
+                    id: 'production',
+                    rules: [
+                        {
+                            criteria: [{ operator: 'ALWAYS_TRUE' }],
+                            value: { type: 'string', value: 'Welcome to our app!' },
+                        },
+                    ],
+                },
+            ],
+            variants: [],
+        },
+    },
+    {
+        path: 'feature-flags/example.dark-mode.json',
+        content: {
+            key: 'example.dark-mode',
+            type: 'feature_flag',
+            valueType: 'bool',
+            sendToClientSdk: true,
+            description: 'Enable dark mode UI.',
+            default: {
+                rules: [
+                    {
+                        criteria: [{ operator: 'ALWAYS_TRUE' }],
+                        value: { type: 'bool', value: false },
+                    },
+                ],
+            },
+            environments: [
+                {
+                    id: 'staging',
+                    rules: [
+                        {
+                            criteria: [{ operator: 'ALWAYS_TRUE' }],
+                            value: { type: 'bool', value: true },
+                        },
+                    ],
+                },
+            ],
+            variants: [],
+        },
+    },
+    {
+        path: 'segments/example.beta-users.json',
+        content: {
+            key: 'example.beta-users',
+            type: 'segment',
+            valueType: 'bool',
+            sendToClientSdk: false,
+            description: 'Users who opted in to the beta program.',
+            default: {
+                rules: [
+                    {
+                        criteria: [
+                            {
+                                operator: 'PROP_IS_ONE_OF',
+                                propertyName: 'user.beta',
+                                valueToMatch: { type: 'string_list', value: ['true'] },
+                            },
+                        ],
+                        value: { type: 'bool', value: true },
+                    },
+                    {
+                        criteria: [{ operator: 'ALWAYS_TRUE' }],
+                        value: { type: 'bool', value: false },
+                    },
+                ],
+            },
+            environments: [],
+            variants: [],
+        },
+    },
+    {
+        path: 'log-levels/example.app.json',
+        content: {
+            key: 'example.app',
+            type: 'log_level',
+            valueType: 'log_level',
+            sendToClientSdk: false,
+            description: 'Application log level.',
+            default: {
+                rules: [
+                    {
+                        criteria: [{ operator: 'ALWAYS_TRUE' }],
+                        value: { type: 'log_level', value: 'INFO' },
+                    },
+                ],
+            },
+            environments: [],
+            variants: [],
+        },
+    },
+];

package/dist/init/schema.d.ts

@@ -0,0 +1,9 @@
+/**
+ * JSON Schema for Quonfig StoredConfig files.
+ *
+ * This is the machine-readable schema for files in configs/, feature-flags/,
+ * segments/, and log-levels/. Written to `quonfig.schema.json` by `qfg init`.
+ *
+ * Derived from the Zod schemas in verify/validate.ts — keep in sync.
+ */
+export declare function storedConfigJsonSchema(): object;

package/dist/init/schema.js

@@ -0,0 +1,334 @@
+/**
+ * JSON Schema for Quonfig StoredConfig files.
+ *
+ * This is the machine-readable schema for files in configs/, feature-flags/,
+ * segments/, and log-levels/. Written to `quonfig.schema.json` by `qfg init`.
+ *
+ * Derived from the Zod schemas in verify/validate.ts — keep in sync.
+ */
+const configTypes = ['config', 'feature_flag', 'log_level', 'segment'];
+const valueTypes = ['bool', 'string', 'int', 'double', 'json', 'string_list', 'duration', 'log_level'];
+const logLevels = ['TRACE', 'DEBUG', 'INFO', 'WARN', 'ERROR', 'FATAL'];
+const operators = [
+    'ALWAYS_TRUE',
+    'PROP_IS_ONE_OF', 'PROP_IS_NOT_ONE_OF',
+    'PROP_STARTS_WITH_ONE_OF', 'PROP_DOES_NOT_START_WITH_ONE_OF',
+    'PROP_ENDS_WITH_ONE_OF', 'PROP_DOES_NOT_END_WITH_ONE_OF',
+    'PROP_CONTAINS_ONE_OF', 'PROP_DOES_NOT_CONTAIN_ONE_OF',
+    'PROP_LESS_THAN', 'PROP_LESS_THAN_OR_EQUAL',
+    'PROP_GREATER_THAN', 'PROP_GREATER_THAN_OR_EQUAL',
+    'PROP_BEFORE', 'PROP_AFTER',
+    'PROP_MATCHES', 'PROP_DOES_NOT_MATCH',
+    'IN_SEG', 'NOT_IN_SEG',
+    'IN_INT_RANGE',
+    'LOOKUP_KEY_IN', 'LOOKUP_KEY_NOT_IN',
+];
+// ── Value sub-schemas ──────────────────────────────────────────────────
+const boolValue = {
+    type: 'object',
+    properties: {
+        type: { const: 'bool' },
+        value: { type: 'boolean' },
+    },
+    required: ['type', 'value'],
+    additionalProperties: false,
+};
+const stringValue = {
+    type: 'object',
+    properties: {
+        type: { const: 'string' },
+        value: { type: 'string' },
+    },
+    required: ['type', 'value'],
+    additionalProperties: false,
+};
+const intValue = {
+    type: 'object',
+    properties: {
+        type: { const: 'int' },
+        value: { oneOf: [{ type: 'number' }, { type: 'string' }] },
+    },
+    required: ['type', 'value'],
+    additionalProperties: false,
+};
+const doubleValue = {
+    type: 'object',
+    properties: {
+        type: { const: 'double' },
+        value: { oneOf: [{ type: 'number' }, { type: 'string' }] },
+    },
+    required: ['type', 'value'],
+    additionalProperties: false,
+};
+const jsonValue = {
+    type: 'object',
+    properties: {
+        type: { const: 'json' },
+        value: {},
+    },
+    required: ['type', 'value'],
+    additionalProperties: false,
+};
+const stringListValue = {
+    type: 'object',
+    properties: {
+        type: { const: 'string_list' },
+        value: { type: 'array', items: { type: 'string' } },
+    },
+    required: ['type', 'value'],
+    additionalProperties: false,
+};
+const durationValue = {
+    type: 'object',
+    properties: {
+        type: { const: 'duration' },
+        value: { type: 'string', description: 'Go-style duration (e.g. "30s", "5m", "1h30m")' },
+    },
+    required: ['type', 'value'],
+    additionalProperties: false,
+};
+const logLevelValue = {
+    type: 'object',
+    properties: {
+        type: { const: 'log_level' },
+        value: { enum: [...logLevels] },
+    },
+    required: ['type', 'value'],
+    additionalProperties: false,
+};
+const schemaValue = {
+    type: 'object',
+    properties: {
+        type: { const: 'schema' },
+        value: {
+            type: 'object',
+            properties: {
+                schemaType: { type: 'string' },
+                schema: { type: 'string' },
+            },
+            required: ['schemaType', 'schema'],
+        },
+    },
+    required: ['type', 'value'],
+    additionalProperties: false,
+};
+const providedValue = {
+    type: 'object',
+    properties: {
+        type: { const: 'provided' },
+        value: {
+            type: 'object',
+            properties: {
+                source: { type: 'string' },
+                lookup: { type: 'string' },
+            },
+            required: ['source', 'lookup'],
+        },
+    },
+    required: ['type', 'value'],
+    additionalProperties: false,
+};
+const simpleValue = {
+    oneOf: [
+        boolValue,
+        stringValue,
+        intValue,
+        doubleValue,
+        jsonValue,
+        stringListValue,
+        durationValue,
+        logLevelValue,
+        schemaValue,
+        providedValue,
+    ],
+};
+const weightedValuesValue = {
+    type: 'object',
+    description: 'Weighted rollout for A/B testing. Weights are out of 100,000.',
+    properties: {
+        type: { const: 'weighted_values' },
+        value: {
+            type: 'object',
+            properties: {
+                weightedValues: {
+                    type: 'array',
+                    items: {
+                        type: 'object',
+                        properties: {
+                            value: simpleValue,
+                            weight: { type: 'integer', minimum: 0, maximum: 100_000 },
+                        },
+                        required: ['value', 'weight'],
+                        additionalProperties: false,
+                    },
+                },
+                hashByPropertyName: { type: 'string', default: 'user.key' },
+                splitEvenly: { type: 'boolean' },
+            },
+            required: ['weightedValues'],
+            additionalProperties: false,
+        },
+    },
+    required: ['type', 'value'],
+    additionalProperties: false,
+};
+const ruleValue = {
+    oneOf: [
+        ...simpleValue.oneOf,
+        weightedValuesValue,
+    ],
+};
+// ── Criterion ──────────────────────────────────────────────────────────
+const criterion = {
+    type: 'object',
+    properties: {
+        operator: {
+            enum: [...operators],
+            description: 'ALWAYS_TRUE needs no extra fields. PROP_* operators require propertyName and valueToMatch. IN_SEG/NOT_IN_SEG require valueToMatch with segment key.',
+        },
+        propertyName: {
+            type: 'string',
+            description: 'Required for PROP_* operators.',
+        },
+        valueToMatch: {
+            ...simpleValue,
+            description: 'Required for all operators except ALWAYS_TRUE.',
+        },
+    },
+    required: ['operator'],
+    additionalProperties: false,
+};
+// ── Rule ───────────────────────────────────────────────────────────────
+const configRule = {
+    type: 'object',
+    description: 'Rules are evaluated in order; first match wins. All criteria within a rule are ANDed.',
+    properties: {
+        criteria: {
+            type: 'array',
+            items: criterion,
+        },
+        value: ruleValue,
+    },
+    required: ['criteria', 'value'],
+    additionalProperties: false,
+};
+// ── Environment ────────────────────────────────────────────────────────
+const configEnvironment = {
+    type: 'object',
+    properties: {
+        id: {
+            type: 'string',
+            pattern: '^[a-z0-9]+(?:-[a-z0-9]+)*$',
+            description: 'Lowercase slug (e.g. "production", "staging"). Must NOT be a UUID.',
+        },
+        rules: {
+            type: 'array',
+            items: configRule,
+        },
+    },
+    required: ['id', 'rules'],
+    additionalProperties: false,
+};
+// ── Variant ────────────────────────────────────────────────────────────
+const variant = {
+    type: 'object',
+    properties: {
+        id: { type: 'string' },
+        key: { type: 'string' },
+        value: simpleValue,
+        description: { type: 'string' },
+    },
+    required: ['value'],
+    additionalProperties: false,
+};
+// ── Top-level StoredConfig ─────────────────────────────────────────────
+export function storedConfigJsonSchema() {
+    return {
+        $schema: 'https://json-schema.org/draft/2020-12/schema',
+        $id: 'https://quonfig.com/schemas/stored-config.json',
+        title: 'Quonfig StoredConfig',
+        description: 'Schema for config files in a Quonfig workspace (configs/, feature-flags/, segments/, log-levels/).',
+        type: 'object',
+        properties: {
+            key: {
+                type: 'string',
+                minLength: 1,
+                maxLength: 512,
+                not: { const: 'new' },
+                pattern: '^[^/\\\\]+$',
+                description: 'Unique identifier. Must match the filename (without .json).',
+            },
+            type: {
+                enum: [...configTypes],
+                description: 'Determines which directory the file lives in: config→configs/, feature_flag→feature-flags/, segment→segments/, log_level→log-levels/.',
+            },
+            valueType: {
+                enum: [...valueTypes],
+                description: 'The value type. Must match the "type" field in rule values. Segments must use "bool". Log levels must use "log_level".',
+            },
+            default: {
+                type: 'object',
+                properties: {
+                    rules: {
+                        type: 'array',
+                        items: configRule,
+                        minItems: 1,
+                    },
+                },
+                required: ['rules'],
+                additionalProperties: false,
+            },
+            id: { type: 'string' },
+            projectId: { type: 'string' },
+            name: { type: 'string' },
+            description: { type: 'string' },
+            sendToClientSdk: {
+                type: 'boolean',
+                default: false,
+                description: 'Whether to expose this config to client-side SDKs. Must be false for segments.',
+            },
+            schemaKey: {
+                type: 'string',
+                description: 'References a schema in schemas/ or schemas-protected/. The referenced file must exist.',
+            },
+            accessLevel: { type: 'string' },
+            protection: { type: 'string' },
+            tags: {
+                type: 'array',
+                items: { type: 'string' },
+            },
+            environments: {
+                type: 'array',
+                items: configEnvironment,
+                default: [],
+            },
+            variants: {
+                type: 'array',
+                items: variant,
+                default: [],
+            },
+        },
+        required: ['key', 'type', 'valueType', 'default'],
+        additionalProperties: true,
+        // Type-specific constraints
+        allOf: [
+            {
+                if: { properties: { type: { const: 'segment' } } },
+                then: {
+                    properties: {
+                        valueType: { const: 'bool' },
+                        sendToClientSdk: { const: false },
+                    },
+                },
+            },
+            {
+                if: { properties: { type: { const: 'log_level' } } },
+                then: {
+                    properties: {
+                        valueType: { const: 'log_level' },
+                    },
+                },
+            },
+        ],
+    };
+}

package/dist/init/templates.d.ts

@@ -0,0 +1,12 @@
+/**
+ * Managed document templates for `qfg init`.
+ *
+ * These are overwritten on every run of `qfg init` — they are not
+ * user-editable.  Each starts with a comment so users know not to
+ * hand-edit them.
+ */
+export declare function readmeTemplate(): string;
+export declare function claudeMdTemplate(): string;
+export declare function agentsMdTemplate(): string;
+export declare const PRE_COMMIT_MARKER = "# --- qfg-verify ---";
+export declare function preCommitHookContent(): string;