@quonfig/cli 0.0.44 → 0.0.46

package/dist/commands/push.js

@@ -1,13 +1,13 @@
 import * as fs from 'node:fs';
-import * as path from 'node:path';
 import { Flags } from '@oclif/core';
 import { BaseCommand } from '../index.js';
 import { mintGiteaToken } from '../util/gitea-api.js';
-import { dirtyTrackedFiles, getOriginMainSha, getRemoteUrl, gitFetch, gitSetRemote, isGitRepo, isLocalBehindOrDivergedFromRemote, runGit, } from '../util/git-ops.js';
+import { dirtyTrackedFiles, getAllRemoteUrls, getOriginMainSha, getRemoteUrl, gitFetch, gitSetRemote, isGitRepo, isLocalBehindOrDivergedFromRemote, runGit, } from '../util/git-ops.js';
 import { PushFatalError, runPush, } from '../push/run-push.js';
 import { computeBarePathDiff } from '../push/bare-path-diff.js';
 import { computeClonePathDiff } from '../push/clone-path-diff.js';
-import { callConfigsPush } from '../push/config-push-client.js';
+import { callConfigsGitPush, callConfigsPush } from '../push/config-push-client.js';
+import { resolveWorkspaceDir } from '../util/resolve-workspace-dir.js';
 import { resolveWorkspaceUuid } from '../util/resolve-workspace.js';
 export default class Push extends BaseCommand {
     static description = `Push local config changes up to your workspace on Quonfig cloud.
@@ -18,7 +18,7 @@ Enforces three guards before touching the remote:
   3. A diff summary is shown; destructive changes (10+ deletes, >=25% of
      files, or an unpinned dir) require typing the workspace slug to confirm.
 
-  qfg push                                 # uses QUONFIG_DIR + profile workspace
+  qfg push                                 # resolves dir from cwd, QUONFIG_DIR, or --dir
   qfg push --dir ./our-config
   qfg push --dir ./our-config --workspace acme-prod
   qfg push --dir ./our-config --yes        # skip normal Y/N (never skips typed-slug)
@@ -30,7 +30,7 @@ Enforces three guards before touching the remote:
     ];
     static flags = {
         dir: Flags.string({
-            description: 'Local directory to push (defaults to QUONFIG_DIR env var)',
+            description: 'Local directory to push (defaults to cwd / nearest ancestor with quonfig.json / QUONFIG_DIR env var)',
         }),
         workspace: Flags.string({
             description: 'Workspace slug or UUID (defaults to active profile)',
@@ -54,11 +54,15 @@ Enforces three guards before touching the remote:
     };
     async run() {
         const { flags } = await this.parse(Push);
-        const dir = flags.dir || process.env.QUONFIG_DIR;
-        if (!dir) {
-            return this.err('No directory specified. Use --dir <path> or set QUONFIG_DIR.');
+        const resolved = resolveWorkspaceDir({
+            flagDir: flags.dir,
+            envDir: process.env.QUONFIG_DIR,
+            cwd: process.cwd(),
+        });
+        if (resolved.kind === 'error') {
+            return this.err(resolved.message);
         }
-        const resolvedDir = path.resolve(dir);
+        const resolvedDir = resolved.dir;
         // Resolve requested target. --workspace > QUONFIG_WORKSPACE > active OAuth
         // profile. Supports API-key mode for headless runs so `qfg push` behaves
         // the same way `qfg create` does (both resolve via resolve-workspace.ts).
@@ -166,6 +170,9 @@ export function buildRealDeps(cmd, orgSlug) {
             const url = await getRemoteUrl(dir);
             return url ?? undefined;
         },
+        async getAllRemoteUrls(dir) {
+            return getAllRemoteUrls(dir);
+        },
         async setRemoteOrigin(dir, url) {
             await gitSetRemote(dir, url);
         },
@@ -238,6 +245,75 @@ export function buildRealDeps(cmd, orgSlug) {
                 return;
             return getOriginMainSha(dir);
         },
+        // Pack-push (qfg-7429.4) — clone-path now ships actual git objects
+        // via `configs.gitPush`. All five hooks below are no-ops on bare
+        // path (the dispatch chooses configs.push instead) and only fire
+        // when the local dir is a clone whose origin matches the backend.
+        async getCurrentBranch(dir) {
+            const { getCurrentBranch } = await import('../push/git-pack.js');
+            return getCurrentBranch(dir);
+        },
+        async getHeadSha(dir) {
+            const { stdout } = await runGit(['-C', dir, 'rev-parse', 'HEAD']);
+            return stdout.trim();
+        },
+        async getRemoteBranchSha(dir, branchName) {
+            try {
+                const { stdout } = await runGit(['-C', dir, 'rev-parse', `origin/${branchName}`]);
+                const sha = stdout.trim();
+                return sha.length > 0 ? sha : undefined;
+            }
+            catch {
+                // No remote-tracking ref yet — brand-new branch. The pack-push
+                // dispatch interprets `undefined` as zero-OID on the wire.
+                return undefined;
+            }
+        },
+        async buildPack(dir, expectedSha, newSha) {
+            const { buildPack } = await import('../push/git-pack.js');
+            return buildPack(dir, expectedSha, newSha);
+        },
+        async countCommitsBetween(dir, expectedSha, newSha) {
+            if (expectedSha === newSha)
+                return 0;
+            const ZERO = '0000000000000000000000000000000000000000';
+            const range = expectedSha === ZERO ? newSha : `${expectedSha}..${newSha}`;
+            try {
+                const { stdout } = await runGit(['-C', dir, 'rev-list', '--count', range]);
+                return Number.parseInt(stdout.trim(), 10) || 0;
+            }
+            catch {
+                return 0;
+            }
+        },
+        async getCommitOneline(dir, sha) {
+            // qfg-7429.5: surface the offending commit's identity alongside
+            // the server's §6 recovery hint. Returns '' if the commit isn't
+            // present locally (best-effort — the recovery message is the
+            // load-bearing piece).
+            try {
+                const { stdout } = await runGit(['-C', dir, 'log', '-1', '--pretty=oneline', sha]);
+                return stdout.trim();
+            }
+            catch {
+                return '';
+            }
+        },
+        async getTreeShaForRef(dir, ref) {
+            // qfg-7429.6: pack-push conflict handler uses this to detect the
+            // legacy orphan-commit state — local commit SHA != origin's, but
+            // the underlying tree content matches. Return undefined on any
+            // git failure so the caller falls back to the "real conflict"
+            // message rather than aborting on an opaque rev-parse error.
+            try {
+                const { stdout } = await runGit(['-C', dir, 'rev-parse', `${ref}^{tree}`]);
+                const sha = stdout.trim();
+                return sha.length > 0 ? sha : undefined;
+            }
+            catch {
+                return undefined;
+            }
+        },
     };
     const deps = {
         async mintWriteToken(requestedTarget) {
@@ -257,6 +333,7 @@ export function buildRealDeps(cmd, orgSlug) {
         },
         gitOps,
         pushToServer: (input) => callConfigsPush(input, orgSlug),
+        pushPackToServer: (input) => callConfigsGitPush(input, orgSlug),
         log,
         errLog,
     };

package/dist/init/schema.d.ts

@@ -2,7 +2,7 @@
  * JSON Schema for Quonfig StoredConfig files.
  *
  * This is the machine-readable schema for files in configs/, feature-flags/,
- * segments/, and log-levels/. Served at api.quonfig.com/schemas/stored-config.json
+ * segments/, and log-levels/. Served at api.quonfig.com/schemas/v1/stored-config.json
  * and printed by `qfg config-schema --json-schema`.
  *
  * Derived from the Zod schemas in verify/validate.ts — keep in sync.

package/dist/init/schema.js

@@ -2,7 +2,7 @@
  * JSON Schema for Quonfig StoredConfig files.
  *
  * This is the machine-readable schema for files in configs/, feature-flags/,
- * segments/, and log-levels/. Served at api.quonfig.com/schemas/stored-config.json
+ * segments/, and log-levels/. Served at api.quonfig.com/schemas/v1/stored-config.json
  * and printed by `qfg config-schema --json-schema`.
  *
  * Derived from the Zod schemas in verify/validate.ts — keep in sync.

package/dist/init/templates.js

@@ -40,7 +40,7 @@ qfg list
 
 ## Schema
 
-Config files reference the hosted JSON Schema at <https://api.quonfig.com/schemas/stored-config.json> via their \`$schema\` field. Editors that support JSON Schema will provide autocomplete and validation automatically.
+Config files reference the hosted JSON Schema at <https://api.quonfig.com/schemas/v1/stored-config.json> via their \`$schema\` field. Editors that support JSON Schema will provide autocomplete and validation automatically.
 
 ## Validation
 
@@ -59,12 +59,12 @@ This is a Quonfig workspace repository. Configuration is stored as JSON files in
 
 ## JSON Schema
 
-The canonical schema for config files is hosted at <https://api.quonfig.com/schemas/stored-config.json>. Use it as the source of truth for field names, types, enums, and constraints.
+The canonical schema for config files is hosted at <https://api.quonfig.com/schemas/v1/stored-config.json>. Use it as the source of truth for field names, types, enums, and constraints.
 
 Config files can reference it for editor support:
 
 \`\`\`json
-{ "$schema": "https://api.quonfig.com/schemas/stored-config.json", "key": "my.config", ... }
+{ "$schema": "https://api.quonfig.com/schemas/v1/stored-config.json", "key": "my.config", ... }
 \`\`\`
 
 ## Directory Structure
@@ -84,7 +84,7 @@ Files must live in the directory matching their \`type\`. The filename (without
 
 \`\`\`json
 {
-  "$schema": "https://api.quonfig.com/schemas/stored-config.json",
+  "$schema": "https://api.quonfig.com/schemas/v1/stored-config.json",
   "key": "my-app.timeout",
   "type": "config",
   "valueType": "int",
@@ -118,7 +118,7 @@ The \`default\` block (and each environment override) contains a \`rules\` array
 | Segment | \`IN_SEG\`, \`NOT_IN_SEG\` | \`valueToMatch\` (segment key) |
 | Other | \`IN_INT_RANGE\`, \`LOOKUP_KEY_IN\`, \`LOOKUP_KEY_NOT_IN\` | \`valueToMatch\` |
 
-See <https://api.quonfig.com/schemas/stored-config.json> for the full operator enum and value type definitions.
+See <https://api.quonfig.com/schemas/v1/stored-config.json> for the full operator enum and value type definitions.
 
 ## Environments
 

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

@@ -1,6 +1,6 @@
 import { type ImportState } from './import-state.js';
 import { type MigrationReportData } from './migration-report.js';
-import { type PushIdentity } from '../util/clone-and-stack-push.js';
+import { type CommitSpec, type PushIdentity } from '../util/clone-and-stack-push.js';
 import type { CoercedSentinelSummary, DroppedOverrideSummary, DuplicateResolution, DuplicateResolutionSummary, LegacyChange, MigrationSource, SkippedConfigSummary } from './source.js';
 export interface ApplyLocalMigrationOptions {
     /** Commit author. Defaults to the migrator identity. */
@@ -10,6 +10,12 @@ export interface ApplyLocalMigrationOptions {
     changes: LegacyChange[];
     /** Environments discovered from the source (slugified). Written to `quonfig.json` if missing. */
     environments: string[];
+    /**
+     * qfg-wbkj: when true, produce one git commit per change (audit-log mode) +
+     * one final state-file commit on top. Requires `source.getCommitMeta` to be
+     * defined. See pushMigrationToCloud's matching option.
+     */
+    fullHistory?: boolean;
     importState: ImportState;
     localDir: string;
     /**
@@ -48,4 +54,58 @@ interface WriteQuonfigFilesResult {
 export declare const buildMigrationCounts: (livePaths: string[], environmentsMapped: number, itemsSkipped: number) => import("./migration-report.js").MigrationReportCounts;
 export declare const buildMigrationCommitMessage: (source: string, counts: import("./migration-report.js").MigrationReportCounts) => string;
 export declare const applyLocalMigration: (opts: ApplyLocalMigrationOptions) => Promise<ApplyLocalMigrationResult>;
+/**
+ * qfg-wbkj: accumulator for source-level summaries that the final state-file
+ * commit collects from the source after all per-change commits have run.
+ * Used by both push-to-cloud and local-write to surface back to callers.
+ */
+export interface AuditAccumulator {
+    coercedSentinels: CoercedSentinelSummary | null;
+    droppedOverrides: DroppedOverrideSummary | null;
+    duplicateResolutions: DuplicateResolutionSummary | null;
+    skippedConfigs: SkippedConfigSummary | null;
+}
+/**
+ * qfg-wbkj: build one CommitSpec per change, each carrying the original
+ * source-side author/date/message when `getCommitMeta` returns metadata. Used
+ * by `--full-summary` from both the local-write and push-to-cloud paths.
+ */
+export declare const buildAuditPerChangeCommits: (changes: LegacyChange[], source: MigrationSource) => CommitSpec[];
+export interface BuildAuditFinalCommitOptions {
+    changes: LegacyChange[];
+    environments: string[];
+    importState: ImportState;
+    /** Receives the accumulated summaries once the commit's apply() has run. */
+    onAccumulatorUpdate?: (acc: AuditAccumulator) => void;
+    /**
+     * Optional hook to run AFTER writeImportState + writeMigrationReport but before
+     * the commit lands. Push-to-cloud uses this to run validateWorkspace (and to
+     * merge source-side environments into the existing quonfig.json). Throwing here
+     * aborts the commit cleanly.
+     */
+    postWrite?: (dir: string) => Promise<void> | void;
+    /**
+     * Optional hook to run BEFORE bookkeeping (state file + report). Push-to-cloud
+     * uses this to merge source-side environments into the cloned quonfig.json.
+     */
+    preWrite?: (dir: string) => Promise<void> | void;
+    reportData: MigrationReportData;
+    source: MigrationSource;
+}
+/**
+ * qfg-wbkj: build the final state-file commit for audit-log mode. Writes
+ * `.qf/import-state.json` + `MIGRATION_REPORT.md` with cumulative counts read
+ * from disk, and surfaces the source's accumulated dropped/skipped/coerced
+ * summaries via `onAccumulatorUpdate`. The `preWrite` / `postWrite` hooks let
+ * push-to-cloud merge environments and run server-side-equivalent validation
+ * without local-write needing to know about either.
+ */
+export declare const buildAuditFinalCommit: (opts: BuildAuditFinalCommitOptions) => CommitSpec;
+/**
+ * Walk the type-dir top-levels we care about, returning all `<type-dir>/*.json`
+ * paths on disk. Used to recompute cumulative counts in audit-log mode where
+ * `writeQuonfigFiles` runs per-change and its in-memory `livePaths` reflects
+ * only the last slice.
+ */
+export declare const collectLivePathsOnDisk: (dir: string) => string[];
 export {};

package/dist/migrate/local-write.js

@@ -3,7 +3,7 @@ import * as path from 'node:path';
 import { removeQfFromGitignore, writeImportState } from './import-state.js';
 import { writeMigrationReport } from './migration-report.js';
 import { detectDuplicateKeys } from './sources/launch/translate.js';
-import { MIGRATOR_IDENTITY } from '../util/clone-and-stack-push.js';
+import { MIGRATOR_IDENTITY, stackCommits } from '../util/clone-and-stack-push.js';
 import { runGit, spawnGit } from '../util/git-ops.js';
 const isGitRepo = async (dir) => {
     try {
@@ -170,9 +170,16 @@ export const buildMigrationCommitMessage = (source, counts) => {
 export const applyLocalMigration = async (opts) => {
     const branch = opts.branch ?? 'main';
     const author = opts.author ?? MIGRATOR_IDENTITY;
+    if (opts.fullHistory && !opts.source.getCommitMeta) {
+        throw new Error(`--full-summary requires the source to provide per-change author + date + summary, but \`${opts.source.name}\` does not. ` +
+            `Drop --full-summary or use a source (e.g. launch) that supports it.`);
+    }
     const action = await ensureLocalRepo(opts.localDir, branch);
     await runGit(['-C', opts.localDir, 'config', 'user.name', author.name]);
     await runGit(['-C', opts.localDir, 'config', 'user.email', author.email]);
+    if (opts.fullHistory) {
+        return runFullHistoryLocal(opts, action);
+    }
     ensureQuonfigJson(opts.localDir, opts.environments);
     const { livePaths, resolutions: resolutionEntries } = writeQuonfigFiles(opts.localDir, opts.changes, opts.source);
     removeQfFromGitignore(opts.localDir);
@@ -225,3 +232,129 @@ export const applyLocalMigration = async (opts) => {
         skippedConfigs,
     };
 };
+const runFullHistoryLocal = async (opts, action) => {
+    ensureQuonfigJson(opts.localDir, opts.environments);
+    const acc = {
+        coercedSentinels: null,
+        droppedOverrides: null,
+        duplicateResolutions: null,
+        skippedConfigs: null,
+    };
+    const commits = [
+        ...buildAuditPerChangeCommits(opts.changes, opts.source),
+        buildAuditFinalCommit({
+            changes: opts.changes,
+            environments: opts.environments,
+            importState: opts.importState,
+            onAccumulatorUpdate: (a) => Object.assign(acc, a),
+            reportData: opts.reportData,
+            source: opts.source,
+        }),
+    ];
+    const { commitShas } = await stackCommits(opts.localDir, commits);
+    return {
+        action,
+        coercedSentinels: acc.coercedSentinels,
+        commitSha: commitShas.at(-1) ?? null,
+        committed: commitShas.length > 0,
+        droppedOverrides: acc.droppedOverrides,
+        duplicateResolutions: acc.duplicateResolutions,
+        skippedConfigs: acc.skippedConfigs,
+    };
+};
+/**
+ * qfg-wbkj: build one CommitSpec per change, each carrying the original
+ * source-side author/date/message when `getCommitMeta` returns metadata. Used
+ * by `--full-summary` from both the local-write and push-to-cloud paths.
+ */
+export const buildAuditPerChangeCommits = (changes, source) => changes.map((change, index) => {
+    const meta = source.getCommitMeta?.(change) ?? null;
+    const apply = async (dir) => {
+        writeQuonfigFiles(dir, [change], source);
+    };
+    if (!meta) {
+        return {
+            apply,
+            author: MIGRATOR_IDENTITY,
+            message: `migrator: imported change ${index + 1} of ${changes.length} from ${source.name}`,
+        };
+    }
+    return { apply, author: meta.author, authorDate: meta.date, message: meta.message };
+});
+/**
+ * qfg-wbkj: build the final state-file commit for audit-log mode. Writes
+ * `.qf/import-state.json` + `MIGRATION_REPORT.md` with cumulative counts read
+ * from disk, and surfaces the source's accumulated dropped/skipped/coerced
+ * summaries via `onAccumulatorUpdate`. The `preWrite` / `postWrite` hooks let
+ * push-to-cloud merge environments and run server-side-equivalent validation
+ * without local-write needing to know about either.
+ */
+export const buildAuditFinalCommit = (opts) => ({
+    async apply(dir) {
+        if (opts.preWrite)
+            await opts.preWrite(dir);
+        // qfg-wbkj follow-up: in audit-log mode, writeQuonfigFiles runs per-change
+        // and cannot detect cross-change duplicate keys (e.g. the same key existing
+        // as both a config and a feature_flag in source history). Resolve here over
+        // the cumulative on-disk tree — same kept/deleted semantics as the
+        // collapsed path — so validateWorkspace doesn't reject the push. The
+        // deletion lands in this final state-file commit under migrator identity,
+        // not in any audit commit.
+        const initialPaths = collectLivePathsOnDisk(dir);
+        const resolutionEntries = detectDuplicateKeys(initialPaths.map((p) => ({ path: p })));
+        for (const resolution of resolutionEntries) {
+            for (const toDelete of resolution.deleted) {
+                try {
+                    fs.unlinkSync(path.join(dir, toDelete));
+                }
+                catch (error) {
+                    if (error.code !== 'ENOENT')
+                        throw error;
+                }
+            }
+        }
+        const livePaths = collectLivePathsOnDisk(dir);
+        const droppedOverrides = opts.source.getDroppedOverrides?.() ?? null;
+        const skippedConfigs = opts.source.getSkippedConfigs?.() ?? null;
+        const coercedSentinels = opts.source.getCoercedSentinels?.() ?? null;
+        const duplicateResolutions = resolutionEntries.length > 0 ? { entries: resolutionEntries, total: resolutionEntries.length } : null;
+        removeQfFromGitignore(dir);
+        writeImportState(dir, opts.importState);
+        const skippedTotal = (skippedConfigs?.total ?? 0) + resolutionEntries.reduce((sum, r) => sum + r.deleted.length, 0);
+        const counts = buildMigrationCounts(livePaths, opts.environments.length, skippedTotal);
+        const reportData = {
+            ...opts.reportData,
+            counts,
+            ...(coercedSentinels ? { coercedSentinels } : {}),
+            ...(droppedOverrides ? { droppedOverrides } : {}),
+            ...(duplicateResolutions ? { duplicateResolutions } : {}),
+            ...(skippedConfigs ? { skippedConfigs } : {}),
+        };
+        writeMigrationReport(dir, reportData);
+        opts.onAccumulatorUpdate?.({ coercedSentinels, droppedOverrides, duplicateResolutions, skippedConfigs });
+        if (opts.postWrite)
+            await opts.postWrite(dir);
+    },
+    author: MIGRATOR_IDENTITY,
+    message: `migrator: imported ${opts.changes.length} change(s) from ${opts.source.name} (audit log)`,
+});
+/**
+ * Walk the type-dir top-levels we care about, returning all `<type-dir>/*.json`
+ * paths on disk. Used to recompute cumulative counts in audit-log mode where
+ * `writeQuonfigFiles` runs per-change and its in-memory `livePaths` reflects
+ * only the last slice.
+ */
+export const collectLivePathsOnDisk = (dir) => {
+    const prefixes = ['feature-flags', 'configs', 'segments', 'schemas', 'log-levels'];
+    const out = [];
+    for (const prefix of prefixes) {
+        const typeDir = path.join(dir, prefix);
+        if (!fs.existsSync(typeDir))
+            continue;
+        for (const entry of fs.readdirSync(typeDir)) {
+            if (entry.endsWith('.json'))
+                out.push(`${prefix}/${entry}`);
+        }
+    }
+    return out;
+};

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

@@ -6,8 +6,8 @@ import type { CoercedSentinelSummary, DroppedOverrideSummary, DuplicateResolutio
 /**
  * Thrown when the migrator's freshly-written workspace fails the same checks
  * that the Gitea pre-receive `qfg-verify` hook will run server-side. We raise
- * this client-side after `applyDelta` writes files but before commit + push,
- * so the customer sees the failure locally rather than after a full push
+ * this client-side after the commit's `apply` writes files but before commit +
+ * push, so the customer sees the failure locally rather than after a full push
  * round-trip is rejected (qfg-52qg).
  */
 export declare class MigratorVerifyError extends Error {
@@ -23,6 +23,15 @@ export interface PushMigrationToCloudOptions {
      * cleanly. Existing target-only envs are preserved.
      */
     environments?: string[];
+    /**
+     * qfg-wbkj: when true, produce one git commit per change (audit-log mode) —
+     * each commit authored as the original Launch user with their `changedAt` as
+     * GIT_AUTHOR_DATE and `summary` as the message. One final state-file commit
+     * (migrator identity, now) lands on top carrying .qf/import-state.json +
+     * MIGRATION_REPORT.md so the audit-log commits aren't polluted by bookkeeping
+     * churn. Requires that `source.getCommitMeta` be defined.
+     */
+    fullHistory?: boolean;
     importState: ImportState;
     localDir: string;
     remoteUrl: string;

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

@@ -1,15 +1,15 @@
 import * as fs from 'node:fs';
 import * as path from 'node:path';
 import { removeQfFromGitignore, writeImportState } from './import-state.js';
-import { buildMigrationCommitMessage, buildMigrationCounts, writeQuonfigFiles } from './local-write.js';
+import { buildAuditFinalCommit, buildAuditPerChangeCommits, buildMigrationCommitMessage, buildMigrationCounts, writeQuonfigFiles, } from './local-write.js';
 import { writeMigrationReport } from './migration-report.js';
 import { cloneAndStackPush, } from '../util/clone-and-stack-push.js';
 import { formatResult, validateWorkspace } from '../verify/validate.js';
 /**
  * Thrown when the migrator's freshly-written workspace fails the same checks
  * that the Gitea pre-receive `qfg-verify` hook will run server-side. We raise
- * this client-side after `applyDelta` writes files but before commit + push,
- * so the customer sees the failure locally rather than after a full push
+ * this client-side after the commit's `apply` writes files but before commit +
+ * push, so the customer sees the failure locally rather than after a full push
  * round-trip is rejected (qfg-52qg).
  */
 export class MigratorVerifyError extends Error {
@@ -42,52 +42,88 @@ const mergeEnvironmentsIntoQuonfigJson = (dir, sourceEnvs) => {
     }
     fs.writeFileSync(quonfigPath, JSON.stringify({ ...existing, environments: merged }, null, 2) + '\n', 'utf8');
 };
+const verifyOnDisk = (dir) => {
+    // qfg-52qg: client-side verify against the cumulative tree before commit
+    // lands. The Gitea pre-receive hook runs against the final HEAD; failing
+    // here matches what the server would reject and avoids a wasted push.
+    const verifyResult = validateWorkspace(dir);
+    if (!verifyResult.valid)
+        throw new MigratorVerifyError(verifyResult);
+};
 export const pushMigrationToCloud = async (opts) => {
-    let coercedSentinels = null;
-    let droppedOverrides = null;
-    let duplicateResolutions = null;
-    let skippedConfigs = null;
+    if (opts.fullHistory && !opts.source.getCommitMeta) {
+        throw new Error(`--full-summary requires the source to provide per-change author + date + summary, but \`${opts.source.name}\` does not. ` +
+            `Drop --full-summary or use a source (e.g. launch) that supports it.`);
+    }
+    const acc = {
+        coercedSentinels: null,
+        droppedOverrides: null,
+        duplicateResolutions: null,
+        skippedConfigs: null,
+    };
     let computedCommitMessage = `migrator: imported 0 objects from ${opts.source.name}`;
+    const mergeEnvsIfPresent = (dir) => {
+        if (opts.environments && opts.environments.length > 0) {
+            mergeEnvironmentsIntoQuonfigJson(dir, opts.environments);
+        }
+    };
+    const commits = opts.fullHistory
+        ? [
+            ...buildAuditPerChangeCommits(opts.changes, opts.source),
+            buildAuditFinalCommit({
+                changes: opts.changes,
+                environments: opts.environments ?? [],
+                importState: opts.importState,
+                onAccumulatorUpdate: (a) => Object.assign(acc, a),
+                postWrite: verifyOnDisk,
+                preWrite: mergeEnvsIfPresent,
+                reportData: opts.reportData,
+                source: opts.source,
+            }),
+        ]
+        : [
+            {
+                message: () => computedCommitMessage,
+                async apply(dir) {
+                    mergeEnvsIfPresent(dir);
+                    const { livePaths, resolutions: resolutionEntries } = writeQuonfigFiles(dir, opts.changes, opts.source);
+                    removeQfFromGitignore(dir);
+                    writeImportState(dir, opts.importState);
+                    acc.droppedOverrides = opts.source.getDroppedOverrides?.() ?? null;
+                    acc.skippedConfigs = opts.source.getSkippedConfigs?.() ?? null;
+                    acc.coercedSentinels = opts.source.getCoercedSentinels?.() ?? null;
+                    acc.duplicateResolutions =
+                        resolutionEntries.length > 0 ? { entries: resolutionEntries, total: resolutionEntries.length } : null;
+                    const skippedTotal = (acc.skippedConfigs?.total ?? 0) + resolutionEntries.reduce((sum, r) => sum + r.deleted.length, 0);
+                    const environmentsCount = opts.environments?.length ?? 0;
+                    const counts = buildMigrationCounts(livePaths, environmentsCount, skippedTotal);
+                    computedCommitMessage = buildMigrationCommitMessage(opts.source.name, counts);
+                    const reportData = {
+                        ...opts.reportData,
+                        counts,
+                        ...(acc.coercedSentinels ? { coercedSentinels: acc.coercedSentinels } : {}),
+                        ...(acc.droppedOverrides ? { droppedOverrides: acc.droppedOverrides } : {}),
+                        ...(acc.duplicateResolutions ? { duplicateResolutions: acc.duplicateResolutions } : {}),
+                        ...(acc.skippedConfigs ? { skippedConfigs: acc.skippedConfigs } : {}),
+                    };
+                    writeMigrationReport(dir, reportData);
+                    verifyOnDisk(dir);
+                },
+            },
+        ];
     const cloneOpts = {
-        applyDelta(dir) {
-            if (opts.environments && opts.environments.length > 0) {
-                mergeEnvironmentsIntoQuonfigJson(dir, opts.environments);
-            }
-            const { livePaths, resolutions: resolutionEntries } = writeQuonfigFiles(dir, opts.changes, opts.source);
-            removeQfFromGitignore(dir);
-            writeImportState(dir, opts.importState);
-            droppedOverrides = opts.source.getDroppedOverrides?.() ?? null;
-            skippedConfigs = opts.source.getSkippedConfigs?.() ?? null;
-            coercedSentinels = opts.source.getCoercedSentinels?.() ?? null;
-            duplicateResolutions =
-                resolutionEntries.length > 0 ? { entries: resolutionEntries, total: resolutionEntries.length } : null;
-            const skippedTotal = (skippedConfigs?.total ?? 0) + resolutionEntries.reduce((sum, r) => sum + r.deleted.length, 0);
-            const environmentsCount = opts.environments?.length ?? 0;
-            const counts = buildMigrationCounts(livePaths, environmentsCount, skippedTotal);
-            computedCommitMessage = buildMigrationCommitMessage(opts.source.name, counts);
-            const reportData = {
-                ...opts.reportData,
-                counts,
-                ...(coercedSentinels ? { coercedSentinels } : {}),
-                ...(droppedOverrides ? { droppedOverrides } : {}),
-                ...(duplicateResolutions ? { duplicateResolutions } : {}),
-                ...(skippedConfigs ? { skippedConfigs } : {}),
-            };
-            writeMigrationReport(dir, reportData);
-            // Pre-flight: run the same validation the Gitea pre-receive `qfg-verify`
-            // hook will run after the push lands. Failing here saves a full
-            // git-push round-trip and gives the customer a local, fixable error
-            // (qfg-52qg).
-            const verifyResult = validateWorkspace(dir);
-            if (!verifyResult.valid)
-                throw new MigratorVerifyError(verifyResult);
-        },
-        commitMessage: () => computedCommitMessage,
+        commits,
         localDir: opts.localDir,
         remoteUrl: opts.remoteUrl,
     };
     if (opts.branch !== undefined)
         cloneOpts.branch = opts.branch;
     const result = await cloneAndStackPush(cloneOpts);
-    return { ...result, coercedSentinels, droppedOverrides, duplicateResolutions, skippedConfigs };
+    return {
+        ...result,
+        coercedSentinels: acc.coercedSentinels,
+        droppedOverrides: acc.droppedOverrides,
+        duplicateResolutions: acc.duplicateResolutions,
+        skippedConfigs: acc.skippedConfigs,
+    };
 };

package/dist/migrate/source.d.ts

@@ -56,6 +56,24 @@ export interface DuplicateResolutionSummary {
     entries: DuplicateResolution[];
     total: number;
 }
+/**
+ * qfg-wbkj: Per-change commit metadata for --full-summary mode. Sources that
+ * carry author + timestamp + summary per change (e.g. Launch's change-history)
+ * implement getCommitMeta() so push-to-cloud can author one git commit per
+ * change with the original Launch user as author and `changedAt` as
+ * GIT_AUTHOR_DATE. Sources without this method are rejected at the command
+ * layer when --full-summary is passed.
+ */
+export interface CommitMeta {
+    author: {
+        email: string;
+        name: string;
+    };
+    /** Author date — any value `new Date(...)` accepts (Date, ISO string, or epoch ms). */
+    date: Date | number | string;
+    /** Non-empty commit message. Empty source-side summaries must be replaced with a fallback by the source. */
+    message: string;
+}
 export interface MigrationSource {
     fetchChanges(sinceEpochMs: null | number): AsyncIterable<LegacyChange>;
     /**
@@ -64,6 +82,12 @@ export interface MigrationSource {
      * typed default. Null when nothing was coerced.
      */
     getCoercedSentinels?(): CoercedSentinelSummary | null;
+    /**
+     * Optional. qfg-wbkj: per-change commit metadata used by --full-summary. Returns
+     * null if the change carries no usable author/date/summary (e.g. legacy or
+     * synthesized entries) and the caller should fall back to the migrator identity.
+     */
+    getCommitMeta?(change: LegacyChange): CommitMeta | null;
     /**
      * Optional post-translate accumulator. Returns any override sections that were
      * dropped during translate() calls because the env.id was not present in the