@quonfig/cli 0.0.15 → 0.0.16

package/dist/push/confirm.d.ts

@@ -0,0 +1,10 @@
+type StreamOpts = {
+    input?: NodeJS.ReadableStream;
+    output?: NodeJS.WritableStream;
+};
+type TypedSlugOpts = {
+    maxAttempts?: number;
+} & StreamOpts;
+export declare function confirmYesNo(prompt: string, opts?: StreamOpts): Promise<boolean>;
+export declare function confirmTypedSlug(expectedSlug: string, prompt: string, opts?: TypedSlugOpts): Promise<boolean>;
+export {};

package/dist/push/confirm.js

@@ -0,0 +1,108 @@
+// Thin prompt primitives for `qfg push` Guard 3.
+//
+// Two levels of confirmation:
+//
+//   confirmYesNo       -- standard y/N. Default NO. Bare Enter is a no.
+//   confirmTypedSlug   -- user has to type the slug EXACTLY. Strict string
+//                         equality (trailing whitespace trimmed). Case-sensitive.
+//
+// Both take injectable input/output streams so tests can drive them with
+// in-memory PassThrough streams. Defaults are process.stdin / process.stdout.
+//
+// No business logic, no diff math, no network. Callers construct the prompt
+// text (including the "[y/N]" hint); this module prints it verbatim.
+import * as readline from 'node:readline';
+const makeLineReader = (rl) => {
+    const lines = [];
+    let closed = false;
+    let pending = null;
+    rl.on('line', (line) => {
+        if (pending) {
+            const p = pending;
+            pending = null;
+            p.resolve(line);
+            return;
+        }
+        lines.push(line);
+    });
+    rl.on('close', () => {
+        closed = true;
+        if (pending) {
+            const p = pending;
+            pending = null;
+            // eslint-disable-next-line unicorn/no-useless-undefined
+            p.resolve(undefined);
+        }
+    });
+    return {
+        close() {
+            rl.close();
+        },
+        readLine() {
+            if (lines.length > 0) {
+                return Promise.resolve(lines.shift());
+            }
+            if (closed) {
+                // eslint-disable-next-line unicorn/no-useless-undefined
+                return Promise.resolve(undefined);
+            }
+            return new Promise((resolve) => {
+                pending = { resolve };
+            });
+        },
+    };
+};
+const YES_ANSWERS = new Set(['y', 'Y', 'yes']);
+// Standard confirmation. Returns true only for 'y' / 'Y' / 'yes' (exact, after
+// trimming trailing whitespace). Anything else -- bare Enter, 'n', garbage,
+// EOF -- is false. Default is NO.
+export async function confirmYesNo(prompt, opts = {}) {
+    const input = opts.input ?? process.stdin;
+    const output = opts.output ?? process.stdout;
+    const rl = readline.createInterface({ input, output, terminal: false });
+    const reader = makeLineReader(rl);
+    try {
+        output.write(prompt);
+        const line = await reader.readLine();
+        if (line === undefined)
+            return false;
+        // readline strips the trailing newline, but be defensive against CRLF and
+        // trailing spaces.
+        const trimmed = line.replace(/\s+$/, '');
+        return YES_ANSWERS.has(trimmed);
+    }
+    finally {
+        reader.close();
+    }
+}
+// Typed-slug confirmation. Returns true only if the user types expectedSlug
+// EXACTLY (case-sensitive) within maxAttempts tries. Trailing whitespace is
+// trimmed before comparison; leading whitespace is NOT -- the plan says "have
+// to type the slug exactly". Empty input / EOF / mismatch all count as a
+// failed attempt.
+//
+// Default maxAttempts = 1 (plan: "have to type the slug exactly" -- one try
+// is sufficient).
+export async function confirmTypedSlug(expectedSlug, prompt, opts = {}) {
+    const input = opts.input ?? process.stdin;
+    const output = opts.output ?? process.stdout;
+    const maxAttempts = opts.maxAttempts ?? 1;
+    const rl = readline.createInterface({ input, output, terminal: false });
+    const reader = makeLineReader(rl);
+    try {
+        for (let attempt = 0; attempt < maxAttempts; attempt++) {
+            output.write(prompt);
+            // eslint-disable-next-line no-await-in-loop
+            const line = await reader.readLine();
+            if (line === undefined)
+                return false;
+            const trimmed = line.replace(/\s+$/, '');
+            if (trimmed === expectedSlug)
+                return true;
+        }
+        return false;
+    }
+    finally {
+        reader.close();
+    }
+}

package/dist/push/diff-summary.d.ts

@@ -0,0 +1,56 @@
+/**
+ * Pure diff-summary + destructive-heuristic module for `qfg push`.
+ *
+ * Implements Guard 3 (pre-push diff summary + destructive-change detection)
+ * from `project/plans/cli-git-sync.md`. This module takes a pre-computed
+ * list of `FileDelta`s (the caller is responsible for walking local vs.
+ * remote trees after `git fetch`) and returns a grouped count + a plain-text
+ * rendering suitable for human confirmation.
+ *
+ * Intentional non-goals:
+ *   - No fs / git / network I/O here. Keeps this pure and test-friendly.
+ *   - No prompts / TTY handling. The caller owns confirmation UX.
+ *   - No ANSI / unicode. Plain ASCII so CI transcripts stay readable.
+ */
+/** A single file-level change between the local working tree and remote HEAD. */
+export interface FileDelta {
+    /**
+     * `added`    — present locally, absent on remote
+     * `modified` — present in both, content differs
+     * `deleted`  — absent locally, present on remote
+     */
+    kind: 'added' | 'deleted' | 'modified';
+    /** Path relative to repo root, e.g. `configs/pricing.json`. */
+    path: string;
+}
+export interface GroupCounts {
+    added: number;
+    deleted: number;
+    modified: number;
+}
+export interface DiffSummary {
+    /** Per-top-level-dir counts. See `KNOWN_GROUPS`; anything else lands in `other`. */
+    byGroup: Record<string, GroupCounts>;
+    /** Whether any destructive heuristic fired. */
+    destructiveReasons: string[];
+    /** Human-readable reasons that each destructive heuristic fired (one per rule). */
+    isDestructive: boolean;
+    /**
+     * Render the plain-text summary shown before the user confirms.
+     * All opts are optional; missing string opts render as `<unknown>`.
+     */
+    renderText(opts?: {
+        branch?: string;
+        localDir?: string;
+        repoUrl?: string;
+        workspaceSlug?: string;
+    }): string;
+    /** Sum across all groups, plus `filesTouched = added + modified + deleted`. */
+    totals: {
+        filesTouched: number;
+    } & GroupCounts;
+}
+export declare function summarizeDiff(deltas: FileDelta[], opts?: {
+    totalFilesInRemote?: number;
+    unpinned?: boolean;
+}): DiffSummary;

package/dist/push/diff-summary.js

@@ -0,0 +1,115 @@
+/**
+ * Pure diff-summary + destructive-heuristic module for `qfg push`.
+ *
+ * Implements Guard 3 (pre-push diff summary + destructive-change detection)
+ * from `project/plans/cli-git-sync.md`. This module takes a pre-computed
+ * list of `FileDelta`s (the caller is responsible for walking local vs.
+ * remote trees after `git fetch`) and returns a grouped count + a plain-text
+ * rendering suitable for human confirmation.
+ *
+ * Intentional non-goals:
+ *   - No fs / git / network I/O here. Keeps this pure and test-friendly.
+ *   - No prompts / TTY handling. The caller owns confirmation UX.
+ *   - No ANSI / unicode. Plain ASCII so CI transcripts stay readable.
+ */
+/**
+ * Top-level directories we present as named rows. Anything else funnels into
+ * `other`. Keeping this closed-set avoids one-off typos silently looking fine.
+ */
+const KNOWN_GROUPS = [
+    'configs',
+    'feature-flags',
+    'segments',
+    'schemas',
+    'schemas-protected',
+    'log-levels',
+];
+const DESTRUCTIVE_DELETE_COUNT = 10;
+const DESTRUCTIVE_DELETE_RATIO = 0.25;
+function emptyCounts() {
+    return { added: 0, deleted: 0, modified: 0 };
+}
+/**
+ * Derive the group label for a path. Top-level dir if it's known, `other`
+ * otherwise (including for files at the repo root).
+ */
+function groupFor(relativePath) {
+    const slash = relativePath.indexOf('/');
+    if (slash === -1)
+        return 'other';
+    const top = relativePath.slice(0, slash);
+    return KNOWN_GROUPS.includes(top) ? top : 'other';
+}
+function pad(s, width) {
+    return s.length >= width ? s : s + ' '.repeat(width - s.length);
+}
+export function summarizeDiff(deltas, opts) {
+    const byGroup = {};
+    const totals = { added: 0, deleted: 0, filesTouched: 0, modified: 0 };
+    for (const delta of deltas) {
+        const group = groupFor(delta.path);
+        const counts = byGroup[group] ?? emptyCounts();
+        counts[delta.kind] += 1;
+        byGroup[group] = counts;
+        totals[delta.kind] += 1;
+        totals.filesTouched += 1;
+    }
+    const destructiveReasons = [];
+    if (totals.deleted >= DESTRUCTIVE_DELETE_COUNT) {
+        destructiveReasons.push(`10+ deletes: ${totals.deleted}`);
+    }
+    const remoteCount = Math.max(opts?.totalFilesInRemote ?? 0, 0);
+    if (remoteCount > 0) {
+        const ratio = totals.deleted / remoteCount;
+        if (ratio >= DESTRUCTIVE_DELETE_RATIO) {
+            // Strict `>=` — 24.9% does not trip this; 25.0% does.
+            destructiveReasons.push(`deletes >= 25% of total: ${totals.deleted}/${remoteCount}`);
+        }
+    }
+    if (opts?.unpinned === true) {
+        destructiveReasons.push('workspace unpinned (no `workspace` field in quonfig.json)');
+    }
+    const isDestructive = destructiveReasons.length > 0;
+    const renderText = (renderOpts) => {
+        const slug = renderOpts?.workspaceSlug ?? '<unknown>';
+        const repo = renderOpts?.repoUrl ?? '<unknown>';
+        const branch = renderOpts?.branch ?? 'main';
+        const localDir = renderOpts?.localDir ?? '.';
+        const lines = [];
+        lines.push(`Pushing to workspace:  ${slug}`, `  Git repo:            ${repo}`, `  Branch:              ${branch}`, `  Local dir:           ${localDir}`, '', 'Changes vs. remote HEAD:');
+        // Render groups in a stable order: known groups first (in declared order),
+        // then `other` if present. Skip rows with zero total activity.
+        const renderOrder = [...KNOWN_GROUPS];
+        if (byGroup.other)
+            renderOrder.push('other');
+        // Two-space indent, left-pad the label column to `labelWidth` so the
+        // +N ~N -N columns line up regardless of group name length.
+        const labelWidth = 18; // e.g. "schemas-protected/" = 18 chars
+        for (const group of renderOrder) {
+            const counts = byGroup[group];
+            if (!counts)
+                continue;
+            if (counts.added === 0 && counts.modified === 0 && counts.deleted === 0)
+                continue;
+            const label = `${group}/`;
+            lines.push(`  ${pad(label, labelWidth)}+${counts.added}  ~${counts.modified}  -${counts.deleted}`);
+        }
+        lines.push('');
+        if (isDestructive) {
+            lines.push('WARNING:');
+            for (const reason of destructiveReasons) {
+                lines.push(`  ${reason}`);
+            }
+            lines.push('');
+        }
+        lines.push(`  Total: ${totals.added} new files, ${totals.modified} modified, ${totals.deleted} deleted`);
+        return lines.join('\n');
+    };
+    return {
+        byGroup,
+        destructiveReasons,
+        isDestructive,
+        renderText,
+        totals,
+    };
+}

package/dist/push/identity-check.d.ts

@@ -0,0 +1,53 @@
+/**
+ * Guards 1 + 2 of `qfg push`, as a pure function.
+ *
+ * See `project/plans/cli-git-sync.md` — "Safety model (three independent guards)".
+ *
+ * The caller collects three identity signals about the local directory the user
+ * is about to push:
+ *
+ *   A. Requested target   — slug or UUID the user asked for (--workspace or profile default)
+ *   B. Repo pin           — `workspace` slug from `quonfig.json`, if present
+ *   C. Remote origin      — `remote.origin.url` on the local git repo, if present
+ *
+ * ...and the canonical `backend` identity (the workspace the gitea.token
+ * response was minted for). This module cross-checks them and returns one of:
+ *
+ *   - ok                                    all defined signals agree
+ *   - abort                                 any two defined signals disagree
+ *   - requires-typed-slug-confirmation      the repo is unpinned and has no
+ *                                           origin, so only the requested
+ *                                           target supports our identity —
+ *                                           we demand the user type the slug
+ *
+ * The module is intentionally pure: no I/O, no prompting, no UI. The UI layer
+ * (confirm prompts, diff summary) and the data-fetch layer (reading quonfig.json,
+ * shelling out to git, calling gitea.token) live elsewhere.
+ */
+export interface IdentityCheckInput {
+    /** The canonical workspace identity from the backend (gitea.token response). */
+    backend: {
+        workspaceSlug: string;
+        workspaceId: string;
+        repoUrl: string;
+    };
+    /** "C. Remote origin" — the origin URL on the local git repo, if present. */
+    remoteOriginUrl: string | undefined;
+    /** "B. Repo pin" — slug from `quonfig.json.workspace`, if present. */
+    repoPinSlug: string | undefined;
+    /** "A. Requested target" — what the user asked for. Slug or UUID. */
+    requestedTarget: string;
+}
+export type IdentityCheckOutcome = {
+    kind: 'ok';
+    canonicalSlug: string;
+} | {
+    kind: 'abort';
+    reason: string;
+    details: Record<string, string>;
+} | {
+    kind: 'requires-typed-slug-confirmation';
+    canonicalSlug: string;
+    reason: string;
+};
+export declare function checkIdentity(input: IdentityCheckInput): IdentityCheckOutcome;

package/dist/push/identity-check.js

@@ -0,0 +1,135 @@
+/**
+ * Guards 1 + 2 of `qfg push`, as a pure function.
+ *
+ * See `project/plans/cli-git-sync.md` — "Safety model (three independent guards)".
+ *
+ * The caller collects three identity signals about the local directory the user
+ * is about to push:
+ *
+ *   A. Requested target   — slug or UUID the user asked for (--workspace or profile default)
+ *   B. Repo pin           — `workspace` slug from `quonfig.json`, if present
+ *   C. Remote origin      — `remote.origin.url` on the local git repo, if present
+ *
+ * ...and the canonical `backend` identity (the workspace the gitea.token
+ * response was minted for). This module cross-checks them and returns one of:
+ *
+ *   - ok                                    all defined signals agree
+ *   - abort                                 any two defined signals disagree
+ *   - requires-typed-slug-confirmation      the repo is unpinned and has no
+ *                                           origin, so only the requested
+ *                                           target supports our identity —
+ *                                           we demand the user type the slug
+ *
+ * The module is intentionally pure: no I/O, no prompting, no UI. The UI layer
+ * (confirm prompts, diff summary) and the data-fetch layer (reading quonfig.json,
+ * shelling out to git, calling gitea.token) live elsewhere.
+ */
+/**
+ * Normalize a git remote URL so we can compare two URLs that describe the
+ * same repo:
+ *   - strip any `user:pw@` basic-auth prefix
+ *   - strip a trailing `.git`
+ *   - lowercase the host (not the path — repo slugs may be case-sensitive)
+ *   - ignore trailing slash
+ *
+ * Returns `undefined` when the URL is too malformed to parse — callers treat
+ * that as the `malformed` resolution.
+ */
+const normalizeRemoteUrl = (url) => {
+    const trimmed = url.trim();
+    if (!trimmed)
+        return undefined;
+    // Strip basic-auth: "https://user:pw@host/..." -> "https://host/..."
+    const stripped = trimmed.replace(/^([a-z][\d+.a-z-]*:\/\/)[^/@]+@/i, '$1');
+    let parsed;
+    try {
+        parsed = new URL(stripped);
+    }
+    catch {
+        return undefined;
+    }
+    const host = parsed.host.toLowerCase();
+    // Strip trailing "/" first so a trailing-slash URL still has its ".git" suffix recognized.
+    const pathname = parsed.pathname.replace(/\/+$/, '').replace(/\.git$/, '');
+    return `${parsed.protocol}//${host}${pathname}`;
+};
+const resolveRequested = (requested, backend) => {
+    if (requested === backend.workspaceSlug || requested === backend.workspaceId)
+        return 'match';
+    return 'mismatch';
+};
+const resolvePin = (pin, backend) => {
+    if (pin === backend.workspaceSlug)
+        return 'match';
+    return 'mismatch';
+};
+const resolveOrigin = (origin, backend) => {
+    const a = normalizeRemoteUrl(origin);
+    const b = normalizeRemoteUrl(backend.repoUrl);
+    if (!a || !b)
+        return 'malformed';
+    return a === b ? 'match' : 'mismatch';
+};
+export function checkIdentity(input) {
+    if (!input.requestedTarget || input.requestedTarget.length === 0) {
+        // Programming error: the caller is responsible for resolving the user's
+        // --workspace flag / profile default into a non-empty string before
+        // calling this function. If they didn't, crash loudly rather than
+        // producing a misleading abort.
+        throw new Error('checkIdentity: requestedTarget is required (slug or UUID)');
+    }
+    const backend = input.backend;
+    const requested = resolveRequested(input.requestedTarget, backend);
+    const pin = input.repoPinSlug === undefined ? undefined : resolvePin(input.repoPinSlug, backend);
+    const origin = input.remoteOriginUrl === undefined ? undefined : resolveOrigin(input.remoteOriginUrl, backend);
+    // Judgment call (flagged in tests): a malformed origin URL is a signal we
+    // cannot resolve. We treat it as `mismatch` rather than `missing` so the
+    // guard aborts — it is safer to refuse a push with an unreadable remote
+    // than to silently drop that signal and rely on the pin alone.
+    const signalLabels = {
+        requested,
+        pin,
+        origin,
+    };
+    // Collect which sources disagree with the backend (or are malformed).
+    const disagreeing = [];
+    for (const [name, res] of Object.entries(signalLabels)) {
+        if (res === 'mismatch' || res === 'malformed')
+            disagreeing.push(name);
+    }
+    // Build a details payload that shows each input's raw value and resolved status.
+    // Useful for the abort UI to render a concrete "this is why we stopped" message.
+    const details = {
+        requestedTarget: input.requestedTarget,
+        requestedResolution: requested,
+        backendSlug: backend.workspaceSlug,
+        backendId: backend.workspaceId,
+        backendRepoUrl: backend.repoUrl,
+    };
+    if (input.repoPinSlug !== undefined) {
+        details.repoPinSlug = input.repoPinSlug;
+        details.pinResolution = pin;
+    }
+    if (input.remoteOriginUrl !== undefined) {
+        details.remoteOriginUrl = input.remoteOriginUrl;
+        details.originResolution = origin;
+    }
+    if (disagreeing.length > 0) {
+        // Any single defined source pointing somewhere other than the backend is
+        // grounds to abort — the user has asked for A but has evidence of B.
+        const reason = disagreeing.length === 1
+            ? `${disagreeing[0]} disagrees with backend workspace "${backend.workspaceSlug}"`
+            : `${disagreeing.join('/')} disagree with backend workspace "${backend.workspaceSlug}"`;
+        return { kind: 'abort', reason, details };
+    }
+    // No disagreement among defined sources. Are we in the "bare dir" case
+    // where only the requested target speaks for identity?
+    if (input.repoPinSlug === undefined && input.remoteOriginUrl === undefined) {
+        return {
+            kind: 'requires-typed-slug-confirmation',
+            canonicalSlug: backend.workspaceSlug,
+            reason: 'Local directory has no workspace pin and no git origin — cannot cross-check the requested target. Confirm by typing the workspace slug.',
+        };
+    }
+    return { kind: 'ok', canonicalSlug: backend.workspaceSlug };
+}

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

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