@quonfig/cli 0.0.11 → 0.0.13

package/dist/migrate/doctor.js

@@ -0,0 +1,222 @@
+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');
+}

package/dist/migrate/local-write.d.ts

@@ -0,0 +1,26 @@
+import { type ImportState } from './import-state.js';
+import { type MigrationReportData } from './migration-report.js';
+import { type PushIdentity } from './push-strategy.js';
+import type { LegacyChange, MigrationSource } from './source.js';
+export interface ApplyLocalMigrationOptions {
+    /** Commit author. Defaults to the migrator identity. */
+    author?: PushIdentity;
+    /** Initial branch name when initializing a fresh repo. Defaults to `main`. */
+    branch?: string;
+    changes: LegacyChange[];
+    commitMessage: string;
+    /** Environments discovered from the source (slugified). Written to `quonfig.json` if missing. */
+    environments: string[];
+    importState: ImportState;
+    localDir: string;
+    reportData: MigrationReportData;
+    source: MigrationSource;
+}
+export interface ApplyLocalMigrationResult {
+    /** `'initialized'` if we had to `git init` the target, `'reused'` if it was already a repo. */
+    action: 'initialized' | 'reused';
+    commitSha: string | null;
+    /** `false` if translate produced no net changes — nothing was committed. */
+    committed: boolean;
+}
+export declare const applyLocalMigration: (opts: ApplyLocalMigrationOptions) => Promise<ApplyLocalMigrationResult>;

package/dist/migrate/local-write.js

@@ -0,0 +1,85 @@
+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';
+import { removeQfFromGitignore, writeImportState } from './import-state.js';
+import { writeMigrationReport } from './migration-report.js';
+import { MIGRATOR_IDENTITY } from './push-strategy.js';
+const execFile = util.promisify(execFileCb);
+const isGitRepo = async (dir) => {
+    try {
+        await execFile('git', ['-C', dir, 'rev-parse', '--git-dir']);
+        return true;
+    }
+    catch {
+        return false;
+    }
+};
+const hasStagedChanges = async (dir) => {
+    const { stdout } = await execFile('git', ['-C', dir, 'status', '--porcelain']);
+    return stdout.trim().length > 0;
+};
+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);
+});
+const ensureQuonfigJson = (dir, environments) => {
+    const filePath = path.join(dir, 'quonfig.json');
+    if (fs.existsSync(filePath))
+        return;
+    const sorted = [...new Set(environments)].sort();
+    fs.writeFileSync(filePath, JSON.stringify({ environments: sorted }, null, 2) + '\n', 'utf8');
+};
+const ensureLocalRepo = async (localDir, branch) => {
+    fs.mkdirSync(localDir, { recursive: true });
+    if (await isGitRepo(localDir))
+        return 'reused';
+    await execFile('git', ['init', `--initial-branch=${branch}`, localDir]);
+    return 'initialized';
+};
+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 applyLocalMigration = async (opts) => {
+    const branch = opts.branch ?? 'main';
+    const author = opts.author ?? MIGRATOR_IDENTITY;
+    const action = await ensureLocalRepo(opts.localDir, branch);
+    await execFile('git', ['-C', opts.localDir, 'config', 'user.name', author.name]);
+    await execFile('git', ['-C', opts.localDir, 'config', 'user.email', author.email]);
+    ensureQuonfigJson(opts.localDir, opts.environments);
+    writeQuonfigFiles(opts.localDir, opts.changes, opts.source);
+    removeQfFromGitignore(opts.localDir);
+    writeImportState(opts.localDir, opts.importState);
+    writeMigrationReport(opts.localDir, opts.reportData);
+    await execFile('git', ['-C', 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_EMAIL: author.email,
+        GIT_AUTHOR_NAME: author.name,
+        GIT_COMMITTER_EMAIL: author.email,
+        GIT_COMMITTER_NAME: author.name,
+    });
+    const { stdout: sha } = await execFile('git', ['-C', opts.localDir, 'rev-parse', 'HEAD']);
+    return { action, commitSha: sha.trim(), committed: true };
+};

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,85 @@
+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})`, `_Reflects only the changes produced by this run. Re-running overwrites this file._`, renderCounts(data.counts), renderCleanMappings(data.cleanMappings), renderLossyMappings(data.lossyMappings), renderUnsupported(data.unsupportedFeatures), renderEnvironmentMap(data.environmentMap), renderIdentifierMap(data.identifierMap), 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>;