@quonfig/cli 0.0.11 → 0.0.12

package/dist/commands/migrate.js

@@ -0,0 +1,256 @@
+import { Flags } from '@oclif/core';
+import fs from 'node:fs';
+import path from 'node:path';
+import { BaseCommand } from '../index.js';
+import { CrossSourceError, assertSourceMatches, readImportState, } from '../migrate/import-state.js';
+import { PushConflictError } from '../migrate/push-strategy.js';
+import { pushMigrationToCloud } from '../migrate/push-to-cloud.js';
+import { UnknownSourceError, getSource } from '../migrate/registry.js';
+import { NotYetImplementedError } from '../migrate/source.js';
+import { applyLaunchBaseUrl } from '../migrate/sources/launch/api.js';
+import { mintGiteaToken } from '../util/gitea-api.js';
+import { displayUrl } from '../util/git-ops.js';
+import { getActiveProfile, loadAuthConfig, resolveWorkspaceId, } from '../util/token-storage.js';
+const DEFAULT_DIR = 'quonfig-config';
+export default class Migrate extends BaseCommand {
+    static description = 'Migrate flags and configs from a legacy feature-flag system into a Quonfig workspace.\n\n' +
+        'Currently supported sources:\n' +
+        '  launch — Reforge Launch (ported from launch-migrator)\n\n' +
+        'See https://docs.quonfig.com/docs/migrating/from-launch for the step-by-step guide,\n' +
+        'and https://docs.quonfig.com/docs/migrating/troubleshooting when something goes sideways.';
+    static examples = [
+        '<%= config.bin %> <%= command.id %> --from launch --api-key $LAUNCH_API_KEY --dir ./quonfig-config',
+        '<%= config.bin %> <%= command.id %> --from launch --api-key $LAUNCH_API_KEY --workspace acme-prod --push',
+        '<%= config.bin %> <%= command.id %> --from launch --api-key $LAUNCH_API_KEY --dir ./quonfig-config --reset',
+        '<%= config.bin %> <%= command.id %> --from launch --api-key $LAUNCH_API_KEY --dir ./quonfig-config --dry-run',
+        '<%= config.bin %> <%= command.id %> --from launch --api-key $LAUNCH_API_KEY --dir ./quonfig-config --staging',
+    ];
+    static flags = {
+        'api-key': Flags.string({
+            description: 'API key for the legacy source (or set LAUNCH_API_KEY)',
+            env: 'LAUNCH_API_KEY',
+        }),
+        dir: Flags.string({
+            description: 'Target local workspace directory. Defaults to cwd if it looks like a Quonfig workspace, otherwise ./quonfig-config.',
+        }),
+        'dry-run': Flags.boolean({
+            default: false,
+            description: 'Fetch and summarize changes without writing anything',
+        }),
+        from: Flags.string({
+            description: 'Legacy source to migrate from',
+            options: ['launch', 'launchdarkly', 'flagsmith'],
+            required: true,
+        }),
+        push: Flags.boolean({
+            default: false,
+            description: 'After migrating to a local dir, also push to the given --workspace on Quonfig cloud',
+        }),
+        recent: Flags.integer({
+            description: 'Import only the last N changes (useful for tire-kicking)',
+        }),
+        reset: Flags.boolean({
+            default: false,
+            description: 'Ignore the delta cursor and re-import everything from scratch',
+        }),
+        since: Flags.string({
+            description: 'Override the delta cursor (epoch milliseconds or ISO-8601 timestamp)',
+        }),
+        staging: Flags.boolean({
+            default: false,
+            description: 'Hit the staging API for the source (dev-only)',
+        }),
+        workspace: Flags.string({
+            description: 'Quonfig cloud workspace slug to push to. Requires `qfg login` and is typically combined with --push.',
+        }),
+    };
+    async run() {
+        const { flags } = await this.parse(Migrate);
+        if (flags.dir && flags.workspace && !flags.push) {
+            return this.err('`--dir` and `--workspace` are mutually exclusive unless `--push` is also passed. ' +
+                'Pass `--push` to migrate locally and then push to the cloud workspace, or drop one of the flags.');
+        }
+        if (!flags['api-key']) {
+            return this.err('--api-key is required. For --from launch you can also set LAUNCH_API_KEY in your environment.');
+        }
+        let workspaceContext = null;
+        if (flags.push) {
+            const resolved = await this.resolvePushWorkspace(flags.workspace);
+            if (typeof resolved === 'string')
+                return this.err(resolved);
+            workspaceContext = resolved;
+        }
+        const dir = resolveTargetDir(flags.dir, process.cwd());
+        if (!flags.reset) {
+            try {
+                assertSourceMatches(dir, flags.from);
+            }
+            catch (error) {
+                if (error instanceof CrossSourceError)
+                    return this.err(error.message);
+                throw error;
+            }
+        }
+        if (flags.from === 'launch') {
+            applyLaunchBaseUrl(flags.staging);
+        }
+        let source;
+        try {
+            source = getSource(flags.from);
+        }
+        catch (error) {
+            if (error instanceof UnknownSourceError)
+                return this.err(error.message);
+            throw error;
+        }
+        try {
+            await source.validateAuth(flags['api-key']);
+            await source.listEnvironments();
+            const existing = readImportState(dir);
+            const sinceEpochMs = computeSince(flags, existing);
+            const changes = [];
+            for await (const change of source.fetchChanges(sinceEpochMs)) {
+                changes.push(change);
+            }
+            const toProcess = flags.recent === undefined ? changes : changes.slice(-flags.recent);
+            const payload = {
+                dir,
+                dryRun: flags['dry-run'],
+                fetched: changes.length,
+                from: flags.from,
+                processed: toProcess.length,
+                since: sinceEpochMs,
+            };
+            if (flags['dry-run']) {
+                this.log(`Dry run: would migrate ${toProcess.length} change(s) from ${flags.from} into ${dir}.`);
+                return payload;
+            }
+            if (flags.push && workspaceContext) {
+                const { workspaceId } = workspaceContext;
+                this.log('Connecting to Gitea...');
+                let repoUrl;
+                try {
+                    const tokenData = await mintGiteaToken(workspaceId, 'write', 'bootstrap');
+                    repoUrl = tokenData.repoUrl;
+                }
+                catch (error) {
+                    return this.err(`Could not get Gitea credentials for workspace ${workspaceId}: ${String(error)}\n` +
+                        'Make sure the workspace is fully provisioned in the Quonfig app before pushing.');
+                }
+                this.verboseLog('Migrate', { repoUrl: displayUrl(repoUrl) });
+                const latestChangedAt = latestChangedAtOf(toProcess, sinceEpochMs ?? undefined);
+                const importState = { source: flags.from };
+                if (latestChangedAt !== undefined)
+                    importState.lastProcessedAt = latestChangedAt;
+                this.log(`Pushing ${toProcess.length} change(s) to workspace ${workspaceId} (clone-and-stack)...`);
+                try {
+                    const result = await pushMigrationToCloud({
+                        changes: toProcess,
+                        commitMessage: buildCommitMessage(flags.from, toProcess.length),
+                        importState,
+                        localDir: dir,
+                        remoteUrl: repoUrl,
+                        reportData: buildReportData(flags.from, toProcess.length),
+                        source,
+                    });
+                    this.log(result.committed
+                        ? `Pushed ${toProcess.length} change(s). commit=${result.commitSha?.slice(0, 8) ?? ''} action=${result.action}`
+                        : `No net changes produced by this run. Nothing to commit or push.`);
+                    return {
+                        ...payload,
+                        action: result.action,
+                        commitSha: result.commitSha,
+                        committed: result.committed,
+                        pushed: true,
+                        workspaceId,
+                    };
+                }
+                catch (error) {
+                    if (error instanceof PushConflictError) {
+                        return this.err(`${error.message}\n\nRe-run \`qfg migrate --from ${flags.from} --workspace ${workspaceId} --push\` to pick up remote changes before retrying.`);
+                    }
+                    throw error;
+                }
+            }
+            this.log(`Fetched ${changes.length} change(s) from ${flags.from}; processing ${toProcess.length}.\n` +
+                'Writing files to a local dir without --push ships in follow-on beads (see qfg-zfl.10).');
+            return payload;
+        }
+        catch (error) {
+            if (error instanceof NotYetImplementedError)
+                return this.err(error.message);
+            throw error;
+        }
+    }
+    async resolvePushWorkspace(slugOrId) {
+        const authConfig = await loadAuthConfig();
+        if (!authConfig)
+            return 'Not logged in. Run `qfg login` first, then re-run with --push.';
+        if (slugOrId) {
+            const resolved = resolveWorkspaceId(authConfig, slugOrId);
+            return { authConfig, workspaceId: resolved ?? slugOrId };
+        }
+        const activeProfile = getActiveProfile();
+        const profile = authConfig.profiles[activeProfile] ||
+            authConfig.profiles[authConfig.defaultProfile || 'default'];
+        if (!profile) {
+            return 'No active profile found. Pass --workspace <slug> or run `qfg login` first.';
+        }
+        return { authConfig, workspaceId: profile.workspace };
+    }
+}
+function latestChangedAtOf(changes, fallback) {
+    let latest;
+    for (const change of changes) {
+        if (typeof change.changedAt === 'number' && (latest === undefined || change.changedAt > latest)) {
+            latest = change.changedAt;
+        }
+    }
+    return latest ?? fallback;
+}
+function buildCommitMessage(source, count) {
+    return `migrator: import ${count} change(s) from ${source}`;
+}
+function buildReportData(source, count) {
+    return {
+        cleanMappings: [],
+        counts: {
+            environmentsMapped: 0,
+            flagsMigrated: count,
+            itemsSkipped: 0,
+            segmentsMigrated: 0,
+        },
+        dryRun: false,
+        environmentMap: [],
+        followUp: { mustFixBeforeCutover: [], reviewPostCutover: [] },
+        identifierMap: {},
+        lossyMappings: [],
+        source,
+        unsupportedFeatures: [],
+    };
+}
+function resolveTargetDir(dirFlag, cwd) {
+    if (dirFlag)
+        return path.resolve(cwd, dirFlag);
+    if (fs.existsSync(path.join(cwd, 'quonfig.json')))
+        return cwd;
+    return path.resolve(cwd, DEFAULT_DIR);
+}
+function computeSince(flags, existing) {
+    if (flags.reset)
+        return null;
+    if (flags.since) {
+        const asNumber = Number(flags.since);
+        if (Number.isFinite(asNumber) && flags.since.trim() !== '')
+            return asNumber;
+        const asDate = new Date(flags.since).getTime();
+        return Number.isFinite(asDate) ? asDate : null;
+    }
+    const value = existing?.lastProcessedAt;
+    if (value === undefined)
+        return null;
+    if (typeof value === 'number')
+        return value;
+    const asDate = new Date(value).getTime();
+    return Number.isFinite(asDate) ? asDate : null;
+}

package/dist/migrate/doctor.d.ts

@@ -0,0 +1,27 @@
+import { type IdentifierMap } from './identifier-map.js';
+export interface DoctorCheck {
+    fix?: string;
+    message: string;
+    name: string;
+    passed: boolean;
+}
+export interface DoctorReport {
+    checks: DoctorCheck[];
+    passed: boolean;
+}
+export interface DoctorSession {
+    expiresAt: number;
+}
+export interface DoctorContext {
+    apiKey?: string;
+    dir: string;
+    from: string;
+    getWorkspaceGitRepo?: () => Promise<null | string>;
+    isWorkingTreeClean?: (dir: string) => Promise<boolean>;
+    language?: string;
+    loadSession?: () => Promise<DoctorSession | null>;
+    readExistingMap?: (dir: string) => IdentifierMap | null;
+    validateSourceAuth?: (from: string, apiKey: string) => Promise<boolean>;
+}
+export declare const runDoctor: (ctx: DoctorContext) => Promise<DoctorReport>;
+export declare const formatHumanReport: (report: DoctorReport) => string;

package/dist/migrate/doctor.js

@@ -0,0 +1,220 @@
+import { isWorkingTreeClean as defaultIsWorkingTreeClean } from '../util/git-ops.js';
+import { detectCollisions, readIdentifierMap } from './identifier-map.js';
+const BROWSER_LANGUAGE_ALIASES = new Set(['javascript-browser', 'js-browser', 'browser', 'browser-js']);
+const checkLegacyApiKey = async (ctx) => {
+    if (!ctx.apiKey) {
+        return {
+            message: `Skipped -- no --api-key provided for source "${ctx.from}".`,
+            name: 'legacy-api-key',
+            passed: true,
+        };
+    }
+    const validate = ctx.validateSourceAuth;
+    if (!validate) {
+        return {
+            fix: `Auth validation for source "${ctx.from}" is not yet implemented. Run without --api-key to skip this check, or upgrade the CLI.`,
+            message: `No validator available for source "${ctx.from}".`,
+            name: 'legacy-api-key',
+            passed: false,
+        };
+    }
+    try {
+        const ok = await validate(ctx.from, ctx.apiKey);
+        if (ok) {
+            return {
+                message: `${ctx.from} API key accepted.`,
+                name: 'legacy-api-key',
+                passed: true,
+            };
+        }
+        return {
+            fix: `Double-check the ${ctx.from} API key you passed to --api-key. Generate a fresh read-only token in the ${ctx.from} dashboard and retry.`,
+            message: `${ctx.from} API key was rejected.`,
+            name: 'legacy-api-key',
+            passed: false,
+        };
+    }
+    catch (error) {
+        const msg = error instanceof Error ? error.message : String(error);
+        return {
+            fix: `Check network connectivity to the ${ctx.from} API, then retry.`,
+            message: `${ctx.from} API key validation errored: ${msg}`,
+            name: 'legacy-api-key',
+            passed: false,
+        };
+    }
+};
+const checkQfgLogin = async (ctx) => {
+    const loader = ctx.loadSession;
+    if (!loader) {
+        return {
+            fix: 'Run `qfg login`.',
+            message: 'No session loader wired -- assume not logged in.',
+            name: 'qfg-login',
+            passed: false,
+        };
+    }
+    const session = await loader();
+    if (!session) {
+        return {
+            fix: 'Run `qfg login` to authenticate with Quonfig.',
+            message: 'No Quonfig session found. Run `qfg login`.',
+            name: 'qfg-login',
+            passed: false,
+        };
+    }
+    if (session.expiresAt <= Date.now()) {
+        return {
+            fix: 'Run `qfg login` again to refresh the session.',
+            message: 'Quonfig session is expired.',
+            name: 'qfg-login',
+            passed: false,
+        };
+    }
+    return {
+        message: 'Quonfig session is valid.',
+        name: 'qfg-login',
+        passed: true,
+    };
+};
+const checkWorkspaceProvisioned = async (ctx) => {
+    const getRepo = ctx.getWorkspaceGitRepo;
+    if (!getRepo) {
+        return {
+            fix: 'Pass --workspace or run `qfg workspace use <slug>` so the doctor can look up the target workspace.',
+            message: 'Cannot look up workspace -- no workspace selected.',
+            name: 'workspace-provisioned',
+            passed: false,
+        };
+    }
+    try {
+        const repo = await getRepo();
+        if (!repo) {
+            return {
+                fix: 'Create or provision the workspace in the Quonfig UI (its gitRepoFullName must be set) before running with --push.',
+                message: 'Target workspace has no gitRepoFullName set.',
+                name: 'workspace-provisioned',
+                passed: false,
+            };
+        }
+        return {
+            message: `Workspace git repo: ${repo}.`,
+            name: 'workspace-provisioned',
+            passed: true,
+        };
+    }
+    catch (error) {
+        const msg = error instanceof Error ? error.message : String(error);
+        return {
+            fix: 'Check that the workspace exists and that your session has access to it.',
+            message: `Workspace lookup failed: ${msg}`,
+            name: 'workspace-provisioned',
+            passed: false,
+        };
+    }
+};
+const checkSdkDatadirSupport = (ctx) => {
+    const language = (ctx.language ?? '').toLowerCase();
+    if (BROWSER_LANGUAGE_ALIASES.has(language)) {
+        return {
+            fix: 'Use Flow B (--push to the workspace git repo). Browser JavaScript SDKs do not read from a local datadir.',
+            message: `Browser JavaScript SDK has no datadir mode -- Flow B (--push) is required.`,
+            name: 'sdk-datadir-support',
+            passed: false,
+        };
+    }
+    return {
+        message: language ? `SDK language "${language}" supports datadir mode.` : 'No SDK language specified; assuming datadir-capable.',
+        name: 'sdk-datadir-support',
+        passed: true,
+    };
+};
+const checkGitWorkingTreeClean = async (ctx) => {
+    const fn = ctx.isWorkingTreeClean ?? defaultIsWorkingTreeClean;
+    try {
+        const clean = await fn(ctx.dir);
+        if (clean) {
+            return {
+                message: `Working tree at ${ctx.dir} is clean.`,
+                name: 'git-working-tree-clean',
+                passed: true,
+            };
+        }
+        return {
+            fix: 'Commit or stash uncommitted changes in the output directory before running the migration.',
+            message: `Working tree at ${ctx.dir} has uncommitted changes.`,
+            name: 'git-working-tree-clean',
+            passed: false,
+        };
+    }
+    catch {
+        return {
+            message: `Output directory ${ctx.dir} is not a git repo -- skipping working-tree check.`,
+            name: 'git-working-tree-clean',
+            passed: true,
+        };
+    }
+};
+const checkIdentifierCollisions = (ctx) => {
+    const reader = ctx.readExistingMap ?? readIdentifierMap;
+    const map = reader(ctx.dir);
+    if (!map) {
+        return {
+            message: 'No existing identifier map found -- nothing to collide with yet.',
+            name: 'identifier-collisions',
+            passed: true,
+        };
+    }
+    const collisions = detectCollisions(map);
+    if (collisions.length === 0) {
+        return {
+            message: `Existing identifier map has ${Object.keys(map).length} entr${Object.keys(map).length === 1 ? 'y' : 'ies'} with no case-insensitive collisions.`,
+            name: 'identifier-collisions',
+            passed: true,
+        };
+    }
+    const lines = collisions.map((c) => `    - "${c.quonfigKeyA}" vs "${c.quonfigKeyB}" (legacy keys "${c.legacyKeyA}", "${c.legacyKeyB}")`);
+    return {
+        fix: 'Rename one of the colliding Quonfig keys in the identifier map so they differ by more than just case.',
+        message: `Found ${collisions.length} case-insensitive collision${collisions.length === 1 ? '' : 's'} in existing identifier map:\n${lines.join('\n')}`,
+        name: 'identifier-collisions',
+        passed: false,
+    };
+};
+export const runDoctor = async (ctx) => {
+    const checks = [
+        await checkLegacyApiKey(ctx),
+        await checkQfgLogin(ctx),
+        await checkWorkspaceProvisioned(ctx),
+        checkSdkDatadirSupport(ctx),
+        await checkGitWorkingTreeClean(ctx),
+        checkIdentifierCollisions(ctx),
+    ];
+    return {
+        checks,
+        passed: checks.every((c) => c.passed),
+    };
+};
+export const formatHumanReport = (report) => {
+    const lines = [];
+    for (const check of report.checks) {
+        const label = check.passed ? 'pass' : 'fail';
+        lines.push(`  ${label}  ${check.name}`);
+        const messageLines = check.message.split('\n');
+        for (const line of messageLines) {
+            lines.push(`          ${line}`);
+        }
+        if (!check.passed && check.fix) {
+            lines.push(`          Fix: ${check.fix}`);
+        }
+    }
+    lines.push('');
+    if (report.passed) {
+        lines.push('All checks passed. Ready to migrate.');
+    }
+    else {
+        const failed = report.checks.filter((c) => !c.passed).length;
+        lines.push(`${failed} check${failed === 1 ? '' : 's'} failed. See "Fix:" hints above.`);
+    }
+    return lines.join('\n');
+};

package/dist/migrate/identifier-map.d.ts

@@ -0,0 +1,14 @@
+export type IdentifierMap = Record<string, string>;
+export interface CollisionPair {
+    legacyKeyA: string;
+    legacyKeyB: string;
+    quonfigKeyA: string;
+    quonfigKeyB: string;
+}
+export declare class IdentifierMapCollisionError extends Error {
+    collisions: CollisionPair[];
+    constructor(collisions: CollisionPair[]);
+}
+export declare function detectCollisions(mapping: IdentifierMap): CollisionPair[];
+export declare function writeIdentifierMap(outputDir: string, mapping: IdentifierMap): void;
+export declare function readIdentifierMap(outputDir: string): IdentifierMap | null;

package/dist/migrate/identifier-map.js

@@ -0,0 +1,55 @@
+import fs from 'node:fs';
+import path from 'node:path';
+export class IdentifierMapCollisionError extends Error {
+    collisions;
+    constructor(collisions) {
+        const lines = collisions.map((c) => `  - "${c.legacyKeyA}" → "${c.quonfigKeyA}" collides with "${c.legacyKeyB}" → "${c.quonfigKeyB}" (differ only in case)`);
+        super(`Identifier map has ${collisions.length} case-insensitive collision${collisions.length === 1 ? '' : 's'} — refusing to write .qf/identifier-map.json:\n${lines.join('\n')}`);
+        this.name = 'IdentifierMapCollisionError';
+        this.collisions = collisions;
+    }
+}
+export function detectCollisions(mapping) {
+    const legacyKeys = Object.keys(mapping).sort();
+    const collisions = [];
+    for (let i = 0; i < legacyKeys.length; i++) {
+        const legacyA = legacyKeys[i];
+        const quonfigA = mapping[legacyA];
+        for (let j = i + 1; j < legacyKeys.length; j++) {
+            const legacyB = legacyKeys[j];
+            const quonfigB = mapping[legacyB];
+            if (quonfigA !== quonfigB && quonfigA.toLowerCase() === quonfigB.toLowerCase()) {
+                collisions.push({
+                    legacyKeyA: legacyA,
+                    legacyKeyB: legacyB,
+                    quonfigKeyA: quonfigA,
+                    quonfigKeyB: quonfigB,
+                });
+            }
+        }
+    }
+    return collisions;
+}
+function identifierMapPath(outputDir) {
+    return path.join(outputDir, '.qf', 'identifier-map.json');
+}
+export function writeIdentifierMap(outputDir, mapping) {
+    const collisions = detectCollisions(mapping);
+    if (collisions.length > 0) {
+        throw new IdentifierMapCollisionError(collisions);
+    }
+    const sorted = {};
+    for (const key of Object.keys(mapping).sort()) {
+        sorted[key] = mapping[key];
+    }
+    const filePath = identifierMapPath(outputDir);
+    fs.mkdirSync(path.dirname(filePath), { recursive: true });
+    fs.writeFileSync(filePath, JSON.stringify(sorted, null, 2) + '\n', 'utf8');
+}
+export function readIdentifierMap(outputDir) {
+    const filePath = identifierMapPath(outputDir);
+    if (!fs.existsSync(filePath))
+        return null;
+    const raw = fs.readFileSync(filePath, 'utf8');
+    return JSON.parse(raw);
+}

package/dist/migrate/import-state.d.ts

@@ -0,0 +1,14 @@
+export interface ImportState {
+    lastProcessedAt?: number | string;
+    source: string;
+    sourceWorkspaceId?: string;
+}
+export declare class CrossSourceError extends Error {
+    readonly requestedSource: string;
+    readonly storedSource: string;
+    constructor(storedSource: string, requestedSource: string);
+}
+export declare function writeImportState(outputDir: string, state: ImportState): void;
+export declare function readImportState(outputDir: string): ImportState | null;
+export declare function assertSourceMatches(outputDir: string, requestedSource: string): void;
+export declare function removeQfFromGitignore(outputDir: string): void;

package/dist/migrate/import-state.js

@@ -0,0 +1,60 @@
+import fs from 'node:fs';
+import path from 'node:path';
+export class CrossSourceError extends Error {
+    requestedSource;
+    storedSource;
+    constructor(storedSource, requestedSource) {
+        super(`This directory was migrated from ${storedSource}. ` +
+            `Pass --from ${storedSource} or use --reset to reimport from scratch ` +
+            `(requested --from ${requestedSource}).`);
+        this.name = 'CrossSourceError';
+        this.storedSource = storedSource;
+        this.requestedSource = requestedSource;
+    }
+}
+function importStatePath(outputDir) {
+    return path.join(outputDir, '.qf', 'import-state.json');
+}
+export function writeImportState(outputDir, state) {
+    const filePath = importStatePath(outputDir);
+    fs.mkdirSync(path.dirname(filePath), { recursive: true });
+    const serialized = { source: state.source };
+    if (state.lastProcessedAt !== undefined)
+        serialized.lastProcessedAt = state.lastProcessedAt;
+    if (state.sourceWorkspaceId !== undefined)
+        serialized.sourceWorkspaceId = state.sourceWorkspaceId;
+    fs.writeFileSync(filePath, JSON.stringify(serialized, null, 2) + '\n', 'utf8');
+}
+export function readImportState(outputDir) {
+    const filePath = importStatePath(outputDir);
+    if (!fs.existsSync(filePath))
+        return null;
+    const raw = fs.readFileSync(filePath, 'utf8');
+    const parsed = JSON.parse(raw);
+    if (typeof parsed.source !== 'string' || parsed.source.length === 0)
+        return null;
+    return parsed;
+}
+export function assertSourceMatches(outputDir, requestedSource) {
+    const state = readImportState(outputDir);
+    if (!state)
+        return;
+    if (state.source === requestedSource)
+        return;
+    throw new CrossSourceError(state.source, requestedSource);
+}
+export function removeQfFromGitignore(outputDir) {
+    const gitignorePath = path.join(outputDir, '.gitignore');
+    if (!fs.existsSync(gitignorePath))
+        return;
+    const original = fs.readFileSync(gitignorePath, 'utf8');
+    const trailingNewline = original.endsWith('\n');
+    const filtered = original
+        .split('\n')
+        .filter((line) => line.trim() !== '.qf' && line.trim() !== '.qf/')
+        .join('\n');
+    const next = trailingNewline && !filtered.endsWith('\n') && filtered.length > 0 ? filtered + '\n' : filtered;
+    if (next === original)
+        return;
+    fs.writeFileSync(gitignorePath, next, 'utf8');
+}