@quonfig/cli 0.0.45 → 0.0.47

package/dist/push/run-push.d.ts

@@ -19,6 +19,7 @@
  * confirmation — that prompt is the destructive-change brake.
  */
 import { FileDelta } from './diff-summary.js';
+import type { CurrentBranchResult } from './git-pack.js';
 export interface GiteaTokenMintResult {
     expiresAt: string | null;
     repoUrl: string;
@@ -27,6 +28,20 @@ export interface GiteaTokenMintResult {
     workspaceSlug: string;
 }
 export interface GitOps {
+    /**
+     * Pack-push — produce a packfile of `<expectedSha>..<newSha>` (or an
+     * empty buffer when expectedSha === newSha). Capped at 25 MiB per §7
+     * open Q #7; throws on overflow so callers see a concrete error
+     * before any HTTP traffic.
+     */
+    buildPack(dir: string, expectedSha: string, newSha: string): Promise<Uint8Array>;
+    /**
+     * Pack-push — count of commits in `<expectedSha>..<newSha>`. Drives
+     * the final "Pushed N commit(s)" log line. Returns 0 for a no-op
+     * push (already at the tip) and best-effort for new branches with
+     * a zero-OID base.
+     */
+    countCommitsBetween(dir: string, expectedSha: string, newSha: string): Promise<number>;
     /** Number of tracked files on origin/main (used for the destructive-ratio heuristic). */
     countFilesInRemote(dir: string): Promise<number>;
     /**
@@ -45,6 +60,32 @@ export interface GitOps {
     dirtyTrackedFiles(dir: string): Promise<string[]>;
     /** `git fetch origin` in the given dir. */
     fetch(dir: string): Promise<void>;
+    /**
+     * Returns every configured remote URL on the repo (i.e. `git remote -v`
+     * URLs, deduped per remote name). Used by the identity check to support
+     * multi-remote workspaces where `origin` points at a customer's PR-review
+     * remote (GitHub) and a secondary remote points at Quonfig (qfg-glrd.3).
+     *
+     * Returns an empty array when the dir isn't a git repo or has no remotes
+     * configured.
+     */
+    getAllRemoteUrls(dir: string): Promise<string[]>;
+    /**
+     * Run `git log -1 --pretty=oneline <sha>` and return the resulting line
+     * (`<short-sha> <subject>`) or an empty string when the commit is not
+     * present locally. Used by the qfg-7429.5 denial renderer to print the
+     * offending commit's identity alongside the server's recovery message.
+     */
+    getCommitOneline(dir: string, sha: string): Promise<string>;
+    /**
+     * Pack-push (qfg-7429.4) — resolve HEAD as a branch name or refuse
+     * cleanly. Returns the documented refusal text for detached HEAD and
+     * the local default branch being `master`. The result drives the
+     * `targetRef` the server sees on success.
+     */
+    getCurrentBranch(dir: string): Promise<CurrentBranchResult>;
+    /** Pack-push — local HEAD SHA. Forwarded as `newSha` on the wire. */
+    getHeadSha(dir: string): Promise<string>;
     /**
      * Returns the local SHA of `origin/main` after fetch — the remote tip
      * the diff was computed against — or undefined if no `origin/main` ref
@@ -55,8 +96,24 @@ export interface GitOps {
      * origin moved between fetch and push.
      */
     getOriginMainSha(dir: string): Promise<string | undefined>;
+    /**
+     * Pack-push — local SHA for `origin/<branchName>`, or undefined when
+     * the remote-tracking ref doesn't exist yet (brand-new branch).
+     * Drives `expectedSha`: defined → SHA, undefined → zero-OID.
+     */
+    getRemoteBranchSha(dir: string, branchName: string): Promise<string | undefined>;
     /** Returns the `remote.origin.url` for the repo, or undefined if unset / not a repo. */
     getRemoteOriginUrl(dir: string): Promise<string | undefined>;
+    /**
+     * qfg-7429.6 — return the tree SHA for `<ref>^{tree}`, or undefined when
+     * the ref can't be resolved. Used by the legacy-divergence detector in
+     * the pack-push conflict handler: workspaces created before pack-push
+     * shipped have local commit SHAs that diverge from origin even when the
+     * tree content is identical (the old server fabricated commits). If
+     * `HEAD^{tree}` matches `origin/<branch>^{tree}`, the apparent conflict
+     * is actually that one-shot legacy state, not a real concurrent push.
+     */
+    getTreeShaForRef(dir: string, ref: string): Promise<string | undefined>;
     /** Returns true if the dir has a `.git/` (worktree or repo). */
     isGitRepo(dir: string): Promise<boolean>;
     /**
@@ -104,6 +161,65 @@ export interface PushDenial {
     reason: string;
     requiredPermission: string;
 }
+/**
+ * Pack-push wire input for `configs.gitPush` (qfg-7429.4). The pack
+ * itself stays raw on the CLI side; the HTTP client base64-encodes it
+ * so the JSON envelope stays text-safe.
+ */
+export interface GitPushInput {
+    /** Remote tip the CLI saw (zero-OID for a brand-new branch). */
+    expectedSha: string;
+    /**
+     * qfg-7429.5 / §6: true when at least one configured git remote on
+     * the local clone does not normalize to the backend's Quonfig repo
+     * URL. The server uses this to decide whether to attach the
+     * GitHub-fork dead-end `suggestedRecovery` block to a 403 response.
+     */
+    hasUpstreamRemote: boolean;
+    /** Local HEAD being published. Server returns this back as commitSha. */
+    newSha: string;
+    pack: Uint8Array;
+    /** `refs/heads/main` or `refs/heads/<branch>`. */
+    targetRef: string;
+    workspaceId: string;
+}
+/**
+ * Pack-push denial. Carries `commitSha` so the CLI can name which
+ * commit failed authz — the §6 GitHub-fork dead-end UX (rendered
+ * fully in qfg-7429.5).
+ */
+export interface GitPushDenial {
+    commitSha: string;
+    path: string;
+    reason: string;
+    requiredPermission: string;
+}
+/**
+ * Server-emitted recovery hint for the GitHub-fork dead-end (§6 of
+ * the design plan). Currently the only `kind` is `revert-upstream`;
+ * future kinds are forward-compatible because the discriminator is
+ * tagged.
+ */
+export type SuggestedRecovery = {
+    kind: 'revert-upstream';
+    offendingCommitSha: string;
+    message: string;
+};
+export type GitPushResult = {
+    kind: 'success';
+    commitSha: string;
+    ref: string;
+} | {
+    kind: 'conflict';
+    message: string;
+} | {
+    kind: 'bad-request';
+    message: string;
+} | {
+    kind: 'denied';
+    denials: GitPushDenial[];
+    suggestedRecovery?: SuggestedRecovery;
+};
 export type ConfirmIO = {
     input?: NodeJS.ReadableStream;
     output?: NodeJS.WritableStream;
@@ -160,6 +276,12 @@ export interface RunPushDeps {
      * stable across the qfg-azk.13 transition.
      */
     mintWriteToken(requestedTarget: string): Promise<GiteaTokenMintResult>;
+    /**
+     * Pack-push — call the server-side `configs.gitPush` oRPC procedure
+     * (qfg-7429.4). Used by the clone-path dispatch; bare-path still
+     * routes through `pushToServer` above.
+     */
+    pushPackToServer(input: GitPushInput): Promise<GitPushResult>;
     /**
      * Call the server-side `configs.push` oRPC procedure. Returns a tagged
      * union so callers can distinguish success / per-file denials / a stale
@@ -187,6 +309,16 @@ export declare class PushFatalError extends Error {
     code: string;
     constructor(message: string, code?: string);
 }
-/** Append the Pushed-Via trailer to a commit message if it isn't already present. */
+/**
+ * qfg-glrd.6: the `Pushed-Via: cli` trailer was retired. Audit data
+ * now lives in the server-side `push_events` table (qfg-glrd.4), so a
+ * CLI-appended trailer would be redundant — and CLI trailers also
+ * break SHA identity end-to-end once pack-push lands (the message the
+ * user committed wouldn't match the message that travels to the server).
+ *
+ * Kept as a no-op shim instead of deleted so callers and tests don't
+ * need a coordinated cross-repo rename. Will be removed once every
+ * caller has been updated to drop the call entirely.
+ */
 export declare const withPushedViaTrailer: (message: string) => string;
 export declare function runPush(input: RunPushInput, deps: RunPushDeps): Promise<RunPushResult>;

package/dist/push/run-push.js

@@ -24,6 +24,8 @@ import { readWorkspaceSlug, tryParseWorkspacePin, writeWorkspaceSlug } from '../
 import { checkIdentity } from './identity-check.js';
 import { confirmTypedSlug, confirmYesNo } from './confirm.js';
 import { summarizeDiff } from './diff-summary.js';
+/** All-zeros object id, the git-protocol convention for "no such ref". */
+const ZERO_OID = '0000000000000000000000000000000000000000';
 export class PushFatalError extends Error {
     code;
     constructor(message, code = 'PUSH_FATAL') {
@@ -50,14 +52,18 @@ const normalizeForCompare = (url) => {
     }
 };
 const sameRepo = (a, b) => normalizeForCompare(a) === normalizeForCompare(b);
-const PUSHED_VIA_TRAILER = 'Pushed-Via: cli';
-/** Append the Pushed-Via trailer to a commit message if it isn't already present. */
-export const withPushedViaTrailer = (message) => {
-    if (message.includes(PUSHED_VIA_TRAILER))
-        return message;
-    const trimmed = message.replace(/\s+$/, '');
-    return `${trimmed}\n\n${PUSHED_VIA_TRAILER}\n`;
-};
+/**
+ * qfg-glrd.6: the `Pushed-Via: cli` trailer was retired. Audit data
+ * now lives in the server-side `push_events` table (qfg-glrd.4), so a
+ * CLI-appended trailer would be redundant — and CLI trailers also
+ * break SHA identity end-to-end once pack-push lands (the message the
+ * user committed wouldn't match the message that travels to the server).
+ *
+ * Kept as a no-op shim instead of deleted so callers and tests don't
+ * need a coordinated cross-repo rename. Will be removed once every
+ * caller has been updated to drop the call entirely.
+ */
+export const withPushedViaTrailer = (message) => message;
 export async function runPush(input, deps) {
     const log = deps.log ?? ((s) => console.log(s));
     const errLog = deps.errLog ?? ((s) => console.error(s));
@@ -83,6 +89,16 @@ export async function runPush(input, deps) {
     }
     const repoPinSlug = repoPin?.workspaceSlug;
     const hasGit = await deps.gitOps.isGitRepo(input.dir);
+    // Multi-remote support (qfg-glrd.3): walk EVERY configured remote, not
+    // just `origin`. Customers commonly run `origin=github` for PR review and
+    // a secondary remote against Quonfig. Identity check accepts as long as
+    // any one of them matches the backend.
+    const remoteUrls = hasGit ? await deps.gitOps.getAllRemoteUrls(input.dir) : [];
+    // Clone-path dispatch still keys off `origin` specifically — the
+    // implementation reads `origin/main` and pushes via origin. With a
+    // non-matching origin (e.g. origin=github), the bare-path probe clone is
+    // used instead. Identity-check already accepted the push via a different
+    // remote, so this is a dispatch detail, not a refusal.
     const remoteOriginUrl = hasGit ? await deps.gitOps.getRemoteOriginUrl(input.dir) : undefined;
     // Mint the write token. The backend accepts a slug OR a UUID for workspaceId
     // and resolves to the same row — we trust whatever `requestedTarget` is.
@@ -91,7 +107,7 @@ export async function runPush(input, deps) {
     const identity = checkIdentity({
         requestedTarget: input.requestedTarget,
         repoPinSlug,
-        remoteOriginUrl,
+        remoteUrls,
         backend: {
             workspaceSlug: backend.workspaceSlug,
             workspaceId: backend.workspaceId,
@@ -132,17 +148,29 @@ export async function runPush(input, deps) {
     // Clone path: align origin with the backend so the gitOps.fetch + diff
     // walk authenticates against the read URL we minted. The bare path's
     // probe-clone path bypasses local origin entirely.
+    //
+    // Pack-push (qfg-7429.4): the §4.1 step-1 refusals run BEFORE any
+    // network work in clone-path so a detached-HEAD or `master` checkout
+    // gets a clear error message without us pinging Gitea or the backend.
+    let currentBranch;
     if (isClonePath) {
+        currentBranch = await deps.gitOps.getCurrentBranch(input.dir);
+        if (currentBranch.kind === 'detached') {
+            throw new PushFatalError(currentBranch.message, 'DETACHED_HEAD');
+        }
+        if (currentBranch.kind === 'master') {
+            throw new PushFatalError(currentBranch.message, 'MASTER_BRANCH');
+        }
         await deps.gitOps.setRemoteOrigin(input.dir, backend.repoUrl);
         log('Fetching from remote...');
         await deps.gitOps.fetch(input.dir);
         // Guard 4 (qfg-fboj): refuse to push when local HEAD is behind or has
-        // diverged from origin/main. Without this guard the HEAD-vs-origin
-        // diff produces REVERSAL deltas that silently undo whatever was
-        // committed to the cloud since the user last pulled. Tell the user
-        // to run `qfg pull` first; the standalone `--ff-only` step keeps
-        // push from doing surprising merges on the user's behalf.
-        if (await deps.gitOps.isLocalBehindRemote(input.dir)) {
+        // diverged from origin/main. The §4.1 server-side fast-forward check
+        // already covers correctness; this client-side guard turns a 409 round
+        // trip into a fast local error with a `qfg pull` hint. Only meaningful
+        // on `main` — branch pushes are evaluated against origin/<branch>, not
+        // origin/main, and may legitimately diverge.
+        if (currentBranch.name === 'main' && (await deps.gitOps.isLocalBehindRemote(input.dir))) {
             throw new PushFatalError('Local HEAD is behind origin/main. Run `qfg pull` first to merge remote changes, then re-run `qfg push`.', 'STALE_HEAD');
         }
         // Migration cleanup (qfg-0fn): older `qfg pull` runs wrote the
@@ -211,38 +239,147 @@ export async function runPush(input, deps) {
         log('Aborted, nothing pushed.');
         return { kind: 'aborted', reason: decision.reason };
     }
-    const baseMessage = input.message ?? `qfg push: ${summary.totals.filesTouched} file change(s)`;
-    const commitMessage = withPushedViaTrailer(baseMessage);
-    const serverFiles = deltas.map((d) => ({
-        path: d.path,
-        kind: toServerKind(d.kind),
-        ...(d.beforeJson === undefined ? {} : { beforeJson: d.beforeJson }),
-        ...(d.afterJson === undefined ? {} : { afterJson: d.afterJson }),
-    }));
-    // qfg-gj3i: pass origin/main SHA as expectedSha so the server-side
-    // optimistic lock can reject the push if origin moved between fetch
-    // and now. Undefined on bare-path; the server treats absence as
-    // "non-clone client" and applies its bare-path policy.
-    const expectedSha = await deps.gitOps.getOriginMainSha(input.dir);
-    log('Sending push to Quonfig cloud...');
-    const result = await deps.pushToServer({
-        workspaceId: backend.workspaceId,
-        files: serverFiles,
-        message: commitMessage,
-        ...(expectedSha === undefined ? {} : { expectedSha }),
-    });
-    if (result.kind === 'denied') {
-        errLog(`Push denied for ${result.denials.length} file(s):`);
-        for (const d of result.denials) {
-            errLog(`  ${d.path}: missing permission ${d.requiredPermission}`);
+    // Pack-push branch (qfg-7429.4): clone-path now ships actual git
+    // commit objects via `configs.gitPush`. The bare-path branch below is
+    // the unchanged file-delta wire shape used by the UI and CI pushes
+    // that don't carry a `.git/`.
+    let pushedCommitSha;
+    if (isClonePath && currentBranch && currentBranch.kind === 'branch') {
+        const branchName = currentBranch.name;
+        const targetRef = `refs/heads/${branchName}`;
+        // expectedSha: for `main`, the origin/main SHA we already know; for
+        // branches, look up `origin/<branch>` (zero-OID for brand-new branches).
+        const expectedShaRaw = branchName === 'main'
+            ? await deps.gitOps.getOriginMainSha(input.dir)
+            : await deps.gitOps.getRemoteBranchSha(input.dir, branchName);
+        const expectedSha = expectedShaRaw ?? ZERO_OID;
+        const newSha = await deps.gitOps.getHeadSha(input.dir);
+        log('Building pack...');
+        const pack = await deps.gitOps.buildPack(input.dir, expectedSha, newSha);
+        // §6 / qfg-7429.5: tell the server whether the local clone has a
+        // non-Quonfig upstream so it can decide whether to attach a
+        // GitHub-fork dead-end recovery hint to a 403.
+        const hasUpstreamRemote = remoteUrls.some((u) => !sameRepo(u, backend.repoUrl));
+        log('Sending push to Quonfig cloud...');
+        const packResult = await deps.pushPackToServer({
+            workspaceId: backend.workspaceId,
+            targetRef,
+            expectedSha,
+            newSha,
+            pack,
+            hasUpstreamRemote,
+        });
+        if (packResult.kind === 'denied') {
+            errLog(`Push denied for ${packResult.denials.length} commit(s):`);
+            for (const d of packResult.denials) {
+                // qfg-7429.5 denial line: `<short-sha>  <path>  -- <reason>, requires <requiredPermission>`
+                errLog(`  ${d.commitSha.slice(0, 8)}  ${d.path}  -- ${d.reason}, requires ${d.requiredPermission}`);
+            }
+            if (packResult.suggestedRecovery) {
+                errLog('');
+                errLog(packResult.suggestedRecovery.message);
+                try {
+                    const oneline = await deps.gitOps.getCommitOneline(input.dir, packResult.suggestedRecovery.offendingCommitSha);
+                    if (oneline.length > 0) {
+                        errLog(`  ${oneline}`);
+                    }
+                }
+                catch {
+                    /* non-fatal — the recovery message is the load-bearing part */
+                }
+            }
+            throw new PushFatalError(`Push denied for ${packResult.denials.length} commit(s). See errors above.`, 'PUSH_DENIED');
         }
-        throw new PushFatalError(`Push denied for ${result.denials.length} file(s). See errors above.`, 'PUSH_DENIED');
-    }
-    if (result.kind === 'conflict') {
-        throw new PushFatalError(`Remote moved while preparing this push (${result.message}). Run \`qfg pull\` and retry.`, 'CONFLICT');
+        if (packResult.kind === 'conflict') {
+            // qfg-7429.6: every workspace ever pushed under the pre-pack-push
+            // fabricate-commit handler has local commit SHAs that diverge from
+            // origin even when content is identical. The first pack push from
+            // such a dir trips the server's fast-forward check. Distinguish
+            // that one-shot legacy state from a real conflict by comparing
+            // HEAD's tree to origin/<branch>'s tree: equal trees → migration
+            // hint (`git reset --hard origin/<branch>`); different trees →
+            // existing qfg-pull message. Rebase would produce phantom replay
+            // commits with new SHAs forever, so it is NOT the recommended path.
+            let headTree;
+            let originTree;
+            try {
+                headTree = await deps.gitOps.getTreeShaForRef(input.dir, 'HEAD');
+            }
+            catch {
+                /* fall through — treat unknown tree as "real conflict" */
+            }
+            try {
+                originTree = await deps.gitOps.getTreeShaForRef(input.dir, `origin/${branchName}`);
+            }
+            catch {
+                /* fall through */
+            }
+            if (headTree && originTree && headTree === originTree) {
+                errLog('');
+                errLog(`Your local ${branchName} and origin/${branchName} have diverged from an older push using the`);
+                errLog('fabricate-commit handler. Your local content matches origin (no real conflict).');
+                errLog('');
+                errLog(`To align: git reset --hard origin/${branchName}`);
+                errLog('Then re-run qfg push.');
+                errLog('');
+                errLog('This is a one-time cutover. Subsequent pushes from this dir will preserve your');
+                errLog('commit SHAs end-to-end.');
+                throw new PushFatalError(`Legacy orphan-commit divergence with origin/${branchName}. Run \`git reset --hard origin/${branchName}\` and retry.`, 'CONFLICT_LEGACY_DIVERGE');
+            }
+            throw new PushFatalError(`Remote moved while preparing this push (${packResult.message}). Run \`qfg pull\` and retry.`, 'CONFLICT');
+        }
+        if (packResult.kind === 'bad-request') {
+            throw new PushFatalError(`Push rejected by server: ${packResult.message}`, 'BAD_REQUEST');
+        }
+        pushedCommitSha = packResult.commitSha;
+        // §4.1 step 4: post-push refresh — `git fetch origin` (NOT `git
+        // reset`) brings the local origin/<ref> tracking ref in line with
+        // the SHA the server published, so subsequent `qfg pull` runs are
+        // a no-op. SHAs already match by construction (pack-push round-trip).
+        try {
+            await deps.gitOps.fetch(input.dir);
+        }
+        catch {
+            /* non-fatal — the push itself succeeded */
+        }
+        const commitCount = await deps.gitOps.countCommitsBetween(input.dir, expectedSha, newSha);
+        log(`Pushed ${commitCount} commit(s) to origin/${targetRef} as ${newSha.slice(0, 7)}. Local repo in sync.`);
     }
-    if (result.kind === 'bad-request') {
-        throw new PushFatalError(`Push rejected by server: ${result.message}`, 'BAD_REQUEST');
+    else {
+        const baseMessage = input.message ?? `qfg push: ${summary.totals.filesTouched} file change(s)`;
+        const commitMessage = withPushedViaTrailer(baseMessage);
+        const serverFiles = deltas.map((d) => ({
+            path: d.path,
+            kind: toServerKind(d.kind),
+            ...(d.beforeJson === undefined ? {} : { beforeJson: d.beforeJson }),
+            ...(d.afterJson === undefined ? {} : { afterJson: d.afterJson }),
+        }));
+        // qfg-gj3i: pass origin/main SHA as expectedSha so the server-side
+        // optimistic lock can reject the push if origin moved between fetch
+        // and now. Undefined on bare-path; the server treats absence as
+        // "non-clone client" and applies its bare-path policy.
+        const expectedSha = await deps.gitOps.getOriginMainSha(input.dir);
+        log('Sending push to Quonfig cloud...');
+        const result = await deps.pushToServer({
+            workspaceId: backend.workspaceId,
+            files: serverFiles,
+            message: commitMessage,
+            ...(expectedSha === undefined ? {} : { expectedSha }),
+        });
+        if (result.kind === 'denied') {
+            errLog(`Push denied for ${result.denials.length} file(s):`);
+            for (const d of result.denials) {
+                errLog(`  ${d.path}: missing permission ${d.requiredPermission}`);
+            }
+            throw new PushFatalError(`Push denied for ${result.denials.length} file(s). See errors above.`, 'PUSH_DENIED');
+        }
+        if (result.kind === 'conflict') {
+            throw new PushFatalError(`Remote moved while preparing this push (${result.message}). Run \`qfg pull\` and retry.`, 'CONFLICT');
+        }
+        if (result.kind === 'bad-request') {
+            throw new PushFatalError(`Push rejected by server: ${result.message}`, 'BAD_REQUEST');
+        }
+        pushedCommitSha = result.commitSha;
     }
     if (unpinned && !input.noPinWrite) {
         // The backend's mint-token still returns the bare workspace component;
@@ -262,7 +399,7 @@ export async function runPush(input, deps) {
             }
         }
     }
-    return { kind: 'pushed', dispatchedAs, commitSha: result.commitSha };
+    return { kind: 'pushed', dispatchedAs, commitSha: pushedCommitSha };
 }
 const toServerKind = (kind) => {
     switch (kind) {

package/dist/util/clone-and-stack-push.d.ts

@@ -6,19 +6,37 @@ 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;
+/**
+ * A single commit to apply on top of the cloned local tree. `apply` writes/deletes
+ * files; it must NOT commit. cloneAndStackPush stages and commits with the given
+ * author + optional author date.
+ */
+export interface CommitSpec {
+    /** File operations to perform in `localDir` before this commit is staged. */
+    apply: (localDir: string) => Promise<void> | void;
     /** Commit author. Defaults to the migrator identity. */
     author?: PushIdentity;
+    /**
+     * Optional author/committer date. Passed via GIT_AUTHOR_DATE +
+     * GIT_COMMITTER_DATE. Any value `new Date(...)` accepts. Omit to use "now".
+     */
+    authorDate?: Date | number | string;
+    /**
+     * Commit message. May be a function when the message depends on counts that
+     * are only known after `apply` runs (qfg-7eig).
+     */
+    message: string | (() => string);
+}
+export interface CloneAndStackPushOptions {
     /** Branch to track and push. Defaults to `main`. */
     branch?: string;
     /**
-     * Commit message for the delta. Pass a function when the message depends on
-     * counts that are only known after `applyDelta` runs (qfg-7eig). The function
-     * is invoked after applyDelta but before commit.
+     * One or more commits to layer onto the clone. Commits are applied + committed
+     * in order; commits whose `apply` produces no staged changes are silently
+     * skipped (no empty commits). All non-empty commits are pushed in a single
+     * `git push`.
      */
-    commitMessage: string | (() => string);
+    commits: CommitSpec[];
     /** Where to clone into, or an existing clone to reuse. */
     localDir: string;
     /** Gitea repo URL (may include token). */
@@ -27,9 +45,11 @@ export interface CloneAndStackPushOptions {
 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. */
+    /** SHA of the LAST commit landed (back-compat alias for the final entry in commitShas). Null when no commit landed. */
     commitSha: string | null;
-    /** `false` if `applyDelta` produced no changes — nothing was committed or pushed. */
+    /** SHAs of every commit landed, in order. Empty when no commit landed. */
+    commitShas: string[];
+    /** `false` if every commit's `apply` produced no changes — nothing was committed or pushed. */
     committed: boolean;
 }
 export declare class PushConflictError extends Error {
@@ -38,4 +58,15 @@ export declare class PushConflictError extends Error {
 export declare class PushHookRejectedError extends Error {
     constructor(message: string);
 }
+/**
+ * Apply + commit a sequence of CommitSpecs against an existing repo at `localDir`.
+ * Per-commit author/date come from each spec (defaults to migrator identity, "now").
+ * Empty commits — where `apply` produces no staged changes — are silently skipped.
+ * Does NOT clone, fetch, or push: callers handle network I/O. Used by
+ * `cloneAndStackPush` for cloud pushes and by the local migrator for `--full-summary`
+ * imports into a `git init`-ed dir.
+ */
+export declare const stackCommits: (localDir: string, commits: CommitSpec[]) => Promise<{
+    commitShas: string[];
+}>;
 export declare const cloneAndStackPush: (opts: CloneAndStackPushOptions) => Promise<CloneAndStackPushResult>;

package/dist/util/clone-and-stack-push.js

@@ -84,29 +84,68 @@ const hasStagedChanges = async (dir) => {
     const { stdout } = await runGitSafe(['-C', dir, 'status', '--porcelain']);
     return stdout.trim().length > 0;
 };
-export const cloneAndStackPush = async (opts) => {
-    const branch = opts.branch ?? 'main';
-    const author = opts.author ?? MIGRATOR_IDENTITY;
-    const action = await ensureCloneOrReuse(opts.remoteUrl, opts.localDir, branch);
-    // Pin committer identity on the repo so commits are reproducible regardless of host git config.
-    await runGit(opts.localDir, ['config', 'user.name', author.name]);
-    await runGit(opts.localDir, ['config', 'user.email', author.email]);
-    await opts.applyDelta(opts.localDir);
-    await runGit(opts.localDir, ['add', '--all']);
-    if (!(await hasStagedChanges(opts.localDir))) {
-        return { action, committed: false, commitSha: null };
-    }
-    const commitMessage = typeof opts.commitMessage === 'function' ? opts.commitMessage() : opts.commitMessage;
-    await spawnGit(['-C', opts.localDir, 'commit', '-F', '-'], {
-        stdin: commitMessage,
-        env: {
+const toGitDate = (value) => {
+    // Normalize via Date so any of the three accepted shapes round-trips through
+    // git's ISO-8601 parser cleanly.
+    const d = value instanceof Date ? value : new Date(value);
+    return d.toISOString();
+};
+/**
+ * Apply + commit a sequence of CommitSpecs against an existing repo at `localDir`.
+ * Per-commit author/date come from each spec (defaults to migrator identity, "now").
+ * Empty commits — where `apply` produces no staged changes — are silently skipped.
+ * Does NOT clone, fetch, or push: callers handle network I/O. Used by
+ * `cloneAndStackPush` for cloud pushes and by the local migrator for `--full-summary`
+ * imports into a `git init`-ed dir.
+ */
+export const stackCommits = async (localDir, commits) => {
+    const commitShas = [];
+    for (const spec of commits) {
+        const author = spec.author ?? MIGRATOR_IDENTITY;
+        // eslint-disable-next-line no-await-in-loop
+        await spec.apply(localDir);
+        // eslint-disable-next-line no-await-in-loop
+        await runGitSafe(['-C', localDir, 'add', '--all']);
+        // eslint-disable-next-line no-await-in-loop
+        if (!(await hasStagedChanges(localDir))) {
+            // No-op commits are silently skipped (qfg-3uks: no empty commits, ever).
+            continue;
+        }
+        const message = typeof spec.message === 'function' ? spec.message() : spec.message;
+        const env = {
             GIT_AUTHOR_NAME: author.name,
             GIT_AUTHOR_EMAIL: author.email,
             GIT_COMMITTER_NAME: author.name,
             GIT_COMMITTER_EMAIL: author.email,
-        },
-    });
-    const { stdout: sha } = await runGitSafe(['-C', opts.localDir, 'rev-parse', 'HEAD']);
+        };
+        if (spec.authorDate !== undefined) {
+            const iso = toGitDate(spec.authorDate);
+            env.GIT_AUTHOR_DATE = iso;
+            env.GIT_COMMITTER_DATE = iso;
+        }
+        // eslint-disable-next-line no-await-in-loop
+        await spawnGit(['-C', localDir, 'commit', '-F', '-'], { stdin: message, env });
+        // eslint-disable-next-line no-await-in-loop
+        const { stdout: sha } = await runGitSafe(['-C', localDir, 'rev-parse', 'HEAD']);
+        commitShas.push(sha.trim());
+    }
+    return { commitShas };
+};
+export const cloneAndStackPush = async (opts) => {
+    const branch = opts.branch ?? 'main';
+    if (opts.commits.length === 0) {
+        throw new Error('cloneAndStackPush: commits array must contain at least one entry');
+    }
+    const action = await ensureCloneOrReuse(opts.remoteUrl, opts.localDir, branch);
+    // Pin a stable committer identity on the repo. Per-commit author overrides
+    // happen via env vars in stackCommits; this default catches the case where a
+    // CommitSpec omits `author` entirely.
+    await runGit(opts.localDir, ['config', 'user.name', MIGRATOR_IDENTITY.name]);
+    await runGit(opts.localDir, ['config', 'user.email', MIGRATOR_IDENTITY.email]);
+    const { commitShas } = await stackCommits(opts.localDir, opts.commits);
+    if (commitShas.length === 0) {
+        return { action, committed: false, commitSha: null, commitShas: [] };
+    }
     try {
         // Plain push — no force, no force-with-lease. If the remote has advanced, we fail
         // and surface a conflict; we do NOT clobber UI edits.
@@ -128,5 +167,5 @@ export const cloneAndStackPush = async (opts) => {
         }
         throw error;
     }
-    return { action, committed: true, commitSha: sha.trim() };
+    return { action, committed: true, commitSha: commitShas.at(-1) ?? null, commitShas };
 };