@bevel-software/platform-core-backend 0.29.0 → 0.30.0

package/dist/modules/workspace/kb-repository.d.ts

@@ -0,0 +1,236 @@
+import { type IGitRunner } from '../../shared/git.contract.js';
+import type { AddWorktreeOptions, FetchOptions, IKbRepository } from './kb-repository.contract.js';
+/** Where a converted clone's stash and other local refs are kept, per workspace (see `importLocalRefs`). */
+export declare const CONVERTED_REFS = "refs/kb-converted";
+/**
+ * Where the repository is: `<root>/<kb folder>.git`, under `override` when the
+ * composition root names one (a folder on a persistent volume beside the
+ * workspaces root), else a folder next to the workspaces root named after it.
+ *
+ * The fallback is derived from the root's own name, so two workspaces roots
+ * that share a parent (every suite's temporary roots) never share a repository.
+ */
+export declare function repositoryDirFor(workspacesRoot: string, kbDirName: string, override?: string): string;
+/**
+ * What a branch workspace's checkout folder is:
+ *  - `worktree` — its `.git` is a file naming a folder that exists;
+ *  - `clone` — its `.git` is a folder: a full clone, from a release before
+ *    worktrees (converted at boot, and served as it is until it is);
+ *  - `broken` — its `.git` is a file naming a folder that does not exist (the
+ *    repository was lost, or the worktree was pruned from under it): an
+ *    unfinished checkout, recreated as an unfinished clone is;
+ *  - `none` — no `.git` at all.
+ *
+ * Errors other than absence propagate: a `.git` that could not be read has
+ * not been shown to be anything.
+ */
+export type WorkingCopyShape = 'worktree' | 'clone' | 'broken' | 'none';
+export declare function workingCopyShape(checkoutDir: string): Promise<WorkingCopyShape>;
+export interface KbRepositoryOptions {
+    /** The bare repository's folder — see {@link repositoryDirFor}. */
+    dir: string;
+    /** The configured remote, read at every use (the setup screen can change it). */
+    kbRepoUrl: () => string;
+    /** Injected by the composition root, as every other git caller's is. */
+    gitRunner: IGitRunner;
+}
+export type { AddWorktreeOptions, FetchOptions, IKbRepository } from './kb-repository.contract.js';
+export declare class KbRepository implements IKbRepository {
+    readonly dir: string;
+    private readonly kbRepoUrl;
+    private readonly gitRunner;
+    /** The administrator's queue: `exclusive` sections run one after another, in call order. */
+    private admin;
+    /** See the contract: the repository's one administrator for `fn`'s duration. Never nested. */
+    exclusive<T>(fn: () => Promise<T>): Promise<T>;
+    /** When the last fetch succeeded, and when the last attempt failed. */
+    private lastSuccessAt;
+    private lastFailureAt;
+    private lastOk;
+    private inFlightFetch;
+    /** When the fetch in flight started: a caller that needs one from `fetchedSince` on joins only a later one. */
+    private inFlightStartedAt;
+    /**
+     * Bumped whenever the repository is taken away (set aside): a fetch that was
+     * in flight for the one that went must not stamp its result on the new one.
+     */
+    private generation;
+    /** The credential fingerprint last stamped into the repository's config, this process. */
+    private stampedCredentials;
+    /** Whether this process has stamped the repository's own configuration yet. */
+    private configStamped;
+    constructor(opts: KbRepositoryOptions);
+    private redact;
+    private git;
+    /**
+     * Whether the repository is on disk and FINISHED: a bare repository whose
+     * first fetch landed. The marker is written last, so a repository whose
+     * making was cut short (a crash, a full disk) is not taken for one.
+     */
+    exists(): Promise<boolean>;
+    /**
+     * Make sure the repository exists and has been fetched at least once; create
+     * it when it does not. As the administrator. Throws when it cannot be
+     * created or its first fetch fails — with git's words, redacted.
+     */
+    ensure(): Promise<void>;
+    private ensureHeld;
+    /** The repository's own configuration — what every worktree of it reads. */
+    private configArgs;
+    private credentialFingerprint;
+    /**
+     * Stamp the repository's configuration once per process, and its credential
+     * helper again whenever the deployment's credential changed — once for every
+     * worktree, since they all read this one config. Never throws: a stamp that
+     * failed leaves the repository as usable as it was, and is tried again next
+     * time.
+     */
+    private stampConfigIfNeeded;
+    /**
+     * Bring the credential helper into line with the deployment's credential when
+     * it changed since it was last stamped. As the administrator, as every write
+     * to the shared config is. A no-op for a repository not yet made.
+     */
+    refreshCredentials(): Promise<void>;
+    /**
+     * Run `git config` arguments against the repository's shared configuration
+     * (from a worktree or the repository, it is one file), one writer at a time:
+     * git refuses a second writer while `config.lock` is held rather than
+     * waiting for it.
+     */
+    writeConfig(cwd: string, argLists: readonly string[][]): Promise<void>;
+    /** See the contract. `gc --auto` decides for itself whether there is enough loose to pack. */
+    maintain(): Promise<void>;
+    /**
+     * `at` for a success is when its fetch STARTED: the refs it wrote are at
+     * least that fresh, and no fresher — a deletion on the remote while it ran
+     * may be missing from them.
+     */
+    private noteFetched;
+    /** The last time the repository reached the remote and whether it worked; null before any attempt. */
+    lastContact(): {
+        at: number;
+        ok: boolean;
+    } | null;
+    /** Why the last fetch failed, redacted; null when it did not. For a fail-closed caller's message. */
+    lastFetchFailure(): string | null;
+    private lastFailure;
+    /**
+     * `git fetch --prune origin` in the repository — ONCE for every workspace.
+     * Throttled by `maxAgeMs` and joined while in flight (ten callers in one
+     * tick share one fetch). Not serialized against the worktrees' own git:
+     * a fetch writes remote-tracking refs and packs, which git locks itself.
+     * Answers whether the remote-tracking refs are provably fresh: this call's
+     * fetch (or the one it joined) succeeded, or one succeeded within the
+     * window. Never throws; a caller that must not act on stale refs reads the
+     * answer.
+     */
+    fetch(opts: FetchOptions): Promise<boolean>;
+    /**
+     * Forget what this process knows about the repository — it was set aside,
+     * and the next use makes a fresh one.
+     */
+    forget(): void;
+    private revParse;
+    private isAncestor;
+    /**
+     * Add the worktree of `branch` at `checkoutDir`. Copies no history: the
+     * repository already has it, and is fetched first when the remote's branch
+     * is not known to it yet.
+     *
+     * The branch's local ref is created from `origin/<branch>`, tracking it. A
+     * local ref already there (a converted clone's tip, a worktree that was lost
+     * with commits the remote lacks) is KEPT when it holds commits the remote
+     * does not have, and fast-forwarded to the remote when it is behind.
+     *
+     * A branch the remote does not have fails with git's own words for a clone
+     * of it ("Remote branch … not found in upstream origin"), so the callers
+     * that tell a deleted branch from one that never existed read it as they
+     * read a clone's failure — unless `allowLocalOnly` (a converted clone whose
+     * branch was never pushed) and the local ref exists.
+     *
+     * `keepLocalTip` (a conversion) leaves a local ref that is behind the
+     * remote where it is: the worktree comes up at the clone's own tip, and the
+     * phase's own update moves it on, as it moved the clone.
+     *
+     * `fetchedSince` (the startup phase, opening every branch) skips asking
+     * the remote when the repository's own fetch succeeded, starting after it,
+     * and already has `origin/<branch>`: that fetch brought every branch, so
+     * opening a hundred branches costs one fetch, not a hundred. A branch it
+     * does not know yet is asked for as usual.
+     */
+    addWorktree(branch: string, checkoutDir: string, opts?: AddWorktreeOptions): Promise<void>;
+    /**
+     * Remove the worktree at `checkoutDir` and prune it from the repository,
+     * with its branch's local ref: deleting a workspace takes what a deleted
+     * clone took. The repository's objects and every other worktree are left
+     * exactly as they were. A folder git will not remove (it is not a worktree
+     * any more, or is locked) is deleted by hand, then pruned.
+     */
+    removeWorktree(checkoutDir: string, branch: string): Promise<void>;
+    /**
+     * After worktree folders were deleted by hand (the orphan sweep): prune them
+     * from the repository and drop their branches' local refs. A branch still
+     * checked out in a worktree that exists is refused by git and kept.
+     */
+    forgetWorktrees(branches: readonly string[]): Promise<void>;
+    /**
+     * `git worktree prune`: forget worktrees whose folders are gone. As the
+     * administrator: a prune beside a `worktree add` can take the entry being
+     * made, before git has marked it as in the making.
+     */
+    prune(): Promise<void>;
+    /** The folders of the repository's worktrees, as git lists them. */
+    listWorktrees(): Promise<string[]>;
+    /**
+     * Bring the tip of `branch` from the full clone at `cloneDir` into the
+     * repository as `refs/heads/<branch>` — its commits the remote lacks
+     * included — without touching the remote. Answers the tip, after checking
+     * the repository now has it.
+     */
+    importBranch(cloneDir: string, branch: string): Promise<string>;
+    /**
+     * Bring what else the full clone at `cloneDir` holds of its own into the
+     * repository, under `refs/kb-converted/<workspaceId>/`, before the clone
+     * goes: every entry of its stash (`stash/0` the latest), and every local
+     * ref but its own branch's and the remote-tracking ones — other local
+     * branches, tags — that the repository does not already hold with the same
+     * value. Nothing in the clone changes: each object is pushed by its id.
+     * Answers the refs written, after checking the repository holds each at the
+     * clone's value; throws, the clone untouched, when one cannot be written.
+     *
+     * The refs are no workspace's: deleting the branch's workspace leaves them,
+     * and the repository's collection keeps what they reach.
+     */
+    importLocalRefs(cloneDir: string, branch: string, workspaceId: string): Promise<string[]>;
+    /** The object a ref names, as it is (a tag is not peeled), or null. */
+    private refValue;
+    /**
+     * The address the repository fetches from, or null when it cannot be read
+     * (no repository, no `origin`).
+     */
+    originUrl(): Promise<string | null>;
+    /**
+     * Re-link a repository and its worktrees that were moved together (set
+     * aside), so `git log` in a moved worktree reads the moved repository.
+     *
+     * Both links are written here rather than left to `git worktree repair`,
+     * which cannot follow a link whose two ends BOTH moved: the worktree's
+     * `.git` file names `<repository>/worktrees/<name>`, and that folder's
+     * `gitdir` names the worktree's `.git`. The name is the last part of the
+     * path the worktree's `.git` file still holds. Answers the moved worktrees
+     * that could not be re-linked (git had already lost track of them, or a
+     * write failed) — their files are all there, only `git` in them is not.
+     * A worktree whose second link cannot be written gets its first one back,
+     * so neither link names a place the other does not.
+     */
+    relinkMovedCopy(movedRepository: string, movedWorktrees: readonly string[]): Promise<string[]>;
+    /**
+     * Point the repository at `url` — the same repository at a new address.
+     * What this process knew of the old address's fetches is forgotten with it,
+     * so the next fetch reaches the new one rather than reading a success from
+     * the old one as fresh.
+     */
+    setOriginUrl(url: string): Promise<void>;
+}
+//# sourceMappingURL=kb-repository.d.ts.map

package/dist/modules/workspace/kb-repository.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"kb-repository.d.ts","sourceRoot":"","sources":["../../../src/modules/workspace/kb-repository.ts"],"names":[],"mappings":"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"}