@bevel-software/platform-core-backend 0.1.0

package/dist/modules/workflow/file-lock.service.d.ts

@@ -0,0 +1,57 @@
+/**
+ * Per-(workspace, branch, path) edit lock store. The spec calls for
+ * file-scoped locks acquired on first edit and released either explicitly
+ * (with an autosave commit) or implicitly by TTL expiry — preventing a
+ * disconnected client from holding a file hostage.
+ *
+ * Lock state lives in Postgres because workspaces share state across
+ * backend instances eventually. The hot read path (does someone hold this
+ * lock?) is one indexed lookup; the hot write path (heartbeat) is a single
+ * row update. We don't bother caching in process memory — the lock table
+ * is the source of truth and any cache would lose its purpose the moment
+ * a different replica takes over.
+ *
+ * Stale-lock semantics: `get`, `acquire`, and `heartbeat` all treat a row
+ * with `expires_at <= now()` as if the lock didn't exist. We purge it
+ * lazily on next access rather than running a sweeper — the row count is
+ * bounded by concurrent editors, not history, so lazy GC is fine.
+ */
+import type { Database } from '../database/connection.js';
+import type { AcquireLockResult, AuthUser, FileLock } from '@bevel-software/platform-shared';
+export declare class FileLockService {
+    private readonly db;
+    constructor(db: Database);
+    /**
+     * Acquire a lock for `(workspaceId, branch, path)` on behalf of `user`.
+     *
+     * Three outcomes folded into the same return shape:
+     *   - No existing row: insert + return `{ acquired: true, lock }`.
+     *   - Existing row, expired: take it over (update) + `{ acquired: true }`.
+     *   - Existing row, live, different user: return `{ acquired: false }`
+     *     with the current holder's lock state so the UI can render
+     *     "Locked by X" without a follow-up call.
+     *   - Existing row, live, same user: refresh TTL + `{ acquired: true }`
+     *     so re-acquiring your own lock is idempotent.
+     */
+    acquire(workspaceId: string, branch: string, targetPath: string, user: AuthUser): Promise<AcquireLockResult>;
+    /**
+     * Extend the lock's TTL. Refuses if the lock is held by someone else or
+     * doesn't exist — the client is then expected to re-call `acquire`,
+     * which will either succeed (taking over a stale lock) or surface the
+     * current holder.
+     */
+    heartbeat(workspaceId: string, branch: string, targetPath: string, user: AuthUser): Promise<FileLock>;
+    /**
+     * Idempotent release. Deletes the lock row when the caller holds it;
+     * silently no-ops otherwise (the lock may have expired and been taken
+     * over by someone else — that's not an error from the caller's POV).
+     */
+    release(workspaceId: string, branch: string, targetPath: string, user: AuthUser): Promise<void>;
+    /**
+     * Read the current lock for `(workspace, branch, path)`. Returns null when
+     * no one holds it, OR when the existing row is expired — expired locks
+     * are purged here lazily.
+     */
+    get(workspaceId: string, branch: string, targetPath: string): Promise<FileLock | null>;
+}
+//# sourceMappingURL=file-lock.service.d.ts.map

package/dist/modules/workflow/file-lock.service.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"file-lock.service.d.ts","sourceRoot":"","sources":["../../../src/modules/workflow/file-lock.service.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AAGH,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,2BAA2B,CAAC;AAE1D,OAAO,KAAK,EAAE,iBAAiB,EAAE,QAAQ,EAAE,QAAQ,EAAE,MAAM,iCAAiC,CAAC;AAwB7F,qBAAa,eAAe;IACd,OAAO,CAAC,QAAQ,CAAC,EAAE;gBAAF,EAAE,EAAE,QAAQ;IAEzC;;;;;;;;;;;OAWG;IACG,OAAO,CACX,WAAW,EAAE,MAAM,EACnB,MAAM,EAAE,MAAM,EACd,UAAU,EAAE,MAAM,EAClB,IAAI,EAAE,QAAQ,GACb,OAAO,CAAC,iBAAiB,CAAC;IAuF7B;;;;;OAKG;IACG,SAAS,CACb,WAAW,EAAE,MAAM,EACnB,MAAM,EAAE,MAAM,EACd,UAAU,EAAE,MAAM,EAClB,IAAI,EAAE,QAAQ,GACb,OAAO,CAAC,QAAQ,CAAC;IAoCpB;;;;OAIG;IACG,OAAO,CACX,WAAW,EAAE,MAAM,EACnB,MAAM,EAAE,MAAM,EACd,UAAU,EAAE,MAAM,EAClB,IAAI,EAAE,QAAQ,GACb,OAAO,CAAC,IAAI,CAAC;IAahB;;;;OAIG;IACG,GAAG,CACP,WAAW,EAAE,MAAM,EACnB,MAAM,EAAE,MAAM,EACd,UAAU,EAAE,MAAM,GACjB,OAAO,CAAC,QAAQ,GAAG,IAAI,CAAC;CAoC5B"}

package/dist/modules/workflow/file-lock.service.js

@@ -0,0 +1,202 @@
+/**
+ * Per-(workspace, branch, path) edit lock store. The spec calls for
+ * file-scoped locks acquired on first edit and released either explicitly
+ * (with an autosave commit) or implicitly by TTL expiry — preventing a
+ * disconnected client from holding a file hostage.
+ *
+ * Lock state lives in Postgres because workspaces share state across
+ * backend instances eventually. The hot read path (does someone hold this
+ * lock?) is one indexed lookup; the hot write path (heartbeat) is a single
+ * row update. We don't bother caching in process memory — the lock table
+ * is the source of truth and any cache would lose its purpose the moment
+ * a different replica takes over.
+ *
+ * Stale-lock semantics: `get`, `acquire`, and `heartbeat` all treat a row
+ * with `expires_at <= now()` as if the lock didn't exist. We purge it
+ * lazily on next access rather than running a sweeper — the row count is
+ * bounded by concurrent editors, not history, so lazy GC is fine.
+ */
+import { and, eq, gt, lte } from 'drizzle-orm';
+import { fileLocks } from '../database/schema.js';
+import { WorkflowValidationError } from './workflow.errors.js';
+/**
+ * Lock lifetime without a heartbeat. The client is expected to heartbeat
+ * every ~half this interval so a single missed ping doesn't release the
+ * lock out from under them. Bumping the TTL trades off "how long does a
+ * crashed client hold a file" against "how forgiving are we of network
+ * blips" — 60s is a balance.
+ */
+const LOCK_TTL_MS = 60_000;
+function rowToFileLock(row) {
+    return {
+        branch: row.branch,
+        path: row.path,
+        holderUserId: row.holderUserId,
+        holderName: row.holderName,
+        acquiredAt: row.acquiredAt.toISOString(),
+        lastHeartbeatAt: row.lastHeartbeatAt.toISOString(),
+        expiresAt: row.expiresAt.toISOString(),
+    };
+}
+export class FileLockService {
+    db;
+    constructor(db) {
+        this.db = db;
+    }
+    /**
+     * Acquire a lock for `(workspaceId, branch, path)` on behalf of `user`.
+     *
+     * Three outcomes folded into the same return shape:
+     *   - No existing row: insert + return `{ acquired: true, lock }`.
+     *   - Existing row, expired: take it over (update) + `{ acquired: true }`.
+     *   - Existing row, live, different user: return `{ acquired: false }`
+     *     with the current holder's lock state so the UI can render
+     *     "Locked by X" without a follow-up call.
+     *   - Existing row, live, same user: refresh TTL + `{ acquired: true }`
+     *     so re-acquiring your own lock is idempotent.
+     */
+    async acquire(workspaceId, branch, targetPath, user) {
+        const now = new Date();
+        const expiresAt = new Date(now.getTime() + LOCK_TTL_MS);
+        // Atomic acquire-or-takeover, in a single statement. Two callers
+        // racing on the same `(workspace, branch, path)` would otherwise
+        // both SELECT no row → both INSERT (one PK-fails) or both SELECT a
+        // stale row → both UPDATE (one silently overwrites the other's
+        // takeover). PostgreSQL's INSERT ... ON CONFLICT DO UPDATE WHERE
+        // collapses both paths into one atomic statement:
+        //
+        //   - No existing row → INSERT succeeds, RETURNING our new row.
+        //   - Existing row, WHERE matches (stale OR same user) → UPDATE
+        //     fires, RETURNING the updated row.
+        //   - Existing row, WHERE doesn't match (live + different user) →
+        //     the conflict is silently absorbed (PG's documented behavior),
+        //     RETURNING is empty. We then read the live holder for the
+        //     "Locked by X" payload.
+        //
+        // **Only expired rows can be taken over.** The same-user clause used
+        // to be here as an "idempotent refresh" shortcut, but it had a nasty
+        // side effect: the AGENT and the HUMAN EDITOR share the same `user.id`
+        // (agent edits attribute to the human), so the agent's
+        // `LockingFilesystem.withLock` would silently steal a lock the human
+        // had taken via the Edit button — overwriting their in-flight edits
+        // and dropping their lock on agent-release. Removing same-user from
+        // setWhere makes acquire strict: a non-expired lock is contended even
+        // by yourself, so the agent's retry/skip path kicks in and the human
+        // keeps editing. Real refresh-while-holding goes through
+        // `heartbeat()` (which has its own same-user UPDATE), and the
+        // editor's save flow detects "I already hold it" via `getLock` in
+        // `workspace.routes.withLock` rather than re-acquiring.
+        const upsertResult = await this.db
+            .insert(fileLocks)
+            .values({
+            workspaceId,
+            branch,
+            path: targetPath,
+            holderUserId: user.id,
+            holderName: user.name,
+            acquiredAt: now,
+            lastHeartbeatAt: now,
+            expiresAt,
+        })
+            .onConflictDoUpdate({
+            target: [fileLocks.workspaceId, fileLocks.branch, fileLocks.path],
+            set: {
+                holderUserId: user.id,
+                holderName: user.name,
+                acquiredAt: now,
+                lastHeartbeatAt: now,
+                expiresAt,
+            },
+            setWhere: lte(fileLocks.expiresAt, now),
+        })
+            .returning();
+        if (upsertResult.length > 0) {
+            return { acquired: true, lock: rowToFileLock(upsertResult[0]) };
+        }
+        // Live lock held by another user. Fetch it for the "Locked by X" UI
+        // payload. We don't filter on `expiresAt > now` here because the
+        // upsert above already proved an unreclaimable row exists; the only
+        // way this read returns null is a tight race where the holder
+        // released between the upsert and this select — rare enough to
+        // surface as a retryable error rather than complicate the happy path.
+        const [holder] = await this.db
+            .select()
+            .from(fileLocks)
+            .where(and(eq(fileLocks.workspaceId, workspaceId), eq(fileLocks.branch, branch), eq(fileLocks.path, targetPath)))
+            .limit(1);
+        if (!holder) {
+            throw new WorkflowValidationError(`Lock contention race on "${targetPath}" — please retry.`, { kind: 'lock-contention-race', branch, path: targetPath });
+        }
+        return { acquired: false, lock: rowToFileLock(holder) };
+    }
+    /**
+     * Extend the lock's TTL. Refuses if the lock is held by someone else or
+     * doesn't exist — the client is then expected to re-call `acquire`,
+     * which will either succeed (taking over a stale lock) or surface the
+     * current holder.
+     */
+    async heartbeat(workspaceId, branch, targetPath, user) {
+        const now = new Date();
+        const expiresAt = new Date(now.getTime() + LOCK_TTL_MS);
+        // The expiry guard (`expiresAt > now`) matters because an expired
+        // lock is conceptually released, even if its row hasn't been swept
+        // and no other user has taken it yet. Without it, a client whose
+        // tab was suspended past the TTL would silently extend a lock that
+        // the rest of the system considers "free for the next acquire" —
+        // any subsequent `acquire()` by another user could already have
+        // taken it (the upsert's `lte(expiresAt, now)` predicate matches),
+        // and the heartbeat would race with that takeover. Failing here
+        // forces the client to re-acquire (which goes through the proper
+        // takeover path) and surfaces the "your session went stale" state
+        // honestly.
+        const [updated] = await this.db
+            .update(fileLocks)
+            .set({ lastHeartbeatAt: now, expiresAt })
+            .where(and(eq(fileLocks.workspaceId, workspaceId), eq(fileLocks.branch, branch), eq(fileLocks.path, targetPath), eq(fileLocks.holderUserId, user.id), gt(fileLocks.expiresAt, now)))
+            .returning();
+        if (!updated) {
+            throw new WorkflowValidationError(`Cannot heartbeat lock on "${targetPath}": not held by you (or no longer exists).`, { kind: 'lock-not-held', branch, path: targetPath });
+        }
+        return rowToFileLock(updated);
+    }
+    /**
+     * Idempotent release. Deletes the lock row when the caller holds it;
+     * silently no-ops otherwise (the lock may have expired and been taken
+     * over by someone else — that's not an error from the caller's POV).
+     */
+    async release(workspaceId, branch, targetPath, user) {
+        await this.db
+            .delete(fileLocks)
+            .where(and(eq(fileLocks.workspaceId, workspaceId), eq(fileLocks.branch, branch), eq(fileLocks.path, targetPath), eq(fileLocks.holderUserId, user.id)));
+    }
+    /**
+     * Read the current lock for `(workspace, branch, path)`. Returns null when
+     * no one holds it, OR when the existing row is expired — expired locks
+     * are purged here lazily.
+     */
+    async get(workspaceId, branch, targetPath) {
+        const rows = await this.db
+            .select()
+            .from(fileLocks)
+            .where(and(eq(fileLocks.workspaceId, workspaceId), eq(fileLocks.branch, branch), eq(fileLocks.path, targetPath)))
+            .limit(1);
+        if (rows.length === 0)
+            return null;
+        const row = rows[0];
+        if (row.expiresAt.getTime() <= Date.now()) {
+            // Lazy GC — drop the stale row so the next `acquire` doesn't have
+            // to bypass it. Bind the delete to this exact row's `expiresAt` so
+            // a concurrent acquire that wrote a fresh row in the gap between
+            // our SELECT and DELETE doesn't get clobbered. Primary key
+            // `(workspaceId, branch, path)` alone isn't enough — a new acquire
+            // for the same triple updates that row in place with a future
+            // expiry, and a path-only delete here would silently nuke it.
+            await this.db
+                .delete(fileLocks)
+                .where(and(eq(fileLocks.workspaceId, workspaceId), eq(fileLocks.branch, branch), eq(fileLocks.path, targetPath), eq(fileLocks.expiresAt, row.expiresAt)));
+            return null;
+        }
+        return rowToFileLock(row);
+    }
+}
+//# sourceMappingURL=file-lock.service.js.map

package/dist/modules/workflow/file-lock.service.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"file-lock.service.js","sourceRoot":"","sources":["../../../src/modules/workflow/file-lock.service.ts"],"names":[],"mappings":"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"}

package/dist/modules/workflow/git/branch-name.d.ts

@@ -0,0 +1,10 @@
+export { PROTECTED_BRANCHES, isProtectedBranch } from '@bevel-software/platform-shared';
+export { branchAuthorLocalpart, isBranchAuthoredBy } from '@bevel-software/platform-shared';
+/** Throw if `name` cannot safely be passed to `git` as a branch name. */
+export declare function assertValidBranchName(name: string): void;
+/**
+ * Guard against path traversal and shell-unsafe characters on any workspace-relative
+ * path we pass to `git` as a pathspec. Must stay within the repo; forward slashes only.
+ */
+export declare function assertValidRelativePath(relativePath: string): void;
+//# sourceMappingURL=branch-name.d.ts.map

package/dist/modules/workflow/git/branch-name.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"branch-name.d.ts","sourceRoot":"","sources":["../../../../src/modules/workflow/git/branch-name.ts"],"names":[],"mappings":"AAIA,OAAO,EAAE,kBAAkB,EAAE,iBAAiB,EAAE,MAAM,iCAAiC,CAAC;AAKxF,OAAO,EAAE,qBAAqB,EAAE,kBAAkB,EAAE,MAAM,iCAAiC,CAAC;AAI5F,yEAAyE;AACzE,wBAAgB,qBAAqB,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI,CAwBxD;AAED;;;GAGG;AACH,wBAAgB,uBAAuB,CAAC,YAAY,EAAE,MAAM,GAAG,IAAI,CAyBlE"}

package/dist/modules/workflow/git/branch-name.js

@@ -0,0 +1,76 @@
+import { BranchNameError, WorkflowValidationError } from '../workflow.errors.js';
+// Single source of truth for the protected-branch list lives in `@bevel-software/platform-shared` so
+// the backend guard and the frontend banner/disabling logic can't drift apart.
+export { PROTECTED_BRANCHES, isProtectedBranch } from '@bevel-software/platform-shared';
+// Authorship inference lives in `@bevel-software/platform-shared` for the same reason — the
+// picker's `canDelete` rule and the backend authorisation check on
+// `deleteBranch` must agree on every edge case (uppercase email, dotted
+// localpart, etc.).
+export { branchAuthorLocalpart, isBranchAuthoredBy } from '@bevel-software/platform-shared';
+const VALID_BRANCH_REGEX = /^[A-Za-z0-9][A-Za-z0-9/_\-.]*$/;
+/** Throw if `name` cannot safely be passed to `git` as a branch name. */
+export function assertValidBranchName(name) {
+    if (!name)
+        throw new BranchNameError('empty name', name);
+    if (name.length > 255)
+        throw new BranchNameError('too long', name);
+    if (!VALID_BRANCH_REGEX.test(name)) {
+        throw new BranchNameError('contains invalid characters', name);
+    }
+    if (name.includes('..'))
+        throw new BranchNameError('contains ".."', name);
+    if (name.includes('//'))
+        throw new BranchNameError('contains "//"', name);
+    if (name.endsWith('/') || name.endsWith('.')) {
+        throw new BranchNameError('ends with "/" or "."', name);
+    }
+    if (name.startsWith('-'))
+        throw new BranchNameError('starts with "-"', name);
+    if (name.includes('@{'))
+        throw new BranchNameError('contains "@{"', name);
+    // Per-segment rules: git forbids any `/`-separated segment from beginning
+    // with "." or ending with ".lock" (e.g. `foo/.tmp`, `foo.lock/bar`).
+    // The whole-name checks above can't catch nested violations.
+    for (const segment of name.split('/')) {
+        if (segment.startsWith('.')) {
+            throw new BranchNameError('segment starts with "."', name);
+        }
+        if (segment.endsWith('.lock')) {
+            throw new BranchNameError('segment ends with ".lock"', name);
+        }
+    }
+}
+/**
+ * Guard against path traversal and shell-unsafe characters on any workspace-relative
+ * path we pass to `git` as a pathspec. Must stay within the repo; forward slashes only.
+ */
+export function assertValidRelativePath(relativePath) {
+    if (!relativePath)
+        throw new WorkflowValidationError('path is required');
+    if (relativePath.length > 1024)
+        throw new WorkflowValidationError('path too long');
+    if (relativePath.includes('\0'))
+        throw new WorkflowValidationError('path contains NUL');
+    if (relativePath.includes('\\')) {
+        throw new WorkflowValidationError('path must use forward slashes only');
+    }
+    if (relativePath.startsWith('/') || /^[A-Za-z]:/.test(relativePath)) {
+        throw new WorkflowValidationError('path must be relative');
+    }
+    const parts = relativePath.split('/');
+    if (parts.some((p) => p === '..' || p === '.')) {
+        throw new WorkflowValidationError('path must not contain "." or ".."');
+    }
+    if (relativePath.startsWith('-')) {
+        throw new WorkflowValidationError('path must not start with "-"');
+    }
+    // Pathspec glob characters (`*`, `?`, `[`, `]`, `!`) and pathspec magic (`:(…)`)
+    // would otherwise be interpreted by `git add -- <path>` / `git log -- <path>`
+    // and match the wrong files. `GitService.git()` sets `GIT_LITERAL_PATHSPECS=1`
+    // on every git subprocess, which forces literal interpretation across the
+    // board — so KB filenames containing `[Approved]`, `[New]`, etc. round-trip
+    // through commit cleanly. The shared `validateFilename` already rejects `:`
+    // along with the rest of Windows-forbidden characters before paths reach this
+    // layer, so a redundant check here would only confuse the error message.
+}
+//# sourceMappingURL=branch-name.js.map

package/dist/modules/workflow/git/branch-name.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"branch-name.js","sourceRoot":"","sources":["../../../../src/modules/workflow/git/branch-name.ts"],"names":[],"mappings":"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"}

package/dist/modules/workflow/git/clone-config.d.ts

@@ -0,0 +1,61 @@
+/**
+ * The git configuration a per-branch workspace clone must have for its branch
+ * to track exactly ONE upstream ref.
+ *
+ * Why this exists: a clone's config is append-only from git's point of view,
+ * and several things write to it:
+ *
+ *   - `git config --add branch.<name>.merge …` / `git branch --set-upstream-to`
+ *     run out of band (an agent shell session in the workspace, a manual fix)
+ *     leaves a SECOND `branch.<name>.merge` value;
+ *   - `git remote set-branches --add origin …`, a re-run `git remote add`, or a
+ *     hand-edited `.git/config` leaves a SECOND `remote.origin.fetch` refspec,
+ *     so one fetch maps the same remote branch in twice.
+ *
+ * A multi-valued `branch.<name>.merge` is what makes a BARE `git fetch origin`
+ * write more than one *for-merge* entry into the clone's shared
+ * `.git/FETCH_HEAD` — git adds one per configured merge ref. That is the
+ * ammunition behind the reported failure: `git pull` reads its rebase target
+ * out of that same shared file, so when one of the app's unmutexed bare
+ * fetches lands inside the pull's fetch→read window, the pull sees two merge
+ * heads and dies with `fatal: Cannot rebase onto multiple branches.`
+ *
+ * The drift alone is NOT sufficient — an explicit `git pull --rebase origin
+ * <branch>` survives every drift shape on its own (verified across the shapes
+ * above on git 2.39.5); it takes the concurrent fetch too. `GitService.pull`
+ * closes the other half by never reading or writing FETCH_HEAD; normalising
+ * the config here removes the ammunition.
+ *
+ * These are the three keys that pin the clone back to "this branch tracks
+ * `origin/<branch>`, nothing else"; applied with `--replace-all` they collapse
+ * any accumulated duplicates into one value.
+ *
+ * Lives here — next to `assertValidBranchName` — as a leaf-level primitive
+ * shared by the git layer (self-heal before every pull) and `WorkspaceService`
+ * (stamped on new clones, and re-stamped on existing ones the first time this
+ * process opens them, which is the migration for clones already on disk).
+ */
+/** The single fetch refspec a workspace clone of the KB is created with. */
+export declare const ORIGIN_FETCH_REFSPEC = "+refs/heads/*:refs/remotes/origin/*";
+/**
+ * The one safe shape for an implicit background fetch of a workspace clone —
+ * shared by `GitService.fetchOriginIfStale` and
+ * `WorkspaceService.ensureRemotesFetched`, both of which run OUTSIDE the
+ * workspace mutex. `--no-write-fetch-head` is what makes that safe: without it
+ * a bare fetch rewrites the clone's shared `.git/FETCH_HEAD` underneath
+ * whatever else is running in it, which is how the post-merge `git pull` read
+ * two merge heads and died with "Cannot rebase onto multiple branches" (see
+ * the header comment above and `GitService.pull`). These paths only want the
+ * remote-tracking refs refreshed; `--prune` keeps deleted remote branches from
+ * lingering. Callers prepend their own runner context (`-C <dir>` /
+ * `-c http.*` options) but must not vary these arguments.
+ */
+export declare const SAFE_IMPLICIT_FETCH_ARGS: readonly string[];
+/**
+ * `git` argument lists that normalise a clone's tracking config for `branch`.
+ * Returns the arguments rather than running them so each caller can use its own
+ * git runner (the git service's mutex-aware wrapper, `git -C` from the
+ * workspace service) — no process is spawned here.
+ */
+export declare function cloneTrackingConfigArgs(branch: string): string[][];
+//# sourceMappingURL=clone-config.d.ts.map

package/dist/modules/workflow/git/clone-config.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"clone-config.d.ts","sourceRoot":"","sources":["../../../../src/modules/workflow/git/clone-config.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAoCG;AAEH,4EAA4E;AAC5E,eAAO,MAAM,oBAAoB,wCAAwC,CAAC;AAE1E;;;;;;;;;;;;GAYG;AACH,eAAO,MAAM,wBAAwB,EAAE,SAAS,MAAM,EAErD,CAAC;AAEF;;;;;GAKG;AACH,wBAAgB,uBAAuB,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,EAAE,EAAE,CAMlE"}

package/dist/modules/workflow/git/clone-config.js

@@ -0,0 +1,69 @@
+/**
+ * The git configuration a per-branch workspace clone must have for its branch
+ * to track exactly ONE upstream ref.
+ *
+ * Why this exists: a clone's config is append-only from git's point of view,
+ * and several things write to it:
+ *
+ *   - `git config --add branch.<name>.merge …` / `git branch --set-upstream-to`
+ *     run out of band (an agent shell session in the workspace, a manual fix)
+ *     leaves a SECOND `branch.<name>.merge` value;
+ *   - `git remote set-branches --add origin …`, a re-run `git remote add`, or a
+ *     hand-edited `.git/config` leaves a SECOND `remote.origin.fetch` refspec,
+ *     so one fetch maps the same remote branch in twice.
+ *
+ * A multi-valued `branch.<name>.merge` is what makes a BARE `git fetch origin`
+ * write more than one *for-merge* entry into the clone's shared
+ * `.git/FETCH_HEAD` — git adds one per configured merge ref. That is the
+ * ammunition behind the reported failure: `git pull` reads its rebase target
+ * out of that same shared file, so when one of the app's unmutexed bare
+ * fetches lands inside the pull's fetch→read window, the pull sees two merge
+ * heads and dies with `fatal: Cannot rebase onto multiple branches.`
+ *
+ * The drift alone is NOT sufficient — an explicit `git pull --rebase origin
+ * <branch>` survives every drift shape on its own (verified across the shapes
+ * above on git 2.39.5); it takes the concurrent fetch too. `GitService.pull`
+ * closes the other half by never reading or writing FETCH_HEAD; normalising
+ * the config here removes the ammunition.
+ *
+ * These are the three keys that pin the clone back to "this branch tracks
+ * `origin/<branch>`, nothing else"; applied with `--replace-all` they collapse
+ * any accumulated duplicates into one value.
+ *
+ * Lives here — next to `assertValidBranchName` — as a leaf-level primitive
+ * shared by the git layer (self-heal before every pull) and `WorkspaceService`
+ * (stamped on new clones, and re-stamped on existing ones the first time this
+ * process opens them, which is the migration for clones already on disk).
+ */
+/** The single fetch refspec a workspace clone of the KB is created with. */
+export const ORIGIN_FETCH_REFSPEC = '+refs/heads/*:refs/remotes/origin/*';
+/**
+ * The one safe shape for an implicit background fetch of a workspace clone —
+ * shared by `GitService.fetchOriginIfStale` and
+ * `WorkspaceService.ensureRemotesFetched`, both of which run OUTSIDE the
+ * workspace mutex. `--no-write-fetch-head` is what makes that safe: without it
+ * a bare fetch rewrites the clone's shared `.git/FETCH_HEAD` underneath
+ * whatever else is running in it, which is how the post-merge `git pull` read
+ * two merge heads and died with "Cannot rebase onto multiple branches" (see
+ * the header comment above and `GitService.pull`). These paths only want the
+ * remote-tracking refs refreshed; `--prune` keeps deleted remote branches from
+ * lingering. Callers prepend their own runner context (`-C <dir>` /
+ * `-c http.*` options) but must not vary these arguments.
+ */
+export const SAFE_IMPLICIT_FETCH_ARGS = [
+    'fetch', '--prune', '--no-write-fetch-head', 'origin',
+];
+/**
+ * `git` argument lists that normalise a clone's tracking config for `branch`.
+ * Returns the arguments rather than running them so each caller can use its own
+ * git runner (the git service's mutex-aware wrapper, `git -C` from the
+ * workspace service) — no process is spawned here.
+ */
+export function cloneTrackingConfigArgs(branch) {
+    return [
+        ['config', '--replace-all', 'remote.origin.fetch', ORIGIN_FETCH_REFSPEC],
+        ['config', '--replace-all', `branch.${branch}.remote`, 'origin'],
+        ['config', '--replace-all', `branch.${branch}.merge`, `refs/heads/${branch}`],
+    ];
+}
+//# sourceMappingURL=clone-config.js.map

package/dist/modules/workflow/git/clone-config.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"clone-config.js","sourceRoot":"","sources":["../../../../src/modules/workflow/git/clone-config.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAoCG;AAEH,4EAA4E;AAC5E,MAAM,CAAC,MAAM,oBAAoB,GAAG,qCAAqC,CAAC;AAE1E;;;;;;;;;;;;GAYG;AACH,MAAM,CAAC,MAAM,wBAAwB,GAAsB;IACzD,OAAO,EAAE,SAAS,EAAE,uBAAuB,EAAE,QAAQ;CACtD,CAAC;AAEF;;;;;GAKG;AACH,MAAM,UAAU,uBAAuB,CAAC,MAAc;IACpD,OAAO;QACL,CAAC,QAAQ,EAAE,eAAe,EAAE,qBAAqB,EAAE,oBAAoB,CAAC;QACxE,CAAC,QAAQ,EAAE,eAAe,EAAE,UAAU,MAAM,SAAS,EAAE,QAAQ,CAAC;QAChE,CAAC,QAAQ,EAAE,eAAe,EAAE,UAAU,MAAM,QAAQ,EAAE,cAAc,MAAM,EAAE,CAAC;KAC9E,CAAC;AACJ,CAAC"}

package/dist/modules/workflow/git/git-version.d.ts

@@ -0,0 +1,34 @@
+/**
+ * The `git` floor this app depends on.
+ *
+ * Every fetch the workspace layer runs passes `--no-write-fetch-head` — the
+ * option that keeps one clone's fetches from steering a concurrent refresh
+ * through the shared `.git/FETCH_HEAD` (see `GitService.pull`) — and git only
+ * learned it in 2.29. On an older binary every one of those fetches dies with
+ * `unknown option`, which takes out `pull`, `resetToRemote` and
+ * `mergeChangeRequest` at once.
+ *
+ * The production image installs git from Debian via `node:22-slim`, which is
+ * well past the floor, so this guard is about a re-based or swapped runtime
+ * image rather than a live problem. Its value is *when* it fires: at boot,
+ * naming the installed version, instead of at the first change-request merge
+ * with an opaque git error.
+ */
+/** Oldest git that understands `--no-write-fetch-head`. */
+export declare const MIN_GIT_VERSION: readonly [number, number];
+/** `git version 2.39.5 (Apple Git-154)` → `[2, 39]`; null if unrecognisable. */
+export declare function parseGitVersion(stdout: string): [number, number] | null;
+/**
+ * Throw when `git --version` output names a version below the floor.
+ *
+ * An output we can't parse is NOT fatal: a git build with an unusual version
+ * string is far more likely than one older than 2.29, and refusing to boot over
+ * an unrecognised string would be a worse failure than the one being guarded.
+ */
+export declare function assertSupportedGitVersion(stdout: string): void;
+/**
+ * Run `git --version` and apply the floor. Call once during startup, before
+ * anything clones or fetches.
+ */
+export declare function assertGitVersion(): Promise<void>;
+//# sourceMappingURL=git-version.d.ts.map

package/dist/modules/workflow/git/git-version.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"git-version.d.ts","sourceRoot":"","sources":["../../../../src/modules/workflow/git/git-version.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AAOH,2DAA2D;AAC3D,eAAO,MAAM,eAAe,EAAE,SAAS,CAAC,MAAM,EAAE,MAAM,CAAW,CAAC;AAElE,gFAAgF;AAChF,wBAAgB,eAAe,CAAC,MAAM,EAAE,MAAM,GAAG,CAAC,MAAM,EAAE,MAAM,CAAC,GAAG,IAAI,CAGvE;AAED;;;;;;GAMG;AACH,wBAAgB,yBAAyB,CAAC,MAAM,EAAE,MAAM,GAAG,IAAI,CAiB9D;AAED;;;GAGG;AACH,wBAAsB,gBAAgB,IAAI,OAAO,CAAC,IAAI,CAAC,CAQtD"}

package/dist/modules/workflow/git/git-version.js

@@ -0,0 +1,63 @@
+/**
+ * The `git` floor this app depends on.
+ *
+ * Every fetch the workspace layer runs passes `--no-write-fetch-head` — the
+ * option that keeps one clone's fetches from steering a concurrent refresh
+ * through the shared `.git/FETCH_HEAD` (see `GitService.pull`) — and git only
+ * learned it in 2.29. On an older binary every one of those fetches dies with
+ * `unknown option`, which takes out `pull`, `resetToRemote` and
+ * `mergeChangeRequest` at once.
+ *
+ * The production image installs git from Debian via `node:22-slim`, which is
+ * well past the floor, so this guard is about a re-based or swapped runtime
+ * image rather than a live problem. Its value is *when* it fires: at boot,
+ * naming the installed version, instead of at the first change-request merge
+ * with an opaque git error.
+ */
+import { execFile } from 'node:child_process';
+import { promisify } from 'node:util';
+const execFileAsync = promisify(execFile);
+/** Oldest git that understands `--no-write-fetch-head`. */
+export const MIN_GIT_VERSION = [2, 29];
+/** `git version 2.39.5 (Apple Git-154)` → `[2, 39]`; null if unrecognisable. */
+export function parseGitVersion(stdout) {
+    const m = /^git version (\d+)\.(\d+)/.exec(stdout.trim());
+    return m ? [Number(m[1]), Number(m[2])] : null;
+}
+/**
+ * Throw when `git --version` output names a version below the floor.
+ *
+ * An output we can't parse is NOT fatal: a git build with an unusual version
+ * string is far more likely than one older than 2.29, and refusing to boot over
+ * an unrecognised string would be a worse failure than the one being guarded.
+ */
+export function assertSupportedGitVersion(stdout) {
+    const found = parseGitVersion(stdout);
+    const [minMajor, minMinor] = MIN_GIT_VERSION;
+    if (!found) {
+        console.warn(`[git] could not read a version from "${stdout.trim()}" — ` +
+            `skipping the git ${minMajor}.${minMinor}+ check`);
+        return;
+    }
+    const [major, minor] = found;
+    if (major > minMajor || (major === minMajor && minor >= minMinor))
+        return;
+    throw new Error(`git ${minMajor}.${minMinor} or newer is required, found ${major}.${minor}. ` +
+        'Every workspace fetch passes --no-write-fetch-head, which older git rejects, ' +
+        'so branch refresh and change-request merges cannot work on this runtime.');
+}
+/**
+ * Run `git --version` and apply the floor. Call once during startup, before
+ * anything clones or fetches.
+ */
+export async function assertGitVersion() {
+    let stdout;
+    try {
+        ({ stdout } = await execFileAsync('git', ['--version']));
+    }
+    catch (err) {
+        throw new Error(`git is required but could not be run: ${String(err)}`);
+    }
+    assertSupportedGitVersion(stdout);
+}
+//# sourceMappingURL=git-version.js.map

package/dist/modules/workflow/git/git-version.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"git-version.js","sourceRoot":"","sources":["../../../../src/modules/workflow/git/git-version.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AAEH,OAAO,EAAE,QAAQ,EAAE,MAAM,oBAAoB,CAAC;AAC9C,OAAO,EAAE,SAAS,EAAE,MAAM,WAAW,CAAC;AAEtC,MAAM,aAAa,GAAG,SAAS,CAAC,QAAQ,CAAC,CAAC;AAE1C,2DAA2D;AAC3D,MAAM,CAAC,MAAM,eAAe,GAA8B,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC;AAElE,gFAAgF;AAChF,MAAM,UAAU,eAAe,CAAC,MAAc;IAC5C,MAAM,CAAC,GAAG,2BAA2B,CAAC,IAAI,CAAC,MAAM,CAAC,IAAI,EAAE,CAAC,CAAC;IAC1D,OAAO,CAAC,CAAC,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,EAAE,MAAM,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC;AACjD,CAAC;AAED;;;;;;GAMG;AACH,MAAM,UAAU,yBAAyB,CAAC,MAAc;IACtD,MAAM,KAAK,GAAG,eAAe,CAAC,MAAM,CAAC,CAAC;IACtC,MAAM,CAAC,QAAQ,EAAE,QAAQ,CAAC,GAAG,eAAe,CAAC;IAC7C,IAAI,CAAC,KAAK,EAAE,CAAC;QACX,OAAO,CAAC,IAAI,CACV,wCAAwC,MAAM,CAAC,IAAI,EAAE,MAAM;YACzD,oBAAoB,QAAQ,IAAI,QAAQ,SAAS,CACpD,CAAC;QACF,OAAO;IACT,CAAC;IACD,MAAM,CAAC,KAAK,EAAE,KAAK,CAAC,GAAG,KAAK,CAAC;IAC7B,IAAI,KAAK,GAAG,QAAQ,IAAI,CAAC,KAAK,KAAK,QAAQ,IAAI,KAAK,IAAI,QAAQ,CAAC;QAAE,OAAO;IAC1E,MAAM,IAAI,KAAK,CACb,OAAO,QAAQ,IAAI,QAAQ,gCAAgC,KAAK,IAAI,KAAK,IAAI;QAC3E,+EAA+E;QAC/E,0EAA0E,CAC7E,CAAC;AACJ,CAAC;AAED;;;GAGG;AACH,MAAM,CAAC,KAAK,UAAU,gBAAgB;IACpC,IAAI,MAAc,CAAC;IACnB,IAAI,CAAC;QACH,CAAC,EAAE,MAAM,EAAE,GAAG,MAAM,aAAa,CAAC,KAAK,EAAE,CAAC,WAAW,CAAC,CAAC,CAAC,CAAC;IAC3D,CAAC;IAAC,OAAO,GAAG,EAAE,CAAC;QACb,MAAM,IAAI,KAAK,CAAC,yCAAyC,MAAM,CAAC,GAAG,CAAC,EAAE,CAAC,CAAC;IAC1E,CAAC;IACD,yBAAyB,CAAC,MAAM,CAAC,CAAC;AACpC,CAAC"}