@quonfig/cli 0.0.15 → 0.0.17

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

@@ -0,0 +1,107 @@
+/**
+ * Core logic for `qfg push`. Pure-ish, dependency-injected, so tests can drive
+ * it without hitting the network, touching git, or running validation.
+ *
+ * The oclif command (`src/commands/push.ts`) is a thin wrapper that fills in
+ * real implementations of every dependency and calls `runPush`.
+ *
+ * The three guards from `project/plans/cli-git-sync.md` are all enforced here:
+ *   - Guards 1 + 2: `checkIdentity` cross-checks the requested target, repo
+ *     pin, and git origin against the backend-resolved workspace.
+ *   - Guard 3: `summarizeDiff` + `confirmYesNo`/`confirmTypedSlug` force the
+ *     user to acknowledge destructive changes.
+ *
+ * Dispatch between the "clone path" (the local dir is a clone of the cloud
+ * repo) and the "bare path" (anything else — no .git, or a mismatched origin)
+ * is decided after identity passes.
+ *
+ * `--yes` skips the normal Y/N confirmation. It NEVER skips a typed-slug
+ * confirmation — that prompt is the destructive-change brake.
+ */
+import { PushIdentity } from '../util/clone-and-stack-push.js';
+import { FileDelta } from './diff-summary.js';
+export interface GiteaTokenMintResult {
+    expiresAt: string | null;
+    repoUrl: string;
+    token: string;
+    workspaceId: string;
+    workspaceSlug: string;
+}
+export interface GitOps {
+    /** Number of tracked files on origin/main (used for the destructive-ratio heuristic). */
+    countFilesInRemote(dir: string): Promise<number>;
+    /**
+     * Produce the list of file deltas to render in the Guard 3 summary and
+     * (for the bare path) commit. For the clone path this is HEAD vs origin/main.
+     * For the bare path the caller hands us the deltas itself.
+     */
+    diffHeadVsOrigin(dir: string): Promise<FileDelta[]>;
+    /** `git fetch origin` in the given dir. */
+    fetch(dir: string): Promise<void>;
+    /** Read local git config for author identity (used for bare-path commits). */
+    getLocalAuthor(dir: string): Promise<PushIdentity | undefined>;
+    /** Returns the `remote.origin.url` for the repo, or undefined if unset / not a repo. */
+    getRemoteOriginUrl(dir: string): Promise<string | undefined>;
+    /** Returns true if the dir has a `.git/` (worktree or repo). */
+    isGitRepo(dir: string): Promise<boolean>;
+    /** `git push origin main`. Throws with a PushConflict-ish message on non-ff. */
+    push(dir: string): Promise<void>;
+    /** Set origin to `url` (add if missing, set-url if present). */
+    setRemoteOrigin(dir: string, url: string): Promise<void>;
+}
+export type ConfirmIO = {
+    input?: NodeJS.ReadableStream;
+    output?: NodeJS.WritableStream;
+};
+export interface RunPushInput {
+    /** Absolute path to the local dir the user is pushing. */
+    dir: string;
+    /** `--message` — optional commit message override (bare path only). */
+    message?: string;
+    /** `--no-pin-write` — do not offer to write the slug pin into quonfig.json. */
+    noPinWrite: boolean;
+    /** `--workspace` flag, or the active profile's workspace UUID. Must be non-empty. */
+    requestedTarget: string;
+    /** `--skip-validate` — suppress the validate step. */
+    skipValidate: boolean;
+    /** `--yes` — skip standard Y/N confirm. Never skips typed-slug. */
+    yes: boolean;
+}
+export interface RunPushDeps {
+    /** Optional io streams for confirmation prompts. Defaults to process stdin/stdout. */
+    confirmIO?: ConfirmIO;
+    /**
+     * Copy files from `sourceDir` into `destDir`, skipping `.git/`. Used by the
+     * bare path as the `applyDelta` callback handed to `cloneAndStackPush`.
+     */
+    copyDirMirror(sourceDir: string, destDir: string): Promise<void>;
+    /** Error logger; defaults to console.error. */
+    errLog?: (line: string) => void;
+    gitOps: GitOps;
+    /** Logger; defaults to console.log. */
+    log?: (line: string) => void;
+    /** Mint a write token via the backend. */
+    mintWriteToken(requestedTarget: string): Promise<GiteaTokenMintResult>;
+    /** Run `qfg validate` semantics. Should throw on error. */
+    validate(dir: string): Promise<{
+        errors: string[];
+    }>;
+}
+export type RunPushResult = {
+    kind: 'aborted';
+    reason: string;
+} | {
+    kind: 'pushed';
+    dispatchedAs: 'clone-path' | 'bare-path';
+    commitSha?: string | null;
+} | {
+    kind: 'no-op';
+    reason: string;
+};
+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. */
+export declare const withPushedViaTrailer: (message: string) => string;
+export declare function runPush(input: RunPushInput, deps: RunPushDeps): Promise<RunPushResult>;

package/dist/push/run-push.js

@@ -0,0 +1,318 @@
+/**
+ * Core logic for `qfg push`. Pure-ish, dependency-injected, so tests can drive
+ * it without hitting the network, touching git, or running validation.
+ *
+ * The oclif command (`src/commands/push.ts`) is a thin wrapper that fills in
+ * real implementations of every dependency and calls `runPush`.
+ *
+ * The three guards from `project/plans/cli-git-sync.md` are all enforced here:
+ *   - Guards 1 + 2: `checkIdentity` cross-checks the requested target, repo
+ *     pin, and git origin against the backend-resolved workspace.
+ *   - Guard 3: `summarizeDiff` + `confirmYesNo`/`confirmTypedSlug` force the
+ *     user to acknowledge destructive changes.
+ *
+ * Dispatch between the "clone path" (the local dir is a clone of the cloud
+ * repo) and the "bare path" (anything else — no .git, or a mismatched origin)
+ * is decided after identity passes.
+ *
+ * `--yes` skips the normal Y/N confirmation. It NEVER skips a typed-slug
+ * confirmation — that prompt is the destructive-change brake.
+ */
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+import { MIGRATOR_IDENTITY, cloneAndStackPush } from '../util/clone-and-stack-push.js';
+import { readWorkspaceSlug, writeWorkspaceSlug } from '../util/quonfig-json.js';
+import { checkIdentity } from './identity-check.js';
+import { confirmTypedSlug, confirmYesNo } from './confirm.js';
+import { summarizeDiff } from './diff-summary.js';
+export class PushFatalError extends Error {
+    code;
+    constructor(message, code = 'PUSH_FATAL') {
+        super(message);
+        this.code = code;
+        this.name = 'PushFatalError';
+    }
+}
+/**
+ * Normalize a git remote URL for case-insensitive-host comparison. Mirrors
+ * the logic in `identity-check.ts` but we only need the boolean "do these
+ * point at the same repo" answer.
+ */
+const normalizeForCompare = (url) => {
+    const stripped = url.replace(/^([a-z][\d+.a-z-]*:\/\/)[^/@]+@/i, '$1');
+    try {
+        const u = new URL(stripped);
+        const host = u.host.toLowerCase();
+        const pathname = u.pathname.replace(/\/+$/, '').replace(/\.git$/, '');
+        return `${u.protocol}//${host}${pathname}`;
+    }
+    catch {
+        return url.trim();
+    }
+};
+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`;
+};
+export async function runPush(input, deps) {
+    const log = deps.log ?? ((s) => console.log(s));
+    const errLog = deps.errLog ?? ((s) => console.error(s));
+    if (!input.requestedTarget || input.requestedTarget.trim().length === 0) {
+        throw new PushFatalError('No workspace target set. Pass --workspace or run `qfg login` to set the active profile workspace.', 'NO_TARGET');
+    }
+    if (!fs.existsSync(input.dir)) {
+        throw new PushFatalError(`Directory does not exist: ${input.dir}`, 'NO_DIR');
+    }
+    // Guard 1 pre-work: read repo pin + current origin BEFORE we mint a write
+    // token. The identity check happens after minting (so we can cross-reference
+    // the backend's canonical identity) but we want the pin/origin up front.
+    const repoPinSlug = await readWorkspaceSlug(input.dir);
+    const hasGit = await deps.gitOps.isGitRepo(input.dir);
+    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.
+    const backend = await deps.mintWriteToken(input.requestedTarget);
+    // Guards 1 + 2: cross-check the three identity signals.
+    const identity = checkIdentity({
+        requestedTarget: input.requestedTarget,
+        repoPinSlug,
+        remoteOriginUrl,
+        backend: {
+            workspaceSlug: backend.workspaceSlug,
+            workspaceId: backend.workspaceId,
+            repoUrl: backend.repoUrl,
+        },
+    });
+    if (identity.kind === 'abort') {
+        errLog(`Identity check failed: ${identity.reason}`);
+        for (const [k, v] of Object.entries(identity.details)) {
+            errLog(`  ${k}: ${v}`);
+        }
+        errLog('Refusing to push. --yes does not override this.');
+        throw new PushFatalError(`identity check: ${identity.reason}`, 'IDENTITY_ABORT');
+    }
+    const requiresTypedSlug = identity.kind === 'requires-typed-slug-confirmation';
+    // Guard: validation. Skipped with --skip-validate.
+    if (!input.skipValidate) {
+        log('Verifying config files...');
+        const result = await deps.validate(input.dir);
+        if (result.errors.length > 0) {
+            errLog(`Found ${result.errors.length} validation error(s):`);
+            for (const msg of result.errors)
+                errLog(`  ${msg}`);
+            throw new PushFatalError('validation failed; pass --skip-validate to bypass', 'VALIDATION_FAILED');
+        }
+        log('Validation passed.');
+    }
+    // Dispatch: clone path vs bare path.
+    //
+    // Clone path: the dir has a `.git/` AND its origin normalizes to the
+    // backend.repoUrl. We push HEAD directly.
+    //
+    // Bare path: no `.git/`, OR the origin points elsewhere. We clone the cloud
+    // repo into a scratch dir inside `.quonfig-push-clone/` and stack a commit
+    // that mirrors the local dir's contents on top.
+    const isClonePath = hasGit && remoteOriginUrl !== undefined && sameRepo(remoteOriginUrl, backend.repoUrl);
+    if (isClonePath) {
+        return doClonePath(input, deps, backend, requiresTypedSlug, repoPinSlug === undefined, log);
+    }
+    return doBarePath(input, deps, backend, requiresTypedSlug, repoPinSlug === undefined, log);
+}
+async function doClonePath(input, deps, backend, requiresTypedSlug, unpinned, log) {
+    // Point origin at the authenticated URL so `git fetch` / `git push` work
+    // without touching global credential helpers.
+    await deps.gitOps.setRemoteOrigin(input.dir, backend.repoUrl);
+    log('Fetching from remote...');
+    await deps.gitOps.fetch(input.dir);
+    const deltas = await deps.gitOps.diffHeadVsOrigin(input.dir);
+    const totalFilesInRemote = await deps.gitOps.countFilesInRemote(input.dir);
+    const summary = summarizeDiff(deltas, { totalFilesInRemote, unpinned });
+    log('');
+    log(summary.renderText({
+        workspaceSlug: backend.workspaceSlug,
+        repoUrl: stripAuth(backend.repoUrl),
+        branch: 'main',
+        localDir: input.dir,
+    }));
+    log('');
+    // Short-circuit: literally nothing to push.
+    if (summary.totals.filesTouched === 0) {
+        return { kind: 'no-op', reason: 'Local tree matches remote HEAD. Nothing to push.' };
+    }
+    const ok = await decideConfirm({
+        destructive: summary.isDestructive,
+        requiresTypedSlug,
+        yes: input.yes,
+        workspaceSlug: backend.workspaceSlug,
+        confirmIO: deps.confirmIO,
+    });
+    if (!ok) {
+        log('Aborted, nothing pushed.');
+        return { kind: 'aborted', reason: 'user declined at confirm prompt' };
+    }
+    log('Pushing to origin/main...');
+    try {
+        await deps.gitOps.push(input.dir);
+    }
+    catch (error) {
+        const msg = error instanceof Error ? error.message : String(error);
+        if (/non-fast-forward|fetch first|rejected/i.test(msg)) {
+            throw new PushFatalError('Remote has changes not in local — run `qfg pull` first, then re-run `qfg push`.', 'NON_FAST_FORWARD');
+        }
+        throw new PushFatalError(`Push failed: ${msg}`, 'PUSH_FAILED');
+    }
+    // Offer to pin the workspace slug in quonfig.json if missing. Non-fatal.
+    if (unpinned && !input.noPinWrite) {
+        try {
+            await writeWorkspaceSlug(input.dir, backend.workspaceSlug);
+            log(`Wrote workspace = "${backend.workspaceSlug}" into quonfig.json`);
+        }
+        catch {
+            // non-fatal; pin is advisory
+        }
+    }
+    return { kind: 'pushed', dispatchedAs: 'clone-path' };
+}
+async function doBarePath(input, deps, backend, requiresTypedSlug, unpinned, log) {
+    // Scratch clone location: sibling `.quonfig-push-clone-<timestamp>` so we
+    // don't clobber or re-use anything from a previous run.
+    const scratchDir = path.join(path.dirname(path.resolve(input.dir)), `.quonfig-push-clone-${Date.now()}`);
+    // Local author for the migrated commit. Prefer the local git config in
+    // `input.dir` so attribution matches what the user has set. If it is not
+    // available, fall back to the migrator identity but tell the user — the plan
+    // requires this be loud.
+    let author = MIGRATOR_IDENTITY;
+    try {
+        const local = await deps.gitOps.getLocalAuthor(input.dir);
+        if (local && local.name && local.email) {
+            author = local;
+        }
+        else {
+            log(`Warning: no local git user.name/user.email in ${input.dir}; commits will be attributed to ${MIGRATOR_IDENTITY.name} <${MIGRATOR_IDENTITY.email}>.`);
+        }
+    }
+    catch {
+        log(`Warning: could not read local git user identity; commits will be attributed to ${MIGRATOR_IDENTITY.name} <${MIGRATOR_IDENTITY.email}>.`);
+    }
+    // We need the deltas for the Guard 3 summary BEFORE we decide to commit and
+    // push. To produce them we need the scratch clone in hand (so we can compare
+    // file-by-file). We clone into the scratch dir, take the diff, show the
+    // summary, confirm, then apply the delta via `cloneAndStackPush`.
+    //
+    // Rather than re-implement cloneAndStackPush's clone step here, we let it
+    // own the clone-commit-push pipeline and pass a deltas callback that runs
+    // AFTER the clone (it receives the localDir/scratchDir) but BEFORE the
+    // commit. `cloneAndStackPush` only exposes an `applyDelta` hook (write files
+    // then return), so we split the flow: first a probe clone to take the
+    // diff, then the real clone-and-stack-push. This is simpler than rewiring
+    // cloneAndStackPush's API.
+    // Probe clone.
+    await deps.gitOps.fetch(input.dir) // no-op for bare path if not a repo; deps.gitOps may short-circuit
+        .catch(() => {
+        // bare-path doesn't require a local fetch — swallow the error
+    });
+    // We don't have a probe clone helper; instead, ask the deps for a bare-path
+    // delta computation. The test double will produce this from a fixture; the
+    // real implementation walks both trees after ensuring a scratch clone exists.
+    // This is provided by the command glue layer.
+    const deltas = await deps.gitOps.diffHeadVsOrigin(input.dir);
+    const totalFilesInRemote = await deps.gitOps.countFilesInRemote(input.dir);
+    const summary = summarizeDiff(deltas, { totalFilesInRemote, unpinned });
+    log('');
+    log(summary.renderText({
+        workspaceSlug: backend.workspaceSlug,
+        repoUrl: stripAuth(backend.repoUrl),
+        branch: 'main',
+        localDir: input.dir,
+    }));
+    log('');
+    if (summary.totals.filesTouched === 0) {
+        return { kind: 'no-op', reason: 'Local tree matches remote HEAD. Nothing to push.' };
+    }
+    const ok = await decideConfirm({
+        destructive: summary.isDestructive,
+        requiresTypedSlug,
+        yes: input.yes,
+        workspaceSlug: backend.workspaceSlug,
+        confirmIO: deps.confirmIO,
+    });
+    if (!ok) {
+        log('Aborted, nothing pushed.');
+        return { kind: 'aborted', reason: 'user declined at confirm prompt' };
+    }
+    const baseMessage = input.message ?? `qfg push: ${summary.totals.filesTouched} file change(s)`;
+    const commitMessage = withPushedViaTrailer(baseMessage);
+    log('Pushing via clone-and-stack...');
+    try {
+        const result = await cloneAndStackPush({
+            remoteUrl: backend.repoUrl,
+            localDir: scratchDir,
+            author,
+            commitMessage,
+            async applyDelta(clonedDir) {
+                // The caller promised deps.copyDirMirror copies `input.dir` into
+                // `clonedDir`, skipping `.git/`. cloneAndStackPush will `git add --all`
+                // after this returns.
+                await deps.copyDirMirror(input.dir, clonedDir);
+            },
+        });
+        if (unpinned && !input.noPinWrite) {
+            try {
+                await writeWorkspaceSlug(input.dir, backend.workspaceSlug);
+                log(`Wrote workspace = "${backend.workspaceSlug}" into quonfig.json`);
+            }
+            catch {
+                // non-fatal
+            }
+        }
+        return { kind: 'pushed', dispatchedAs: 'bare-path', commitSha: result.commitSha };
+    }
+    catch (error) {
+        const msg = error instanceof Error ? error.message : String(error);
+        if (/non-fast-forward|fetch first|rejected/i.test(msg)) {
+            throw new PushFatalError('Remote has changes not in local — run `qfg pull` first, then re-run `qfg push`.', 'NON_FAST_FORWARD');
+        }
+        throw new PushFatalError(`Push failed: ${msg}`, 'PUSH_FAILED');
+    }
+    finally {
+        // Best-effort cleanup of the scratch clone. Ignore failures so a cleanup
+        // problem doesn't mask a real error.
+        try {
+            fs.rmSync(scratchDir, { recursive: true, force: true });
+        }
+        catch {
+            /* ignore */
+        }
+    }
+}
+/**
+ * Map the guard outputs to the right prompt:
+ *   - Typed-slug (always, never skipped by --yes) when identity demanded it
+ *     OR when the diff is destructive.
+ *   - Standard Y/N otherwise, unless --yes is set.
+ */
+async function decideConfirm(args) {
+    const needsTyped = args.requiresTypedSlug || args.destructive;
+    if (needsTyped) {
+        return confirmTypedSlug(args.workspaceSlug, `Type the workspace slug "${args.workspaceSlug}" to confirm: `, args.confirmIO ?? {});
+    }
+    if (args.yes)
+        return true;
+    return confirmYesNo('Proceed? [y/N] ', args.confirmIO ?? {});
+}
+const stripAuth = (url) => {
+    try {
+        const u = new URL(url);
+        u.username = '';
+        u.password = '';
+        return u.toString();
+    }
+    catch {
+        return url;
+    }
+};

package/dist/util/get-client.js

@@ -29,7 +29,7 @@ const getClient = async (command, sdkKey, profile) => {
         // API-key (workspace-scoped bearer) path. getValidAccessToken short-circuits
         // when QUONFIG_API_KEY is set, so this never touches disk.
         try {
-            jwt = await getValidAccessToken();
+            jwt = await getValidAccessToken(command.verboseLog);
         }
         catch (error) {
             command.error(error instanceof Error ? error.message : String(error), { exit: 1 });
@@ -81,11 +81,12 @@ const getClient = async (command, sdkKey, profile) => {
         }
         command.verboseLog('Checking token validity...');
         try {
-            jwt = await getValidAccessToken();
+            jwt = await getValidAccessToken(command.verboseLog);
             command.verboseLog('Token valid (or refreshed)');
         }
-        catch {
-            command.error('Session expired. Please run `qfg login` to re-authenticate.', { exit: 401 });
+        catch (error) {
+            const detail = error instanceof Error ? error.message : String(error);
+            command.error(`Session expired. Please run \`qfg login\` to re-authenticate. (${detail})`, { exit: 401 });
         }
         // Resolve workspace: --workspace/QUONFIG_WORKSPACE (slug) → QUONFIG_PROFILE (profile name) → default
         const workspaceSlugOverride = profile ?? process.env.QUONFIG_WORKSPACE;

package/dist/util/get-valid-token.d.ts

@@ -6,4 +6,6 @@
  * directly as a bearer token and no disk reads/writes or refresh calls
  * are made. This is the non-interactive (CI) path.
  */
-export declare function getValidAccessToken(): Promise<string>;
+type Logger = (msg: string, data?: unknown) => void;
+export declare function getValidAccessToken(log?: Logger): Promise<string>;
+export {};

package/dist/util/get-valid-token.js

@@ -6,38 +6,62 @@
  * directly as a bearer token and no disk reads/writes or refresh calls
  * are made. This is the non-interactive (CI) path.
  */
+import { getDomain } from './domain-urls.js';
 import { decodeJWT, refreshAccessToken } from './oauth-client.js';
 import { loadTokens, saveTokens } from './token-storage.js';
-export async function getValidAccessToken() {
+const noopLog = () => { };
+export async function getValidAccessToken(log = noopLog) {
     const envKey = process.env.QUONFIG_API_KEY;
     if (envKey && envKey.length > 0) {
         if (!envKey.startsWith('qf_uk_')) {
             throw new Error(`QUONFIG_API_KEY must start with "qf_uk_" (got "${envKey.slice(0, 8)}..."). Generate one from the web UI under Settings → API Keys.`);
         }
+        log('getValidAccessToken: using QUONFIG_API_KEY (CI path)');
         return envKey;
     }
     const tokens = await loadTokens();
+    log('getValidAccessToken: loaded tokens', {
+        domain: getDomain(),
+        hasAccessToken: Boolean(tokens?.accessToken),
+        hasRefreshToken: Boolean(tokens?.refreshToken),
+        expiresAt: tokens?.expiresAt,
+    });
     if (!tokens?.accessToken) {
         throw new Error('Not authenticated. Please run `qfg login` first.');
     }
     // Check expiry using the JWT's exp claim, falling back to stored expiresAt
     let expired = tokens.expiresAt ? tokens.expiresAt < Date.now() : false;
+    let expirySource = 'stored';
     try {
         const payload = decodeJWT(tokens.accessToken);
         if (typeof payload.exp === 'number') {
             expired = payload.exp * 1000 < Date.now();
+            expirySource = 'jwt';
         }
     }
     catch {
         /* use stored expiresAt */
     }
+    log('getValidAccessToken: expiry check', { expired, expirySource, now: Date.now() });
     if (!expired) {
         return tokens.accessToken;
     }
     if (!tokens.refreshToken) {
-        throw new Error('Session expired. Please run `qfg login` to re-authenticate.');
+        throw new Error('Session expired (no refresh_token on disk). Please run `qfg login` to re-authenticate.');
     }
-    const refreshed = await refreshAccessToken(tokens.refreshToken);
+    log('getValidAccessToken: access token expired, calling WorkOS refresh');
+    let refreshed;
+    try {
+        refreshed = await refreshAccessToken(tokens.refreshToken);
+    }
+    catch (error) {
+        const detail = error instanceof Error ? error.message : String(error);
+        log('getValidAccessToken: refresh FAILED', { detail });
+        throw new Error(`Token refresh failed: ${detail}`);
+    }
+    log('getValidAccessToken: refresh succeeded', {
+        gotNewRefreshToken: Boolean(refreshed.refresh_token),
+    });
     let expiresAt = Date.now() + 300 * 1000;
     try {
         const payload = decodeJWT(refreshed.access_token);
@@ -55,5 +79,6 @@ export async function getValidAccessToken() {
         refreshToken: refreshed.refresh_token,
     };
     await saveTokens(updated);
+    log('getValidAccessToken: refreshed tokens saved', { newExpiresAt: expiresAt });
     return refreshed.access_token;
 }

package/dist/util/gitea-api.d.ts

@@ -3,8 +3,22 @@ export interface GiteaTokenResponse {
     expiresAt: string | null;
     repoUrl: string;
     token: string;
+    /**
+     * Canonical workspace UUID for the minted token. Used as the backend
+     * identity in the push identity check — required so the CLI can match a
+     * `--workspace <UUID>` request against the canonical workspace row without
+     * assuming the slug is also the UUID. Backend returns this alongside
+     * `workspaceSlug` as of the Guard 1 rollout in `project/plans/cli-git-sync.md`.
+     */
+    workspaceId: string;
+    /**
+     * Human-readable workspace slug (NOT the UUID). Used to pin `quonfig.json`
+     * and for identity-check guard messages. Required as of the Guard 1 rollout
+     * in `project/plans/cli-git-sync.md`; the backend always returns it.
+     */
+    workspaceSlug: string;
 }
-export declare const mintGiteaToken: (workspaceId: string, scope: "read" | "write", purpose: "pull" | "bootstrap") => Promise<GiteaTokenResponse>;
+export declare const mintGiteaToken: (workspaceId: string, scope: "read" | "write", purpose: "pull" | "bootstrap" | "push") => Promise<GiteaTokenResponse>;
 /**
  * Mint a Gitea read token, store it, and return the entry.
  */

package/dist/util/gitea-api.js

@@ -41,6 +41,7 @@ export const mintAndStoreGiteaReadToken = async (workspaceId) => {
         token: data.token,
         repoUrl: data.repoUrl,
         expiresAt: data.expiresAt,
+        workspaceSlug: data.workspaceSlug,
     };
     await saveGiteaToken(workspaceId, entry);
     return entry;

package/dist/util/gitea-token-storage.d.ts

@@ -2,6 +2,13 @@ export interface GiteaTokenEntry {
     expiresAt: string | null;
     repoUrl: string;
     token: string;
+    /**
+     * Human-readable workspace slug (NOT the UUID). Populated from the
+     * `gitea.token` response. Optional to stay backward-compatible with older
+     * entries written before the field was added; callers must handle the
+     * `undefined` case by re-minting.
+     */
+    workspaceSlug?: string;
 }
 export declare const loadGiteaToken: (workspaceId: string) => Promise<GiteaTokenEntry | null>;
 export declare const saveGiteaToken: (workspaceId: string, entry: GiteaTokenEntry) => Promise<void>;

package/dist/util/quonfig-json.d.ts

@@ -0,0 +1,44 @@
+/**
+ * Reader/writer for the workspace's `quonfig.json` file.
+ *
+ * Today the file is `{ environments: string[] }`. We are adding an optional
+ * `workspace: "<slug>"` pin (Guard 1 in `project/plans/cli-git-sync.md`)
+ * so commands like `qfg push` can confirm that the local dir belongs to the
+ * cloud workspace they think it does.
+ *
+ * The reader is permissive: missing file or missing field returns `undefined`
+ * (no throw). It only throws when the file exists but cannot be parsed.
+ *
+ * The writer preserves all unknown fields, sticks to 2-space indent, and
+ * always ends with a trailing newline — matching how `qfg init` and the
+ * migrate flow create the file today.
+ */
+/**
+ * Shape of `quonfig.json`. Everything is optional from the reader's
+ * perspective so a partially-written or in-flight file doesn't blow up
+ * downstream consumers — `qfg verify` is the source of strict validation.
+ */
+export interface QuonfigJson {
+    [key: string]: unknown;
+    environments?: string[];
+    /** Workspace slug (human-readable, not the UUID). Used as the repo pin. */
+    workspace?: string;
+}
+/**
+ * Read the workspace slug pin from `<dir>/quonfig.json`.
+ *
+ * Returns `undefined` when the file is missing OR when the `workspace`
+ * field is absent OR when the field is present but not a string.
+ * Throws only when the file exists but contains malformed JSON, since
+ * that is a real bug a caller should surface.
+ */
+export declare function readWorkspaceSlug(dir: string): Promise<string | undefined>;
+/**
+ * Write the workspace slug pin into `<dir>/quonfig.json`.
+ *
+ * If the file exists, all other fields are preserved and only `workspace`
+ * is set/overwritten. If the file is missing, a minimal `{workspace: slug}`
+ * file is created. Format is 2-space indent + trailing newline to match
+ * the file shape produced by `qfg init` and `qfg migrate`.
+ */
+export declare function writeWorkspaceSlug(dir: string, slug: string): Promise<void>;