@quonfig/cli 0.0.10 → 0.0.12

package/dist/commands/migrate/status.js

@@ -0,0 +1,112 @@
+import { Flags } from '@oclif/core';
+import fs from 'node:fs';
+import path from 'node:path';
+import { BaseCommand } from '../../index.js';
+import { readImportState } from '../../migrate/import-state.js';
+const FLAGS_DIR = 'feature-flags';
+const SEGMENTS_DIR = 'segments';
+const WORKSPACE_FILE = 'quonfig.json';
+const NO_STATE_MESSAGE = 'No migration state found. Run qfg migrate --from <source> first.';
+function countJsonFiles(dir) {
+    if (!fs.existsSync(dir) || !fs.statSync(dir).isDirectory())
+        return 0;
+    return fs
+        .readdirSync(dir)
+        .filter((name) => name.endsWith('.json') && !name.startsWith('.'))
+        .length;
+}
+function countEnvironments(dir) {
+    const file = path.join(dir, WORKSPACE_FILE);
+    if (!fs.existsSync(file))
+        return 0;
+    try {
+        const parsed = JSON.parse(fs.readFileSync(file, 'utf8'));
+        return Array.isArray(parsed.environments) ? parsed.environments.length : 0;
+    }
+    catch {
+        return 0;
+    }
+}
+function workspaceCounts(dir) {
+    return {
+        environments: countEnvironments(dir),
+        flags: countJsonFiles(path.join(dir, FLAGS_DIR)),
+        segments: countJsonFiles(path.join(dir, SEGMENTS_DIR)),
+    };
+}
+function toIsoTimestamp(value) {
+    if (value == null)
+        return null;
+    const date = typeof value === 'number' ? new Date(value) : new Date(value);
+    if (Number.isNaN(date.getTime()))
+        return null;
+    return date.toISOString();
+}
+function nextHint(source, counts) {
+    if (counts.flags === 0 && counts.segments === 0) {
+        return `Run \`qfg migrate --from ${source}\` to import flags and segments.`;
+    }
+    return `Run \`qfg migrate my-code --from ${source}\` to update your SDK call sites, or re-run \`qfg migrate --from ${source}\` to pick up changes.`;
+}
+function formatHuman(payload) {
+    const lines = [];
+    lines.push(`Source:            ${payload.source}`);
+    lines.push(`Source workspace:  ${payload.sourceWorkspaceId ?? '(not recorded)'}`);
+    lines.push(`Last processed at: ${payload.lastProcessedAtIso ?? '(not recorded)'}`);
+    lines.push(`Workspace dir:     ${payload.dir}`);
+    lines.push('');
+    lines.push('Counts:');
+    lines.push(`  Flags:         ${payload.counts.flags}`);
+    lines.push(`  Segments:      ${payload.counts.segments}`);
+    lines.push(`  Environments:  ${payload.counts.environments}`);
+    lines.push('');
+    lines.push(`Next: ${payload.next}`);
+    return lines.join('\n');
+}
+export default class MigrateStatus extends BaseCommand {
+    static description = 'Show the status of a workspace migrated with `qfg migrate`. Reads .qf/import-state.json and summarizes source, counts, and next steps.';
+    static examples = [
+        '<%= config.bin %> <%= command.id %>',
+        '<%= config.bin %> <%= command.id %> --dir ./my-workspace',
+        '<%= config.bin %> <%= command.id %> --json',
+    ];
+    static flags = {
+        dir: Flags.string({
+            default: '.',
+            description: 'Workspace directory to inspect',
+        }),
+    };
+    async run() {
+        const { flags } = await this.parse(MigrateStatus);
+        const dir = path.resolve(flags.dir);
+        const state = readImportState(dir);
+        if (!state) {
+            const payload = {
+                dir,
+                found: false,
+                message: NO_STATE_MESSAGE,
+            };
+            if (this.jsonEnabled())
+                return payload;
+            this.log(NO_STATE_MESSAGE);
+            return payload;
+        }
+        const counts = workspaceCounts(dir);
+        const lastProcessedAtIso = toIsoTimestamp(state.lastProcessedAt);
+        const next = nextHint(state.source, counts);
+        const payload = {
+            counts,
+            dir,
+            found: true,
+            lastProcessedAt: state.lastProcessedAt ?? null,
+            lastProcessedAtIso,
+            next,
+            source: state.source,
+            sourceWorkspaceId: state.sourceWorkspaceId ?? null,
+        };
+        if (this.jsonEnabled())
+            return payload;
+        this.log(formatHuman(payload));
+        return payload;
+    }
+}

package/dist/commands/migrate.d.ts

@@ -0,0 +1,20 @@
+import type { JsonObj } from '../result.js';
+import { BaseCommand } from '../index.js';
+export default class Migrate extends BaseCommand {
+    static description: string;
+    static examples: string[];
+    static flags: {
+        'api-key': import("@oclif/core/lib/interfaces/parser.js").OptionFlag<string | undefined, import("@oclif/core/lib/interfaces/parser.js").CustomOptions>;
+        dir: import("@oclif/core/lib/interfaces/parser.js").OptionFlag<string | undefined, import("@oclif/core/lib/interfaces/parser.js").CustomOptions>;
+        'dry-run': import("@oclif/core/lib/interfaces/parser.js").BooleanFlag<boolean>;
+        from: import("@oclif/core/lib/interfaces/parser.js").OptionFlag<string, import("@oclif/core/lib/interfaces/parser.js").CustomOptions>;
+        push: import("@oclif/core/lib/interfaces/parser.js").BooleanFlag<boolean>;
+        recent: import("@oclif/core/lib/interfaces/parser.js").OptionFlag<number | undefined, import("@oclif/core/lib/interfaces/parser.js").CustomOptions>;
+        reset: import("@oclif/core/lib/interfaces/parser.js").BooleanFlag<boolean>;
+        since: import("@oclif/core/lib/interfaces/parser.js").OptionFlag<string | undefined, import("@oclif/core/lib/interfaces/parser.js").CustomOptions>;
+        staging: import("@oclif/core/lib/interfaces/parser.js").BooleanFlag<boolean>;
+        workspace: import("@oclif/core/lib/interfaces/parser.js").OptionFlag<string | undefined, import("@oclif/core/lib/interfaces/parser.js").CustomOptions>;
+    };
+    run(): Promise<JsonObj | void>;
+    private resolvePushWorkspace;
+}

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;