@quonfig/cli 0.0.33 → 0.0.35

package/dist/migrate/local-write.js

@@ -32,11 +32,54 @@ const ensureLocalRepo = async (localDir, branch) => {
     await runGit(['init', `--initial-branch=${branch}`, localDir]);
     return 'initialized';
 };
-const writeQuonfigFiles = (dir, changes, source) => {
+export class MigratorKeyCollisionError extends Error {
+    destPath;
+    firstSourceKey;
+    secondSourceKey;
+    constructor(destPath, firstSourceKey, secondSourceKey) {
+        super(`Two source keys collide on destination ${destPath} after key normalization: ` +
+            `"${firstSourceKey}" and "${secondSourceKey}". Quonfig keys must be globally unique within a type tree. ` +
+            `Rename one in the source system and re-run.`);
+        this.destPath = destPath;
+        this.firstSourceKey = firstSourceKey;
+        this.secondSourceKey = secondSourceKey;
+        this.name = 'MigratorKeyCollisionError';
+    }
+}
+const ensureNoNestedPath = (relativePath) => {
+    // qfg-qhk1: every output must be exactly `<type-dir>/<flat-key>.json` —
+    // never nested. If we ever emit a nested path, refuse to write so we surface
+    // it loudly rather than silently producing dirs that lose the flat-file
+    // contract (and break tombstone cleanup on subsequent runs).
+    const parts = relativePath.split('/');
+    if (parts.length !== 2) {
+        throw new Error(`Migrator refusing to write nested path "${relativePath}" — outputs must be flat <type-dir>/<key>.json. ` +
+            `This is a bug in the source's translate() — it should normalize key separators before computing the path.`);
+    }
+};
+const rmdirIfEmpty = (dir) => {
+    try {
+        fs.rmdirSync(dir);
+    }
+    catch (error) {
+        const e = error;
+        // ENOTEMPTY: still has contents (expected, leave alone). ENOENT: already gone.
+        if (e.code !== 'ENOTEMPTY' && e.code !== 'ENOENT')
+            throw error;
+    }
+};
+export const writeQuonfigFiles = (dir, changes, source) => {
     const livePaths = new Map();
+    // qfg-qhk1: track which source key wrote each destination path. If a second,
+    // different source key tries to write to the same destination, that is a
+    // post-normalization collision (e.g. source had keys `foo/bar` and `foo.bar`,
+    // both normalize to `foo.bar`). Throw with a clear message.
+    const pathOwners = new Map();
     for (const change of changes) {
         const files = source.translate(change);
+        const sourceKey = change.key ?? '(unknown)';
         for (const file of files) {
+            ensureNoNestedPath(file.path);
             const full = path.join(dir, file.path);
             if (file.deleted) {
                 try {
@@ -47,14 +90,25 @@ const writeQuonfigFiles = (dir, changes, source) => {
                         throw error;
                 }
                 livePaths.delete(file.path);
+                pathOwners.delete(file.path);
+                // qfg-qhk1: clean up any empty parent dirs left over from prior runs
+                // that wrote under a nested layout. (New runs never create nested
+                // dirs because of normalizeKey + ensureNoNestedPath, but stale dirs
+                // from older versions on disk would otherwise persist.)
+                rmdirIfEmpty(path.dirname(full));
             }
             else {
                 if (file.contents === undefined) {
                     throw new Error(`translate() emitted a write op for ${file.path} without contents`);
                 }
+                const existingOwner = pathOwners.get(file.path);
+                if (existingOwner !== undefined && existingOwner !== sourceKey) {
+                    throw new MigratorKeyCollisionError(file.path, existingOwner, sourceKey);
+                }
                 fs.mkdirSync(path.dirname(full), { recursive: true });
                 fs.writeFileSync(full, file.contents);
                 livePaths.set(file.path, true);
+                pathOwners.set(file.path, sourceKey);
             }
         }
     }
@@ -71,7 +125,47 @@ const writeQuonfigFiles = (dir, changes, source) => {
             livePaths.delete(toDelete);
         }
     }
-    return resolutions;
+    return { livePaths: [...livePaths.keys()], resolutions };
+};
+const countsFromLivePaths = (livePaths) => {
+    let flagsMigrated = 0;
+    let configsMigrated = 0;
+    let segmentsMigrated = 0;
+    let schemasMigrated = 0;
+    let logLevelsMigrated = 0;
+    for (const p of livePaths) {
+        if (p.startsWith('feature-flags/'))
+            flagsMigrated++;
+        else if (p.startsWith('configs/'))
+            configsMigrated++;
+        else if (p.startsWith('segments/'))
+            segmentsMigrated++;
+        else if (p.startsWith('schemas/'))
+            schemasMigrated++;
+        else if (p.startsWith('log-levels/'))
+            logLevelsMigrated++;
+    }
+    return { configsMigrated, flagsMigrated, logLevelsMigrated, schemasMigrated, segmentsMigrated };
+};
+export const buildMigrationCounts = (livePaths, environmentsMapped, itemsSkipped) => ({
+    ...countsFromLivePaths(livePaths),
+    environmentsMapped,
+    itemsSkipped,
+});
+export const buildMigrationCommitMessage = (source, counts) => {
+    const parts = [];
+    if (counts.flagsMigrated > 0)
+        parts.push(`${counts.flagsMigrated} flag(s)`);
+    if (counts.configsMigrated > 0)
+        parts.push(`${counts.configsMigrated} config(s)`);
+    if (counts.segmentsMigrated > 0)
+        parts.push(`${counts.segmentsMigrated} segment(s)`);
+    if (counts.schemasMigrated > 0)
+        parts.push(`${counts.schemasMigrated} schema(s)`);
+    if (counts.logLevelsMigrated > 0)
+        parts.push(`${counts.logLevelsMigrated} log-level(s)`);
+    const summary = parts.length === 0 ? 'no objects' : parts.join(', ');
+    return `migrator: imported ${summary} from ${source}`;
 };
 export const applyLocalMigration = async (opts) => {
     const branch = opts.branch ?? 'main';
@@ -80,15 +174,18 @@ export const applyLocalMigration = async (opts) => {
     await runGit(['-C', opts.localDir, 'config', 'user.name', author.name]);
     await runGit(['-C', opts.localDir, 'config', 'user.email', author.email]);
     ensureQuonfigJson(opts.localDir, opts.environments);
-    const resolutionEntries = writeQuonfigFiles(opts.localDir, opts.changes, opts.source);
+    const { livePaths, resolutions: resolutionEntries } = writeQuonfigFiles(opts.localDir, opts.changes, opts.source);
     removeQfFromGitignore(opts.localDir);
     writeImportState(opts.localDir, opts.importState);
     const droppedOverrides = opts.source.getDroppedOverrides?.() ?? null;
     const skippedConfigs = opts.source.getSkippedConfigs?.() ?? null;
     const coercedSentinels = opts.source.getCoercedSentinels?.() ?? null;
     const duplicateResolutions = resolutionEntries.length > 0 ? { entries: resolutionEntries, total: resolutionEntries.length } : null;
+    const skippedTotal = (skippedConfigs?.total ?? 0) + resolutionEntries.reduce((sum, r) => sum + r.deleted.length, 0);
+    const counts = buildMigrationCounts(livePaths, opts.environments.length, skippedTotal);
     const reportData = {
         ...opts.reportData,
+        counts,
         ...(coercedSentinels ? { coercedSentinels } : {}),
         ...(droppedOverrides ? { droppedOverrides } : {}),
         ...(duplicateResolutions ? { duplicateResolutions } : {}),
@@ -107,8 +204,9 @@ export const applyLocalMigration = async (opts) => {
             skippedConfigs,
         };
     }
+    const commitMessage = buildMigrationCommitMessage(opts.source.name, counts);
     await spawnGit(['-C', opts.localDir, 'commit', '-F', '-'], {
-        stdin: opts.commitMessage,
+        stdin: commitMessage,
         env: {
             GIT_AUTHOR_EMAIL: author.email,
             GIT_AUTHOR_NAME: author.name,

package/dist/migrate/migration-report.d.ts

@@ -1,9 +1,12 @@
 import type { IdentifierMap } from './identifier-map.js';
 import type { CoercedSentinelSummary, DroppedOverrideSummary, DuplicateResolutionSummary, SkippedConfigSummary } from './source.js';
 export interface MigrationReportCounts {
+    configsMigrated: number;
     environmentsMapped: number;
     flagsMigrated: number;
     itemsSkipped: number;
+    logLevelsMigrated: number;
+    schemasMigrated: number;
     segmentsMigrated: number;
 }
 export interface CleanMapping {

package/dist/migrate/migration-report.js

@@ -5,7 +5,10 @@ const renderCounts = (counts) => [
     '## Counts',
     '',
     `- Flags migrated: ${counts.flagsMigrated}`,
+    `- Configs migrated: ${counts.configsMigrated}`,
     `- Segments migrated: ${counts.segmentsMigrated}`,
+    `- Schemas migrated: ${counts.schemasMigrated}`,
+    `- Log levels migrated: ${counts.logLevelsMigrated}`,
     `- Environments mapped: ${counts.environmentsMapped}`,
     `- Items skipped: ${counts.itemsSkipped}`,
 ].join('\n');

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

@@ -17,7 +17,6 @@ export declare class MigratorVerifyError extends Error {
 export interface PushMigrationToCloudOptions {
     branch?: string;
     changes: LegacyChange[];
-    commitMessage: string;
     /**
      * Source-side environments (slugified). Additively merged into the target
      * workspace's quonfig.json so flag files that reference these envs verify
@@ -27,6 +26,10 @@ export interface PushMigrationToCloudOptions {
     importState: ImportState;
     localDir: string;
     remoteUrl: string;
+    /**
+     * Base report data. The migrator overrides `counts` after writing files,
+     * since counts must reflect what was actually written to disk (qfg-7eig).
+     */
     reportData: MigrationReportData;
     source: MigrationSource;
 }

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

@@ -1,8 +1,8 @@
 import * as fs from 'node:fs';
 import * as path from 'node:path';
 import { removeQfFromGitignore, writeImportState } from './import-state.js';
+import { buildMigrationCommitMessage, buildMigrationCounts, writeQuonfigFiles } from './local-write.js';
 import { writeMigrationReport } from './migration-report.js';
-import { detectDuplicateKeys } from './sources/launch/translate.js';
 import { cloneAndStackPush, } from '../util/clone-and-stack-push.js';
 import { formatResult, validateWorkspace } from '../verify/validate.js';
 /**
@@ -23,47 +23,6 @@ export class MigratorVerifyError extends Error {
         this.result = result;
     }
 }
-const writeQuonfigFiles = (dir, changes, source) => {
-    const livePaths = new Map();
-    for (const change of changes) {
-        const files = source.translate(change);
-        for (const file of files) {
-            const full = path.join(dir, file.path);
-            if (file.deleted) {
-                try {
-                    fs.unlinkSync(full);
-                }
-                catch (error) {
-                    if (error.code !== 'ENOENT')
-                        throw error;
-                }
-                livePaths.delete(file.path);
-            }
-            else {
-                if (file.contents === undefined) {
-                    throw new Error(`translate() emitted a write op for ${file.path} without contents`);
-                }
-                fs.mkdirSync(path.dirname(full), { recursive: true });
-                fs.writeFileSync(full, file.contents);
-                livePaths.set(file.path, true);
-            }
-        }
-    }
-    const resolutions = detectDuplicateKeys([...livePaths.keys()].map((p) => ({ path: p })));
-    for (const resolution of resolutions) {
-        for (const toDelete of resolution.deleted) {
-            try {
-                fs.unlinkSync(path.join(dir, toDelete));
-            }
-            catch (error) {
-                if (error.code !== 'ENOENT')
-                    throw error;
-            }
-            livePaths.delete(toDelete);
-        }
-    }
-    return resolutions;
-};
 const QUONFIG_JSON_FILENAME = 'quonfig.json';
 const mergeEnvironmentsIntoQuonfigJson = (dir, sourceEnvs) => {
     const quonfigPath = path.join(dir, QUONFIG_JSON_FILENAME);
@@ -88,12 +47,13 @@ export const pushMigrationToCloud = async (opts) => {
     let droppedOverrides = null;
     let duplicateResolutions = null;
     let skippedConfigs = null;
+    let computedCommitMessage = `migrator: imported 0 objects from ${opts.source.name}`;
     const cloneOpts = {
         applyDelta(dir) {
             if (opts.environments && opts.environments.length > 0) {
                 mergeEnvironmentsIntoQuonfigJson(dir, opts.environments);
             }
-            const resolutionEntries = writeQuonfigFiles(dir, opts.changes, opts.source);
+            const { livePaths, resolutions: resolutionEntries } = writeQuonfigFiles(dir, opts.changes, opts.source);
             removeQfFromGitignore(dir);
             writeImportState(dir, opts.importState);
             droppedOverrides = opts.source.getDroppedOverrides?.() ?? null;
@@ -101,8 +61,13 @@ export const pushMigrationToCloud = async (opts) => {
             coercedSentinels = opts.source.getCoercedSentinels?.() ?? null;
             duplicateResolutions =
                 resolutionEntries.length > 0 ? { entries: resolutionEntries, total: resolutionEntries.length } : null;
+            const skippedTotal = (skippedConfigs?.total ?? 0) + resolutionEntries.reduce((sum, r) => sum + r.deleted.length, 0);
+            const environmentsCount = opts.environments?.length ?? 0;
+            const counts = buildMigrationCounts(livePaths, environmentsCount, skippedTotal);
+            computedCommitMessage = buildMigrationCommitMessage(opts.source.name, counts);
             const reportData = {
                 ...opts.reportData,
+                counts,
                 ...(coercedSentinels ? { coercedSentinels } : {}),
                 ...(droppedOverrides ? { droppedOverrides } : {}),
                 ...(duplicateResolutions ? { duplicateResolutions } : {}),
@@ -117,7 +82,7 @@ export const pushMigrationToCloud = async (opts) => {
             if (!verifyResult.valid)
                 throw new MigratorVerifyError(verifyResult);
         },
-        commitMessage: opts.commitMessage,
+        commitMessage: () => computedCommitMessage,
         localDir: opts.localDir,
         remoteUrl: opts.remoteUrl,
     };

package/dist/migrate/sources/launch/translate.d.ts

@@ -11,6 +11,22 @@ export declare class InvalidSourceConfigError extends Error {
 export declare function slugify(value: string): string;
 export declare function isLegacyLogLevel(type: string): boolean;
 export declare function normalizeLogLevelKey(key: string): string;
+/**
+ * qfg-qhk1: Quonfig keys cannot contain `/` — keys are stored as flat dotted
+ * filenames, and a `/` in a source key would create a nested directory tree
+ * (data-loss-on-tombstone, cross-key collisions). Normalize `/` to `.` so the
+ * destination is always flat.
+ */
+export declare function normalizeKey(key: string): string;
+/**
+ * qfg-l18w: Operators Quonfig accepts in rule criteria. Mirrors the
+ * `OperatorSchema` enum in cli/src/verify/validate.ts (and app-quonfig's
+ * config-schemas.ts). If we emit an operator outside this set, qfg verify
+ * fails — which is what was happening for `PROP_SEMVER_*` in the FormHealth
+ * dry-run before this check existed. Keep this list in lockstep with the
+ * verify schema; a CI test in this file enforces parity.
+ */
+export declare const QUONFIG_SUPPORTED_OPERATORS: Set<string>;
 export declare function transformConfig(config: LaunchConfig, envIdMap: Record<string, string>, onDroppedEnv?: (envId: string) => void, onCoercedSentinel?: (envId: string, valueType: string) => void): Record<string, unknown>;
 export declare function getOutputPath(type: string, key: string): string;
 /**

package/dist/migrate/sources/launch/translate.js

@@ -23,6 +23,106 @@ export function isLegacyLogLevel(type) {
 export function normalizeLogLevelKey(key) {
     return key.startsWith('log-level.') ? key : `log-level.${key}`;
 }
+/**
+ * qfg-qhk1: Quonfig keys cannot contain `/` — keys are stored as flat dotted
+ * filenames, and a `/` in a source key would create a nested directory tree
+ * (data-loss-on-tombstone, cross-key collisions). Normalize `/` to `.` so the
+ * destination is always flat.
+ */
+export function normalizeKey(key) {
+    return key.replaceAll('/', '.');
+}
+/**
+ * qfg-l18w: Operators Quonfig accepts in rule criteria. Mirrors the
+ * `OperatorSchema` enum in cli/src/verify/validate.ts (and app-quonfig's
+ * config-schemas.ts). If we emit an operator outside this set, qfg verify
+ * fails — which is what was happening for `PROP_SEMVER_*` in the FormHealth
+ * dry-run before this check existed. Keep this list in lockstep with the
+ * verify schema; a CI test in this file enforces parity.
+ */
+export const QUONFIG_SUPPORTED_OPERATORS = new Set([
+    'ALWAYS_TRUE',
+    'PROP_IS_ONE_OF',
+    'PROP_IS_NOT_ONE_OF',
+    'PROP_STARTS_WITH_ONE_OF',
+    'PROP_DOES_NOT_START_WITH_ONE_OF',
+    'PROP_ENDS_WITH_ONE_OF',
+    'PROP_DOES_NOT_END_WITH_ONE_OF',
+    'PROP_CONTAINS_ONE_OF',
+    'PROP_DOES_NOT_CONTAIN_ONE_OF',
+    'PROP_LESS_THAN',
+    'PROP_LESS_THAN_OR_EQUAL',
+    'PROP_GREATER_THAN',
+    'PROP_GREATER_THAN_OR_EQUAL',
+    'PROP_BEFORE',
+    'PROP_AFTER',
+    'PROP_MATCHES',
+    'PROP_DOES_NOT_MATCH',
+    'IN_SEG',
+    'NOT_IN_SEG',
+    'IN_INT_RANGE',
+    'LOOKUP_KEY_IN',
+    'LOOKUP_KEY_NOT_IN',
+]);
+/**
+ * qfg-l18w: Walk every rule criterion in a transformed config and fail-fast at
+ * migrate time if it carries an operator Quonfig does not understand. The
+ * primary offender today is `PROP_SEMVER_*` (Launch supports semver
+ * comparisons; Quonfig does not have a semver operator at all). Without this
+ * check the migrator silently writes invalid JSON and the failure surfaces
+ * later at qfg-verify — the customer's local file is broken and re-runs
+ * re-clobber any manual fix.
+ *
+ * Routes through `InvalidSourceConfigError` so the failure is per-config (the
+ * rest of the run still produces a usable workspace, and the offending key
+ * lands in MIGRATION_REPORT.md's "Skipped invalid configs" section with a
+ * specific reason — exactly what the customer needs to take to support).
+ */
+function collectUnsupportedOperators(rules) {
+    if (!Array.isArray(rules))
+        return [];
+    const found = [];
+    for (const rule of rules) {
+        if (!rule || typeof rule !== 'object')
+            continue;
+        const r = rule;
+        if (!Array.isArray(r.criteria))
+            continue;
+        for (const crit of r.criteria) {
+            if (!crit || typeof crit !== 'object')
+                continue;
+            const c = crit;
+            if (typeof c.operator !== 'string')
+                continue;
+            if (!QUONFIG_SUPPORTED_OPERATORS.has(c.operator)) {
+                found.push(c.operator);
+            }
+        }
+    }
+    return found;
+}
+function validateOperators(out) {
+    const offenders = new Set();
+    const defaultSection = out.default;
+    if (defaultSection) {
+        for (const op of collectUnsupportedOperators(defaultSection.rules))
+            offenders.add(op);
+    }
+    if (Array.isArray(out.environments)) {
+        for (const env of out.environments) {
+            for (const op of collectUnsupportedOperators(env.rules))
+                offenders.add(op);
+        }
+    }
+    if (offenders.size === 0)
+        return;
+    const key = String(out.key ?? 'unknown');
+    const sorted = [...offenders].sort();
+    throw new InvalidSourceConfigError(`Unsupported operator(s) for "${key}": ${sorted.join(', ')}. ` +
+        `Quonfig does not currently translate these from the source schema. ` +
+        `Recreate the rule in the source system using a supported operator (see qfg config-schema), ` +
+        `or contact support@quonfig.com if you need this operator added to Quonfig.`);
+}
 function zeroValue(valueType) {
     switch (valueType) {
         case 'bool': {
@@ -148,6 +248,11 @@ function normalizeJsonValuesInConfig(out) {
 }
 export function transformConfig(config, envIdMap, onDroppedEnv, onCoercedSentinel) {
     const out = JSON.parse(JSON.stringify(config));
+    // qfg-qhk1: normalize `/` to `.` in the key so the JSON `key` field matches
+    // the flat dotted filename the migrator will write.
+    if (typeof out.key === 'string') {
+        out.key = normalizeKey(out.key);
+    }
     delete out.changedBy;
     delete out.modifiedAt;
     delete out.createdAt;
@@ -244,25 +349,27 @@ export function transformConfig(config, envIdMap, onDroppedEnv, onCoercedSentine
         }
     }
     normalizeJsonValuesInConfig(out);
+    validateOperators(out);
     return out;
 }
 export function getOutputPath(type, key) {
     const normalizedType = type.toUpperCase();
+    const k = normalizeKey(key);
     switch (normalizedType) {
         case 'FEATURE_FLAG': {
-            return `feature-flags/${key}.json`;
+            return `feature-flags/${k}.json`;
         }
         case 'LOG_LEVEL_V2': {
-            return `log-levels/${normalizeLogLevelKey(key)}.json`;
+            return `log-levels/${normalizeLogLevelKey(k)}.json`;
         }
         case 'SCHEMA': {
-            return `schemas/${key}.json`;
+            return `schemas/${k}.json`;
         }
         case 'SEGMENT': {
-            return `segments/${key}.json`;
+            return `segments/${k}.json`;
         }
         default: {
-            return `configs/${key}.json`;
+            return `configs/${k}.json`;
         }
     }
 }

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/clone-and-stack-push.d.ts

@@ -13,8 +13,12 @@ export interface CloneAndStackPushOptions {
     author?: PushIdentity;
     /** Branch to track and push. Defaults to `main`. */
     branch?: string;
-    /** Single commit message for the delta. */
-    commitMessage: string;
+    /**
+     * Commit message for the delta. Pass a function when the message depends on
+     * counts that are only known after `applyDelta` runs (qfg-7eig). The function
+     * is invoked after applyDelta but before commit.
+     */
+    commitMessage: string | (() => string);
     /** Where to clone into, or an existing clone to reuse. */
     localDir: string;
     /** Gitea repo URL (may include token). */

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

@@ -62,7 +62,13 @@ const ensureCloneOrReuse = async (remoteUrl, localDir, branch) => {
             await runGit(localDir, ['merge', '--ff-only', `origin/${branch}`]);
             return 'reused';
         }
-        throw new Error(`Local dir ${localDir} is a git repo but its origin (${origin ? redactToken(origin) : 'unset'}) does not match the target remote. Refuse to clobber — pass an empty/non-existent path or a matching clone.`);
+        throw new Error(`Local dir ${localDir} is a git repo but its origin (${origin ? redactToken(origin) : 'unset'}) does not match the target remote.\n` +
+            `Refuse to clobber.\n\n` +
+            `Most likely cause: you ran \`qfg migrate --dir ${localDir}\` first (which \`git init\`s a fresh repo with no remote) and are now trying to \`--push\` from the same dir.\n\n` +
+            `Pick one of:\n` +
+            `  - Re-run with \`--push\` against a NEW empty/non-existent path (the canonical flow).\n` +
+            `  - Run \`qfg pull --workspace <org/slug> --dir ${localDir}-clone\` to seed a fresh clone, then \`qfg migrate --dir ${localDir}-clone --workspace <org/slug> --push\`.\n` +
+            `Docs: https://docs.quonfig.com/docs/migrating/from-launch (Flow B).`);
     }
     if (fs.existsSync(localDir)) {
         const entries = fs.readdirSync(localDir);
@@ -90,8 +96,9 @@ export const cloneAndStackPush = async (opts) => {
     if (!(await hasStagedChanges(opts.localDir))) {
         return { action, committed: false, commitSha: null };
     }
+    const commitMessage = typeof opts.commitMessage === 'function' ? opts.commitMessage() : opts.commitMessage;
     await spawnGit(['-C', opts.localDir, 'commit', '-F', '-'], {
-        stdin: opts.commitMessage,
+        stdin: commitMessage,
         env: {
             GIT_AUTHOR_NAME: author.name,
             GIT_AUTHOR_EMAIL: author.email,

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