@quonfig/cli 0.0.73 → 0.1.0

package/dist/util/git-ops.js

@@ -1,4 +1,4 @@
-import { execFile as execFileCb, spawn } from 'node:child_process';
+import { execFile as execFileCb, execFileSync, spawn } from 'node:child_process';
 import * as util from 'node:util';
 const execFile = util.promisify(execFileCb);
 /**
@@ -365,11 +365,309 @@ export const gitSetRemote = async (dir, url) => {
         await runGit(['-C', dir, 'remote', 'set-url', 'origin', url]);
     }
 };
-export const gitPushForceLease = async (dir) => {
-    await runGit(['-C', dir, 'push', 'origin', 'main', '--force-with-lease']);
+const revParse = async (dir, rev) => {
+    try {
+        const { stdout } = await runGit(['-C', dir, 'rev-parse', '--verify', '--quiet', rev]);
+        return stdout.trim() || null;
+    }
+    catch {
+        return null;
+    }
+};
+const treePaths = async (dir, rev) => {
+    const { stdout } = await runGit(['-C', dir, 'ls-tree', '-r', '--name-only', rev]);
+    return stdout
+        .split('\n')
+        .map((s) => s.trim())
+        .filter(Boolean);
+};
+const countCommits = async (dir, rev) => {
+    const { stdout } = await runGit(['-C', dir, 'rev-list', '--count', rev]);
+    return Number.parseInt(stdout.trim(), 10) || 0;
+};
+/**
+ * Every file the validator owns at `ref` — config documents (`configs/`,
+ * `feature-flags/`, `segments/`, `log-levels/`) AND schemas (`schemas/`,
+ * `schemas-protected/`) — sorted.
+ *
+ * A workspace repo is FRESH exactly when this list is empty. It is NOT "the
+ * remote holds only the auto-init commit": provisioning commits `README.md`
+ * AND `quonfig.json`, so a commit-count test refuses every real workspace
+ * (plan project/plans/2026-09-17-tree-derived-cache.md 5.6, 13.2 risk 5).
+ * Schemas count because a UI-authored schema is content a local-wins rebase
+ * would silently overwrite, exactly like a flag.
+ *
+ * FAILS CLOSED: if the ref cannot be listed this throws. "I could not look"
+ * must never read as "the workspace is empty".
+ */
+export const workspaceDocumentsAtRef = async (dir, ref) => {
+    // Dynamic import: `src/verify/` is copied on its own into the standalone
+    // pre-receive-hook build, so it must stay self-contained — and pulling the
+    // validator in statically would load it for every command that touches git.
+    const { KNOWN_DIRS } = await import('../verify/validate.js');
+    const paths = await treePaths(dir, ref);
+    return paths.filter((p) => KNOWN_DIRS.has(p.split('/')[0])).sort();
+};
+/** Subject of the one commit that puts the tree back to the customer's. */
+const RECONCILE_SUBJECT = 'reconcile merge resolutions';
+/** Subject when the only thing put back is the workspace's own pin file. */
+const PIN_SUBJECT = "use the hosted workspace's quonfig.json";
+/**
+ * `-c` args that keep the CUSTOMER's git config out of the commits bootstrap
+ * makes in the temporary worktree. A worktree shares the repo's config, so
+ * `commit.gpgsign=true` with an unusable `gpg.program` fails the rebase and a
+ * failing `pre-commit` under `core.hooksPath` fails the reconcile commit (both
+ * verified). Neither commit is the customer's to sign or to gate: the rebase
+ * replays commits they already made, and the reconcile commit only restores
+ * their own tree.
+ */
+const GIT_UNCONFIGURED_ARGS = [
+    '-c',
+    'commit.gpgsign=false',
+    '-c',
+    'tag.gpgsign=false',
+    '-c',
+    'core.hooksPath=/dev/null',
+    '-c',
+    'rebase.autosquash=false',
+    '-c',
+    'rerere.enabled=false',
+];
+/**
+ * The identity the CLI commits as when nothing better is known: `qfg push`
+ * and `qfg migrate` stack their commits under it, and bootstrap's replayed
+ * commits get it as COMMITTER when the machine has no git identity at all.
+ */
+export const MIGRATOR_IDENTITY = {
+    name: 'quonfig migrator',
+    email: 'migrator@quonfig.com',
+};
+/**
+ * Env that gives git a committer when it cannot find one itself, and nothing
+ * otherwise. A rebase writes a committer on every replayed commit, and git
+ * refuses ("empty ident name ... not allowed") on a machine with no
+ * `user.name` / `user.email` and no guessable one — every GitHub runner, and
+ * a fresh laptop. `git var GIT_COMMITTER_IDENT` is git's own check, so a
+ * customer whose identity works keeps it, guessed or configured.
+ */
+const committerFallbackEnv = async (dir) => {
+    try {
+        await runGit(['-C', dir, 'var', 'GIT_COMMITTER_IDENT']);
+        return {};
+    }
+    catch {
+        return {
+            GIT_AUTHOR_EMAIL: MIGRATOR_IDENTITY.email,
+            GIT_AUTHOR_NAME: MIGRATOR_IDENTITY.name,
+            GIT_COMMITTER_EMAIL: MIGRATOR_IDENTITY.email,
+            GIT_COMMITTER_NAME: MIGRATOR_IDENTITY.name,
+        };
+    }
+};
+const hasMismatch = (m) => m.pinLost || m.content.length > 0;
+const describeMismatch = (m) => [...m.content, ...(m.pinLost ? ["quonfig.json (the workspace's pin was lost)"] : [])].join(', ');
+const treeMismatch = async (dir, opts) => {
+    const { stdout } = await runGit(['-C', dir, 'diff', '--no-renames', '--name-status', opts.local, opts.candidate]);
+    const content = [];
+    for (const line of stdout.split('\n').filter(Boolean)) {
+        const [status, ...rest] = line.split('\t');
+        const file = rest.join('\t');
+        // A file only the workspace had is expected to appear.
+        if (status === 'A' && opts.seededOnly.has(file))
+            continue;
+        // The workspace's own quonfig.json wins over a local one: it is the pin
+        // that names the hosted workspace. Checked separately, below.
+        if (file === 'quonfig.json' && opts.remoteQuonfigJson !== null)
+            continue;
+        content.push(`${status} ${file}`);
+    }
+    let pinLost = false;
+    if (opts.remoteQuonfigJson !== null) {
+        const candidatePin = await revParse(dir, `${opts.candidate}:quonfig.json`);
+        pinLost = candidatePin !== opts.remoteQuonfigJson;
+    }
+    return { content, pinLost };
 };
-export const gitPushForce = async (dir) => {
-    await runGit(['-C', dir, 'push', 'origin', 'main', '--force']);
+const removeWorktree = async (dir, worktree) => {
+    try {
+        await runGit(['-C', dir, 'worktree', 'remove', '--force', worktree]);
+    }
+    catch {
+        /* already gone, or never created */
+    }
+    try {
+        await runGit(['-C', dir, 'worktree', 'prune']);
+    }
+    catch {
+        /* best effort */
+    }
+};
+/**
+ * Run the workspace validator — the same one the server's pre-receive hook
+ * runs — over a checked-out tree, and throw with its errors if it would be
+ * rejected.
+ */
+const requireWorkspaceValidates = async (tree) => {
+    const { validateWorkspace } = await import('../verify/validate.js');
+    const errors = validateWorkspace(tree).issues.filter((i) => i.severity === 'error');
+    if (errors.length === 0)
+        return;
+    const shown = errors.slice(0, 10).map((i) => `  ${i.file}: ${i.message}`);
+    if (errors.length > shown.length)
+        shown.push(`  ...and ${errors.length - shown.length} more`);
+    const envHint = errors.some((i) => i.message.includes('not declared in quonfig.json'))
+        ? "\nThe workspace's own quonfig.json replaces yours, so an environment that exists only in your local file is not declared on the workspace. Create it in the Quonfig app (or drop the override), then run bootstrap again."
+        : '';
+    throw new Error(`Refusing to push: the workspace would reject this content.\n${shown.join('\n')}${envHint}\nNothing was pushed and your local repository is unchanged.`);
+};
+/**
+ * Land the local repo's history on `origin/main` WITHOUT ever force-pushing
+ * (plan 5.6 "Bootstrap keeps its history without force"; `main` is
+ * append-only, so a rewrite is not just forbidden, it silently wedges config
+ * delivery).
+ *
+ * `git fetch origin` is the caller's job. Then:
+ *
+ *   1. Replay the whole local history onto the remote head on a TEMPORARY
+ *      worktree — never on the customer's branch. Whatever happens, their
+ *      local refs and working tree are untouched.
+ *   2. Require the replayed tip's tree to equal the local tip's tree, ignoring
+ *      files the workspace seeded that the local repo does not have. Rebasing
+ *      linearises merges and `-X theirs` silently picks a side, so a
+ *      hand-resolved merge conflict can otherwise ship the wrong content with
+ *      exit 0 (13.2 risk 4).
+ *   3. If it differs, add ONE commit that sets the tree to the local tip's
+ *      tree, keeping the seeded files and the workspace's `quonfig.json`. If
+ *      that cannot be done cleanly, abort with nothing pushed.
+ *   4. Validate the tree that is ACTUALLY about to be pushed (unless
+ *      `validate: false`), so content the workspace would reject fails here
+ *      instead of at the server hook.
+ *   5. Plain `git push` of the result to `main`.
+ */
+export const rebaseOntoOriginAndPush = async (dir, opts) => {
+    const localHead = await revParse(dir, 'HEAD');
+    if (localHead === null)
+        throw new Error('The local repository has no commits to push.');
+    const remoteHead = await revParse(dir, 'origin/main');
+    if (remoteHead === null) {
+        // Provisioning always creates `main` with auto_init, and the pre-receive
+        // hook rejects a zero-oid create (plan 5.6 item 1), so pushing the branch
+        // into existence is a dead end, not a fallback.
+        throw new Error('The workspace repository is not provisioned (it has no `main` branch).\nFinish creating the workspace in the Quonfig app, then run bootstrap again.');
+    }
+    const remotePaths = await treePaths(dir, remoteHead);
+    const localPaths = new Set(await treePaths(dir, localHead));
+    const seededOnly = new Set(remotePaths.filter((p) => !localPaths.has(p)));
+    const remoteQuonfigJson = remotePaths.includes('quonfig.json')
+        ? await revParse(dir, `${remoteHead}:quonfig.json`)
+        : null;
+    const { tmpdir } = await import('node:os');
+    const { join } = await import('node:path');
+    const worktree = join(tmpdir(), `qfg-bootstrap-${process.pid}-${Date.now()}`);
+    // The rebase keeps each commit's AUTHOR; this only decides the committer
+    // (and the author of the reconcile commit, which is the CLI's own).
+    const identityEnv = await committerFallbackEnv(dir);
+    // Ctrl-C between `worktree add` and the `finally` would leave the temp
+    // worktree registered in the customer's repo; drop it synchronously.
+    const onInterrupt = () => {
+        try {
+            execFileSync('git', [...GIT_SAFE_ARGS, '-C', dir, 'worktree', 'remove', '--force', worktree], { stdio: 'ignore' });
+        }
+        catch {
+            /* best effort — `git worktree prune` also clears it later */
+        }
+        // eslint-disable-next-line n/no-process-exit, unicorn/no-process-exit
+        process.exit(130);
+    };
+    process.once('SIGINT', onInterrupt);
+    try {
+        await runGit(['-C', dir, 'worktree', 'add', '--detach', worktree, localHead]);
+        try {
+            await runGit([
+                '-C',
+                worktree,
+                ...GIT_UNCONFIGURED_ARGS,
+                'rebase',
+                '--root',
+                '--onto',
+                remoteHead,
+                '-X',
+                'theirs',
+                '--committer-date-is-author-date',
+            ], { env: identityEnv });
+        }
+        catch (error) {
+            try {
+                await runGit(['-C', worktree, 'rebase', '--abort']);
+            }
+            catch {
+                /* nothing to abort */
+            }
+            throw new Error([
+                'Could not replay your history onto the workspace repository.',
+                'Nothing was pushed and your local repository is unchanged.',
+                '',
+                'To land the files you have now WITHOUT their history, run:',
+                `  qfg push --dir ${dir}`,
+                '',
+                String(error),
+            ].join('\n'));
+        }
+        let candidate = await revParse(worktree, 'HEAD');
+        if (candidate === null)
+            throw new Error('The rebase produced no commit. Nothing was pushed.');
+        let reconcileSubject = null;
+        let mismatch = await treeMismatch(dir, { candidate, local: localHead, remoteQuonfigJson, seededOnly });
+        if (hasMismatch(mismatch)) {
+            // Honest subject: when the ONLY thing being put back is the workspace's
+            // own pin file, nothing was "reconciled" and saying so would be a lie.
+            reconcileSubject = mismatch.content.length > 0 ? RECONCILE_SUBJECT : PIN_SUBJECT;
+            const body = reconcileSubject === RECONCILE_SUBJECT
+                ? 'Sets the tree to the state of the local repository, keeping the files this workspace already had. Replaying merge commits one by one can otherwise resolve a conflict differently than you did.'
+                : 'The hosted workspace seeds its own quonfig.json, which carries the workspace pin and its environment list, so it wins over the one in the local repository.';
+            const keepFromRemote = [...seededOnly];
+            if (remoteQuonfigJson !== null && !seededOnly.has('quonfig.json'))
+                keepFromRemote.push('quonfig.json');
+            try {
+                await runGit(['-C', worktree, 'restore', `--source=${localHead}`, '--staged', '--worktree', '--', '.']);
+                if (keepFromRemote.length > 0) {
+                    await runGit([
+                        '-C',
+                        worktree,
+                        'restore',
+                        `--source=${remoteHead}`,
+                        '--staged',
+                        '--worktree',
+                        '--',
+                        ...keepFromRemote,
+                    ]);
+                }
+                await runGit(['-C', worktree, ...GIT_UNCONFIGURED_ARGS, 'commit', '--no-verify', '-m', reconcileSubject, '-m', body], { env: identityEnv });
+            }
+            catch (error) {
+                throw new Error(`Could not reconcile your local content with the workspace repository: ${String(error)}\nNothing was pushed and your local repository is unchanged.`);
+            }
+            candidate = await revParse(worktree, 'HEAD');
+            if (candidate === null)
+                throw new Error('The reconcile commit produced no commit. Nothing was pushed.');
+            mismatch = await treeMismatch(dir, { candidate, local: localHead, remoteQuonfigJson, seededOnly });
+            if (hasMismatch(mismatch)) {
+                throw new Error(`Refusing to push: the result would not match your local files (${describeMismatch(mismatch)}).\nNothing was pushed and your local repository is unchanged.`);
+            }
+        }
+        // Validate what is ACTUALLY going to be pushed. The worktree holds exactly
+        // the candidate's tree, which is the local content plus the workspace's own
+        // quonfig.json — so an environment that exists only in the local pin file
+        // fails HERE, with a readable message, instead of at the server hook.
+        if (opts?.validate !== false)
+            await requireWorkspaceValidates(worktree);
+        await runGit(['-C', dir, 'push', 'origin', `${candidate}:refs/heads/main`]);
+        return { commitsRebased: await countCommits(dir, localHead), pushedSha: candidate, reconcileSubject };
+    }
+    finally {
+        process.off('SIGINT', onInterrupt);
+        await removeWorktree(dir, worktree);
+    }
 };
 export const hasAtLeastOneCommit = async (dir) => {
     try {

package/dist/verify/standalone.d.ts

@@ -10,6 +10,37 @@
  *   0  All checks pass
  *   1  Validation errors found
  */
+export type RefUpdate = {
+    newOid: string;
+    oldOid: string;
+    refName: string;
+};
+export type HookEnv = Record<string, string | undefined>;
+export type HookOptions = {
+    cwd?: string;
+    env: HookEnv;
+    log: (line: string) => void;
+    logErr: (line: string) => void;
+};
+/**
+ * The whole pre-receive decision, as a function: returns the process exit code
+ * (0 accept, 1 reject). Split out of runGitHook so tests can drive it against
+ * real bare repos without a subprocess.
+ */
+export declare function runHookChecks(refs: readonly RefUpdate[], opts: HookOptions): number;
+/** The `cli` sha this binary was built from; `dev` for an unstamped build. */
+export declare function hookVersion(env?: HookEnv): string;
+/**
+ * `main` is append-only: every update to refs/heads/main must have a non-zero
+ * old oid that is an ancestor of the new oid. A delete and a create are both
+ * rejected (provisioning creates `main` with auto_init; no writer creates it by
+ * push, and the zero-oid door is the only way to delete-then-recreate).
+ * Other refs are untouched. See plan 2026-09-17-tree-derived-cache 5.6.
+ */
+export declare function checkAppendOnlyMain(refs: readonly RefUpdate[], env: HookEnv, cwd?: string): {
+    bypassReason?: string;
+    errors: string[];
+};
 /**
  * Read all JSON config files from a git commit using `git show`.
  * Works in bare repos (no working tree needed).

package/dist/verify/standalone.js

@@ -10,7 +10,7 @@
  *   0  All checks pass
  *   1  Validation errors found
  */
-import { execFileSync } from 'node:child_process';
+import { execFileSync, spawnSync } from 'node:child_process';
 import * as readline from 'node:readline';
 import { formatResult, validateFileMap, validateWorkspace } from './validate.js';
 async function main() {
@@ -57,36 +57,181 @@ async function runGitHook() {
         rl.on('line', (line) => {
             const parts = line.trim().split(' ');
             if (parts.length >= 3) {
-                refs.push({ oldOid: parts[0], newOid: parts[1], refName: parts[2] });
+                refs.push({ newOid: parts[1], oldOid: parts[0], refName: parts[2] });
             }
         });
         rl.on('close', resolve);
     });
+    process.exit(runHookChecks(refs, { env: process.env, log: console.log, logErr: console.error }));
+}
+/**
+ * The whole pre-receive decision, as a function: returns the process exit code
+ * (0 accept, 1 reject). Split out of runGitHook so tests can drive it against
+ * real bare repos without a subprocess.
+ */
+export function runHookChecks(refs, opts) {
+    const { cwd, env, log, logErr } = opts;
+    // Always the first line, so a rollout or rollback can be confirmed by
+    // something other than behaviour (plan 5.6 item 5).
+    log(`qfg-verify ${hookVersion(env)}`);
     if (refs.length === 0) {
-        console.log('qfg-verify: no refs received');
-        process.exit(0);
+        log('qfg-verify: no refs received');
+        return 0;
     }
-    // Validate the latest pushed commit for each ref
     let hasErrors = false;
+    // Append-only `main` (qfg-jxml.21). Runs BEFORE content validation, but does
+    // not short-circuit it: an operator repair is still validated for content.
+    const appendOnly = checkAppendOnlyMain(refs, env, cwd);
+    if (appendOnly.bypassReason) {
+        logErr(`qfg-verify: operator rewrite bypass by ${env.GITEA_PUSHER_NAME ?? '?'}: ${appendOnly.bypassReason}`);
+    }
+    for (const message of appendOnly.errors) {
+        logErr(message);
+        hasErrors = true;
+    }
+    // Content validation: the latest pushed commit for each ref.
     for (const ref of refs) {
         // Skip deletions
-        if (ref.newOid === '0000000000000000000000000000000000000000')
+        if (isZeroOid(ref.newOid))
             continue;
-        console.log(`qfg-verify: validating ${ref.refName} (${ref.newOid.slice(0, 8)})`);
+        log(`qfg-verify: validating ${ref.refName} (${ref.newOid.slice(0, 8)})`);
         try {
-            const files = readFilesFromCommit(ref.newOid);
+            const files = readFilesFromCommit(ref.newOid, cwd);
             const result = validateFileMap(files);
-            console.log(formatResult(result));
+            log(formatResult(result));
             if (!result.valid) {
                 hasErrors = true;
             }
         }
         catch (error) {
-            console.error(`qfg-verify: error reading commit ${ref.newOid}: ${error.message}`);
+            logErr(`qfg-verify: error reading commit ${ref.newOid}: ${error.message}`);
             hasErrors = true;
         }
     }
-    process.exit(hasErrors ? 1 : 0);
+    return hasErrors ? 1 : 0;
+}
+function isZeroOid(oid) {
+    return /^0+$/.test(oid);
+}
+/** The `cli` sha this binary was built from; `dev` for an unstamped build. */
+export function hookVersion(env = process.env) {
+    return env.QFG_VERIFY_SHA?.trim() || 'dev';
+}
+const MAIN_REF = 'refs/heads/main';
+const REWRITE_OPTION = 'quonfig-rewrite=';
+/**
+ * `main` is append-only: every update to refs/heads/main must have a non-zero
+ * old oid that is an ancestor of the new oid. A delete and a create are both
+ * rejected (provisioning creates `main` with auto_init; no writer creates it by
+ * push, and the zero-oid door is the only way to delete-then-recreate).
+ * Other refs are untouched. See plan 2026-09-17-tree-derived-cache 5.6.
+ */
+export function checkAppendOnlyMain(refs, env, cwd) {
+    const mainUpdates = refs.filter((ref) => ref.refName === MAIN_REF);
+    if (mainUpdates.length === 0 || !ffEnforcedForRepo(env))
+        return { errors: [] };
+    const bypassReason = operatorBypassReason(env);
+    if (bypassReason)
+        return { bypassReason, errors: [] };
+    const errors = [];
+    for (const ref of mainUpdates) {
+        try {
+            if (isZeroOid(ref.newOid)) {
+                errors.push(rejection('deleting main is not allowed'));
+            }
+            else if (isZeroOid(ref.oldOid)) {
+                errors.push(rejection('creating main by push is not allowed'));
+            }
+            else if (!isAncestor(ref.oldOid, ref.newOid, cwd)) {
+                errors.push(rejection(`${ref.newOid.slice(0, 8)} is not a descendant of the current tip ${ref.oldOid.slice(0, 8)}`));
+            }
+        }
+        catch (error) {
+            // The ancestry check itself failed: git exited 128 (old oid missing from
+            // the repo), git could not be spawned, ... Fail CLOSED, but as the normal
+            // rejection with the recovery recipe — an escaped throw reaches the
+            // pusher as an opaque `qfg-verify: fatal: ...` (qfg-jxml.21 review).
+            errors.push(rejection(`could not check that ${ref.newOid.slice(0, 8)} descends from the current tip ${ref.oldOid.slice(0, 8)}: ${error.message}`));
+        }
+    }
+    return { errors };
+}
+/** Rollout switch: enforce only for repos named in the allowlist; `*` = all. */
+function ffEnforcedForRepo(env) {
+    const allowlist = (env.QUONFIG_HOOK_FF_ENFORCE ?? '')
+        .split(',')
+        .map((entry) => entry.trim().toLowerCase())
+        .filter(Boolean);
+    if (allowlist.length === 0)
+        return false;
+    if (allowlist.includes('*'))
+        return true;
+    // Gitea 1.25 hands the hook its repo via these (modules/repository/env.go).
+    const owner = (env.GITEA_REPO_USER_NAME ?? '').trim().toLowerCase();
+    const name = (env.GITEA_REPO_NAME ?? '').trim().toLowerCase();
+    if (!owner || !name)
+        return false;
+    return allowlist.includes(`${owner}/${name}`);
+}
+/**
+ * Operator bypass, two keys, BOTH required: the pusher is the operator admin
+ * account (the app pushes as admin too, so identity only excludes customers)
+ * AND the push declares a reason with `-o quonfig-rewrite=<reason>` (which is
+ * what excludes accidents). No flag-file fallback.
+ */
+function operatorBypassReason(env) {
+    const operator = (env.QUONFIG_HOOK_OPERATOR ?? '').trim();
+    const pusher = (env.GITEA_PUSHER_NAME ?? '').trim();
+    if (!operator || !pusher || pusher.toLowerCase() !== operator.toLowerCase())
+        return undefined;
+    const count = Number.parseInt(env.GIT_PUSH_OPTION_COUNT ?? '', 10);
+    if (!Number.isInteger(count))
+        return undefined;
+    for (let index = 0; index < count; index++) {
+        const option = env[`GIT_PUSH_OPTION_${index}`] ?? '';
+        if (option.startsWith(REWRITE_OPTION)) {
+            const reason = option.slice(REWRITE_OPTION.length).trim();
+            if (reason)
+                return reason;
+        }
+    }
+    return undefined;
+}
+/**
+ * `git merge-base --is-ancestor` via spawnSync, never simple-git: simple-git
+ * swallows a non-zero exit with no stderr, so a diverged pair would RESOLVE as
+ * "ancestor" and the rule would be vacuous (plan 12.2 S2). Exit 1 = not an
+ * ancestor; any other non-zero is an error and the push is rejected.
+ * The env is inherited as-is so Gitea's quarantine (GIT_QUARANTINE_PATH,
+ * GIT_OBJECT_DIRECTORY, GIT_ALTERNATE_OBJECT_DIRECTORIES) still resolves the
+ * incoming objects.
+ */
+function isAncestor(oldOid, newOid, cwd) {
+    const result = spawnSync('git', ['merge-base', '--is-ancestor', oldOid, newOid], { cwd, encoding: 'utf8' });
+    if (result.error)
+        throw result.error;
+    if (result.status === 0)
+        return true;
+    if (result.status === 1)
+        return false;
+    throw new Error(`git merge-base --is-ancestor exited ${result.status}: ${(result.stderr || '').trim()}`);
+}
+function rejection(what) {
+    return `qfg-verify: REJECTED ${MAIN_REF}: ${what}.
+
+main is append-only: every push must fast-forward from the current tip. What to do:
+
+  * Lost a race with another writer -- pull and rebase, then push again:
+      qfg pull && qfg push        (or: git pull --rebase origin main && git push origin main)
+
+  * Want the content from an earlier commit -- restore it as a FORWARD commit:
+      git restore --source=<sha> --staged --worktree -- .
+      git commit -m "restore <sha>"
+      qfg push
+
+  * This came from \`qfg workspace bootstrap\` on an older CLI, which force-pushes --
+    upgrade the CLI and run it again:
+      npm install -g @quonfig/cli@latest`;
 }
 /**
  * Read all JSON config files from a git commit using `git show`.

package/dist/verify/validate.d.ts

@@ -47,6 +47,8 @@ export interface ValidationResult {
     stats: ValidationStats;
     valid: boolean;
 }
+/** Every directory this validator owns: config documents plus schemas. */
+export declare const KNOWN_DIRS: Set<string>;
 /**
  * Validate an entire workspace directory on disk.
  */

package/dist/verify/validate.js

@@ -157,9 +157,11 @@ const DIR_TO_TYPE = {
     segments: 'segment',
     'log-levels': 'log_level',
 };
+/** The directories a config document can live in. Source of truth. */
 const CONFIG_DIRS = new Set(Object.keys(DIR_TO_TYPE));
 const SCHEMA_DIRS = new Set(['schemas', 'schemas-protected']);
-const KNOWN_DIRS = new Set([...CONFIG_DIRS, ...SCHEMA_DIRS]);
+/** Every directory this validator owns: config documents plus schemas. */
+export const KNOWN_DIRS = new Set([...CONFIG_DIRS, ...SCHEMA_DIRS]);
 // ── Ghost-file prevention (qfg-hbuy.4) ──────────────────────────────────
 // Within the validated content dirs (KNOWN_DIRS), every entry must be a
 // top-level, non-dot, lowercase-`.json` file. Anything else used to be

package/dist/version.d.ts

@@ -1,2 +1,2 @@
-declare const _default: "0.0.73";
+declare const _default: "0.1.0";
 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.73';
+export default '0.1.0';

package/oclif.manifest.json

@@ -1600,7 +1600,7 @@
           "type": "boolean"
         },
         "env": {
-          "description": "environment to operate in (default: $QUONFIG_ENVIRONMENT)",
+          "description": "environment to operate in (required; QUONFIG_ENVIRONMENT is never read)",
           "name": "env",
           "hasDynamicHelp": false,
           "multiple": false,
@@ -2176,7 +2176,8 @@
           "type": "option"
         },
         "environment": {
-          "description": "Which environment slug to evaluate. Honors QUONFIG_ENVIRONMENT.",
+          "description": "Which environment slug to evaluate. Flag wins, then QUONFIG_ENVIRONMENT (serve hosts a service, so the var is its identity), then development.",
+          "env": "QUONFIG_ENVIRONMENT",
           "name": "environment",
           "default": "development",
           "hasDynamicHelp": false,
@@ -3981,7 +3982,7 @@
           "type": "option"
         },
         "force": {
-          "description": "Force push even if remote already has commits",
+          "description": "Accepted and ignored (no-op). Bootstrap never rewrites the workspace history.",
           "name": "force",
           "allowNo": false,
           "type": "boolean"
@@ -4149,5 +4150,5 @@
       ]
     }
   },
-  "version": "0.0.73"
+  "version": "0.1.0"
 }

package/package.json

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