@quonfig/cli 0.0.11 → 0.0.12

package/dist/migrate/migration-report.d.ts

@@ -0,0 +1,42 @@
+import type { IdentifierMap } from './identifier-map.js';
+export interface MigrationReportCounts {
+    environmentsMapped: number;
+    flagsMigrated: number;
+    itemsSkipped: number;
+    segmentsMigrated: number;
+}
+export interface CleanMapping {
+    legacyKey: string;
+    quonfigKey: string;
+}
+export interface LossyMapping {
+    legacyKey: string;
+    quonfigKey: string;
+    reason: string;
+}
+export interface UnsupportedFeature {
+    feature: string;
+    note?: string;
+}
+export interface EnvironmentMapEntry {
+    quonfigName: string;
+    sourceName: string;
+}
+export interface FollowUpChecklist {
+    mustFixBeforeCutover: string[];
+    reviewPostCutover: string[];
+}
+export interface MigrationReportData {
+    cleanMappings: CleanMapping[];
+    counts: MigrationReportCounts;
+    dryRun: boolean;
+    environmentMap: EnvironmentMapEntry[];
+    followUp: FollowUpChecklist;
+    identifierMap: IdentifierMap;
+    lossyMappings: LossyMapping[];
+    source: string;
+    unsupportedFeatures: UnsupportedFeature[];
+}
+export declare const buildMigrationReport: (data: MigrationReportData) => string;
+export declare const migrationReportPath: (outputDir: string) => string;
+export declare const writeMigrationReport: (outputDir: string, data: MigrationReportData) => string;

package/dist/migrate/migration-report.js

@@ -0,0 +1,93 @@
+import fs from 'node:fs';
+import path from 'node:path';
+const NONE = '_(none)_';
+const renderCounts = (counts) => [
+    '## Counts',
+    '',
+    `- Flags migrated: ${counts.flagsMigrated}`,
+    `- Segments migrated: ${counts.segmentsMigrated}`,
+    `- Environments mapped: ${counts.environmentsMapped}`,
+    `- Items skipped: ${counts.itemsSkipped}`,
+].join('\n');
+const renderCleanMappings = (entries) => {
+    const header = '## Clean mapping list';
+    if (entries.length === 0)
+        return `${header}\n\n${NONE}`;
+    const sorted = [...entries].sort((a, b) => a.legacyKey.localeCompare(b.legacyKey));
+    const lines = sorted.map((e) => `- \`${e.legacyKey}\` → \`${e.quonfigKey}\``);
+    return [header, '', ...lines].join('\n');
+};
+const renderLossyMappings = (entries) => {
+    const header = '## Lossy mapping list';
+    if (entries.length === 0)
+        return `${header}\n\n${NONE}`;
+    const sorted = [...entries].sort((a, b) => a.legacyKey.localeCompare(b.legacyKey));
+    const lines = sorted.map((e) => `- \`${e.legacyKey}\` → \`${e.quonfigKey}\` — ${e.reason}`);
+    return [header, '', ...lines].join('\n');
+};
+const renderUnsupported = (entries) => {
+    const header = '## Unsupported feature list';
+    if (entries.length === 0)
+        return `${header}\n\n${NONE}`;
+    const lines = entries.map((e) => (e.note ? `- **${e.feature}** — ${e.note}` : `- ${e.feature}`));
+    return [header, '', ...lines].join('\n');
+};
+const renderEnvironmentMap = (entries) => {
+    const header = '## Environment mapping table';
+    if (entries.length === 0)
+        return `${header}\n\n${NONE}`;
+    const sorted = [...entries].sort((a, b) => a.sourceName.localeCompare(b.sourceName));
+    const rows = sorted.map((e) => `| ${e.sourceName} | ${e.quonfigName} |`);
+    return [header, '', '| Source | Quonfig |', '| --- | --- |', ...rows].join('\n');
+};
+const renderIdentifierMap = (map) => {
+    const header = '## Identifier map';
+    const keys = Object.keys(map);
+    if (keys.length === 0)
+        return `${header}\n\n${NONE}`;
+    const sorted = [...keys].sort();
+    const rows = sorted.map((k) => `| \`${k}\` | \`${map[k]}\` |`);
+    return [header, '', '| Legacy key | Quonfig key |', '| --- | --- |', ...rows].join('\n');
+};
+const renderFollowUp = (followUp) => {
+    const must = followUp.mustFixBeforeCutover.length === 0
+        ? NONE
+        : followUp.mustFixBeforeCutover.map((item) => `- [ ] ${item}`).join('\n');
+    const review = followUp.reviewPostCutover.length === 0
+        ? NONE
+        : followUp.reviewPostCutover.map((item) => `- [ ] ${item}`).join('\n');
+    return [
+        '## Follow-up checklist',
+        '',
+        '### Must fix before cutover',
+        '',
+        must,
+        '',
+        '### Review post-cutover',
+        '',
+        review,
+    ].join('\n');
+};
+export const buildMigrationReport = (data) => {
+    const sections = [];
+    if (data.dryRun) {
+        sections.push('> **DRY RUN** — no files were written to the workspace during this run.');
+    }
+    sections.push(`# Migration Report (from ${data.source})`);
+    sections.push(`_Reflects only the changes produced by this run. Re-running overwrites this file._`);
+    sections.push(renderCounts(data.counts));
+    sections.push(renderCleanMappings(data.cleanMappings));
+    sections.push(renderLossyMappings(data.lossyMappings));
+    sections.push(renderUnsupported(data.unsupportedFeatures));
+    sections.push(renderEnvironmentMap(data.environmentMap));
+    sections.push(renderIdentifierMap(data.identifierMap));
+    sections.push(renderFollowUp(data.followUp));
+    return sections.join('\n\n') + '\n';
+};
+export const migrationReportPath = (outputDir) => path.join(outputDir, 'MIGRATION_REPORT.md');
+export const writeMigrationReport = (outputDir, data) => {
+    fs.mkdirSync(outputDir, { recursive: true });
+    const filePath = migrationReportPath(outputDir);
+    fs.writeFileSync(filePath, buildMigrationReport(data), 'utf8');
+    return filePath;
+};

package/dist/migrate/push-strategy.d.ts

@@ -0,0 +1,34 @@
+export declare const MIGRATOR_IDENTITY: {
+    readonly name: "quonfig migrator";
+    readonly email: "migrator@quonfig.com";
+};
+export interface PushIdentity {
+    email: string;
+    name: string;
+}
+export interface CloneAndStackPushOptions {
+    /** Called once `localDir` is a clone synced with origin/main. Must write/delete files under `localDir` — do NOT commit. */
+    applyDelta: (localDir: string) => Promise<void> | void;
+    /** Commit author. Defaults to the migrator identity. */
+    author?: PushIdentity;
+    /** Branch to track and push. Defaults to `main`. */
+    branch?: string;
+    /** Single commit message for the delta. */
+    commitMessage: string;
+    /** Where to clone into, or an existing clone to reuse. */
+    localDir: string;
+    /** Gitea repo URL (may include token). */
+    remoteUrl: string;
+}
+export interface CloneAndStackPushResult {
+    /** `'cloned'` if we had to clone fresh, `'reused'` if the local dir was already a clone of the remote. */
+    action: 'cloned' | 'reused';
+    /** SHA of the new commit, if one was made. */
+    commitSha: string | null;
+    /** `false` if `applyDelta` produced no changes — nothing was committed or pushed. */
+    committed: boolean;
+}
+export declare class PushConflictError extends Error {
+    constructor(message: string);
+}
+export declare const cloneAndStackPush: (opts: CloneAndStackPushOptions) => Promise<CloneAndStackPushResult>;

package/dist/migrate/push-strategy.js

@@ -0,0 +1,133 @@
+import { execFile as execFileCb, spawn } from 'node:child_process';
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+import * as util from 'node:util';
+const execFile = util.promisify(execFileCb);
+const gitCommitFromStdin = (cwd, message, env) => new Promise((resolve, reject) => {
+    const child = spawn('git', ['-C', cwd, 'commit', '-F', '-'], { env });
+    let stderr = '';
+    child.stderr.on('data', (d) => {
+        stderr += d.toString();
+    });
+    child.on('error', reject);
+    child.on('close', (code) => {
+        if (code === 0)
+            resolve();
+        else
+            reject(new Error(`git commit exited ${code}: ${stderr}`));
+    });
+    child.stdin.end(message);
+});
+export const MIGRATOR_IDENTITY = {
+    name: 'quonfig migrator',
+    email: 'migrator@quonfig.com',
+};
+const redactToken = (s) => s.replaceAll(/:([^\s/@]+)@/g, ':***@');
+export class PushConflictError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = 'PushConflictError';
+    }
+}
+const runGit = async (cwd, args) => {
+    try {
+        return await execFile('git', args, { cwd });
+    }
+    catch (error) {
+        const e = error;
+        const stderr = redactToken(e.stderr ?? '');
+        const stdout = redactToken(e.stdout ?? '');
+        const message = redactToken(e.message || String(error));
+        const wrapped = new Error(`${message}\n${stderr}`.trim());
+        wrapped.stderr = stderr;
+        wrapped.stdout = stdout;
+        throw wrapped;
+    }
+};
+const isGitRepo = async (dir) => {
+    try {
+        await execFile('git', ['-C', dir, 'rev-parse', '--git-dir']);
+        return true;
+    }
+    catch {
+        return false;
+    }
+};
+const getOriginUrl = async (dir) => {
+    try {
+        const { stdout } = await execFile('git', ['-C', dir, 'remote', 'get-url', 'origin']);
+        return stdout.trim() || null;
+    }
+    catch {
+        return null;
+    }
+};
+const normalizeRemoteUrl = (url) => redactToken(url.replace(/\.git$/, '').trim());
+const ensureCloneOrReuse = async (remoteUrl, localDir, branch) => {
+    if (fs.existsSync(localDir) && (await isGitRepo(localDir))) {
+        const origin = await getOriginUrl(localDir);
+        if (origin && normalizeRemoteUrl(origin) === normalizeRemoteUrl(remoteUrl)) {
+            // Reuse: fetch + ff-merge
+            await runGit(localDir, ['fetch', 'origin', branch]);
+            await runGit(localDir, ['checkout', branch]);
+            await runGit(localDir, ['merge', '--ff-only', `origin/${branch}`]);
+            return 'reused';
+        }
+        throw new Error(`Local dir ${localDir} is a git repo but its origin (${origin ? redactToken(origin) : 'unset'}) does not match the target remote. Refuse to clobber — pass an empty/non-existent path or a matching clone.`);
+    }
+    if (fs.existsSync(localDir)) {
+        const entries = fs.readdirSync(localDir);
+        if (entries.length > 0) {
+            throw new Error(`Local dir ${localDir} exists and is not empty, but is not a git clone of ${redactToken(remoteUrl)}. Refuse to clobber.`);
+        }
+    }
+    fs.mkdirSync(path.dirname(localDir), { recursive: true });
+    await runGit(path.dirname(localDir) || '.', [
+        'clone',
+        '--branch',
+        branch,
+        remoteUrl,
+        localDir,
+    ]);
+    return 'cloned';
+};
+const hasStagedChanges = async (dir) => {
+    const { stdout } = await execFile('git', ['-C', dir, 'status', '--porcelain']);
+    return stdout.trim().length > 0;
+};
+export const cloneAndStackPush = async (opts) => {
+    const branch = opts.branch ?? 'main';
+    const author = opts.author ?? MIGRATOR_IDENTITY;
+    const action = await ensureCloneOrReuse(opts.remoteUrl, opts.localDir, branch);
+    // Pin committer identity on the repo so commits are reproducible regardless of host git config.
+    await runGit(opts.localDir, ['config', 'user.name', author.name]);
+    await runGit(opts.localDir, ['config', 'user.email', author.email]);
+    await opts.applyDelta(opts.localDir);
+    await runGit(opts.localDir, ['add', '--all']);
+    if (!(await hasStagedChanges(opts.localDir))) {
+        return { action, committed: false, commitSha: null };
+    }
+    await gitCommitFromStdin(opts.localDir, opts.commitMessage, {
+        ...process.env,
+        GIT_AUTHOR_NAME: author.name,
+        GIT_AUTHOR_EMAIL: author.email,
+        GIT_COMMITTER_NAME: author.name,
+        GIT_COMMITTER_EMAIL: author.email,
+    });
+    const { stdout: sha } = await execFile('git', ['-C', opts.localDir, 'rev-parse', 'HEAD']);
+    try {
+        // Plain push — no force, no force-with-lease. If the remote has advanced, we fail
+        // and surface a conflict; we do NOT clobber UI edits.
+        await runGit(opts.localDir, ['push', 'origin', branch]);
+    }
+    catch (error) {
+        const e = error;
+        const stderr = e.stderr ?? '';
+        const combined = `${e.message}\n${stderr}`;
+        if (/non-fast-forward|fetch first|rejected/i.test(combined)) {
+            throw new PushConflictError(`Push to origin/${branch} was rejected: the remote has changes we do not have locally. Re-run the migrator to pick up those changes, then push again. Original git error:\n${redactToken(stderr || e.message)}`);
+        }
+        throw error;
+    }
+    return { action, committed: true, commitSha: sha.trim() };
+};

package/dist/migrate/push-to-cloud.d.ts

@@ -0,0 +1,15 @@
+import { type ImportState } from './import-state.js';
+import { type MigrationReportData } from './migration-report.js';
+import { type CloneAndStackPushResult } from './push-strategy.js';
+import type { LegacyChange, MigrationSource } from './source.js';
+export interface PushMigrationToCloudOptions {
+    branch?: string;
+    changes: LegacyChange[];
+    commitMessage: string;
+    importState: ImportState;
+    localDir: string;
+    remoteUrl: string;
+    reportData: MigrationReportData;
+    source: MigrationSource;
+}
+export declare const pushMigrationToCloud: (opts: PushMigrationToCloudOptions) => Promise<CloneAndStackPushResult>;

package/dist/migrate/push-to-cloud.js

@@ -0,0 +1,31 @@
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+import { removeQfFromGitignore, writeImportState } from './import-state.js';
+import { writeMigrationReport } from './migration-report.js';
+import { cloneAndStackPush, } from './push-strategy.js';
+const writeQuonfigFiles = (dir, changes, source) => {
+    for (const change of changes) {
+        const files = source.translate(change);
+        for (const file of files) {
+            const full = path.join(dir, file.path);
+            fs.mkdirSync(path.dirname(full), { recursive: true });
+            fs.writeFileSync(full, file.contents);
+        }
+    }
+};
+export const pushMigrationToCloud = async (opts) => {
+    const cloneOpts = {
+        applyDelta(dir) {
+            writeQuonfigFiles(dir, opts.changes, opts.source);
+            removeQfFromGitignore(dir);
+            writeImportState(dir, opts.importState);
+            writeMigrationReport(dir, opts.reportData);
+        },
+        commitMessage: opts.commitMessage,
+        localDir: opts.localDir,
+        remoteUrl: opts.remoteUrl,
+    };
+    if (opts.branch !== undefined)
+        cloneOpts.branch = opts.branch;
+    return cloneAndStackPush(cloneOpts);
+};

package/dist/migrate/registry.d.ts

@@ -0,0 +1,6 @@
+import { type MigrationSource } from './source.js';
+export declare class UnknownSourceError extends Error {
+    constructor(name: string);
+}
+export declare function getSource(name: string): MigrationSource;
+export declare function listSources(): string[];

package/dist/migrate/registry.js

@@ -0,0 +1,25 @@
+import { flagsmithSource } from './sources/flagsmith.js';
+import { launchSource } from './sources/launch.js';
+import { launchdarklySource } from './sources/launchdarkly.js';
+const SOURCES = {
+    flagsmith: flagsmithSource,
+    launch: launchSource,
+    launchdarkly: launchdarklySource,
+};
+export class UnknownSourceError extends Error {
+    constructor(name) {
+        const supported = Object.keys(SOURCES).sort().join(', ');
+        super(`Unknown migration source "${name}". Supported: ${supported}.`);
+        this.name = 'UnknownSourceError';
+    }
+}
+export function getSource(name) {
+    const source = SOURCES[name];
+    if (!source) {
+        throw new UnknownSourceError(name);
+    }
+    return source;
+}
+export function listSources() {
+    return Object.keys(SOURCES).sort();
+}

package/dist/migrate/source.d.ts

@@ -0,0 +1,22 @@
+export interface LegacyChange {
+    changedAt?: number;
+    key?: string;
+    raw: unknown;
+    source: string;
+}
+export interface QuonfigFile {
+    contents: string;
+    path: string;
+}
+export interface MigrationSource {
+    fetchChanges(sinceEpochMs: null | number): AsyncIterable<LegacyChange>;
+    listEnvironments(): Promise<string[]>;
+    name: string;
+    translate(change: LegacyChange): QuonfigFile[];
+    validateAuth(apiKey: string): Promise<void>;
+}
+export declare class NotYetImplementedError extends Error {
+    readonly issueUrl: string;
+    readonly sourceName: string;
+    constructor(sourceName: string, operation: string);
+}

package/dist/migrate/source.js

@@ -0,0 +1,12 @@
+export class NotYetImplementedError extends Error {
+    issueUrl;
+    sourceName;
+    constructor(sourceName, operation) {
+        const issueUrl = `https://github.com/quonfig/cli/issues/new?title=qfg+migrate+--from+${encodeURIComponent(sourceName)}`;
+        super(`qfg migrate --from ${sourceName} is not yet implemented (${operation}). ` +
+            `File a bead to prioritize this source: ${issueUrl}`);
+        this.name = 'NotYetImplementedError';
+        this.sourceName = sourceName;
+        this.issueUrl = issueUrl;
+    }
+}

package/dist/migrate/sources/flagsmith.d.ts

@@ -0,0 +1,2 @@
+import { type MigrationSource } from '../source.js';
+export declare const flagsmithSource: MigrationSource;

package/dist/migrate/sources/flagsmith.js

@@ -0,0 +1,18 @@
+import { NotYetImplementedError } from '../source.js';
+const SOURCE_NAME = 'flagsmith';
+export const flagsmithSource = {
+    // eslint-disable-next-line require-yield
+    async *fetchChanges() {
+        throw new NotYetImplementedError(SOURCE_NAME, 'fetchChanges');
+    },
+    listEnvironments() {
+        throw new NotYetImplementedError(SOURCE_NAME, 'listEnvironments');
+    },
+    name: SOURCE_NAME,
+    translate() {
+        throw new NotYetImplementedError(SOURCE_NAME, 'translate');
+    },
+    validateAuth() {
+        throw new NotYetImplementedError(SOURCE_NAME, 'validateAuth');
+    },
+};

package/dist/migrate/sources/launch/api.d.ts

@@ -0,0 +1,7 @@
+import type { LaunchChangeEntry, LaunchChangeHistoryResponse } from './types.js';
+export declare function setLaunchBaseUrl(url: string): void;
+export declare function selectLaunchBaseUrl(staging: boolean): string;
+export declare function applyLaunchBaseUrl(staging: boolean): void;
+export declare function fetchEnvironments(apiKey: string): Promise<Record<string, string>>;
+export declare function fetchChangeHistoryPage(apiKey: string, cursor?: string): Promise<LaunchChangeHistoryResponse>;
+export declare function fetchAllChangeHistory(apiKey: string, sinceEpochMs?: number): Promise<LaunchChangeEntry[]>;

package/dist/migrate/sources/launch/api.js

@@ -0,0 +1,75 @@
+const PROD_BASE_URL = 'https://api.reforge.com';
+const STAGING_BASE_URL = 'https://api.goatsofreforge.com';
+const PAGE_LIMIT = 50;
+let baseUrl = PROD_BASE_URL;
+export function setLaunchBaseUrl(url) {
+    baseUrl = url;
+}
+export function selectLaunchBaseUrl(staging) {
+    return process.env.LAUNCH_API_URL ?? (staging ? STAGING_BASE_URL : PROD_BASE_URL);
+}
+export function applyLaunchBaseUrl(staging) {
+    baseUrl = selectLaunchBaseUrl(staging);
+}
+function makeToken(apiKey) {
+    return Buffer.from(`authuser:${apiKey}`).toString('base64');
+}
+async function apiFetch(path, apiKey) {
+    const url = `${baseUrl}${path}`;
+    const token = makeToken(apiKey);
+    const res = await fetch(url, {
+        headers: {
+            Accept: 'application/json',
+            Authorization: `Basic ${token}`,
+        },
+    });
+    if (!res.ok) {
+        const body = await res.text().catch(() => '(no body)');
+        throw new Error(`Launch API request failed: ${res.status} ${res.statusText} — ${url}\n${body}`);
+    }
+    return res.json();
+}
+export async function fetchEnvironments(apiKey) {
+    const data = (await apiFetch('/api/v1/project-environments', apiKey));
+    const envMap = {};
+    for (const env of data.envs) {
+        envMap[String(env.id)] = env.name;
+    }
+    return envMap;
+}
+export async function fetchChangeHistoryPage(apiKey, cursor) {
+    const params = new URLSearchParams({
+        expands: 'changedBy',
+        includeNewVersion: 'true',
+        includeSummary: 'true',
+        limit: String(PAGE_LIMIT),
+    });
+    if (cursor) {
+        params.set('cursor', cursor);
+    }
+    return (await apiFetch(`/api/v1/change-history?${params}`, apiKey));
+}
+export async function fetchAllChangeHistory(apiKey, sinceEpochMs) {
+    const collected = [];
+    const seenCursors = new Set();
+    let cursor;
+    let done = false;
+    while (!done) {
+        // eslint-disable-next-line no-await-in-loop
+        const page = await fetchChangeHistoryPage(apiKey, cursor);
+        if (page.changes.length === 0)
+            break;
+        for (const change of page.changes) {
+            if (sinceEpochMs !== undefined && change.changedAt <= sinceEpochMs) {
+                done = true;
+                break;
+            }
+            collected.push(change);
+        }
+        if (done || !page.cursor || seenCursors.has(page.cursor))
+            break;
+        seenCursors.add(page.cursor);
+        cursor = page.cursor;
+    }
+    return collected.reverse();
+}

package/dist/migrate/sources/launch/translate.d.ts

@@ -0,0 +1,6 @@
+import type { LaunchChangeEntry, LaunchChangeGroup, LaunchConfig } from './types.js';
+export declare function slugify(value: string): string;
+export declare function isLegacyLogLevel(type: string): boolean;
+export declare function transformConfig(config: LaunchConfig, envIdMap: Record<string, string>): Record<string, unknown>;
+export declare function getOutputPath(type: string, key: string): string;
+export declare function groupChanges(changes: LaunchChangeEntry[]): LaunchChangeGroup[];