@bevel-software/platform-core-backend 0.14.0 → 0.19.0

package/src/modules/marketplace/github-facade/github-facade.service.ts

@@ -0,0 +1,282 @@
+import { createHash, randomBytes, timingSafeEqual } from 'node:crypto';
+import { logger } from '../../../shared/logging.js';
+
+const log = logger('github-facade');
+import type { KeyKindSpec, MintedExternalApiKey } from '../../tool-auth/external-api-key.interface.js';
+import { signAuthRequest, type McpAuthRequestState } from '../../mcp/oauth/oauth-state.js';
+import type { GitHubFacadeCredentialsService } from './github-facade-credentials.service.js';
+import type { GitHubFacadeCodeStore } from './github-facade-codes.store.js';
+import { printable } from '../../../shared/printable.js';
+
+/**
+ * The KIND stored on a connection key minted through the facade, and how
+ * that kind is spelled. `gho_` plus forty letters and digits is what a
+ * GitHub OAuth token looks like — the shape a consumer expecting a GitHub
+ * Enterprise host accepts, and may well check; the key is otherwise an
+ * ordinary connection key — hashed at rest, revocable from the person's
+ * external-agent page, accepted by every surface a connection key is. The
+ * kind, not the label, is what tells such a key apart: a label is the
+ * person's to edit.
+ */
+export const GITHUB_LINK_KEY_KIND = 'github-link';
+export const GITHUB_LINK_KEY_PREFIX = 'gho_';
+export const GITHUB_LINK_KEY_SPEC: KeyKindSpec = { prefix: GITHUB_LINK_KEY_PREFIX, shape: 'github-token' };
+
+/**
+ * A product that talks to this deployment as if it were a GitHub Enterprise
+ * Server. The facade itself is consumer-neutral — GitHub's OAuth pair and
+ * REST subset are the contract — and a consumer is the one thing that is not:
+ * where its callback lives (the only place a code may be sent), what the
+ * consent page calls it, and how the keys it holds are labelled for the
+ * person. Claude is the first; another product with a "connect your GitHub
+ * Enterprise" flow is one more entry, not one more module.
+ */
+export interface GitHubFacadeConsumer {
+  id: string;
+  /** What the consent page says is asking. */
+  name: string;
+  /** Hostnames a redirect_uri may point at. */
+  redirectHosts: readonly string[];
+  /** The label on the connection keys minted for this consumer. */
+  keyLabel: string;
+}
+
+/** claude.ai and Cowork: the consumer this facade was built against. */
+export const CLAUDE_CONSUMER: GitHubFacadeConsumer = {
+  id: 'claude',
+  name: 'Claude',
+  redirectHosts: ['claude.ai'],
+  keyLabel: 'Claude (claude.ai and Cowork)',
+};
+
+const CODE_TTL_MS = 10 * 60_000;
+const CODE_BYTES = 10;
+
+export interface GitHubFacadeKeyMinter {
+  mint(userId: string, label: string, options?: { kind?: string }): Promise<MintedExternalApiKey>;
+}
+
+export interface GitHubFacadeDeps {
+  credentials: GitHubFacadeCredentialsService;
+  codes: GitHubFacadeCodeStore;
+  keys: GitHubFacadeKeyMinter;
+  /** Who may connect through the facade. */
+  consumers: readonly GitHubFacadeConsumer[];
+  /** HMAC secret for the signed authorize state — the same one the MCP flow uses. */
+  stateSecret: string;
+  /** SPA base URL — where the browser is sent to sign in and approve. */
+  publicFrontendUrl: string;
+}
+
+/**
+ * A refusal the caller is answered with in GitHub's terms — and, for the
+ * server log only, WHY: `detail` names the check that failed (a client
+ * secret that is not the registered one, a code nobody issued) where the
+ * response deliberately says no more than GitHub would. A consumer's
+ * backend never shows its user what we answered; the log is the only place
+ * an operator can see which hop of the connect flow went wrong. It never
+ * carries a secret or a code.
+ */
+export class GitHubFacadeRequestError extends Error {
+  constructor(
+    readonly status: number,
+    readonly code: string,
+    message: string,
+    readonly detail: string = message,
+  ) {
+    super(message);
+    this.name = 'GitHubFacadeRequestError';
+  }
+}
+
+/**
+ * The "connect your GitHub Enterprise account" flow, as a consumer such as claude.ai drives it
+ * against a GitHub Enterprise host — with hexis standing where GitHub would.
+ *
+ *   1. The browser lands on `/login/oauth/authorize?client_id&redirect_uri&state`.
+ *      We check the client id is ours and the redirect goes to claude.ai,
+ *      pack the request into the SAME signed state the MCP authorization
+ *      flow uses, and send the browser to the SPA's `/connect` page — where a
+ *      hexis session (or a sign-in) attaches a person to the request.
+ *   2. Finish on that page comes back through the consent routes with the
+ *      state; {@link completeConsent} stores a one-time code bound to that
+ *      person and returns the callback URL carrying it.
+ *   3. Anthropic's backend posts the code with our client id and secret to
+ *      `/login/oauth/access_token`; {@link exchangeCode} turns it into a
+ *      connection key for that person — the token every later fetch carries.
+ *
+ * Nothing here is remembered in the process: credentials and codes are read
+ * from their stores on every step, so the replica that issued a code and the
+ * replica that exchanges it need not be the same one.
+ */
+export class GitHubFacade {
+  constructor(private readonly deps: GitHubFacadeDeps) {}
+
+  /** Where to send the browser for an authorize request, or a 4xx to answer with. */
+  async authorizeRedirect(query: Record<string, unknown>): Promise<string> {
+    const clientId = str(query.client_id);
+    const redirectUri = str(query.redirect_uri);
+    const state = str(query.state);
+    const creds = await this.deps.credentials.ensure();
+    if (!clientId || !safeEqual(clientId, creds.clientId)) {
+      throw new GitHubFacadeRequestError(
+        400,
+        'unknown_client',
+        'Unknown client_id.',
+        clientId ? 'client_id is not the registered one (rotated since, or mistyped)' : 'no client_id in the request',
+      );
+    }
+    if (!this.consumerFor(redirectUri)) {
+      throw new GitHubFacadeRequestError(
+        400,
+        'invalid_redirect',
+        'redirect_uri does not belong to a known consumer.',
+        `redirect_uri host is ${hostOf(redirectUri)}, not a consumer's`,
+      );
+    }
+    const signed = signAuthRequest(this.deps.stateSecret, {
+      c: clientId,
+      r: redirectUri,
+      s: state || undefined,
+      gh: true,
+    });
+    const url = new URL('/connect', this.deps.publicFrontendUrl);
+    url.searchParams.set('oauth', signed);
+    return url.toString();
+  }
+
+  /** True when a verified state is one of ours (a GitHub-shaped link, not an MCP client). */
+  isFacadeRequest(st: McpAuthRequestState): boolean {
+    return st.gh === true;
+  }
+
+  /** What the consent page should say is asking, for one of our states. */
+  clientNameFor(st: McpAuthRequestState): string {
+    return this.consumerFor(st.r)?.name ?? 'an external product';
+  }
+
+  /**
+   * The person approved on `/connect`: a one-time code for them, and the
+   * claude.ai callback to send the browser to. Supersedes any live code the
+   * same person already had for this client.
+   */
+  async completeConsent(userId: string, st: McpAuthRequestState): Promise<{ redirectTo: string }> {
+    const creds = await this.deps.credentials.ensure();
+    if (!safeEqual(st.c, creds.clientId) || !this.consumerFor(st.r)) {
+      throw new GitHubFacadeRequestError(400, 'invalid_request', 'The authorization request is not one of ours.');
+    }
+    const code = randomBytes(CODE_BYTES).toString('hex');
+    await this.deps.codes.put({
+      codeHash: hashCode(code),
+      userId,
+      clientId: st.c,
+      redirectUri: st.r,
+      expiresAt: new Date(Date.now() + CODE_TTL_MS),
+    });
+    const url = new URL(st.r);
+    url.searchParams.set('code', code);
+    if (st.s) url.searchParams.set('state', st.s);
+    return { redirectTo: url.toString() };
+  }
+
+  /**
+   * The token exchange. Client id and secret must be ours and the code live;
+   * every check runs BEFORE the code is spent, so a request that is wrong
+   * about something else (its redirect, say) can be corrected and retried.
+   * Spending is one conditional update in the store — the first exchange
+   * wins, on whichever replica, and only the winner mints.
+   */
+  async exchangeCode(body: Record<string, unknown>): Promise<{
+    access_token: string;
+    token_type: 'bearer';
+    scope: '';
+  }> {
+    const creds = await this.deps.credentials.ensure();
+    const clientId = str(body.client_id);
+    const clientSecret = str(body.client_secret);
+    const code = str(body.code);
+    // One answer for every credential failure, as GitHub gives; the log
+    // alone says which half was wrong.
+    const credentialsWrong = (detail: string) =>
+      new GitHubFacadeRequestError(
+        401,
+        'incorrect_client_credentials',
+        'The client_id and/or client_secret passed are incorrect.',
+        detail,
+      );
+    if (!clientId || !safeEqual(clientId, creds.clientId)) {
+      throw credentialsWrong(clientId ? 'client_id is not the registered one (rotated since, or mistyped)' : 'no client_id in the request');
+    }
+    if (!clientSecret || !safeEqual(clientSecret, creds.clientSecret)) {
+      throw credentialsWrong(clientSecret ? 'client_secret is not the registered one (rotated since, or mistyped)' : 'no client_secret in the request');
+    }
+    const codeWrong = (detail: string) =>
+      new GitHubFacadeRequestError(400, 'bad_verification_code', 'The code passed is incorrect or expired.', detail);
+    if (!code) throw codeWrong('no code in the request');
+    const pending = await this.deps.codes.peek(hashCode(code));
+    if (!pending) throw codeWrong('no live code with that value: never issued, already spent, or older than 10 minutes');
+    if (pending.clientId !== clientId) throw codeWrong('the code was issued under a different client id');
+    const redirectUri = str(body.redirect_uri);
+    if (redirectUri && redirectUri !== pending.redirectUri) {
+      throw new GitHubFacadeRequestError(
+        400,
+        'redirect_uri_mismatch',
+        'The redirect_uri does not match the authorization.',
+        `redirect_uri host is ${hostOf(redirectUri)}, the code was issued for ${hostOf(pending.redirectUri)}`,
+      );
+    }
+    const spent = await this.deps.codes.consume(pending.codeHash);
+    if (!spent) throw codeWrong('the code was spent by a concurrent exchange');
+    // The consumer is the one the code was issued for — the redirect the
+    // person approved names it — so the key is labelled for that product.
+    const consumer = this.consumerFor(spent.redirectUri);
+    const minted = await this.deps.keys.mint(spent.userId, consumer?.keyLabel ?? 'GitHub-compatible link', {
+      kind: GITHUB_LINK_KEY_KIND,
+    });
+    log.info(
+      `${printable(consumer?.name ?? 'a consumer')} connected user ${printable(spent.userId)}: link key ${printable(minted.summary.id)} minted`,
+    );
+    return { access_token: minted.plaintext, token_type: 'bearer', scope: '' };
+  }
+
+  /** The consumer whose callback a redirect_uri is, or null — https only, host exactly. */
+  private consumerFor(redirectUri: string): GitHubFacadeConsumer | null {
+    let parsed: URL;
+    try {
+      parsed = new URL(redirectUri);
+    } catch {
+      return null;
+    }
+    if (parsed.protocol !== 'https:') return null;
+    return this.deps.consumers.find((c) => c.redirectHosts.includes(parsed.hostname)) ?? null;
+  }
+}
+
+function hashCode(code: string): string {
+  return createHash('sha256').update(code).digest('hex');
+}
+
+/**
+ * The host of a URL for a log line, or what was sent when it is not one.
+ * The caller chose the URL, so the host is rendered printable even though a
+ * parsed host is ASCII: the log's one-line rule holds by construction, not
+ * by an argument about URL parsing.
+ */
+function hostOf(url: string): string {
+  try {
+    const host = new URL(url).host;
+    return host ? printable(host) : '(empty)';
+  } catch {
+    return url ? '(not a URL)' : '(empty)';
+  }
+}
+
+function str(v: unknown): string {
+  return typeof v === 'string' ? v : '';
+}
+
+function safeEqual(a: string, b: string): boolean {
+  const ab = Buffer.from(a);
+  const bb = Buffer.from(b);
+  return ab.length === bb.length && timingSafeEqual(ab, bb);
+}

package/src/modules/marketplace/github-facade/index.ts

@@ -0,0 +1,26 @@
+export {
+  GitHubFacadeCredentialsService,
+  DbGitHubFacadeCredentialsStore,
+  MemoryGitHubFacadeCredentialsStore,
+  GitHubFacadeUnavailableError,
+  type GitHubFacadeCredentials,
+  type GitHubFacadeCredentialsStore,
+} from './github-facade-credentials.service.js';
+export {
+  DbGitHubFacadeCodeStore,
+  MemoryGitHubFacadeCodeStore,
+  type GitHubFacadeCodeStore,
+  type PendingFacadeCode,
+} from './github-facade-codes.store.js';
+export {
+  GitHubFacade,
+  GitHubFacadeRequestError,
+  GITHUB_LINK_KEY_KIND,
+  GITHUB_LINK_KEY_PREFIX,
+  GITHUB_LINK_KEY_SPEC,
+  CLAUDE_CONSUMER,
+  type GitHubFacadeConsumer,
+  type GitHubFacadeDeps,
+} from './github-facade.service.js';
+export { createGitHubFacadeRoutes, type GitHubFacadeRoutesDeps } from './github-facade.routes.js';
+export { createGitHubFacadeAdminRoutes, type GitHubFacadeAdminRoutesDeps } from './github-facade-admin.routes.js';

package/src/modules/marketplace/index.ts

@@ -0,0 +1,3 @@
+export { MarketplaceRepoService, type MarketplaceCompiler, type EnsureResult } from './marketplace-repo.service.js';
+export { createMarketplaceGitRoutes, type MarketplaceKeyResolver } from './git-http.routes.js';
+export * from './github-facade/index.js';

package/src/modules/marketplace/marketplace-repo.service.ts

@@ -0,0 +1,352 @@
+import fs from 'node:fs/promises';
+import os from 'node:os';
+import path from 'node:path';
+import { spawn, type ChildProcess } from 'node:child_process';
+import { WorkspaceMutex } from '../kb-fs/mutex.js';
+import type { VirtualTree } from '../plugins/compile/compile-marketplace.js';
+import { type IGitRunner } from '../../shared/git.contract.js';
+
+/** What the repo service asks the compiler for — the one seam it has. */
+export interface MarketplaceCompiler {
+  sourceCommit(): Promise<string>;
+  compileFor(
+    audience: { userEmail: string },
+    /** The commit the tree is compiled from, when the caller already read it. */
+    sourceCommit?: string,
+  ): Promise<VirtualTree & { sourceCommit: string }>;
+}
+
+export interface EnsureResult {
+  /** The git namespace the caller's tree lives in. */
+  namespace: string;
+  /** True when a new commit was written this call. */
+  compiled: boolean;
+  sourceCommit: string;
+}
+
+/**
+ * ONE bare repository, ONE git namespace per caller.
+ *
+ * Every person's compiled marketplace is a branch in its own namespace
+ * (`refs/namespaces/<ns>/refs/heads/main`), which is exactly what git
+ * namespaces exist for (gitnamespaces(7)): `git http-backend` run with
+ * `GIT_NAMESPACE=<ns>` advertises only that namespace's refs, so a clone sees
+ * a repository whose `main` is their tree and nothing else — while every
+ * identical skill across callers is one blob in one object store.
+ *
+ * Freshness is LAZY and keyed on the knowledge base's default-branch commit:
+ * every input to a compile (skills, manifests, access rules, roles, groups)
+ * lives in that repository, so "same source commit" means "same answer".
+ * The last compiled source per namespace sits in a sidecar file rather than
+ * a commit trailer, so an unchanged tree costs no commit and no re-check.
+ *
+ * Each recompile appends a commit whose parent is the namespace's current
+ * head, so a client's `git pull` is always a fast-forward — including when
+ * access was withdrawn and files vanish. Writes go through git plumbing
+ * against a temporary index: no working tree of the bare repo, no checkout.
+ *
+ * Read-only by construction: `http.receivepack` is pinned off (http-backend
+ * would otherwise enable pushes for an authenticated REMOTE_USER), and the
+ * route refuses the receive-pack service before git ever sees it.
+ */
+export class MarketplaceRepoService {
+  private readonly locks = new WorkspaceMutex();
+  private initialised: Promise<void> | null = null;
+
+  constructor(
+    /** Absolute path of the bare repository (created on first use). */
+    readonly repoDir: string,
+    private readonly compiler: MarketplaceCompiler,
+    /** How git is run — see `shared/git.contract.ts`. */
+    private readonly gitRunner: IGitRunner,
+    private readonly committer: { name: string; email: string } = {
+      name: 'Hexis',
+      email: 'hexis@localhost',
+    },
+  ) {}
+
+  /** The directory `GIT_PROJECT_ROOT` points at, and the repo's name under it. */
+  get projectRoot(): string {
+    return path.dirname(this.repoDir);
+  }
+  get repoName(): string {
+    return path.basename(this.repoDir);
+  }
+
+  /** The namespace for a user id — one path segment, stable, opaque. */
+  static namespaceFor(userId: string): string {
+    return `u-${userId.replace(/[^A-Za-z0-9._-]+/g, '_').slice(0, 120)}`;
+  }
+
+  async ensureRepo(): Promise<void> {
+    this.initialised ??= (async () => {
+      await fs.mkdir(this.projectRoot, { recursive: true });
+      const isRepo = await fs
+        .access(path.join(this.repoDir, 'HEAD'))
+        .then(() => true, () => false);
+      if (!isRepo) await this.git(['init', '--bare', '--quiet', this.repoDir]);
+      await this.git(['-C', this.repoDir, 'config', 'http.receivepack', 'false']);
+      await this.git(['-C', this.repoDir, 'config', 'http.uploadpack', 'true']);
+      await fs.mkdir(this.sidecarDir(), { recursive: true });
+    })().catch((err: unknown) => {
+      // A failed initialisation is retried by the next request, not
+      // remembered until restart: a volume that was briefly unavailable must
+      // not turn every later fetch into a 500.
+      this.initialised = null;
+      throw err;
+    });
+    await this.initialised;
+  }
+
+  /**
+   * Bring the caller's namespace up to the knowledge base's current commit,
+   * compiling only when it moved. Serialised per namespace: two fetches
+   * arriving together compile once.
+   */
+  async ensureCompiled(user: { id: string; email: string }): Promise<EnsureResult> {
+    await this.ensureRepo();
+    const namespace = MarketplaceRepoService.namespaceFor(user.id);
+    return this.locks.run(`ns:${namespace}`, async () => {
+      const last = await this.readSidecar(namespace);
+      const head = await this.headOf(namespace);
+      let current = await this.compiler.sourceCommit();
+      if (last === current && head !== null) {
+        // Unchanged source is still a served namespace: its HEAD is checked
+        // on every fetch (a read) and written only when it is missing, so a
+        // crash after an earlier branch update cannot leave a clone that sees
+        // no default branch — and the cache hit stays a read on a healthy repo.
+        await this.ensureHead(namespace);
+        return { namespace, compiled: false, sourceCommit: current };
+      }
+
+      // The commit just read is the one the tree is stamped with: a second
+      // read that failed would otherwise record a placeholder as the compiled
+      // source and make every later fetch recompile. And the checkout can
+      // move WHILE we compile from it (a merge landing mid-read), so the
+      // commit is re-read afterwards: a tree stamped with a commit it was
+      // not compiled from would freeze that caller on a stale tree until the
+      // next change. Bounded — a checkout that moves on every attempt is
+      // served the latest attempt rather than never.
+      let tree = await this.compiler.compileFor({ userEmail: user.email }, current);
+      for (let attempt = 0; attempt < 3; attempt++) {
+        const after = await this.compiler.sourceCommit();
+        if (after === current) break;
+        current = after;
+        tree = await this.compiler.compileFor({ userEmail: user.email }, current);
+      }
+      const sha = await this.commitTree(namespace, tree, head);
+      await this.writeSidecar(namespace, tree.sourceCommit);
+      return { namespace, compiled: sha !== head, sourceCommit: tree.sourceCommit };
+    });
+  }
+
+  /**
+   * The caller's namespace and its head commit, compiled if stale — what the
+   * GitHub-shaped REST surface (the Cowork path) reads instead of cloning.
+   */
+  async headFor(user: { id: string; email: string }): Promise<{ namespace: string; sha: string }> {
+    const { namespace } = await this.ensureCompiled(user);
+    const sha = await this.headOf(namespace);
+    if (!sha) throw new Error(`namespace ${namespace} has no head after compiling`);
+    return { namespace, sha };
+  }
+
+  /** One commit as the REST surface describes it. */
+  async describeCommit(sha: string): Promise<{
+    sha: string;
+    tree: string;
+    message: string;
+    authorName: string;
+    authorEmail: string;
+    date: string;
+  }> {
+    assertObjectId(sha);
+    const { stdout } = await this.git(['-C', this.repoDir, 'log', '-1', '--format=%H%n%T%n%an%n%ae%n%aI%n%B', sha]);
+    const [full, tree, authorName, authorEmail, date, ...rest] = stdout.split('\n');
+    return {
+      sha: full ?? sha,
+      tree: tree ?? '',
+      message: rest.join('\n').trim(),
+      authorName: authorName ?? '',
+      authorEmail: authorEmail ?? '',
+      date: date ?? '',
+    };
+  }
+
+  /**
+   * Whether `sha` is the namespace's head or one of its ancestors — the only
+   * commits a caller may read as that namespace. The object store is shared
+   * across everyone, so a sha alone is never enough.
+   */
+  async contains(namespace: string, sha: string): Promise<boolean> {
+    if (!looksLikeObjectId(sha)) return false;
+    const head = await this.headOf(namespace);
+    if (!head) return false;
+    // Two questions with two answers each, and only "no" is ever silent:
+    // a commit git does not have is simply not contained; a commit it has
+    // is an ancestor (exit 0) or not (exit 1); anything else — a corrupt
+    // store, a lock, a bad ref — is a failure the caller must hear about,
+    // not a 404 wearing its clothes.
+    try {
+      await this.git(['-C', this.repoDir, 'rev-parse', '--verify', '--quiet', `${sha}^{commit}`]);
+    } catch (err) {
+      if (exitCodeOf(err) === 1) return false;
+      throw err;
+    }
+    try {
+      await this.git(['-C', this.repoDir, 'merge-base', '--is-ancestor', sha, head]);
+      return true;
+    } catch (err) {
+      if (exitCodeOf(err) === 1) return false;
+      throw err;
+    }
+  }
+
+  /** The tree at `sha` as a zip stream, every path under `prefix/`. Check {@link contains} first. */
+  archiveZip(sha: string, prefix: string): ChildProcess {
+    assertObjectId(sha);
+    return spawn('git', ['-C', this.repoDir, 'archive', '--format=zip', `--prefix=${prefix}/`, sha], {
+      stdio: ['ignore', 'pipe', 'pipe'],
+    });
+  }
+
+  // --- internal --------------------------------------------------------------
+
+  private refOf(namespace: string): string {
+    return `refs/namespaces/${namespace}/refs/heads/main`;
+  }
+
+  private async headOf(namespace: string): Promise<string | null> {
+    try {
+      const { stdout } = await this.git(['-C', this.repoDir, 'rev-parse', '--verify', '--quiet', this.refOf(namespace)]);
+      return stdout.trim() || null;
+    } catch (err) {
+      // "No such ref" is the answer this null stands for, and `rev-parse
+      // --verify --quiet` says it with exit code 1 and nothing else. Every
+      // other failure — a deadline, a repository git cannot open, a spawn that
+      // never ran — is not an answer about the ref, and read as one it would
+      // have `ensureCompiled` start a namespace's history over on top of the
+      // one it has.
+      if (exitCodeOf(err) !== 1) throw err;
+      return null;
+    }
+  }
+
+  /**
+   * Write `tree` as a commit on the namespace's branch. Materialises the
+   * virtual tree into a scratch directory, stages it into a throwaway index
+   * against the bare object store, and commits — no working tree involved.
+   * When the tree hash equals the head's, nothing is committed.
+   */
+  private async commitTree(
+    namespace: string,
+    tree: VirtualTree & { sourceCommit: string },
+    parent: string | null,
+  ): Promise<string> {
+    const scratch = await fs.mkdtemp(path.join(os.tmpdir(), 'hexis-marketplace-'));
+    // The throwaway index lives BESIDE the scratch worktree, never inside it:
+    // `git add -A` would otherwise stage the index (and its lock) into every
+    // compiled tree.
+    const indexDir = await fs.mkdtemp(path.join(os.tmpdir(), 'hexis-marketplace-index-'));
+    try {
+      for (const [rel, bytes] of tree.files) {
+        // The compiler sanitises every segment it invents, but the tree is
+        // built from repository content, so the sink checks containment
+        // itself: nothing is written outside the scratch directory.
+        const abs = path.resolve(scratch, rel);
+        if (!abs.startsWith(scratch + path.sep)) {
+          throw new Error(`refusing to materialise "${rel}": escapes the scratch tree`);
+        }
+        await fs.mkdir(path.dirname(abs), { recursive: true });
+        await fs.writeFile(abs, bytes);
+      }
+      const index = path.join(indexDir, 'index');
+      const env = { ...process.env, GIT_INDEX_FILE: index, GIT_DIR: this.repoDir, GIT_WORK_TREE: scratch };
+      await this.git(['add', '-A', '--', '.'], { cwd: scratch, env });
+      const treeSha = (await this.git(['write-tree'], { env })).stdout.trim();
+      if (parent) {
+        const parentTree = (await this.git(['-C', this.repoDir, 'rev-parse', `${parent}^{tree}`])).stdout.trim();
+        if (parentTree === treeSha) return parent;
+      }
+      const message = `Compile marketplace from ${tree.sourceCommit}\n\nHexis-Source-Commit: ${tree.sourceCommit}\n`;
+      const commitEnv = {
+        ...process.env,
+        GIT_AUTHOR_NAME: this.committer.name,
+        GIT_AUTHOR_EMAIL: this.committer.email,
+        GIT_COMMITTER_NAME: this.committer.name,
+        GIT_COMMITTER_EMAIL: this.committer.email,
+      };
+      const args = ['-C', this.repoDir, 'commit-tree', treeSha, '-m', message, ...(parent ? ['-p', parent] : [])];
+      const sha = (await this.git(args, { env: commitEnv })).stdout.trim();
+      // HEAD FIRST, then the branch: a symbolic ref may dangle, a branch
+      // without a HEAD is a clone that checks out nothing. Ordered so that a
+      // crash between the two leaves the recoverable state.
+      await this.ensureHead(namespace);
+      await this.git(['-C', this.repoDir, 'update-ref', this.refOf(namespace), sha, ...(parent ? [parent] : [])]);
+      return sha;
+    } finally {
+      await fs.rm(scratch, { recursive: true, force: true });
+      await fs.rm(indexDir, { recursive: true, force: true });
+    }
+  }
+
+  /**
+   * Point the namespace's HEAD at its branch — valid before the branch
+   * exists. A read first: the symref is written only when absent or wrong,
+   * so the common path touches nothing.
+   */
+  private async ensureHead(namespace: string): Promise<void> {
+    const head = `refs/namespaces/${namespace}/HEAD`;
+    const current = await this.git(['-C', this.repoDir, 'symbolic-ref', '--quiet', head]).then(
+      (r) => r.stdout.trim(),
+      () => null,
+    );
+    if (current === this.refOf(namespace)) return;
+    await this.git(['-C', this.repoDir, 'symbolic-ref', head, this.refOf(namespace)]);
+  }
+
+  private sidecarDir(): string {
+    return path.join(this.repoDir, 'hexis-namespaces');
+  }
+
+  private async readSidecar(namespace: string): Promise<string | null> {
+    try {
+      return (await fs.readFile(path.join(this.sidecarDir(), `${namespace}.json`), 'utf-8')).trim() || null;
+    } catch {
+      return null;
+    }
+  }
+
+  private async writeSidecar(namespace: string, sourceCommit: string): Promise<void> {
+    await fs.writeFile(path.join(this.sidecarDir(), `${namespace}.json`), sourceCommit);
+  }
+
+  /**
+   * Every command names the bare repository with `-C`, so the working
+   * directory only has to be somewhere that EXISTS: the process's own, as
+   * before. Not the repository — the first command ever run here is the `init`
+   * that creates it, and a spawn into a directory that is not there fails as
+   * `ENOENT` on git itself, which reads as git being missing. The plumbing
+   * that reads a scratch checkout passes its own `cwd`.
+   */
+  private git(args: string[], opts: { cwd?: string; env?: NodeJS.ProcessEnv } = {}) {
+    return this.gitRunner.run(opts.cwd ?? process.cwd(), args, { env: opts.env });
+  }
+}
+
+/** The exit code a git failure carries, or null when the process never ran. */
+function exitCodeOf(err: unknown): number | null {
+  const code = (err as { exitCode?: unknown } | null)?.exitCode;
+  return typeof code === 'number' ? code : null;
+}
+
+function looksLikeObjectId(sha: string): boolean {
+  return /^(?:[0-9a-f]{40}|[0-9a-f]{64})$/.test(sha);
+}
+
+function assertObjectId(sha: string): void {
+  // An object id is the only thing these commands accept as a revision — a
+  // ref name, an option, anything git would interpret, is refused before it
+  // reaches the argument list.
+  if (!looksLikeObjectId(sha)) throw new Error(`not an object id: ${sha}`);
+}