@quonfig/cli 0.0.1 → 0.0.4

package/dist/init/templates.js

@@ -0,0 +1,161 @@
+/**
+ * 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.
+ */
+const MANAGED_HEADER = '<!-- Managed by `qfg init` — do not edit manually. Run `qfg init` to update. -->';
+// ── README.md ──────────────────────────────────────────────────────────
+export function readmeTemplate() {
+    return `${MANAGED_HEADER}
+
+# Quonfig Workspace
+
+This is a [Quonfig](https://quonfig.com) workspace repository. All configuration — feature flags, configs, segments, log levels, and schemas — is stored as JSON files tracked in git.
+
+## Directory layout
+
+| Directory | What goes here |
+|-----------|---------------|
+| \`configs/\` | Application configuration (strings, ints, JSON, etc.) |
+| \`feature-flags/\` | Boolean or multi-variant feature flags |
+| \`segments/\` | Audience segments for targeting rules |
+| \`log-levels/\` | Dynamic log level configuration |
+| \`schemas/\` | JSON Schemas that configs can reference for validation |
+| \`schemas-protected/\` | Admin-only schemas |
+
+## Quick start
+
+\`\`\`bash
+# Validate the workspace
+qfg verify
+
+# Create a new feature flag
+qfg create my.new.flag --type=boolean-flag
+
+# List all configs
+qfg list
+\`\`\`
+
+## Schema
+
+\`quonfig.schema.json\` in the repo root defines the config file format. Editors that support JSON Schema will provide autocomplete and validation automatically.
+
+## Validation
+
+Run \`qfg verify\` after every change. A git pre-commit hook is installed to do this automatically.
+`;
+}
+// ── CLAUDE.md ──────────────────────────────────────────────────────────
+export function claudeMdTemplate() {
+    return `${MANAGED_HEADER}
+
+# Quonfig Workspace — Agent Reference
+
+This is a Quonfig workspace repository. Configuration is stored as JSON files in git.
+
+**After every change to this repo, run \`qfg verify\` to validate.**
+
+## JSON Schema
+
+The canonical schema for config files is \`quonfig.schema.json\` in the repo root. Use it as the source of truth for field names, types, enums, and constraints.
+
+Config files can reference it for editor support:
+
+\`\`\`json
+{ "$schema": "./quonfig.schema.json", "key": "my.config", ... }
+\`\`\`
+
+## Directory Structure
+
+Files must live in the directory matching their \`type\`. The filename (without \`.json\`) must exactly match the \`key\` field.
+
+| Directory | Config \`type\` field | Description |
+|-----------|---------------------|-------------|
+| \`configs/\` | \`"config"\` | Application configuration values |
+| \`feature-flags/\` | \`"feature_flag"\` | Boolean or multi-variant feature flags |
+| \`segments/\` | \`"segment"\` | Audience segments for targeting rules |
+| \`log-levels/\` | \`"log_level"\` | Dynamic log level configuration |
+| \`schemas/\` | \`"schema"\` | JSON Schemas that configs can reference |
+| \`schemas-protected/\` | \`"schema"\` | Protected schemas (admin-only) |
+
+## Minimal Example
+
+\`\`\`json
+{
+  "$schema": "./quonfig.schema.json",
+  "key": "my-app.timeout",
+  "type": "config",
+  "valueType": "int",
+  "default": {
+    "rules": [
+      {
+        "criteria": [{ "operator": "ALWAYS_TRUE" }],
+        "value": { "type": "int", "value": 30 }
+      }
+    ]
+  },
+  "environments": [],
+  "variants": []
+}
+\`\`\`
+
+## Rules and Criteria
+
+The \`default\` block (and each environment override) contains a \`rules\` array. Rules are evaluated in order; the first rule whose criteria all match wins. All criteria within one rule are ANDed. Use multiple rules for OR logic.
+
+### Operator quick reference
+
+| Category | Operators | Required fields |
+|----------|-----------|----------------|
+| Always match | \`ALWAYS_TRUE\` | (none) |
+| Property string | \`PROP_IS_ONE_OF\`, \`PROP_IS_NOT_ONE_OF\`, \`PROP_STARTS_WITH_ONE_OF\`, \`PROP_ENDS_WITH_ONE_OF\`, \`PROP_CONTAINS_ONE_OF\` + negative variants | \`propertyName\`, \`valueToMatch\` |
+| Property comparison | \`PROP_LESS_THAN\`, \`PROP_LESS_THAN_OR_EQUAL\`, \`PROP_GREATER_THAN\`, \`PROP_GREATER_THAN_OR_EQUAL\` | \`propertyName\`, \`valueToMatch\` |
+| Property date | \`PROP_BEFORE\`, \`PROP_AFTER\` | \`propertyName\`, \`valueToMatch\` |
+| Property regex | \`PROP_MATCHES\`, \`PROP_DOES_NOT_MATCH\` | \`propertyName\`, \`valueToMatch\` |
+| Segment | \`IN_SEG\`, \`NOT_IN_SEG\` | \`valueToMatch\` (segment key) |
+| Other | \`IN_INT_RANGE\`, \`LOOKUP_KEY_IN\`, \`LOOKUP_KEY_NOT_IN\` | \`valueToMatch\` |
+
+See \`quonfig.schema.json\` for the full operator enum and value type definitions.
+
+## Environments
+
+Environment overrides go in the \`environments\` array. Each has an \`id\` (lowercase slug like \`production\`, never a UUID) and its own \`rules\` array. Environment IDs are defined in \`quonfig.json\` at the repo root.
+
+## Cross-File Validation Rules
+
+These constraints span multiple files and are enforced by \`qfg verify\` (not expressible in the JSON Schema alone):
+
+1. **Filename = key**: the JSON filename (without .json) must exactly match the \`key\` field
+2. **No duplicate keys** across the entire workspace
+3. **Segment references** (\`IN_SEG\`/\`NOT_IN_SEG\`) must point to existing segments in \`segments/\`
+4. **Schema references** (\`schemaKey\`) must point to existing files in \`schemas/\` or \`schemas-protected/\`
+`;
+}
+// ── AGENTS.md ──────────────────────────────────────────────────────────
+export function agentsMdTemplate() {
+    return `${MANAGED_HEADER}
+
+# Agent Instructions
+
+This is a Quonfig workspace repository. See \`CLAUDE.md\` for the complete schema reference and validation rules.
+
+## Key rules
+
+1. **Always validate**: run \`qfg verify\` after any change to this repo.
+2. Filename must match the \`key\` field (e.g. \`my.flag.json\` has \`"key": "my.flag"\`).
+3. Files must be in the correct directory for their \`type\`.
+4. See \`CLAUDE.md\` for the full list of value types, operators, and constraints.
+`;
+}
+// ── Pre-commit hook ────────────────────────────────────────────────────
+export const PRE_COMMIT_MARKER = '# --- qfg-verify ---';
+export function preCommitHookContent() {
+    return `#!/bin/sh
+${PRE_COMMIT_MARKER}
+# Validate workspace before committing.
+# Installed by \`qfg init\`. Safe to remove if you prefer manual validation.
+qfg verify .
+`;
+}

package/dist/util/coerce.js

@@ -17,7 +17,8 @@ export const coerceIntoType = (type, value) => {
         }
         case 'int': {
             try {
-                const int = BigInt(value);
+                const bigInt = BigInt(value);
+                const int = Number(bigInt);
                 return [{ int }, TYPE_MAPPING[type]];
             }
             catch {

package/dist/util/get-client.js

@@ -1,8 +1,8 @@
 import { Client } from '@quonfig/node';
 import { getApiUrl } from '../util/domain-urls.js';
 import jsonMaybe from '../util/json-maybe.js';
-import { decodeJWT, refreshAccessToken } from '../util/oauth-client.js';
-import { getActiveProfile, loadAuthConfig, loadTokens, saveTokens } from '../util/token-storage.js';
+import { getActiveProfile, loadAuthConfig, loadTokens } from '../util/token-storage.js';
+import { getValidAccessToken } from '../util/get-valid-token.js';
 import version from '../version.js';
 let clientInstance;
 let cachedWorkspaceId;
@@ -31,45 +31,13 @@ const getClient = async (command, sdkKey, profile) => {
         if (!authConfig || !tokens?.accessToken) {
             command.error('No authentication found. Please run `qfg login`.', { exit: 401 });
         }
-        // Check if token is expired and refresh if needed.
-        // Prefer the JWT's actual exp claim over the stored expiresAt.
-        let tokenExpired = tokens.expiresAt ? tokens.expiresAt < Date.now() : false;
+        command.verboseLog('Checking token validity...');
         try {
-            const payload = decodeJWT(tokens.accessToken);
-            if (typeof payload.exp === 'number') {
-                tokenExpired = payload.exp * 1000 < Date.now();
-            }
+            jwt = await getValidAccessToken();
+            command.verboseLog('Token valid (or refreshed)');
         }
         catch {
-            // If we can't decode, fall back to stored expiresAt
-        }
-        if (tokenExpired && tokens.refreshToken) {
-            command.verboseLog('Token expired, refreshing...');
-            try {
-                const refreshed = await refreshAccessToken(tokens.refreshToken);
-                // Use the JWT's actual exp claim for expiry, not a hardcoded duration
-                let expiresAt = Date.now() + 300 * 1000; // fallback: 5 minutes
-                try {
-                    const payload = decodeJWT(refreshed.access_token);
-                    if (typeof payload.exp === 'number') {
-                        expiresAt = payload.exp * 1000; // convert seconds to ms
-                    }
-                }
-                catch {
-                    // Use fallback
-                }
-                tokens = {
-                    ...tokens,
-                    accessToken: refreshed.access_token,
-                    expiresAt,
-                    refreshToken: refreshed.refresh_token,
-                };
-                await saveTokens(tokens);
-                command.verboseLog('Token refreshed successfully');
-            }
-            catch (error) {
-                command.error('Session expired. Please run `qfg login` to re-authenticate.', { exit: 401 });
-            }
+            command.error('Session expired. Please run `qfg login` to re-authenticate.', { exit: 401 });
         }
         // Get the active profile to find the workspace
         const activeProfile = getActiveProfile(profile);
@@ -82,12 +50,6 @@ const getClient = async (command, sdkKey, profile) => {
         if (profileData) {
             workspaceId = profileData.workspace;
         }
-        // Use the WorkOS access token directly as the JWT
-        jwt = tokens.accessToken;
-        // If still no JWT, user needs to login
-        if (!jwt) {
-            command.error('No authentication found. Please run `qfg login`.', { exit: 401 });
-        }
     }
     // Store workspaceId on the command for use in building URLs and cache it
     if (workspaceId) {

package/dist/util/get-valid-token.d.ts

@@ -0,0 +1,5 @@
+/**
+ * Returns a valid (non-expired) WorkOS access token, refreshing if needed.
+ * Throws if not logged in or if refresh fails.
+ */
+export declare function getValidAccessToken(): Promise<string>;

package/dist/util/get-valid-token.js

@@ -0,0 +1,44 @@
+/**
+ * Returns a valid (non-expired) WorkOS access token, refreshing if needed.
+ * Throws if not logged in or if refresh fails.
+ */
+import { decodeJWT, refreshAccessToken } from './oauth-client.js';
+import { loadTokens, saveTokens } from './token-storage.js';
+export async function getValidAccessToken() {
+    const tokens = await loadTokens();
+    if (!tokens?.accessToken) {
+        throw new Error('Not authenticated. Please run `qfg login` first.');
+    }
+    // Check expiry using the JWT's exp claim, falling back to stored expiresAt
+    let expired = tokens.expiresAt ? tokens.expiresAt < Date.now() : false;
+    try {
+        const payload = decodeJWT(tokens.accessToken);
+        if (typeof payload.exp === 'number') {
+            expired = payload.exp * 1000 < Date.now();
+        }
+    }
+    catch { /* use stored expiresAt */ }
+    if (!expired) {
+        return tokens.accessToken;
+    }
+    if (!tokens.refreshToken) {
+        throw new Error('Session expired. Please run `qfg login` to re-authenticate.');
+    }
+    const refreshed = await refreshAccessToken(tokens.refreshToken);
+    let expiresAt = Date.now() + 300 * 1000;
+    try {
+        const payload = decodeJWT(refreshed.access_token);
+        if (typeof payload.exp === 'number') {
+            expiresAt = payload.exp * 1000;
+        }
+    }
+    catch { /* use fallback */ }
+    const updated = {
+        ...tokens,
+        accessToken: refreshed.access_token,
+        expiresAt,
+        refreshToken: refreshed.refresh_token,
+    };
+    await saveTokens(updated);
+    return refreshed.access_token;
+}

package/dist/util/git-ops.d.ts

@@ -0,0 +1,32 @@
+/**
+ * Redact a token from a URL string so it is safe to display to users.
+ */
+export declare const redactToken: (url: string) => string;
+export declare const gitClone: (repoUrl: string, dir: string) => Promise<void>;
+export declare const isGitRepo: (dir: string) => Promise<boolean>;
+export declare const getRemoteUrl: (dir: string) => Promise<string | null>;
+export declare const isWorkingTreeClean: (dir: string) => Promise<boolean>;
+export declare const gitFetch: (dir: string) => Promise<void>;
+/**
+ * Returns true if origin/main has commits that can be fast-forwarded into the local branch.
+ */
+export declare const canFastForward: (dir: string) => Promise<boolean>;
+/**
+ * Returns true if local has commits not reachable from origin/main (diverged).
+ */
+export declare const hasDivergedFromRemote: (dir: string) => Promise<boolean>;
+/**
+ * Performs a fast-forward-only merge of origin/main. Returns list of new commit subjects.
+ */
+export declare const gitMergeFfOnly: (dir: string) => Promise<string[]>;
+/**
+ * Adds or updates the origin remote for a repo.
+ */
+export declare const gitSetRemote: (dir: string, url: string) => Promise<void>;
+export declare const gitPushForceLease: (dir: string) => Promise<void>;
+export declare const gitPushForce: (dir: string) => Promise<void>;
+export declare const hasAtLeastOneCommit: (dir: string) => Promise<boolean>;
+/**
+ * Get the URL stripped of credentials for display purposes.
+ */
+export declare const displayUrl: (url: string) => string;

package/dist/util/git-ops.js

@@ -0,0 +1,164 @@
+import { execFile as execFileCb } from 'node:child_process';
+import * as util from 'node:util';
+const execFile = util.promisify(execFileCb);
+/**
+ * Redact a token from a URL string so it is safe to display to users.
+ */
+export const redactToken = (url) => url.replace(/:([^@/]+)@/, ':***@');
+/**
+ * Wrap execFile errors to strip tokens from the message.
+ */
+const safeExec = async (file, args, options) => {
+    try {
+        return await execFile(file, args, { cwd: options?.cwd });
+    }
+    catch (err) {
+        const e = err;
+        const message = redactToken(e.message || String(err));
+        const stderr = redactToken(e.stderr ?? '');
+        const safeErr = new Error(message);
+        safeErr.stderr = stderr;
+        throw safeErr;
+    }
+};
+export const gitClone = async (repoUrl, dir) => {
+    await safeExec('git', ['clone', repoUrl, dir]);
+};
+export const isGitRepo = async (dir) => {
+    try {
+        await execFile('git', ['-C', dir, 'rev-parse', '--git-dir']);
+        return true;
+    }
+    catch {
+        return false;
+    }
+};
+export const getRemoteUrl = async (dir) => {
+    try {
+        const { stdout } = await execFile('git', ['-C', dir, 'remote', 'get-url', 'origin']);
+        return stdout.trim() || null;
+    }
+    catch {
+        return null;
+    }
+};
+export const isWorkingTreeClean = async (dir) => {
+    const { stdout } = await execFile('git', ['-C', dir, 'status', '--porcelain']);
+    return stdout.trim() === '';
+};
+export const gitFetch = async (dir) => {
+    await safeExec('git', ['-C', dir, 'fetch', 'origin']);
+};
+/**
+ * Returns true if origin/main has commits that can be fast-forwarded into the local branch.
+ */
+export const canFastForward = async (dir) => {
+    try {
+        // Get the local HEAD and origin/main SHAs
+        const { stdout: localSha } = await execFile('git', ['-C', dir, 'rev-parse', 'HEAD']);
+        const { stdout: remoteSha } = await execFile('git', ['-C', dir, 'rev-parse', 'origin/main']);
+        const local = localSha.trim();
+        const remote = remoteSha.trim();
+        if (local === remote)
+            return false; // already up to date
+        // Check if local is an ancestor of remote (i.e. ff is possible)
+        try {
+            await execFile('git', ['-C', dir, 'merge-base', '--is-ancestor', local, remote]);
+            return true; // exit code 0 means local is an ancestor of remote
+        }
+        catch {
+            return false; // local has diverged
+        }
+    }
+    catch {
+        return false;
+    }
+};
+/**
+ * Returns true if local has commits not reachable from origin/main (diverged).
+ */
+export const hasDivergedFromRemote = async (dir) => {
+    try {
+        const { stdout: localSha } = await execFile('git', ['-C', dir, 'rev-parse', 'HEAD']);
+        const { stdout: remoteSha } = await execFile('git', ['-C', dir, 'rev-parse', 'origin/main']);
+        const local = localSha.trim();
+        const remote = remoteSha.trim();
+        if (local === remote)
+            return false;
+        // If remote is an ancestor of local, local is ahead (diverged for our purposes)
+        try {
+            await execFile('git', ['-C', dir, 'merge-base', '--is-ancestor', remote, local]);
+            return true;
+        }
+        catch {
+            // Check if truly diverged (neither is ancestor of the other)
+            try {
+                await execFile('git', ['-C', dir, 'merge-base', '--is-ancestor', local, remote]);
+                return false; // ff possible, not diverged
+            }
+            catch {
+                return true; // truly diverged
+            }
+        }
+    }
+    catch {
+        return false;
+    }
+};
+/**
+ * Performs a fast-forward-only merge of origin/main. Returns list of new commit subjects.
+ */
+export const gitMergeFfOnly = async (dir) => {
+    // Get commits that will be merged (before merge)
+    let newCommits = [];
+    try {
+        const { stdout: localSha } = await execFile('git', ['-C', dir, 'rev-parse', 'HEAD']);
+        const { stdout: log } = await execFile('git', [
+            '-C',
+            dir,
+            'log',
+            '--pretty=format:%s',
+            `${localSha.trim()}..origin/main`,
+        ]);
+        newCommits = log
+            .split('\n')
+            .map((s) => s.trim())
+            .filter(Boolean);
+    }
+    catch {
+        // Non-fatal — we'll still attempt the merge
+    }
+    await safeExec('git', ['-C', dir, 'merge', '--ff-only', 'origin/main']);
+    return newCommits;
+};
+/**
+ * Adds or updates the origin remote for a repo.
+ */
+export const gitSetRemote = async (dir, url) => {
+    const existing = await getRemoteUrl(dir);
+    if (existing !== null) {
+        await safeExec('git', ['-C', dir, 'remote', 'set-url', 'origin', url]);
+    }
+    else {
+        await safeExec('git', ['-C', dir, 'remote', 'add', 'origin', url]);
+    }
+};
+export const gitPushForceLease = async (dir) => {
+    await safeExec('git', ['-C', dir, 'push', 'origin', 'main', '--force-with-lease']);
+};
+export const gitPushForce = async (dir) => {
+    await safeExec('git', ['-C', dir, 'push', 'origin', 'main', '--force']);
+};
+export const hasAtLeastOneCommit = async (dir) => {
+    try {
+        await execFile('git', ['-C', dir, 'rev-parse', 'HEAD']);
+        return true;
+    }
+    catch {
+        return false;
+    }
+};
+/**
+ * Get the URL stripped of credentials for display purposes.
+ */
+export const displayUrl = (url) => redactToken(url);

package/dist/util/gitea-api.d.ts

@@ -0,0 +1,11 @@
+import { GiteaTokenEntry } from './gitea-token-storage.js';
+export interface GiteaTokenResponse {
+    token: string;
+    repoUrl: string;
+    expiresAt: string | null;
+}
+export declare const mintGiteaToken: (workspaceId: string, scope: "read" | "write", purpose: "pull" | "bootstrap") => Promise<GiteaTokenResponse>;
+/**
+ * Mint a Gitea read token, store it, and return the entry.
+ */
+export declare const mintAndStoreGiteaReadToken: (workspaceId: string) => Promise<GiteaTokenEntry>;

package/dist/util/gitea-api.js

@@ -0,0 +1,45 @@
+import { getApiUrl } from './domain-urls.js';
+import { getValidAccessToken } from './get-valid-token.js';
+import { saveGiteaToken } from './gitea-token-storage.js';
+export const mintGiteaToken = async (workspaceId, scope, purpose) => {
+    const accessToken = await getValidAccessToken();
+    const apiUrl = getApiUrl();
+    const res = await fetch(`${apiUrl}/api/v1/gitea/token`, {
+        method: 'POST',
+        headers: {
+            'Authorization': `Bearer ${accessToken}`,
+            'Content-Type': 'application/json',
+        },
+        body: JSON.stringify({ json: { scope, workspaceId, purpose } }),
+    });
+    if (!res.ok) {
+        const text = await res.text().catch(() => '');
+        let message = `HTTP ${res.status}`;
+        try {
+            const body = JSON.parse(text);
+            // oRPC error shape
+            if (body?.json?.message)
+                message = body.json.message;
+            else if (body?.message)
+                message = body.message;
+        }
+        catch { /* use raw text */ }
+        throw new Error(message || text);
+    }
+    const body = await res.json();
+    const data = body.json ?? body;
+    return data;
+};
+/**
+ * Mint a Gitea read token, store it, and return the entry.
+ */
+export const mintAndStoreGiteaReadToken = async (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;
+};

package/dist/util/gitea-token-storage.d.ts

@@ -0,0 +1,8 @@
+export interface GiteaTokenEntry {
+    token: string;
+    repoUrl: string;
+    expiresAt: string | null;
+}
+export declare const loadGiteaToken: (workspaceId: string) => Promise<GiteaTokenEntry | null>;
+export declare const saveGiteaToken: (workspaceId: string, entry: GiteaTokenEntry) => Promise<void>;
+export declare const isGiteaTokenExpired: (entry: GiteaTokenEntry) => boolean;

package/dist/util/gitea-token-storage.js

@@ -0,0 +1,47 @@
+import * as fs from 'node:fs';
+import * as os from 'node:os';
+import * as path from 'node:path';
+import { getDomain } from './domain-urls.js';
+const BUFFER_MS = 5 * 60 * 1000; // 5 minutes
+const getQuonfigDir = () => path.join(os.homedir(), '.quonfig');
+const getGiteaTokenFile = () => {
+    const domain = getDomain();
+    const filename = domain !== 'quonfig.com' ? `gitea-tokens-${domain.replaceAll('.', '-')}.json` : 'gitea-tokens.json';
+    return path.join(getQuonfigDir(), filename);
+};
+const ensureQuonfigDir = async () => {
+    const dir = getQuonfigDir();
+    try {
+        await fs.promises.access(dir, fs.constants.F_OK);
+    }
+    catch {
+        await fs.promises.mkdir(dir, { recursive: true });
+    }
+};
+const loadStore = async () => {
+    try {
+        const data = await fs.promises.readFile(getGiteaTokenFile(), 'utf8');
+        return JSON.parse(data);
+    }
+    catch {
+        return {};
+    }
+};
+export const loadGiteaToken = async (workspaceId) => {
+    const store = await loadStore();
+    return store[workspaceId] ?? null;
+};
+export const saveGiteaToken = async (workspaceId, entry) => {
+    await ensureQuonfigDir();
+    const store = await loadStore();
+    store[workspaceId] = entry;
+    const targetFile = getGiteaTokenFile();
+    const tmpFile = `${targetFile}.tmp`;
+    await fs.promises.writeFile(tmpFile, JSON.stringify(store, null, 2), { encoding: 'utf8', mode: 0o600 });
+    await fs.promises.rename(tmpFile, targetFile);
+};
+export const isGiteaTokenExpired = (entry) => {
+    if (!entry.expiresAt)
+        return false;
+    return new Date(entry.expiresAt).getTime() - BUFFER_MS < Date.now();
+};

package/dist/util/token-storage.d.ts

@@ -14,6 +14,7 @@ export interface AuthConfig {
         [profileName: string]: {
             workspace: string;
             workspaceName?: string;
+            workspaceSlug?: string;
         };
     };
 }