@quonfig/cli 0.0.33 → 0.0.34

package/README.md

@@ -14,7 +14,7 @@ $ npm install -g @quonfig/cli
 $ qfg COMMAND
 running command...
 $ qfg (--version)
-@quonfig/cli/0.0.33 linux-x64 node-v24.4.1
+@quonfig/cli/0.0.34 linux-x64 node-v24.4.1
 $ qfg --help [COMMAND]
 USAGE
   $ qfg COMMAND
@@ -91,7 +91,7 @@ EXAMPLES
   $ qfg config-schema --json-schema    # full JSON Schema document (copy into your editor)
 ```
 
-_See code: [src/commands/config-schema.ts](https://github.com/quonfig/cli/blob/v0.0.33/src/commands/config-schema.ts)_
+_See code: [src/commands/config-schema.ts](https://github.com/quonfig/cli/blob/v0.0.34/src/commands/config-schema.ts)_
 
 ## `qfg create NAME`
 
@@ -176,7 +176,7 @@ EXAMPLES
   $ qfg set-rollout my.new.flag --environment production --true-percent 20
 ```
 
-_See code: [src/commands/create.ts](https://github.com/quonfig/cli/blob/v0.0.33/src/commands/create.ts)_
+_See code: [src/commands/create.ts](https://github.com/quonfig/cli/blob/v0.0.34/src/commands/create.ts)_
 
 ## `qfg delete NAME`
 
@@ -222,7 +222,7 @@ EXAMPLES
   $ qfg delete my.config --yes
 ```
 
-_See code: [src/commands/delete.ts](https://github.com/quonfig/cli/blob/v0.0.33/src/commands/delete.ts)_
+_See code: [src/commands/delete.ts](https://github.com/quonfig/cli/blob/v0.0.34/src/commands/delete.ts)_
 
 ## `qfg flag info [NAME]`
 
@@ -425,7 +425,7 @@ EXAMPLES
   $ qfg generate --targets node-ts -o ./dist # combine with targets
 ```
 
-_See code: [src/commands/generate.ts](https://github.com/quonfig/cli/blob/v0.0.33/src/commands/generate.ts)_
+_See code: [src/commands/generate.ts](https://github.com/quonfig/cli/blob/v0.0.34/src/commands/generate.ts)_
 
 ## `qfg generate-new-hex-key`
 
@@ -448,7 +448,7 @@ EXAMPLES
   $ qfg generate-new-hex-key
 ```
 
-_See code: [src/commands/generate-new-hex-key.ts](https://github.com/quonfig/cli/blob/v0.0.33/src/commands/generate-new-hex-key.ts)_
+_See code: [src/commands/generate-new-hex-key.ts](https://github.com/quonfig/cli/blob/v0.0.34/src/commands/generate-new-hex-key.ts)_
 
 ## `qfg get [NAME]`
 
@@ -480,7 +480,7 @@ EXAMPLES
   $ qfg get my.config.name --environment=production
 ```
 
-_See code: [src/commands/get.ts](https://github.com/quonfig/cli/blob/v0.0.33/src/commands/get.ts)_
+_See code: [src/commands/get.ts](https://github.com/quonfig/cli/blob/v0.0.34/src/commands/get.ts)_
 
 ## `qfg info [NAME]`
 
@@ -528,7 +528,7 @@ EXAMPLES
   $ qfg info my.config.name --exclude-evaluations   # skip 24h stats
 ```
 
-_See code: [src/commands/info.ts](https://github.com/quonfig/cli/blob/v0.0.33/src/commands/info.ts)_
+_See code: [src/commands/info.ts](https://github.com/quonfig/cli/blob/v0.0.34/src/commands/info.ts)_
 
 ## `qfg init [DIRECTORY]`
 
@@ -568,7 +568,7 @@ EXAMPLES
   $ qfg init --dry-run
 ```
 
-_See code: [src/commands/init.ts](https://github.com/quonfig/cli/blob/v0.0.33/src/commands/init.ts)_
+_See code: [src/commands/init.ts](https://github.com/quonfig/cli/blob/v0.0.34/src/commands/init.ts)_
 
 ## `qfg interactive`
 
@@ -598,7 +598,7 @@ EXAMPLES
   $ qfg
 ```
 
-_See code: [src/commands/interactive.ts](https://github.com/quonfig/cli/blob/v0.0.33/src/commands/interactive.ts)_
+_See code: [src/commands/interactive.ts](https://github.com/quonfig/cli/blob/v0.0.34/src/commands/interactive.ts)_
 
 ## `qfg list`
 
@@ -638,7 +638,7 @@ EXAMPLES
   $ qfg list --feature-flags
 ```
 
-_See code: [src/commands/list.ts](https://github.com/quonfig/cli/blob/v0.0.33/src/commands/list.ts)_
+_See code: [src/commands/list.ts](https://github.com/quonfig/cli/blob/v0.0.34/src/commands/list.ts)_
 
 ## `qfg log-level NAME`
 
@@ -703,7 +703,7 @@ EXAMPLES
   $ qfg log-level log-level.my-app --target=Chatty --value=INFO --environment=production
 ```
 
-_See code: [src/commands/log-level.ts](https://github.com/quonfig/cli/blob/v0.0.33/src/commands/log-level.ts)_
+_See code: [src/commands/log-level.ts](https://github.com/quonfig/cli/blob/v0.0.34/src/commands/log-level.ts)_
 
 ## `qfg login`
 
@@ -728,7 +728,7 @@ EXAMPLES
   $ qfg login --profile myprofile
 ```
 
-_See code: [src/commands/login.ts](https://github.com/quonfig/cli/blob/v0.0.33/src/commands/login.ts)_
+_See code: [src/commands/login.ts](https://github.com/quonfig/cli/blob/v0.0.34/src/commands/login.ts)_
 
 ## `qfg logout`
 
@@ -751,7 +751,7 @@ EXAMPLES
   $ qfg logout
 ```
 
-_See code: [src/commands/logout.ts](https://github.com/quonfig/cli/blob/v0.0.33/src/commands/logout.ts)_
+_See code: [src/commands/logout.ts](https://github.com/quonfig/cli/blob/v0.0.34/src/commands/logout.ts)_
 
 ## `qfg migrate`
 
@@ -805,7 +805,7 @@ EXAMPLES
   $ qfg migrate --from launch --api-key $LAUNCH_API_KEY --dir ./quonfig-repo --staging
 ```
 
-_See code: [src/commands/migrate.ts](https://github.com/quonfig/cli/blob/v0.0.33/src/commands/migrate.ts)_
+_See code: [src/commands/migrate.ts](https://github.com/quonfig/cli/blob/v0.0.34/src/commands/migrate.ts)_
 
 ## `qfg migrate doctor`
 
@@ -843,7 +843,7 @@ EXAMPLES
   $ qfg migrate doctor --json
 ```
 
-_See code: [src/commands/migrate/doctor.ts](https://github.com/quonfig/cli/blob/v0.0.33/src/commands/migrate/doctor.ts)_
+_See code: [src/commands/migrate/doctor.ts](https://github.com/quonfig/cli/blob/v0.0.34/src/commands/migrate/doctor.ts)_
 
 ## `qfg migrate my-code`
 
@@ -875,7 +875,7 @@ EXAMPLES
   $ qfg migrate my-code --dry-run
 ```
 
-_See code: [src/commands/migrate/my-code.ts](https://github.com/quonfig/cli/blob/v0.0.33/src/commands/migrate/my-code.ts)_
+_See code: [src/commands/migrate/my-code.ts](https://github.com/quonfig/cli/blob/v0.0.34/src/commands/migrate/my-code.ts)_
 
 ## `qfg migrate status`
 
@@ -906,7 +906,7 @@ EXAMPLES
   $ qfg migrate status --json
 ```
 
-_See code: [src/commands/migrate/status.ts](https://github.com/quonfig/cli/blob/v0.0.33/src/commands/migrate/status.ts)_
+_See code: [src/commands/migrate/status.ts](https://github.com/quonfig/cli/blob/v0.0.34/src/commands/migrate/status.ts)_
 
 ## `qfg override [NAME] [VALUE]`
 
@@ -961,7 +961,7 @@ EXAMPLES
   $ qfg override my.flag true --env=staging
 ```
 
-_See code: [src/commands/override.ts](https://github.com/quonfig/cli/blob/v0.0.33/src/commands/override.ts)_
+_See code: [src/commands/override.ts](https://github.com/quonfig/cli/blob/v0.0.34/src/commands/override.ts)_
 
 ## `qfg pull`
 
@@ -969,10 +969,13 @@ Clone or update a local copy of your workspace config files.
 
 ```
 USAGE
-  $ qfg pull [--json] [--interactive] [--no-color] [--verbose] [--dir <value>] [--workspace <value>]
+  $ qfg pull [--json] [--interactive] [--no-color] [--verbose] [--dir <value>] [--rebase] [--workspace
+    <value>]
 
 FLAGS
   --dir=<value>        Local directory to clone/update (defaults to QUONFIG_DIR env var)
+  --rebase             Replay local commits on top of origin/main when the two have diverged. Conflicts are surfaced via
+                       standard git markers; resolve with `git rebase --continue`.
   --workspace=<value>  Workspace ID (defaults to active profile)
 
 GLOBAL FLAGS
@@ -1005,7 +1008,7 @@ EXAMPLES
   $ qfg pull  # uses QUONFIG_DIR env var
 ```
 
-_See code: [src/commands/pull.ts](https://github.com/quonfig/cli/blob/v0.0.33/src/commands/pull.ts)_
+_See code: [src/commands/pull.ts](https://github.com/quonfig/cli/blob/v0.0.34/src/commands/pull.ts)_
 
 ## `qfg push`
 
@@ -1053,7 +1056,7 @@ EXAMPLES
   $ qfg push --dir ./our-config --yes
 ```
 
-_See code: [src/commands/push.ts](https://github.com/quonfig/cli/blob/v0.0.33/src/commands/push.ts)_
+_See code: [src/commands/push.ts](https://github.com/quonfig/cli/blob/v0.0.34/src/commands/push.ts)_
 
 ## `qfg schema NAME`
 
@@ -1091,7 +1094,7 @@ EXAMPLES
   $ qfg schema my-schema --set-json-schema=@schemas/my-schema.json --protected
 ```
 
-_See code: [src/commands/schema.ts](https://github.com/quonfig/cli/blob/v0.0.33/src/commands/schema.ts)_
+_See code: [src/commands/schema.ts](https://github.com/quonfig/cli/blob/v0.0.34/src/commands/schema.ts)_
 
 ## `qfg sdk-key`
 
@@ -1118,7 +1121,7 @@ EXAMPLES
   $ qfg sdk-key revoke <key-id>
 ```
 
-_See code: [src/commands/sdk-key.ts](https://github.com/quonfig/cli/blob/v0.0.33/src/commands/sdk-key.ts)_
+_See code: [src/commands/sdk-key.ts](https://github.com/quonfig/cli/blob/v0.0.34/src/commands/sdk-key.ts)_
 
 ## `qfg sdk-key create`
 
@@ -1150,7 +1153,7 @@ EXAMPLES
   $ qfg sdk-key create --environment staging --type browser
 ```
 
-_See code: [src/commands/sdk-key/create.ts](https://github.com/quonfig/cli/blob/v0.0.33/src/commands/sdk-key/create.ts)_
+_See code: [src/commands/sdk-key/create.ts](https://github.com/quonfig/cli/blob/v0.0.34/src/commands/sdk-key/create.ts)_
 
 ## `qfg sdk-key list`
 
@@ -1179,7 +1182,7 @@ EXAMPLES
   $ qfg sdk-key list --environment production
 ```
 
-_See code: [src/commands/sdk-key/list.ts](https://github.com/quonfig/cli/blob/v0.0.33/src/commands/sdk-key/list.ts)_
+_See code: [src/commands/sdk-key/list.ts](https://github.com/quonfig/cli/blob/v0.0.34/src/commands/sdk-key/list.ts)_
 
 ## `qfg sdk-key revoke KEYID`
 
@@ -1206,7 +1209,7 @@ EXAMPLES
   $ qfg sdk-key revoke a1b2c3d4-e5f6-7890-abcd-ef1234567890
 ```
 
-_See code: [src/commands/sdk-key/revoke.ts](https://github.com/quonfig/cli/blob/v0.0.33/src/commands/sdk-key/revoke.ts)_
+_See code: [src/commands/sdk-key/revoke.ts](https://github.com/quonfig/cli/blob/v0.0.34/src/commands/sdk-key/revoke.ts)_
 
 ## `qfg set-default [NAME]`
 
@@ -1277,7 +1280,7 @@ EXAMPLES
   $ qfg pull && qfg config-schema
 ```
 
-_See code: [src/commands/set-default.ts](https://github.com/quonfig/cli/blob/v0.0.33/src/commands/set-default.ts)_
+_See code: [src/commands/set-default.ts](https://github.com/quonfig/cli/blob/v0.0.34/src/commands/set-default.ts)_
 
 ## `qfg set-rollout [NAME]`
 
@@ -1354,7 +1357,7 @@ EXAMPLES
   $ qfg set-rollout my.variant.flag --environment production --weights "a:33,b:33,c:34" --hash-by user.id
 ```
 
-_See code: [src/commands/set-rollout.ts](https://github.com/quonfig/cli/blob/v0.0.33/src/commands/set-rollout.ts)_
+_See code: [src/commands/set-rollout.ts](https://github.com/quonfig/cli/blob/v0.0.34/src/commands/set-rollout.ts)_
 
 ## `qfg sync`
 
@@ -1386,7 +1389,7 @@ EXAMPLES
   $ qfg sync --watch --dir ./our-config --interval 30
 ```
 
-_See code: [src/commands/sync.ts](https://github.com/quonfig/cli/blob/v0.0.33/src/commands/sync.ts)_
+_See code: [src/commands/sync.ts](https://github.com/quonfig/cli/blob/v0.0.34/src/commands/sync.ts)_
 
 ## `qfg toggle [NAME]`
 
@@ -1488,7 +1491,7 @@ EXAMPLES
   $ qfg verify --json
 ```
 
-_See code: [src/commands/verify.ts](https://github.com/quonfig/cli/blob/v0.0.33/src/commands/verify.ts)_
+_See code: [src/commands/verify.ts](https://github.com/quonfig/cli/blob/v0.0.34/src/commands/verify.ts)_
 
 ## `qfg whoami`
 
@@ -1511,7 +1514,7 @@ EXAMPLES
   $ qfg whoami
 ```
 
-_See code: [src/commands/whoami.ts](https://github.com/quonfig/cli/blob/v0.0.33/src/commands/whoami.ts)_
+_See code: [src/commands/whoami.ts](https://github.com/quonfig/cli/blob/v0.0.34/src/commands/whoami.ts)_
 
 ## `qfg workspace`
 
@@ -1534,7 +1537,7 @@ EXAMPLES
   $ qfg workspace
 ```
 
-_See code: [src/commands/workspace.ts](https://github.com/quonfig/cli/blob/v0.0.33/src/commands/workspace.ts)_
+_See code: [src/commands/workspace.ts](https://github.com/quonfig/cli/blob/v0.0.34/src/commands/workspace.ts)_
 
 ## `qfg workspace bootstrap`
 
@@ -1567,7 +1570,7 @@ EXAMPLES
   $ qfg workspace bootstrap --dir ./our-config --skip-validate
 ```
 
-_See code: [src/commands/workspace/bootstrap.ts](https://github.com/quonfig/cli/blob/v0.0.33/src/commands/workspace/bootstrap.ts)_
+_See code: [src/commands/workspace/bootstrap.ts](https://github.com/quonfig/cli/blob/v0.0.34/src/commands/workspace/bootstrap.ts)_
 
 ## `qfg workspace create SLUG`
 
@@ -1601,7 +1604,7 @@ EXAMPLES
   $ qfg workspace create my-team --org 11111111-1111-1111-1111-111111111111
 ```
 
-_See code: [src/commands/workspace/create.ts](https://github.com/quonfig/cli/blob/v0.0.33/src/commands/workspace/create.ts)_
+_See code: [src/commands/workspace/create.ts](https://github.com/quonfig/cli/blob/v0.0.34/src/commands/workspace/create.ts)_
 
 ## `qfg workspace switch [SLUG]`
 
@@ -1629,7 +1632,7 @@ EXAMPLES
   $ qfg workspace switch acme/production
 ```
 
-_See code: [src/commands/workspace/switch.ts](https://github.com/quonfig/cli/blob/v0.0.33/src/commands/workspace/switch.ts)_
+_See code: [src/commands/workspace/switch.ts](https://github.com/quonfig/cli/blob/v0.0.34/src/commands/workspace/switch.ts)_
 <!-- commandsstop -->
 
 ## Local Development

package/dist/commands/pull.d.ts

@@ -5,6 +5,7 @@ export default class Pull extends BaseCommand {
     static examples: string[];
     static flags: {
         dir: import("@oclif/core/lib/interfaces/parser.js").OptionFlag<string | undefined, import("@oclif/core/lib/interfaces/parser.js").CustomOptions>;
+        rebase: import("@oclif/core/lib/interfaces/parser.js").BooleanFlag<boolean>;
         workspace: import("@oclif/core/lib/interfaces/parser.js").OptionFlag<string | undefined, import("@oclif/core/lib/interfaces/parser.js").CustomOptions>;
     };
     run(): Promise<JsonObj | void>;

package/dist/commands/pull.js

@@ -6,7 +6,7 @@ import { loadGiteaToken, isGiteaTokenExpired, saveGiteaToken } from '../util/git
 import { mintAndStoreGiteaReadToken, mintGiteaToken } from '../util/gitea-api.js';
 import { readWorkspaceSlug, tryParseWorkspacePin, writeWorkspaceSlug } from '../util/quonfig-json.js';
 import { resolveWorkspaceUuid } from '../util/resolve-workspace.js';
-import { isGitRepo, getRemoteUrl, gitFetch, gitSetRemote, canFastForward, hasDivergedFromRemote, gitMergeFfOnly, gitClone, displayUrl, addAndCommitFile, dirtyTrackedFiles, } from '../util/git-ops.js';
+import { isGitRepo, getRemoteUrl, gitFetch, gitSetRemote, canFastForward, hasDivergedFromRemote, gitMergeFfOnly, gitPullRebase, gitClone, displayUrl, addAndCommitFile, dirtyTrackedFiles, } from '../util/git-ops.js';
 export default class Pull extends BaseCommand {
     static description = `Clone or update a local copy of your workspace config files.
 
@@ -29,6 +29,10 @@ CLI shortcuts (no JSON editing needed for simple cases):
         dir: Flags.string({
             description: 'Local directory to clone/update (defaults to QUONFIG_DIR env var)',
         }),
+        rebase: Flags.boolean({
+            default: false,
+            description: 'Replay local commits on top of origin/main when the two have diverged. Conflicts are surfaced via standard git markers; resolve with `git rebase --continue`.',
+        }),
         workspace: Flags.string({
             description: 'Workspace ID (defaults to active profile)',
         }),
@@ -85,7 +89,43 @@ CLI shortcuts (no JSON editing needed for simple cases):
             const ff = await canFastForward(resolvedDir);
             const diverged = !ff && (await hasDivergedFromRemote(resolvedDir));
             if (diverged) {
-                return this.err('Local commits diverge from remote — resolve manually.');
+                if (flags.rebase) {
+                    this.log('Local and origin/main have diverged. Rebasing local commits on top of origin/main...');
+                    const result = await gitPullRebase(resolvedDir);
+                    if (result.kind === 'clean') {
+                        this.log(`Rebased ${result.commitsRebased} local commit(s) onto origin/main. Run \`qfg push\` to publish.`);
+                        // Fall through to post-pull work (QUONFIG_DIR write, pin backfill).
+                    }
+                    else if (result.kind === 'conflicts') {
+                        this.log('');
+                        this.log('Rebase paused with conflicts in:');
+                        for (const f of result.conflictedFiles)
+                            this.log(`  ${f}`);
+                        this.log('');
+                        this.log('To finish the rebase:');
+                        this.log(`  1. Edit each file above and pick the values you want; remove the git conflict markers.`);
+                        this.log(`  2. git -C ${resolvedDir} add <files>`);
+                        this.log(`  3. git -C ${resolvedDir} rebase --continue`);
+                        this.log(`  4. qfg push`);
+                        this.log('');
+                        this.log('To abort the rebase and try a different approach:');
+                        this.log(`  git -C ${resolvedDir} rebase --abort`);
+                        return this.err('Rebase paused on conflicts — see instructions above.');
+                    }
+                    else {
+                        return this.err(`Rebase could not start: ${result.reason}\n\n` +
+                            `Most likely the working tree has uncommitted edits. Commit or stash them, then re-run \`qfg pull --rebase\`.`);
+                    }
+                }
+                else {
+                    return this.err(`Local commits diverge from origin/main.\n\n` +
+                        `Your local branch has commits that are not on origin, and origin has commits that are not local. ` +
+                        `qfg pull will not merge automatically. Pick one:\n\n` +
+                        `  Replay your local commits on top of origin/main:\n` +
+                        `    qfg pull --rebase --dir ${resolvedDir}\n\n` +
+                        `  Discard your local commits and take origin/main as-is (LOSES local work):\n` +
+                        `    git -C ${resolvedDir} reset --hard origin/main`);
+                }
             }
             if (ff) {
                 const newCommits = await gitMergeFfOnly(resolvedDir);

package/dist/commands/push.js

@@ -3,7 +3,7 @@ import * as path from 'node:path';
 import { Flags } from '@oclif/core';
 import { BaseCommand } from '../index.js';
 import { mintGiteaToken } from '../util/gitea-api.js';
-import { getRemoteUrl, gitFetch, gitSetRemote, isGitRepo, runGit } from '../util/git-ops.js';
+import { dirtyTrackedFiles, getRemoteUrl, gitFetch, gitSetRemote, isGitRepo, isLocalBehindOrDivergedFromRemote, runGit } from '../util/git-ops.js';
 import { PushFatalError, runPush, } from '../push/run-push.js';
 import { computeBarePathDiff } from '../push/bare-path-diff.js';
 import { callConfigsPush } from '../push/config-push-client.js';
@@ -202,6 +202,29 @@ export function buildRealDeps(cmd, orgSlug) {
             const probe = await ensureBarePathProbe(dir);
             return probe.totalRemoteFiles;
         },
+        async isLocalBehindRemote(dir) {
+            // qfg-fboj: stale-HEAD guard for the clone path. Implementation
+            // lives in git-ops.ts so it can be unit-tested against a real
+            // local git repo. We still gate on isGitRepo here because the
+            // helper does not (it returns false on any error, but we want to
+            // skip the rev-parse cost on the bare path entirely).
+            if (!(await isGitRepo(dir)))
+                return false;
+            return isLocalBehindOrDivergedFromRemote(dir);
+        },
+        async dirtyTrackedFiles(dir) {
+            // qfg-fboj: surface uncommitted edits so the user sees they were
+            // not included in this push. Only meaningful on the clone path —
+            // bare path doesn't have a .git/ to status.
+            if (!(await isGitRepo(dir)))
+                return [];
+            try {
+                return await dirtyTrackedFiles(dir);
+            }
+            catch {
+                return [];
+            }
+        },
     };
     const deps = {
         async mintWriteToken(requestedTarget) {

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

@@ -42,6 +42,23 @@ export interface GitOps {
     getRemoteOriginUrl(dir: string): Promise<string | undefined>;
     /** Returns true if the dir has a `.git/` (worktree or repo). */
     isGitRepo(dir: string): Promise<boolean>;
+    /**
+     * Returns true if origin/main has commits the local HEAD does not have
+     * (local strictly behind, or diverged). False when local is up-to-date
+     * or strictly ahead of origin/main, or when origin/main is unknown.
+     *
+     * The clone-path stale-HEAD guard (qfg-fboj) refuses to push in either
+     * "behind" or "diverged" state because both produce a diff that ships
+     * REVERSAL deltas to the server, silently undoing remote-newer commits.
+     */
+    isLocalBehindRemote(dir: string): Promise<boolean>;
+    /**
+     * Tracked files (relative paths) with working-tree or staged changes.
+     * Used by the clone-path dirty-tree warning to surface uncommitted
+     * edits the user may believe are being pushed (qfg-fboj). Untracked
+     * files are excluded — same rule as `dirtyTrackedFiles` in git-ops.ts.
+     */
+    dirtyTrackedFiles(dir: string): Promise<string[]>;
     /** Set origin to `url` (add if missing, set-url if present). */
     setRemoteOrigin(dir: string, url: string): Promise<void>;
 }

package/dist/push/run-push.js

@@ -136,6 +136,15 @@ export async function runPush(input, deps) {
         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)) {
+            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
         // workspace pin to the working tree without committing. The next
         // diff would miss it. Sweep up that legacy state IF the only dirty
@@ -153,6 +162,27 @@ export async function runPush(input, deps) {
         catch {
             /* non-fatal */
         }
+        // Guard 5 (qfg-fboj): warn loudly about any tracked file with
+        // uncommitted edits beyond the workspace pin. The clone path pushes
+        // HEAD content, not the working tree, so these edits are silently
+        // dropped from the push. Listing them in the log gives the user a
+        // chance to ctrl-C, commit, and retry instead of believing they
+        // shipped what's on disk. Untracked files are intentionally not
+        // included — same rule as dirtyTrackedFiles in git-ops.ts.
+        try {
+            const dirty = await deps.gitOps.dirtyTrackedFiles(input.dir);
+            const noisyDirty = dirty.filter((f) => f !== 'quonfig.json');
+            if (noisyDirty.length > 0) {
+                log('');
+                log('Warning: working tree has uncommitted changes that will NOT be included in this push:');
+                for (const f of noisyDirty)
+                    log(`  ${f}`);
+                log('Commit them with `git add` + `git commit` and re-run `qfg push` if you meant to ship them.');
+            }
+        }
+        catch {
+            /* non-fatal */
+        }
     }
     const deltas = await deps.gitOps.diffHeadVsOrigin(input.dir);
     const totalFilesInRemote = await deps.gitOps.countFilesInRemote(input.dir);

package/dist/util/git-ops.d.ts

@@ -101,6 +101,20 @@ export declare const gitFetch: (dir: string) => Promise<void>;
  * Returns true if origin/main has commits that can be fast-forwarded into the local branch.
  */
 export declare const canFastForward: (dir: string) => Promise<boolean>;
+/**
+ * Returns true iff origin/main is NOT an ancestor of the local HEAD —
+ * covering both "local strictly behind" and "diverged" in one boolean.
+ *
+ * Used by the clone-path stale-HEAD guard in `qfg push` (qfg-fboj):
+ * either of those two states would otherwise produce a `HEAD..origin/main`
+ * diff that ships REVERSAL deltas to the server, silently undoing
+ * remote-newer commits. Both must refuse.
+ *
+ * Returns false on any git failure (no `origin/main` ref yet, no `.git/`,
+ * etc.) so the caller falls through to its other guards rather than
+ * aborting on an opaque error.
+ */
+export declare const isLocalBehindOrDivergedFromRemote: (dir: string) => Promise<boolean>;
 /**
  * Returns true if local has commits not reachable from origin/main (diverged).
  */
@@ -120,3 +134,29 @@ export declare const hasAtLeastOneCommit: (dir: string) => Promise<boolean>;
  * Get the URL stripped of credentials for display purposes.
  */
 export declare const displayUrl: (url: string) => string;
+/**
+ * Outcome of `gitPullRebase`. Three branches the caller MUST distinguish
+ * — silent failure here is what made qfg-4tey a P1 (qfg pull exit 0 with
+ * no recovery path).
+ */
+export type GitPullRebaseResult = {
+    kind: 'clean';
+    commitsRebased: number;
+} | {
+    kind: 'conflicts';
+    conflictedFiles: string[];
+} | {
+    kind: 'failed';
+    reason: string;
+};
+/**
+ * `git pull --rebase origin main`. Replays local commits on top of the
+ * remote tip. On conflicts, leaves the repo in rebase-in-progress state
+ * with `<<<<<<<` / `=======` / `>>>>>>>` markers planted by git so the
+ * user can resolve via standard git tools (`git rebase --continue` /
+ * `git rebase --abort`).
+ *
+ * Caller is responsible for surfacing recovery instructions; this function
+ * only reports the outcome.
+ */
+export declare const gitPullRebase: (dir: string) => Promise<GitPullRebaseResult>;

package/dist/util/git-ops.js

@@ -222,6 +222,41 @@ export const canFastForward = async (dir) => {
         return false;
     }
 };
+/**
+ * Returns true iff origin/main is NOT an ancestor of the local HEAD —
+ * covering both "local strictly behind" and "diverged" in one boolean.
+ *
+ * Used by the clone-path stale-HEAD guard in `qfg push` (qfg-fboj):
+ * either of those two states would otherwise produce a `HEAD..origin/main`
+ * diff that ships REVERSAL deltas to the server, silently undoing
+ * remote-newer commits. Both must refuse.
+ *
+ * Returns false on any git failure (no `origin/main` ref yet, no `.git/`,
+ * etc.) so the caller falls through to its other guards rather than
+ * aborting on an opaque error.
+ */
+export const isLocalBehindOrDivergedFromRemote = async (dir) => {
+    try {
+        const { stdout: localSha } = await runGit(['-C', dir, 'rev-parse', 'HEAD']);
+        const { stdout: remoteSha } = await runGit(['-C', dir, 'rev-parse', 'origin/main']);
+        const local = localSha.trim();
+        const remote = remoteSha.trim();
+        if (local === remote)
+            return false;
+        try {
+            // exit 0 → remote is an ancestor of local → local is strictly ahead, fine.
+            await runGit(['-C', dir, 'merge-base', '--is-ancestor', remote, local]);
+            return false;
+        }
+        catch {
+            // non-zero exit → remote is NOT an ancestor → behind or diverged.
+            return true;
+        }
+    }
+    catch {
+        return false;
+    }
+};
 /**
  * Returns true if local has commits not reachable from origin/main (diverged).
  */
@@ -310,3 +345,50 @@ export const hasAtLeastOneCommit = async (dir) => {
  * Get the URL stripped of credentials for display purposes.
  */
 export const displayUrl = (url) => redactToken(url);
+/**
+ * `git pull --rebase origin main`. Replays local commits on top of the
+ * remote tip. On conflicts, leaves the repo in rebase-in-progress state
+ * with `<<<<<<<` / `=======` / `>>>>>>>` markers planted by git so the
+ * user can resolve via standard git tools (`git rebase --continue` /
+ * `git rebase --abort`).
+ *
+ * Caller is responsible for surfacing recovery instructions; this function
+ * only reports the outcome.
+ */
+export const gitPullRebase = async (dir) => {
+    // Count local-only commits BEFORE the rebase so the success path can
+    // tell the user how many got moved. After a clean rebase, origin/main
+    // is the merge-base and ahead-count == commits-rebased.
+    let commitsRebased = 0;
+    try {
+        const { stdout } = await runGit(['-C', dir, 'rev-list', '--count', 'origin/main..HEAD']);
+        commitsRebased = Number.parseInt(stdout.trim(), 10) || 0;
+    }
+    catch {
+        // Non-fatal — counting is for UX, not correctness.
+    }
+    try {
+        await runGit(['-C', dir, 'pull', '--rebase', 'origin', 'main']);
+        return { kind: 'clean', commitsRebased };
+    }
+    catch (err) {
+        // Distinguish "rebase paused on conflicts" from "rebase never started".
+        // Conflicts: `diff --diff-filter=U` lists the unmerged paths and
+        // `.git/rebase-merge/` is present.
+        try {
+            const { stdout } = await runGit(['-C', dir, 'diff', '--name-only', '--diff-filter=U']);
+            const conflictedFiles = stdout
+                .split('\n')
+                .map((s) => s.trim())
+                .filter(Boolean);
+            if (conflictedFiles.length > 0) {
+                return { kind: 'conflicts', conflictedFiles };
+            }
+        }
+        catch {
+            // Fall through to 'failed' — diff itself errored.
+        }
+        const reason = err instanceof Error ? err.message : String(err);
+        return { kind: 'failed', reason };
+    }
+};

package/dist/version.d.ts

@@ -1,2 +1,2 @@
-declare const _default: "0.0.33";
+declare const _default: "0.0.34";
 export default _default;

package/dist/version.js

@@ -1,2 +1,2 @@
 // AUTO-GENERATED from package.json by scripts/generate-version.mjs — do not edit.
-export default '0.0.33';
+export default '0.0.34';

package/oclif.manifest.json

@@ -1415,6 +1415,12 @@
           "multiple": false,
           "type": "option"
         },
+        "rebase": {
+          "description": "Replay local commits on top of origin/main when the two have diverged. Conflicts are surfaced via standard git markers; resolve with `git rebase --continue`.",
+          "name": "rebase",
+          "allowNo": false,
+          "type": "boolean"
+        },
         "workspace": {
           "description": "Workspace ID (defaults to active profile)",
           "name": "workspace",
@@ -2910,5 +2916,5 @@
       ]
     }
   },
-  "version": "0.0.33"
+  "version": "0.0.34"
 }

package/package.json

@@ -1,7 +1,7 @@
 {
   "packageManager": "yarn@4.11.0+sha512.4e54aeace9141df2f0177c266b05ec50dc044638157dae128c471ba65994ac802122d7ab35bcd9e81641228b7dcf24867d28e750e0bcae8a05277d600008ad54",
   "name": "@quonfig/cli",
-  "version": "0.0.33",
+  "version": "0.0.34",
   "bugs": {
     "url": "https://github.com/quonfig/cli/issues"
   },