@quonfig/cli 0.0.14 → 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/commands/workspace/switch.d.ts

@@ -1,6 +1,9 @@
 import type { JsonObj } from '../../result.js';
 import { BaseCommand } from '../../index.js';
 export default class WorkspaceSwitch extends BaseCommand {
+    static args: {
+        slug: import("@oclif/core/lib/interfaces/parser.js").Arg<string | undefined, Record<string, unknown>>;
+    };
     static description: string;
     static examples: string[];
     run(): Promise<JsonObj | void>;

package/dist/commands/workspace/switch.js

@@ -1,12 +1,24 @@
+import { Args } from '@oclif/core';
 import { select } from '@inquirer/prompts';
 import { BaseCommand } from '../../index.js';
 import { getApiUrl } from '../../util/domain-urls.js';
 import { getValidAccessToken } from '../../util/get-valid-token.js';
 import { loadAuthConfig, saveAuthConfig } from '../../util/token-storage.js';
+const UUID_PATTERN = /^[\da-f]{8}(?:-[\da-f]{4}){3}-[\da-f]{12}$/i;
 export default class WorkspaceSwitch extends BaseCommand {
+    static args = {
+        slug: Args.string({
+            description: 'Workspace slug (or UUID) to switch to. Omit for an interactive picker.',
+            required: false,
+        }),
+    };
     static description = 'Switch to a different workspace';
-    static examples = ['<%= config.bin %> <%= command.id %>'];
+    static examples = [
+        '<%= config.bin %> <%= command.id %>',
+        '<%= config.bin %> <%= command.id %> my-workspace-slug',
+    ];
     async run() {
+        const { args } = await this.parse(WorkspaceSwitch);
         // Get a valid token — refresh silently if needed, error if not logged in
         let accessToken;
         try {
@@ -44,9 +56,19 @@ export default class WorkspaceSwitch extends BaseCommand {
         if (candidates.length === 0) {
             return this.err('No workspaces found for your account.');
         }
-        // Pick workspace
+        // Pick workspace: positional arg → interactive picker → auto-select if only one
         let match;
-        if (candidates.length === 1) {
+        if (args.slug) {
+            const found = UUID_PATTERN.test(args.slug)
+                ? candidates.find((w) => w.workspaceId === args.slug)
+                : candidates.find((w) => w.workspaceSlug === args.slug);
+            if (!found) {
+                const available = candidates.map((w) => w.workspaceSlug).join(', ') || '(none)';
+                return this.err(`Workspace "${args.slug}" not found. Available: ${available}.`);
+            }
+            match = found;
+        }
+        else if (candidates.length === 1) {
             match = candidates[0];
             this.log(`Only one workspace available: ${match.organizationName} / ${match.workspaceSlug}`);
         }

package/dist/commands/workspace.d.ts

@@ -4,4 +4,5 @@ export default class Workspace extends BaseCommand {
     static description: string;
     static examples: string[];
     run(): Promise<JsonObj | void>;
+    private runApiKeyMode;
 }

package/dist/commands/workspace.js

@@ -1,9 +1,18 @@
 import { BaseCommand } from '../index.js';
+import { getApiUrl } from '../util/domain-urls.js';
+import { getValidAccessToken } from '../util/get-valid-token.js';
 import { getActiveProfile, loadAuthConfig } from '../util/token-storage.js';
+const UUID_PATTERN = /^[\da-f]{8}(?:-[\da-f]{4}){3}-[\da-f]{12}$/i;
 export default class Workspace extends BaseCommand {
     static description = 'Show the current workspace';
     static examples = ['<%= config.bin %> <%= command.id %>'];
     async run() {
+        // API-key mode: resolve the workspace from QUONFIG_WORKSPACE via the server
+        // so we show the workspace the key is actually scoped to, not whatever
+        // the local OAuth config happens to point at.
+        if (process.env.QUONFIG_API_KEY) {
+            return this.runApiKeyMode();
+        }
         const authConfig = await loadAuthConfig();
         if (!authConfig || Object.keys(authConfig.profiles).length === 0) {
             return this.err('Not logged in. Run `qfg login` first.');
@@ -26,4 +35,50 @@ export default class Workspace extends BaseCommand {
             workspaceSlug,
         };
     }
+    async runApiKeyMode() {
+        const override = process.env.QUONFIG_WORKSPACE;
+        if (!override) {
+            return this.err('QUONFIG_API_KEY is set but QUONFIG_WORKSPACE is not. Set QUONFIG_WORKSPACE=<workspace-slug> (UUIDs also work).');
+        }
+        // getValidAccessToken short-circuits when QUONFIG_API_KEY is set.
+        let jwt;
+        try {
+            jwt = await getValidAccessToken();
+        }
+        catch (error) {
+            return this.err(error instanceof Error ? error.message : String(error));
+        }
+        let entries = [];
+        try {
+            const res = await fetch(`${getApiUrl()}/api/v1/userWorkspaces/list`, {
+                method: 'POST',
+                headers: { Authorization: `Bearer ${jwt}`, 'Content-Type': 'application/json' },
+                body: JSON.stringify({ json: {} }),
+            });
+            if (!res.ok) {
+                return this.err(`Failed to resolve workspace (HTTP ${res.status}). Check that QUONFIG_API_KEY is valid.`);
+            }
+            const body = (await res.json());
+            entries = body.json ?? body ?? [];
+        }
+        catch (error) {
+            return this.err(`Failed to resolve workspace "${override}": ${error instanceof Error ? error.message : String(error)}`);
+        }
+        const match = UUID_PATTERN.test(override)
+            ? entries.find((w) => w.workspaceId === override)
+            : entries.find((w) => w.workspaceSlug === override);
+        if (!match) {
+            const available = entries.map((w) => w.workspaceSlug).join(', ') || '(none)';
+            return this.err(`Workspace "${override}" not accessible with this API key. Available: ${available}.`);
+        }
+        const orgLine = match.organizationName ? `${match.organizationName} / ` : '';
+        this.log(`Workspace:    ${orgLine}${match.workspaceSlug}  (API key mode)`);
+        this.log(`ID:           ${match.workspaceId}`);
+        this.log(`Source:       QUONFIG_API_KEY + QUONFIG_WORKSPACE=${override}`);
+        return {
+            organizationName: match.organizationName,
+            workspace: match.workspaceId,
+            workspaceSlug: match.workspaceSlug,
+        };
+    }
 }

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);