@quonfig/cli 0.0.15 → 0.0.16

package/dist/commands/push.js

@@ -0,0 +1,370 @@
+import { execFile as execFileCb } from 'node:child_process';
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+import * as util from 'node:util';
+import { Flags } from '@oclif/core';
+import { BaseCommand } from '../index.js';
+import { mintGiteaToken } from '../util/gitea-api.js';
+import { getRemoteUrl, gitFetch, gitSetRemote, isGitRepo, } from '../util/git-ops.js';
+import { PushFatalError, runPush } from '../push/run-push.js';
+import { computeBarePathDiff } from '../push/bare-path-diff.js';
+import { getActiveProfile, loadAuthConfig } from '../util/token-storage.js';
+const execFile = util.promisify(execFileCb);
+export default class Push extends BaseCommand {
+    static description = `Push local config changes up to your workspace on Quonfig cloud.
+
+Enforces three guards before touching the remote:
+  1. The dir's quonfig.json "workspace" pin must match the backend (if set).
+  2. The dir's git origin must match the backend repo URL (if set).
+  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 --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)
+  qfg push --dir ./our-config --skip-validate`;
+    static examples = [
+        '<%= config.bin %> push --dir ./our-config',
+        '<%= config.bin %> push --workspace acme-prod --dir ./our-config',
+        '<%= config.bin %> push --dir ./our-config --yes',
+    ];
+    static flags = {
+        dir: Flags.string({
+            description: 'Local directory to push (defaults to QUONFIG_DIR env var)',
+        }),
+        workspace: Flags.string({
+            description: 'Workspace slug or UUID (defaults to active profile)',
+        }),
+        yes: Flags.boolean({
+            default: false,
+            description: 'Skip the standard Y/N confirm. Never skips typed-slug prompts.',
+        }),
+        'skip-validate': Flags.boolean({
+            default: false,
+            description: 'Skip `qfg validate` preflight',
+        }),
+        'no-pin-write': Flags.boolean({
+            default: false,
+            description: 'Do not offer to write workspace slug into quonfig.json on success',
+        }),
+        message: Flags.string({
+            char: 'm',
+            description: 'Commit message for bare-path pushes (ignored on clone-path; push what is already committed)',
+        }),
+    };
+    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 resolvedDir = path.resolve(dir);
+        // Resolve requested target: --workspace overrides the active profile.
+        let requestedTarget = flags.workspace;
+        if (!requestedTarget) {
+            const authConfig = await loadAuthConfig();
+            if (!authConfig) {
+                return this.err('No active profile workspace; pass --workspace or run `qfg login`.');
+            }
+            const activeProfile = getActiveProfile();
+            const profile = authConfig.profiles[activeProfile] || authConfig.profiles[authConfig.defaultProfile || 'default'];
+            if (!profile || !profile.workspace) {
+                return this.err('No active profile workspace; pass --workspace or run `qfg login`.');
+            }
+            requestedTarget = profile.workspace;
+        }
+        const { deps, cleanup } = buildRealDeps(this);
+        try {
+            const result = await runPush({
+                dir: resolvedDir,
+                requestedTarget,
+                yes: flags.yes,
+                skipValidate: flags['skip-validate'],
+                noPinWrite: flags['no-pin-write'],
+                message: flags.message,
+            }, deps);
+            if (result.kind === 'aborted') {
+                this.log(`Aborted: ${result.reason}`);
+                return { aborted: true, reason: result.reason };
+            }
+            if (result.kind === 'no-op') {
+                this.log(result.reason);
+                return { noop: true, reason: result.reason };
+            }
+            this.log(`Pushed via ${result.dispatchedAs}.`);
+            return { pushed: true, via: result.dispatchedAs, commitSha: result.commitSha ?? null };
+        }
+        catch (error) {
+            if (error instanceof PushFatalError) {
+                return this.err(error.message);
+            }
+            throw error;
+        }
+        finally {
+            await cleanup();
+        }
+    }
+}
+/**
+ * Map a raw `gitea.token` API response into the `GiteaTokenMintResult` shape
+ * the push core (`runPush`) consumes. Kept as a pure function so we can unit
+ * test the wiring without a network — specifically, to regression-test that
+ * `workspaceId` on the result is the UUID the server returned, not the slug.
+ *
+ * The bug this guards against: before the backend started returning
+ * `workspaceId`, this module used `resp.workspaceSlug` as the `workspaceId`
+ * field, which caused `checkIdentity` to fail when the user passed
+ * `--workspace <UUID>` (requested=UUID, backend.workspaceId=slug → mismatch).
+ */
+export function giteaResponseToMintResult(resp) {
+    return {
+        token: resp.token,
+        repoUrl: resp.repoUrl,
+        expiresAt: resp.expiresAt,
+        workspaceSlug: resp.workspaceSlug,
+        // Canonical workspace UUID from the server. checkIdentity compares this
+        // against `requestedTarget` — so if the user passed --workspace as a
+        // UUID, the UUID path matches backend.workspaceId; if they passed a
+        // slug, the slug path matches backend.workspaceSlug. Either way the
+        // backend row is the same workspace.
+        workspaceId: resp.workspaceId,
+    };
+}
+/**
+ * Wire the real implementations of every dependency runPush needs. Kept in
+ * the command file so the pure core stays free of oclif / git shell imports.
+ *
+ * Returns a `{deps, cleanup}` pair. The caller MUST call `cleanup()` in a
+ * finally block so the bare-path probe clone is removed even on errors.
+ */
+export function buildRealDeps(cmd) {
+    const log = (line) => cmd.log(line);
+    const errLog = (line) => cmd.logToStderr(line);
+    // State captured across calls so a bare-path diff can share its probe clone
+    // between `diffHeadVsOrigin` and `countFilesInRemote`. Populated lazily on
+    // the first call that needs it.
+    //
+    // `authenticatedRepoUrl` is set by the wrapped `mintWriteToken` below —
+    // runPush always calls mint before it calls any gitOps method that needs
+    // the probe clone, so by the time we read it here it is populated.
+    let authenticatedRepoUrl;
+    let barePathProbe;
+    const ensureBarePathProbe = async (dir) => {
+        if (barePathProbe)
+            return barePathProbe;
+        if (!authenticatedRepoUrl) {
+            throw new Error('buildRealDeps: bare-path diff requested before mintWriteToken ran. This is a bug in runPush ordering.');
+        }
+        barePathProbe = await computeBarePathDiff(dir, authenticatedRepoUrl);
+        return barePathProbe;
+    };
+    const gitOps = {
+        async isGitRepo(dir) {
+            return isGitRepo(dir);
+        },
+        async getRemoteOriginUrl(dir) {
+            const url = await getRemoteUrl(dir);
+            return url ?? undefined;
+        },
+        async setRemoteOrigin(dir, url) {
+            await gitSetRemote(dir, url);
+        },
+        async fetch(dir) {
+            // fetch is only meaningful for the clone path. For a bare-path dir it
+            // is still called by runPush but the dir has no origin, so we swallow
+            // the failure here rather than in runPush. The probe-clone strategy
+            // handles the remote-state read.
+            try {
+                await gitFetch(dir);
+            }
+            catch {
+                /* bare path: no origin to fetch from — intentional no-op */
+            }
+        },
+        async diffHeadVsOrigin(dir) {
+            // Clone path: .git/ exists AND origin matches backend. Prefer the native
+            // git diff; it is fast and doesn't require a second clone.
+            if (await isGitRepo(dir)) {
+                try {
+                    return await diffHeadVsOrigin(dir);
+                }
+                catch {
+                    // Fall through to the probe-clone path. This can happen if the dir
+                    // is a git repo but origin doesn't have a main branch fetched, etc.
+                }
+            }
+            const probe = await ensureBarePathProbe(dir);
+            return probe.deltas;
+        },
+        async push(dir) {
+            await execFile('git', ['-C', dir, 'push', 'origin', 'main']);
+        },
+        async getLocalAuthor(dir) {
+            return readLocalAuthor(dir);
+        },
+        async countFilesInRemote(dir) {
+            if (await isGitRepo(dir)) {
+                const fromGit = await countTrackedFilesAtRef(dir, 'origin/main');
+                // If origin/main is present we get a positive count; if the dir is a
+                // bare path with a stale .git we get 0 and fall through.
+                if (fromGit > 0)
+                    return fromGit;
+            }
+            const probe = await ensureBarePathProbe(dir);
+            return probe.totalRemoteFiles;
+        },
+    };
+    const deps = {
+        async mintWriteToken(requestedTarget) {
+            const resp = await mintGiteaToken(requestedTarget, 'write', 'push');
+            // Stash the authenticated URL so the bare-path gitOps methods can
+            // probe-clone it without a second mint.
+            authenticatedRepoUrl = resp.repoUrl;
+            return giteaResponseToMintResult(resp);
+        },
+        async validate(dir) {
+            const { validateWorkspace } = await import('../verify/validate.js');
+            const result = validateWorkspace(dir);
+            const errors = result.issues.filter((i) => i.severity === 'error').map((i) => i.message);
+            return { errors };
+        },
+        gitOps,
+        copyDirMirror,
+        log,
+        errLog,
+    };
+    const cleanup = async () => {
+        if (!barePathProbe)
+            return;
+        try {
+            fs.rmSync(barePathProbe.scratchDir, { force: true, recursive: true });
+        }
+        catch {
+            /* ignore — cleanup is best-effort */
+        }
+    };
+    return { deps, cleanup };
+}
+/**
+ * Diff the working tree (what we are about to push) against origin/main. We
+ * use `git diff --name-status HEAD..origin/main` with inverted semantics:
+ *   Added here  = present locally (in HEAD), absent in origin/main.
+ *   Deleted     = absent locally, present in origin/main.
+ *   Modified    = content differs.
+ *
+ * `git diff A..B` reports B relative to A. So `HEAD..origin/main` tells us
+ * what origin has that we don't. We want "local vs remote" with local as the
+ * baseline — i.e. origin/main..HEAD.
+ */
+async function diffHeadVsOrigin(dir) {
+    // origin/main..HEAD reports changes HEAD has relative to origin/main.
+    // 'A' -> added locally, 'D' -> deleted locally, 'M' -> modified locally.
+    const { stdout } = await execFile('git', [
+        '-C',
+        dir,
+        'diff',
+        '--name-status',
+        'origin/main..HEAD',
+    ]);
+    const deltas = [];
+    for (const raw of stdout.split('\n')) {
+        const line = raw.trim();
+        if (!line)
+            continue;
+        const [status, ...rest] = line.split(/\s+/);
+        const pathStr = rest.join(' ');
+        if (!pathStr)
+            continue;
+        if (status.startsWith('A'))
+            deltas.push({ kind: 'added', path: pathStr });
+        else if (status.startsWith('D'))
+            deltas.push({ kind: 'deleted', path: pathStr });
+        else if (status.startsWith('M') || status.startsWith('R') || status.startsWith('C')) {
+            // Treat renames / copies as modifications for diff-summary purposes.
+            deltas.push({ kind: 'modified', path: pathStr });
+        }
+    }
+    return deltas;
+}
+async function countTrackedFilesAtRef(dir, ref) {
+    try {
+        const { stdout } = await execFile('git', ['-C', dir, 'ls-tree', '-r', '--name-only', ref]);
+        return stdout.split('\n').filter((l) => l.trim().length > 0).length;
+    }
+    catch {
+        return 0;
+    }
+}
+async function readLocalAuthor(dir) {
+    try {
+        const { stdout: name } = await execFile('git', ['-C', dir, 'config', 'user.name']);
+        const { stdout: email } = await execFile('git', ['-C', dir, 'config', 'user.email']);
+        const n = name.trim();
+        const e = email.trim();
+        if (!n || !e)
+            return undefined;
+        return { name: n, email: e };
+    }
+    catch {
+        return undefined;
+    }
+}
+/**
+ * Copy the contents of `sourceDir` into `destDir`, skipping `.git/` and any
+ * temp push-clone scratch directories. Used as the `applyDelta` callback for
+ * bare-path pushes — we mirror local files into a fresh clone so that
+ * `cloneAndStackPush`'s `git add --all` + diff will reflect the union of
+ * (deletes, modifies, adds) we intend.
+ *
+ * IMPORTANT: this deletes files in destDir that are not in sourceDir so that
+ * deletions make it into the push. Without this the clone-and-stack produces
+ * an "adds-only" delta and destructive heuristics would never fire in the UI.
+ */
+export async function copyDirMirror(sourceDir, destDir) {
+    // Collect source entries (except .git, .quonfig-push-clone-*)
+    const sourceRel = collectRelPaths(sourceDir);
+    const destRel = collectRelPaths(destDir);
+    // Delete anything in dest that isn't in source
+    for (const rel of destRel) {
+        if (!sourceRel.has(rel)) {
+            const full = path.join(destDir, rel);
+            try {
+                fs.rmSync(full, { force: true });
+            }
+            catch {
+                /* ignore */
+            }
+        }
+    }
+    // Copy / overwrite everything from source into dest
+    for (const rel of sourceRel) {
+        const src = path.join(sourceDir, rel);
+        const dst = path.join(destDir, rel);
+        fs.mkdirSync(path.dirname(dst), { recursive: true });
+        fs.copyFileSync(src, dst);
+    }
+}
+function collectRelPaths(root) {
+    const out = new Set();
+    if (!fs.existsSync(root))
+        return out;
+    const walk = (dir, prefix) => {
+        for (const entry of fs.readdirSync(dir, { withFileTypes: true })) {
+            if (entry.name === '.git')
+                continue;
+            if (entry.name.startsWith('.quonfig-push-clone-'))
+                continue;
+            const rel = prefix ? `${prefix}/${entry.name}` : entry.name;
+            const full = path.join(dir, entry.name);
+            if (entry.isDirectory()) {
+                walk(full, rel);
+            }
+            else if (entry.isFile() || entry.isSymbolicLink()) {
+                out.add(rel);
+            }
+        }
+    };
+    walk(root, '');
+    return out;
+}

package/dist/commands/workspace/bootstrap.d.ts

@@ -9,5 +9,12 @@ export default class WorkspaceBootstrap extends BaseCommand {
         'skip-validate': import("@oclif/core/lib/interfaces/parser.js").BooleanFlag<boolean>;
     };
     run(): Promise<JsonObj | void>;
+    /**
+     * Stage, commit, and push the `quonfig.json` pin. Runs after the main
+     * bootstrap push so the pin lands as a committed+pushed change rather than
+     * an uncommitted local edit. We stage only `quonfig.json` (not `-A`) so we
+     * don't accidentally sweep in unrelated user edits.
+     */
+    private commitAndPushPin;
     private remoteHasCommits;
 }

package/dist/commands/workspace/bootstrap.js

@@ -4,6 +4,7 @@ import { Flags } from '@oclif/core';
 import { BaseCommand } from '../../index.js';
 import { getActiveProfile, loadAuthConfig } from '../../util/token-storage.js';
 import { mintGiteaToken } from '../../util/gitea-api.js';
+import { readWorkspaceSlug, writeWorkspaceSlug } from '../../util/quonfig-json.js';
 import { isGitRepo, hasAtLeastOneCommit, gitSetRemote, gitPushForceLease, gitPushForce, getRemoteUrl, displayUrl, } from '../../util/git-ops.js';
 export default class WorkspaceBootstrap extends BaseCommand {
     static description = "Push a local git repo to Gitea as this workspace's config repository";
@@ -102,8 +103,8 @@ export default class WorkspaceBootstrap extends BaseCommand {
         catch (error) {
             return this.err(`Could not get Gitea credentials: ${String(error)}\n\nMake sure the workspace is fully provisioned in the Quonfig app before bootstrapping.`);
         }
-        const { repoUrl } = tokenData;
-        this.verboseLog('WorkspaceBootstrap', { repoUrl: displayUrl(repoUrl) });
+        const { repoUrl, workspaceSlug: backendSlug } = tokenData;
+        this.verboseLog('WorkspaceBootstrap', { repoUrl: displayUrl(repoUrl), backendSlug });
         // Idempotency: check if remote already has commits
         if (!flags.force) {
             const remoteHasCommits = await this.remoteHasCommits(repoUrl);
@@ -135,6 +136,35 @@ export default class WorkspaceBootstrap extends BaseCommand {
         catch (error) {
             return this.err(`Push failed: ${String(error)}`);
         }
+        // Write the workspace pin into `quonfig.json` (Guard 1 in
+        // project/plans/cli-git-sync.md). If the pin already exists and disagrees,
+        // we keep what is there — bootstrap is for fresh cases, not re-pinning.
+        // If we do write it, commit and push so the bootstrap leaves no
+        // uncommitted changes behind.
+        try {
+            const existingPin = await readWorkspaceSlug(resolvedDir);
+            if (existingPin && existingPin !== backendSlug) {
+                this.log('');
+                this.log(`Warning: quonfig.json already pins workspace "${existingPin}", but the backend says this workspace is "${backendSlug}".`);
+                this.log('Leaving the existing pin in place. If this is wrong, edit quonfig.json manually and re-run.');
+            }
+            else if (existingPin === backendSlug) {
+                this.verboseLog('WorkspaceBootstrap', `quonfig.json already pinned to ${backendSlug}; no-op.`);
+            }
+            else {
+                this.log('');
+                this.log(`Pinning quonfig.json to workspace "${backendSlug}"...`);
+                await writeWorkspaceSlug(resolvedDir, backendSlug);
+                await this.commitAndPushPin(resolvedDir, backendSlug, flags.force);
+            }
+        }
+        catch (error) {
+            // The main push has already succeeded, so don't fail the whole command.
+            // Surface the issue clearly so the user knows to follow up.
+            this.log('');
+            this.log(`Warning: could not write the workspace pin to quonfig.json: ${String(error)}`);
+            this.log('The workspace is connected, but you should re-run `qfg pull` to backfill the pin.');
+        }
         this.log(`\nBootstrap complete.`);
         this.log(`Workspace "${workspaceName}" is now connected to your local directory.`);
         this.log(`\nTo keep it in sync locally, run:`);
@@ -145,6 +175,32 @@ export default class WorkspaceBootstrap extends BaseCommand {
             workspaceId,
         };
     }
+    /**
+     * Stage, commit, and push the `quonfig.json` pin. Runs after the main
+     * bootstrap push so the pin lands as a committed+pushed change rather than
+     * an uncommitted local edit. We stage only `quonfig.json` (not `-A`) so we
+     * don't accidentally sweep in unrelated user edits.
+     */
+    async commitAndPushPin(dir, slug, force) {
+        const { execFile: execFileCb } = await import('node:child_process');
+        const util = await import('node:util');
+        const execFile = util.promisify(execFileCb);
+        // Stage just quonfig.json so we don't accidentally commit other dirty files.
+        await execFile('git', ['-C', dir, 'add', 'quonfig.json']);
+        // If `git add` produced no staged change (e.g. content matched an earlier
+        // version on disk), `git commit` would fail. Check the index first.
+        const { stdout: diffStat } = await execFile('git', ['-C', dir, 'diff', '--cached', '--name-only']);
+        if (!diffStat.trim()) {
+            this.verboseLog('WorkspaceBootstrap', 'quonfig.json pin matches HEAD; no commit needed.');
+            return;
+        }
+        await execFile('git', ['-C', dir, 'commit', '-m', `chore: pin quonfig.json to workspace "${slug}"`]);
+        // Push the new commit using the same force semantics as the main push.
+        const pushArgs = ['-C', dir, 'push', 'origin', 'main'];
+        pushArgs.push(force ? '--force' : '--force-with-lease');
+        await execFile('git', pushArgs);
+        this.log(`Pushed pin commit.`);
+    }
     async remoteHasCommits(repoUrl) {
         const { execFile: execFileCb } = await import('node:child_process');
         const util = await import('node:util');

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 './push-strategy.js';
+import { type PushIdentity } from '../util/clone-and-stack-push.js';
 import type { LegacyChange, MigrationSource } from './source.js';
 export interface ApplyLocalMigrationOptions {
     /** Commit author. Defaults to the migrator identity. */

package/dist/migrate/local-write.js

@@ -4,7 +4,7 @@ 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';
+import { MIGRATOR_IDENTITY } from '../util/clone-and-stack-push.js';
 const execFile = util.promisify(execFileCb);
 const isGitRepo = async (dir) => {
     try {

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

@@ -1,6 +1,6 @@
 import { type ImportState } from './import-state.js';
 import { type MigrationReportData } from './migration-report.js';
-import { type CloneAndStackPushResult } from './push-strategy.js';
+import { type CloneAndStackPushResult } from '../util/clone-and-stack-push.js';
 import type { LegacyChange, MigrationSource } from './source.js';
 export interface PushMigrationToCloudOptions {
     branch?: string;

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

@@ -2,7 +2,7 @@ import * as fs from 'node:fs';
 import * as path from 'node:path';
 import { removeQfFromGitignore, writeImportState } from './import-state.js';
 import { writeMigrationReport } from './migration-report.js';
-import { cloneAndStackPush } from './push-strategy.js';
+import { cloneAndStackPush } from '../util/clone-and-stack-push.js';
 const writeQuonfigFiles = (dir, changes, source) => {
     for (const change of changes) {
         const files = source.translate(change);

package/dist/push/bare-path-diff.d.ts

@@ -0,0 +1,40 @@
+/**
+ * Bare-path diff helper for `qfg push`.
+ *
+ * When the user's local dir is NOT a clone of the cloud repo (no `.git/`, or
+ * a mismatched origin) we still need to show a Guard 3 diff summary BEFORE
+ * asking them to confirm the push. The clone-path implementation uses
+ * `git log origin/main..HEAD` — that doesn't work here because there is no
+ * origin in the local dir.
+ *
+ * Strategy: probe-clone the cloud repo into an OS tmpdir, then walk both
+ * trees file-by-file and classify each as added / modified / deleted.
+ *
+ * The caller owns cleanup of `scratchDir`. The real caller (buildRealDeps in
+ * `commands/push.ts`) stashes the scratch clone path on a closure so it can
+ * delete it in a finally-block after runPush resolves — matching the bare
+ * path's existing scratch-clone lifecycle in `run-push.ts`.
+ *
+ * Intentional non-goals:
+ *   - No token handling. Caller passes a fully-authenticated `remoteUrl`.
+ *   - No filtering to "known" workspace dirs (configs/, feature-flags/, ...).
+ *     We exclude dotfiles/dotdirs (`.git`, `.DS_Store`, `.quonfig-*`) so the
+ *     scratch clone's own `.git/` does not leak into the diff, but otherwise
+ *     diff whatever is on disk. This keeps the diff surface consistent with
+ *     `copyDirMirror` in `commands/push.ts`, which mirrors every non-dotfile
+ *     into the real push clone.
+ */
+import { FileDelta } from './diff-summary.js';
+export interface BarePathDiffResult {
+    deltas: FileDelta[];
+    /** Tmp dir holding the probe clone. Caller must rm -rf in a finally block. */
+    scratchDir: string;
+    /** Total file count in the scratch clone (under the same prefix rules as `deltas`). */
+    totalRemoteFiles: number;
+}
+/**
+ * Clone `remoteUrl` into an OS tmp dir, then diff the working tree of `localDir`
+ * against the scratch clone's working tree. Returns `FileDelta[]` plus the
+ * scratch clone's file count.
+ */
+export declare function computeBarePathDiff(localDir: string, remoteUrl: string): Promise<BarePathDiffResult>;

package/dist/push/bare-path-diff.js

@@ -0,0 +1,126 @@
+/**
+ * Bare-path diff helper for `qfg push`.
+ *
+ * When the user's local dir is NOT a clone of the cloud repo (no `.git/`, or
+ * a mismatched origin) we still need to show a Guard 3 diff summary BEFORE
+ * asking them to confirm the push. The clone-path implementation uses
+ * `git log origin/main..HEAD` — that doesn't work here because there is no
+ * origin in the local dir.
+ *
+ * Strategy: probe-clone the cloud repo into an OS tmpdir, then walk both
+ * trees file-by-file and classify each as added / modified / deleted.
+ *
+ * The caller owns cleanup of `scratchDir`. The real caller (buildRealDeps in
+ * `commands/push.ts`) stashes the scratch clone path on a closure so it can
+ * delete it in a finally-block after runPush resolves — matching the bare
+ * path's existing scratch-clone lifecycle in `run-push.ts`.
+ *
+ * Intentional non-goals:
+ *   - No token handling. Caller passes a fully-authenticated `remoteUrl`.
+ *   - No filtering to "known" workspace dirs (configs/, feature-flags/, ...).
+ *     We exclude dotfiles/dotdirs (`.git`, `.DS_Store`, `.quonfig-*`) so the
+ *     scratch clone's own `.git/` does not leak into the diff, but otherwise
+ *     diff whatever is on disk. This keeps the diff surface consistent with
+ *     `copyDirMirror` in `commands/push.ts`, which mirrors every non-dotfile
+ *     into the real push clone.
+ */
+import { execFile as execFileCb } from 'node:child_process';
+import { createHash } from 'node:crypto';
+import * as fs from 'node:fs';
+import * as os from 'node:os';
+import * as path from 'node:path';
+import * as util from 'node:util';
+const execFile = util.promisify(execFileCb);
+/**
+ * Clone `remoteUrl` into an OS tmp dir, then diff the working tree of `localDir`
+ * against the scratch clone's working tree. Returns `FileDelta[]` plus the
+ * scratch clone's file count.
+ */
+export async function computeBarePathDiff(localDir, remoteUrl) {
+    const scratchDir = await fs.promises.mkdtemp(path.join(os.tmpdir(), 'qfg-push-probe-'));
+    try {
+        // --depth 1 would miss information needed for later identity checks, but
+        // for the diff we only need the tip — shallow is fine and a lot faster on
+        // workspaces with 2 years of history.
+        await execFile('git', ['clone', '--branch', 'main', '--depth', '1', remoteUrl, scratchDir]);
+    }
+    catch (error) {
+        // Clean up before re-throwing so we never leak a scratch dir on failure.
+        try {
+            fs.rmSync(scratchDir, { force: true, recursive: true });
+        }
+        catch {
+            /* ignore */
+        }
+        throw error;
+    }
+    const localFiles = collectFilesWithHash(localDir);
+    const remoteFiles = collectFilesWithHash(scratchDir);
+    const deltas = [];
+    for (const [rel, localHash] of localFiles) {
+        const remoteHash = remoteFiles.get(rel);
+        if (remoteHash === undefined) {
+            deltas.push({ kind: 'added', path: rel });
+        }
+        else if (remoteHash !== localHash) {
+            deltas.push({ kind: 'modified', path: rel });
+        }
+    }
+    for (const rel of remoteFiles.keys()) {
+        if (!localFiles.has(rel)) {
+            deltas.push({ kind: 'deleted', path: rel });
+        }
+    }
+    return { deltas, scratchDir, totalRemoteFiles: remoteFiles.size };
+}
+/**
+ * Walk `root` and return a map of relative-path -> content-hash for every
+ * non-dotfile file under it.
+ *
+ * We skip any entry whose name starts with a `.`, which covers `.git/`,
+ * `.DS_Store`, and the transient `.quonfig-push-clone-*` scratch dirs that
+ * `run-push.ts` creates next to the local workspace. Keeping the rule simple
+ * and symmetric on both sides prevents one-off false positives.
+ */
+function collectFilesWithHash(root) {
+    const out = new Map();
+    if (!fs.existsSync(root))
+        return out;
+    const walk = (dir, prefix) => {
+        let entries;
+        try {
+            entries = fs.readdirSync(dir, { withFileTypes: true });
+        }
+        catch {
+            return;
+        }
+        for (const entry of entries) {
+            if (entry.name.startsWith('.'))
+                continue;
+            const rel = prefix ? `${prefix}/${entry.name}` : entry.name;
+            const full = path.join(dir, entry.name);
+            if (entry.isDirectory()) {
+                walk(full, rel);
+            }
+            else if (entry.isFile() || entry.isSymbolicLink()) {
+                try {
+                    const buf = fs.readFileSync(full);
+                    out.set(rel, hashBytes(buf));
+                }
+                catch {
+                    /* ignore unreadable files — they won't appear on either side */
+                }
+            }
+        }
+    };
+    walk(root, '');
+    return out;
+}
+/**
+ * Content hash. We don't need cryptographic strength — just a stable
+ * fingerprint so we can say "file A on local matches file A on remote". The
+ * contents are small JSON in practice, so sha1 is plenty fast.
+ */
+function hashBytes(buf) {
+    return createHash('sha1').update(buf).digest('hex');
+}