@quonfig/cli 0.0.74 → 0.1.0

package/dist/commands/workspace/bootstrap.js

@@ -4,9 +4,16 @@ import { Flags } from '@oclif/core';
 import { BaseCommand } from '../../index.js';
 import { getActiveProfile, loadAuthConfig } from '../../util/token-storage.js';
 import { mintGiteaToken } from '../../util/gitea-api.js';
-import { readWorkspaceSlug, tryParseWorkspacePin, writeWorkspaceSlug } from '../../util/quonfig-json.js';
+import { bootstrapPinMismatch, describeBootstrapTarget } from '../../util/bootstrap-target.js';
+import { readWorkspaceSlug } from '../../util/quonfig-json.js';
 import { resolveWorkspaceUuid } from '../../util/resolve-workspace.js';
-import { isGitRepo, hasAtLeastOneCommit, gitSetRemote, gitPushForceLease, gitPushForce, getRemoteUrl, displayUrl, runGit, } from '../../util/git-ops.js';
+import { isGitRepo, hasAtLeastOneCommit, gitSetRemote, gitFetch, workspaceDocumentsAtRef, rebaseOntoOriginAndPush, getRemoteUrl, getOriginMainSha, displayUrl, } from '../../util/git-ops.js';
+/**
+ * How the customer points their clone at the workspace after bootstrap.
+ * `pre-bootstrap` keeps their original history; the reset is safe because the
+ * pushed tree was proven equal to their tree before the push.
+ */
+const LOCAL_RESET_RECIPE = 'git branch pre-bootstrap && git fetch origin && git reset --hard origin/main';
 export default class WorkspaceBootstrap extends BaseCommand {
     static description = "Push a local git repo to Gitea as this workspace's config repository";
     static examples = [
@@ -21,7 +28,7 @@ export default class WorkspaceBootstrap extends BaseCommand {
         }),
         force: Flags.boolean({
             default: false,
-            description: 'Force push even if remote already has commits',
+            description: 'Accepted and ignored (no-op). Bootstrap never rewrites the workspace history.',
         }),
         'skip-validate': Flags.boolean({
             default: false,
@@ -33,13 +40,34 @@ export default class WorkspaceBootstrap extends BaseCommand {
         // Resolve target directory
         const dir = flags.dir || process.env.QUONFIG_DIR || process.cwd();
         const resolvedDir = path.resolve(dir);
-        const { workspaceId, orgSlug } = await resolveWorkspaceUuid(this);
-        // The display name is best-effort; we still want it for the confirmation
-        // prompt. Fall back through saved profile → workspaceId UUID.
+        // `--force` is kept so pinned scripts don't die on an unknown flag, but a
+        // workspace's `main` is append-only: nothing here ever rewrites it.
+        if (flags.force) {
+            this.log('Note: --force is accepted for compatibility and ignored — bootstrap never rewrites the workspace.\n');
+        }
+        // The target is resolved like push/pull/sync resolve theirs: QUONFIG_WORKSPACE,
+        // then the directory's quonfig.json pin, then the active profile.
+        const { workspaceId, orgSlug } = await resolveWorkspaceUuid(this, undefined, resolvedDir);
+        // The pin is read again here for the prompt and for the mismatch guard
+        // below. A legacy bare-slug pin reads as "no pin", as it does for push.
+        let pin;
+        try {
+            pin = await readWorkspaceSlug(resolvedDir);
+        }
+        catch {
+            pin = undefined;
+        }
+        // The prompt names whichever source chose the target; the profile only
+        // when it IS the resolved workspace (qfg-8p8i).
         const authConfig = await loadAuthConfig();
         const activeProfile = getActiveProfile();
         const profile = authConfig?.profiles[activeProfile] || authConfig?.profiles[authConfig?.defaultProfile || 'default'];
-        const workspaceName = profile?.workspaceSlug || profile?.workspaceName || workspaceId;
+        const workspaceName = describeBootstrapTarget({
+            envOverride: process.env.QUONFIG_WORKSPACE,
+            pin,
+            profile,
+            workspaceId,
+        });
         this.verboseLog('WorkspaceBootstrap', { workspaceId, orgSlug, dir: resolvedDir });
         // Validate: must be a git repo with at least one commit
         const isRepo = await isGitRepo(resolvedDir);
@@ -101,16 +129,11 @@ export default class WorkspaceBootstrap extends BaseCommand {
         }
         const { repoUrl, workspaceSlug: backendSlug } = tokenData;
         this.verboseLog('WorkspaceBootstrap', { repoUrl: displayUrl(repoUrl), backendSlug });
-        // Idempotency: check if remote already has commits
-        if (!flags.force) {
-            const remoteHasCommits = await this.remoteHasCommits(repoUrl);
-            if (remoteHasCommits) {
-                this.log(`\nThe remote repository already has commits.`);
-                this.log(`Run \`qfg pull --dir ${resolvedDir}\` to sync, then re-run bootstrap.`);
-                this.log(`Or run with --force to overwrite the remote.\n`);
-                return this.err('Remote is not empty.');
-            }
-        }
+        // Guard, as `qfg push` has: a directory pinned to one workspace is not
+        // pushed to another. Checked before the remote is touched.
+        const mismatch = bootstrapPinMismatch(pin, backendSlug);
+        if (mismatch)
+            return this.err(mismatch);
         // Set remote
         if (existingRemote) {
             this.log(`Updating remote origin...`);
@@ -119,96 +142,65 @@ export default class WorkspaceBootstrap extends BaseCommand {
             this.log(`Setting remote origin...`);
         }
         await gitSetRemote(resolvedDir, repoUrl);
-        // Push
+        await gitFetch(resolvedDir);
+        // Every workspace repo is provisioned with `main`; no `main` means the
+        // workspace is half-created, and the pre-receive hook rejects creating it
+        // by push (plan 5.6 item 1).
+        if ((await getOriginMainSha(resolvedDir)) === undefined) {
+            return this.err('The workspace repository is not provisioned (it has no `main` branch).\nFinish creating the workspace in the Quonfig app, then run bootstrap again.');
+        }
+        // Bootstrap is for a FRESH workspace only. "Fresh" is "holds no documents",
+        // NOT "has no commits": provisioning seeds README.md and quonfig.json, so
+        // every real workspace arrives with two commits (plan
+        // 2026-09-17-tree-derived-cache.md 5.6, 13.2 risk 5).
+        const documents = await workspaceDocumentsAtRef(resolvedDir, 'origin/main');
+        if (documents.length > 0) {
+            const sample = documents.slice(0, 3).join(', ') + (documents.length > 3 ? ', ...' : '');
+            this.log(`\nThis workspace already holds ${documents.length} document(s): ${sample}`);
+            this.log(`Bootstrap lands your local history UNDER what is already there, so it is for fresh workspaces only.`);
+            this.log(`To send local changes to a workspace that is already in use, run:`);
+            this.log(`  qfg push --dir ${resolvedDir}\n`);
+            return this.err('Workspace is not empty.');
+        }
+        // Push. The history is replayed onto the workspace's own head on a
+        // temporary worktree and pushed plainly: `main` is append-only, and a
+        // force-push silently wedges config delivery (plan 5.6).
         this.log('Pushing to Gitea...');
+        let pushResult;
         try {
-            if (flags.force) {
-                await gitPushForce(resolvedDir);
-            }
-            else {
-                await gitPushForceLease(resolvedDir);
-            }
+            // Validation runs again against the tree that is actually pushed (which
+            // carries the WORKSPACE's quonfig.json, not the local one), so content
+            // the server would reject fails here.
+            pushResult = await rebaseOntoOriginAndPush(resolvedDir, { validate: !flags['skip-validate'] });
         }
         catch (error) {
             return this.err(`Push failed: ${String(error)}`);
         }
-        // Write the workspace pin into `quonfig.json` (Guard 1 in
-        // project/plans/cli-git-sync.md). If the pin already exists and disagrees,
-        // we keep what is there — bootstrap is for fresh cases, not re-pinning.
-        // If we do write it, commit and push so the bootstrap leaves no
-        // uncommitted changes behind.
-        //
-        // The pin is stored as `<org-slug>/<workspace-slug>`. The backend's
-        // `workspaceSlug` is just the workspace component today; until the
-        // server returns the slash form, we skip the write rather than
-        // emitting a bare slug.
-        const backendPin = tryParseWorkspacePin(backendSlug);
-        try {
-            const existingPin = await readWorkspaceSlug(resolvedDir);
-            const existingFormatted = existingPin ? `${existingPin.orgSlug}/${existingPin.workspaceSlug}` : undefined;
-            if (!backendPin) {
-                this.verboseLog('WorkspaceBootstrap', `Backend workspaceSlug "${backendSlug}" is not in <org>/<ws> form; skipping pin write.`);
-            }
-            else if (existingPin &&
-                (existingPin.orgSlug !== backendPin.orgSlug || existingPin.workspaceSlug !== backendPin.workspaceSlug)) {
-                const backendFormatted = `${backendPin.orgSlug}/${backendPin.workspaceSlug}`;
-                this.log('');
-                this.log(`Warning: quonfig.json already pins workspace "${existingFormatted}", but the backend says this workspace is "${backendFormatted}".`);
-                this.log('Leaving the existing pin in place. If this is wrong, edit quonfig.json manually and re-run.');
-            }
-            else if (existingPin) {
-                this.verboseLog('WorkspaceBootstrap', `quonfig.json already pinned to ${existingFormatted}; no-op.`);
-            }
-            else {
-                const backendFormatted = `${backendPin.orgSlug}/${backendPin.workspaceSlug}`;
-                this.log('');
-                this.log(`Pinning quonfig.json to workspace "${backendFormatted}"...`);
-                await writeWorkspaceSlug(resolvedDir, backendPin);
-                await this.commitAndPushPin(resolvedDir, backendFormatted, flags.force);
-            }
-        }
-        catch (error) {
-            // The main push has already succeeded, so don't fail the whole command.
-            // Surface the issue clearly so the user knows to follow up.
-            this.log('');
-            this.log(`Warning: could not write the workspace pin to quonfig.json: ${String(error)}`);
-            this.log('The workspace is connected, but you should re-run `qfg pull` to backfill the pin.');
+        this.log(`Landed ${pushResult.commitsRebased} commit(s) on the workspace's history.`);
+        if (pushResult.reconcileSubject !== null) {
+            this.log(`Added one commit ("${pushResult.reconcileSubject}") so the workspace tree matches your local files.`);
         }
         this.log(`\nBootstrap complete.`);
-        this.log(`Workspace "${workspaceName}" is now connected to your local directory.`);
-        this.log(`\nTo keep it in sync locally, run:`);
-        this.log(`  qfg sync --watch --dir ${resolvedDir}`);
+        this.log(`Workspace "${workspaceName}" now holds the history from ${resolvedDir}.`);
+        // The customer's branch is never touched, on success or failure, so it
+        // still points at the pre-bootstrap history — which shares no commit with
+        // what was just pushed (the replayed commits have new ids). `qfg pull` and
+        // `qfg sync` both refuse that state ("diverge" / STALE_HEAD), so the only
+        // honest advice is a reset onto the workspace.
+        //
+        // If we ever move the local branch ourselves (option A: save
+        // refs/quonfig/pre-bootstrap and fast-forward `main` to pushedSha once
+        // tree equality is proven), this block is what it replaces.
+        this.log(`\nYour local branch was not moved. The workspace has the same content under new commit ids.`);
+        this.log(`To point this clone at the workspace, keeping your old history on a branch:`);
+        this.log(`  ${LOCAL_RESET_RECIPE}`);
         return {
+            commitsRebased: pushResult.commitsRebased,
             dir: resolvedDir,
+            localResetRecipe: LOCAL_RESET_RECIPE,
+            reconciled: pushResult.reconcileSubject !== null,
             repoUrl: displayUrl(repoUrl),
             workspaceId,
         };
     }
-    /**
-     * Stage, commit, and push the `quonfig.json` pin. Runs after the main
-     * bootstrap push so the pin lands as a committed+pushed change rather than
-     * an uncommitted local edit. We stage only `quonfig.json` (not `-A`) so we
-     * don't accidentally sweep in unrelated user edits.
-     */
-    async commitAndPushPin(dir, slug, force) {
-        // Stage just quonfig.json so we don't accidentally commit other dirty files.
-        await runGit(['-C', dir, 'add', 'quonfig.json']);
-        // If `git add` produced no staged change (e.g. content matched an earlier
-        // version on disk), `git commit` would fail. Check the index first.
-        const { stdout: diffStat } = await runGit(['-C', dir, 'diff', '--cached', '--name-only']);
-        if (!diffStat.trim()) {
-            this.verboseLog('WorkspaceBootstrap', 'quonfig.json pin matches HEAD; no commit needed.');
-            return;
-        }
-        await runGit(['-C', dir, 'commit', '-m', `chore: pin quonfig.json to workspace "${slug}"`]);
-        // Push the new commit using the same force semantics as the main push.
-        const pushArgs = ['-C', dir, 'push', 'origin', 'main'];
-        pushArgs.push(force ? '--force' : '--force-with-lease');
-        await runGit(pushArgs);
-        this.log(`Pushed pin commit.`);
-    }
-    async remoteHasCommits(repoUrl) {
-        const { stdout } = await runGit(['ls-remote', '--heads', repoUrl]);
-        return stdout.trim().length > 0;
-    }
 }

package/dist/util/bootstrap-target.d.ts

@@ -0,0 +1,40 @@
+/**
+ * What `qfg workspace bootstrap` tells the user about the workspace it is
+ * about to push to, and the one check that stops it landing content in the
+ * wrong place.
+ *
+ * The target is resolved the same way `qfg push` / `qfg pull` / `qfg sync`
+ * resolve theirs: `QUONFIG_WORKSPACE`, then the directory's `quonfig.json`
+ * pin, then the active profile. The prompt must name whichever of those won;
+ * naming the profile when the env var chose another workspace is how a
+ * customer confirms a push to the wrong place (qfg-8p8i).
+ */
+import type { WorkspacePin } from './quonfig-json.js';
+export interface BootstrapProfile {
+    organizationSlug?: string;
+    workspace: string;
+    workspaceName?: string;
+    workspaceSlug?: string;
+}
+export interface BootstrapTargetInput {
+    /** `QUONFIG_WORKSPACE`, when set: it outranks everything else. */
+    envOverride: string | undefined;
+    /** The `--dir` directory's `quonfig.json` pin, when readable. */
+    pin: WorkspacePin | undefined;
+    /** The active profile, if any. Only trusted when it IS the resolved workspace. */
+    profile: BootstrapProfile | undefined;
+    /** What the resolver actually returned. */
+    workspaceId: string;
+}
+/**
+ * The name to show for the resolved workspace, from whichever source chose
+ * it. Falls back to the id rather than to a profile that points elsewhere.
+ */
+export declare const describeBootstrapTarget: (input: BootstrapTargetInput) => string;
+/**
+ * `qfg push`'s Guard 1 for bootstrap: a directory pinned to one workspace is
+ * not pushed to another. Compares the workspace component only, as push does
+ * (backend responses do not carry the org slug yet). Returns the refusal
+ * message, or nothing when there is no pin or it matches.
+ */
+export declare const bootstrapPinMismatch: (pin: WorkspacePin | undefined, backendWorkspaceSlug: string) => string | undefined;

package/dist/util/bootstrap-target.js

@@ -0,0 +1,46 @@
+/**
+ * What `qfg workspace bootstrap` tells the user about the workspace it is
+ * about to push to, and the one check that stops it landing content in the
+ * wrong place.
+ *
+ * The target is resolved the same way `qfg push` / `qfg pull` / `qfg sync`
+ * resolve theirs: `QUONFIG_WORKSPACE`, then the directory's `quonfig.json`
+ * pin, then the active profile. The prompt must name whichever of those won;
+ * naming the profile when the env var chose another workspace is how a
+ * customer confirms a push to the wrong place (qfg-8p8i).
+ */
+/** The pin form of a workspace, `<org>/<workspace>`. */
+const pinForm = (pin) => `${pin.orgSlug}/${pin.workspaceSlug}`;
+/**
+ * The name to show for the resolved workspace, from whichever source chose
+ * it. Falls back to the id rather than to a profile that points elsewhere.
+ */
+export const describeBootstrapTarget = (input) => {
+    if (input.envOverride)
+        return input.envOverride;
+    if (input.pin)
+        return pinForm(input.pin);
+    const { profile } = input;
+    if (profile && profile.workspace === input.workspaceId) {
+        if (profile.workspaceSlug) {
+            return profile.organizationSlug ? `${profile.organizationSlug}/${profile.workspaceSlug}` : profile.workspaceSlug;
+        }
+        if (profile.workspaceName)
+            return profile.workspaceName;
+    }
+    return input.workspaceId;
+};
+/**
+ * `qfg push`'s Guard 1 for bootstrap: a directory pinned to one workspace is
+ * not pushed to another. Compares the workspace component only, as push does
+ * (backend responses do not carry the org slug yet). Returns the refusal
+ * message, or nothing when there is no pin or it matches.
+ */
+export const bootstrapPinMismatch = (pin, backendWorkspaceSlug) => {
+    if (!pin || pin.workspaceSlug === backendWorkspaceSlug)
+        return undefined;
+    return (`This directory's quonfig.json is pinned to workspace "${pinForm(pin)}", ` +
+        `but the target workspace is "${backendWorkspaceSlug}".\n` +
+        `Nothing was pushed. Unset QUONFIG_WORKSPACE to bootstrap the pinned workspace, ` +
+        `or change the pin in quonfig.json if "${backendWorkspaceSlug}" is really the target.`);
+};

package/dist/util/clone-and-stack-push.d.ts

@@ -1,7 +1,4 @@
-export declare const MIGRATOR_IDENTITY: {
-    readonly name: "quonfig migrator";
-    readonly email: "migrator@quonfig.com";
-};
+export { MIGRATOR_IDENTITY } from './git-ops.js';
 export interface PushIdentity {
     email: string;
     name: string;

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

@@ -1,10 +1,7 @@
 import * as fs from 'node:fs';
 import * as path from 'node:path';
-import { runGit as runGitSafe, spawnGit } from './git-ops.js';
-export const MIGRATOR_IDENTITY = {
-    name: 'quonfig migrator',
-    email: 'migrator@quonfig.com',
-};
+import { MIGRATOR_IDENTITY, runGit as runGitSafe, spawnGit } from './git-ops.js';
+export { MIGRATOR_IDENTITY } from './git-ops.js';
 const redactToken = (s) => s.replaceAll(/:([^\s/@]+)@/g, ':***@');
 export class PushConflictError extends Error {
     constructor(message) {

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

@@ -142,8 +142,66 @@ export declare const gitMergeFfOnly: (dir: string) => Promise<string[]>;
  * Adds or updates the origin remote for a repo.
  */
 export declare const gitSetRemote: (dir: string, url: string) => Promise<void>;
-export declare const gitPushForceLease: (dir: string) => Promise<void>;
-export declare const gitPushForce: (dir: string) => Promise<void>;
+/**
+ * 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 declare const workspaceDocumentsAtRef: (dir: string, ref: string) => Promise<string[]>;
+export interface RebaseOntoOriginResult {
+    /** How many of the customer's commits were replayed onto the remote head. */
+    commitsRebased: number;
+    /** The sha now at `origin/main`. */
+    pushedSha: string;
+    /** Subject of the extra commit that put the tree right, or null if none was needed. */
+    reconcileSubject: null | string;
+}
+/**
+ * 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 declare const MIGRATOR_IDENTITY: {
+    readonly name: "quonfig migrator";
+    readonly email: "migrator@quonfig.com";
+};
+/**
+ * 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 declare const rebaseOntoOriginAndPush: (dir: string, opts?: {
+    validate?: boolean;
+}) => Promise<RebaseOntoOriginResult>;
 export declare const hasAtLeastOneCommit: (dir: string) => Promise<boolean>;
 /**
  * Get the URL stripped of credentials for display purposes.