@h-rig/repos-plugin 0.0.6-alpha.156

package/README.md

@@ -0,0 +1 @@
+# @h-rig/repos-plugin

package/dist/src/index.d.ts

@@ -0,0 +1,7 @@
+export * from "./registry";
+export * from "./layout";
+export * from "./mirror/state";
+export * from "./mirror/bootstrap";
+export * from "./mirror/refresh";
+export * from "./service";
+export * from "./plugin";

package/dist/src/index.js

@@ -0,0 +1,491 @@
+// @bun
+var __defProp = Object.defineProperty;
+var __returnValue = (v) => v;
+function __exportSetter(name, newValue) {
+  this[name] = __returnValue.bind(null, newValue);
+}
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, {
+      get: all[name],
+      enumerable: true,
+      configurable: true,
+      set: __exportSetter.bind(all, name)
+    });
+};
+var __esm = (fn, res) => () => (fn && (res = fn(fn = 0)), res);
+
+// packages/repos-plugin/src/registry.ts
+function createRepoRegistry(entries) {
+  const map = new Map;
+  for (const e of entries) {
+    if (map.has(e.id))
+      throw new Error(`repo already registered: ${e.id}`);
+    map.set(e.id, { ...e });
+  }
+  const ordered = Array.from(map.values());
+  return {
+    getById: (id) => map.get(id),
+    list: () => ordered
+  };
+}
+function setManagedRepos(entries) {
+  const next = new Map;
+  for (const e of entries) {
+    if (next.has(e.id)) {
+      throw new Error(`managed repo already registered: ${e.id}`);
+    }
+    next.set(e.id, e);
+  }
+  MANAGED_REPOS = next;
+}
+function clearManagedRepos() {
+  MANAGED_REPOS = new Map;
+}
+function getManagedRepoEntry(repoId) {
+  const entry = MANAGED_REPOS.get(repoId);
+  if (!entry) {
+    throw new Error(`managed repo not registered: ${repoId}. Plugins contribute repos via RigPlugin.contributes.repoSources; ` + `make sure a plugin declares this id and the plugin host has been initialized.`);
+  }
+  return entry;
+}
+function tryGetManagedRepoEntry(repoId) {
+  return MANAGED_REPOS.get(repoId);
+}
+function listManagedRepoEntries() {
+  return Array.from(MANAGED_REPOS.values());
+}
+function resolveManagedRepoIdByAlias(alias) {
+  for (const entry of MANAGED_REPOS.values()) {
+    if (entry.alias === alias) {
+      return entry.id;
+    }
+  }
+  return null;
+}
+function isManagedRepoAlias(alias) {
+  return resolveManagedRepoIdByAlias(alias) !== null;
+}
+function repoRegistrationToManagedEntry(reg) {
+  if (!reg.defaultBranch) {
+    return null;
+  }
+  return {
+    id: reg.id,
+    alias: reg.defaultPath ?? reg.id,
+    defaultBranch: reg.defaultBranch,
+    defaultRemoteUrl: reg.url,
+    remoteEnvVar: reg.remoteEnvVar,
+    checkoutEnvVar: reg.checkoutEnvVar
+  };
+}
+var MANAGED_REPOS;
+var init_registry = __esm(() => {
+  MANAGED_REPOS = new Map;
+});
+
+// packages/repos-plugin/src/layout.ts
+import { existsSync } from "fs";
+import { basename, dirname, join, resolve } from "path";
+import { resolveMonorepoRoot } from "@rig/runtime/layout";
+function resolveRepoStateDir(projectRoot) {
+  const normalizedProjectRoot = resolve(projectRoot);
+  const projectParent = dirname(normalizedProjectRoot);
+  if (basename(projectParent) === ".worktrees") {
+    const ownerRoot = dirname(projectParent);
+    const ownerHasRepoMarkers = existsSync(resolve(ownerRoot, ".git")) || existsSync(resolve(ownerRoot, ".rig", "state"));
+    if (ownerHasRepoMarkers) {
+      return resolve(ownerRoot, ".rig", "state");
+    }
+  }
+  return resolve(projectRoot, ".rig", "state");
+}
+function resolveManagedRepoLayout(projectRoot, repoId) {
+  const normalizedProjectRoot = resolve(projectRoot);
+  const entry = getManagedRepoEntry(repoId);
+  const stateDir = resolveRepoStateDir(normalizedProjectRoot);
+  const metadataRelativePath = join("repos", entry.id);
+  const metadataRoot = resolve(stateDir, metadataRelativePath);
+  const runtimeWorkspace = process.env.RIG_TASK_WORKSPACE?.trim();
+  const runsInsideTaskWorktree = runtimeWorkspace && resolve(runtimeWorkspace) === normalizedProjectRoot || basename(dirname(normalizedProjectRoot)) === ".worktrees";
+  const isPrimaryManagedRepo = listManagedRepoEntries()[0]?.id === repoId;
+  const checkoutRoot = isPrimaryManagedRepo && runsInsideTaskWorktree ? resolveMonorepoRoot(normalizedProjectRoot) : entry.checkoutEnvVar && process.env[entry.checkoutEnvVar]?.trim() ? resolve(process.env[entry.checkoutEnvVar].trim()) : resolve(normalizedProjectRoot, entry.alias);
+  return {
+    projectRoot: normalizedProjectRoot,
+    repoId: entry.id,
+    alias: entry.alias,
+    defaultBranch: entry.defaultBranch,
+    remoteUrl: entry.remoteEnvVar && process.env[entry.remoteEnvVar]?.trim() ? process.env[entry.remoteEnvVar].trim() : entry.defaultRemoteUrl,
+    checkoutRoot,
+    worktreesRoot: resolve(checkoutRoot, ".worktrees"),
+    stateDir,
+    metadataRoot,
+    metadataRelativePath,
+    mirrorRoot: resolve(metadataRoot, "mirror.git"),
+    mirrorStatePath: resolve(metadataRoot, "mirror-state.json"),
+    mirrorStateRelativePath: join(metadataRelativePath, "mirror-state.json")
+  };
+}
+function resolveManagedRepoLayoutByAlias(projectRoot, alias) {
+  const repoId = resolveManagedRepoIdByAlias(alias);
+  return repoId ? resolveManagedRepoLayout(projectRoot, repoId) : null;
+}
+function resolveMonorepoRepoLayout(projectRoot) {
+  const entries = listManagedRepoEntries();
+  if (entries.length === 0) {
+    throw new Error("resolveMonorepoRepoLayout: no managed repos registered. Either contribute one via " + "RigPlugin.contributes.repoSources (with defaultBranch set), or avoid calling this " + "function for projects where the project root IS the monorepo.");
+  }
+  const primary = entries[0];
+  return resolveManagedRepoLayout(projectRoot, primary.id);
+}
+var init_layout = __esm(() => {
+  init_registry();
+});
+
+// packages/repos-plugin/src/mirror/state.ts
+import { readAuthorityProjectStateJson, writeAuthorityProjectStateJson } from "@rig/runtime/control-plane/json-files";
+function defaultMirrorState(projectRoot, repoId) {
+  const layout = resolveManagedRepoLayout(projectRoot, repoId);
+  return {
+    version: STATE_VERSION,
+    repoId,
+    remoteUrl: layout.remoteUrl,
+    defaultBranch: layout.defaultBranch
+  };
+}
+function readManagedRepoMirrorState(projectRoot, repoId) {
+  const layout = resolveManagedRepoLayout(projectRoot, repoId);
+  return readAuthorityProjectStateJson(projectRoot, layout.mirrorStateRelativePath, null);
+}
+function writeManagedRepoMirrorState(projectRoot, repoId, patch) {
+  const current = readManagedRepoMirrorState(projectRoot, repoId) || defaultMirrorState(projectRoot, repoId);
+  const next = {
+    ...current,
+    ...patch,
+    version: STATE_VERSION,
+    repoId
+  };
+  const layout = resolveManagedRepoLayout(projectRoot, repoId);
+  writeAuthorityProjectStateJson(projectRoot, layout.mirrorStateRelativePath, next);
+  return next;
+}
+var STATE_VERSION = 1;
+var init_state = __esm(() => {
+  init_layout();
+});
+
+// packages/repos-plugin/src/mirror/bootstrap.ts
+import { existsSync as existsSync2, mkdirSync, realpathSync } from "fs";
+import { resolve as resolve2 } from "path";
+function nowIso() {
+  return new Date().toISOString();
+}
+function runGit(command, cwd) {
+  const result = Bun.spawnSync(command, {
+    cwd,
+    stdout: "pipe",
+    stderr: "pipe",
+    env: process.env
+  });
+  return {
+    exitCode: result.exitCode,
+    stdout: result.stdout.toString(),
+    stderr: result.stderr.toString()
+  };
+}
+function ensureGitSuccess(result, command) {
+  if (result.exitCode !== 0) {
+    throw new Error(result.stderr || result.stdout || `git command failed: ${command.join(" ")}`);
+  }
+}
+function isUsableRemoteUrl(candidate, layout) {
+  return candidate.length > 0 && candidate !== layout.mirrorRoot && candidate !== layout.checkoutRoot;
+}
+function sameExistingPath(left, right) {
+  try {
+    return realpathSync(left) === realpathSync(right);
+  } catch {
+    return resolve2(left) === resolve2(right);
+  }
+}
+function repoLooksUsable(repoRoot, projectRoot) {
+  const probe = runGit(["git", "-C", repoRoot, "rev-parse", "--show-toplevel"], projectRoot);
+  return probe.exitCode === 0 && sameExistingPath(probe.stdout.trim(), repoRoot);
+}
+function checkoutLooksUsable(layout) {
+  return repoLooksUsable(layout.checkoutRoot, layout.projectRoot);
+}
+function resolveMirrorRemoteUrl(layout) {
+  const entry = getManagedRepoEntry(layout.repoId);
+  const explicit = entry.remoteEnvVar ? process.env[entry.remoteEnvVar]?.trim() : "";
+  if (explicit) {
+    return explicit;
+  }
+  const persisted = readManagedRepoMirrorState(layout.projectRoot, layout.repoId)?.remoteUrl?.trim();
+  if (persisted && isUsableRemoteUrl(persisted, layout)) {
+    return persisted;
+  }
+  const mirrorOrigin = runGit(["git", "--git-dir", layout.mirrorRoot, "remote", "get-url", "origin"], layout.projectRoot);
+  if (mirrorOrigin.exitCode === 0) {
+    const currentOrigin = mirrorOrigin.stdout.trim();
+    if (isUsableRemoteUrl(currentOrigin, layout)) {
+      return currentOrigin;
+    }
+  }
+  if (repoLooksUsable(layout.projectRoot, layout.projectRoot)) {
+    const projectOrigin = runGit(["git", "-C", layout.projectRoot, "remote", "get-url", "origin"], layout.projectRoot);
+    if (projectOrigin.exitCode === 0) {
+      const currentOrigin = projectOrigin.stdout.trim();
+      if (isUsableRemoteUrl(currentOrigin, layout)) {
+        return currentOrigin;
+      }
+    }
+  }
+  if (existsSync2(resolve2(layout.checkoutRoot, ".git")) && checkoutLooksUsable(layout)) {
+    const checkoutOrigin = runGit(["git", "-C", layout.checkoutRoot, "remote", "get-url", "origin"], layout.projectRoot);
+    if (checkoutOrigin.exitCode === 0) {
+      const currentOrigin = checkoutOrigin.stdout.trim();
+      if (isUsableRemoteUrl(currentOrigin, layout)) {
+        return currentOrigin;
+      }
+    }
+  }
+  return layout.remoteUrl;
+}
+function ensureManagedRepoMirror(projectRoot, repoId) {
+  const layout = resolveManagedRepoLayout(projectRoot, repoId);
+  mkdirSync(layout.metadataRoot, { recursive: true });
+  const remoteUrl = resolveMirrorRemoteUrl(layout);
+  if (!existsSync2(resolve2(layout.mirrorRoot, "HEAD"))) {
+    ensureGitSuccess(runGit(["git", "init", "--bare", layout.mirrorRoot], layout.projectRoot), ["git", "init", "--bare", layout.mirrorRoot]);
+  }
+  const getOrigin = runGit(["git", "--git-dir", layout.mirrorRoot, "remote", "get-url", "origin"], layout.projectRoot);
+  if (getOrigin.exitCode === 0) {
+    const currentOrigin = getOrigin.stdout.trim();
+    if (currentOrigin !== remoteUrl) {
+      ensureGitSuccess(runGit(["git", "--git-dir", layout.mirrorRoot, "remote", "set-url", "origin", remoteUrl], layout.projectRoot), ["git", "--git-dir", layout.mirrorRoot, "remote", "set-url", "origin", remoteUrl]);
+    }
+  } else {
+    ensureGitSuccess(runGit(["git", "--git-dir", layout.mirrorRoot, "remote", "add", "origin", remoteUrl], layout.projectRoot), ["git", "--git-dir", layout.mirrorRoot, "remote", "add", "origin", remoteUrl]);
+  }
+  writeManagedRepoMirrorState(projectRoot, repoId, {
+    remoteUrl,
+    defaultBranch: layout.defaultBranch,
+    initializedAt: nowIso()
+  });
+  return layout;
+}
+var init_bootstrap = __esm(() => {
+  init_registry();
+  init_layout();
+  init_state();
+});
+
+// packages/repos-plugin/src/mirror/refresh.ts
+import { existsSync as existsSync3, mkdirSync as mkdirSync2, realpathSync as realpathSync2, rmSync } from "fs";
+import { resolve as resolve3 } from "path";
+function nowIso2() {
+  return new Date().toISOString();
+}
+function runGit2(command, cwd) {
+  const result = Bun.spawnSync(command, {
+    cwd,
+    stdout: "pipe",
+    stderr: "pipe",
+    env: process.env
+  });
+  return {
+    exitCode: result.exitCode,
+    stdout: result.stdout.toString(),
+    stderr: result.stderr.toString()
+  };
+}
+function ensureGitSuccess2(result, command) {
+  if (result.exitCode !== 0) {
+    throw new Error(result.stderr || result.stdout || `git command failed: ${command.join(" ")}`);
+  }
+  return result.stdout.trim();
+}
+function sameExistingPath2(left, right) {
+  try {
+    return realpathSync2(left) === realpathSync2(right);
+  } catch {
+    return resolve3(left) === resolve3(right);
+  }
+}
+function ensureMirrorHead(layout) {
+  ensureGitSuccess2(runGit2([
+    "git",
+    "--git-dir",
+    layout.mirrorRoot,
+    "fetch",
+    "--prune",
+    "origin",
+    "+refs/heads/*:refs/heads/*",
+    "+refs/tags/*:refs/tags/*"
+  ], layout.projectRoot), [
+    "git",
+    "--git-dir",
+    layout.mirrorRoot,
+    "fetch",
+    "--prune",
+    "origin",
+    "+refs/heads/*:refs/heads/*",
+    "+refs/tags/*:refs/tags/*"
+  ]);
+  const headRef = `refs/heads/${layout.defaultBranch}`;
+  const headCommit = ensureGitSuccess2(runGit2(["git", "--git-dir", layout.mirrorRoot, "rev-parse", headRef], layout.projectRoot), ["git", "--git-dir", layout.mirrorRoot, "rev-parse", headRef]);
+  const remoteUrl = ensureGitSuccess2(runGit2(["git", "--git-dir", layout.mirrorRoot, "remote", "get-url", "origin"], layout.projectRoot), ["git", "--git-dir", layout.mirrorRoot, "remote", "get-url", "origin"]);
+  ensureGitSuccess2(runGit2(["git", "--git-dir", layout.mirrorRoot, "symbolic-ref", "HEAD", headRef], layout.projectRoot), ["git", "--git-dir", layout.mirrorRoot, "symbolic-ref", "HEAD", headRef]);
+  writeManagedRepoMirrorState(layout.projectRoot, layout.repoId, {
+    remoteUrl,
+    defaultBranch: layout.defaultBranch,
+    lastSyncedAt: nowIso2(),
+    headRef,
+    headCommit
+  });
+  return headCommit;
+}
+function refreshManagedRepoMirror(projectRoot, repoId) {
+  const layout = ensureManagedRepoMirror(projectRoot, repoId);
+  const headCommit = ensureMirrorHead(layout);
+  return { layout, headCommit };
+}
+function checkoutLooksUsable2(layout) {
+  const probe = runGit2(["git", "-C", layout.checkoutRoot, "rev-parse", "--show-toplevel"], layout.projectRoot);
+  return probe.exitCode === 0 && sameExistingPath2(probe.stdout.trim(), layout.checkoutRoot);
+}
+function ensureCheckoutFromMirror(layout) {
+  mkdirSync2(resolve3(layout.checkoutRoot, ".."), { recursive: true });
+  const gitPath = resolve3(layout.checkoutRoot, ".git");
+  if (existsSync3(layout.checkoutRoot) && (!existsSync3(gitPath) || !checkoutLooksUsable2(layout))) {
+    rmSync(layout.checkoutRoot, { recursive: true, force: true });
+  }
+  if (!existsSync3(gitPath)) {
+    ensureGitSuccess2(runGit2(["git", "clone", layout.mirrorRoot, layout.checkoutRoot], layout.projectRoot), ["git", "clone", layout.mirrorRoot, layout.checkoutRoot]);
+  }
+  const getOrigin = runGit2(["git", "-C", layout.checkoutRoot, "remote", "get-url", "origin"], layout.projectRoot);
+  if (getOrigin.exitCode === 0) {
+    const currentOrigin = getOrigin.stdout.trim();
+    if (currentOrigin !== layout.mirrorRoot) {
+      ensureGitSuccess2(runGit2(["git", "-C", layout.checkoutRoot, "remote", "set-url", "origin", layout.mirrorRoot], layout.projectRoot), ["git", "-C", layout.checkoutRoot, "remote", "set-url", "origin", layout.mirrorRoot]);
+    }
+  } else {
+    ensureGitSuccess2(runGit2(["git", "-C", layout.checkoutRoot, "remote", "add", "origin", layout.mirrorRoot], layout.projectRoot), ["git", "-C", layout.checkoutRoot, "remote", "add", "origin", layout.mirrorRoot]);
+  }
+  ensureGitSuccess2(runGit2(["git", "-C", layout.checkoutRoot, "fetch", "origin", layout.defaultBranch], layout.projectRoot), ["git", "-C", layout.checkoutRoot, "fetch", "origin", layout.defaultBranch]);
+  ensureGitSuccess2(runGit2(["git", "-C", layout.checkoutRoot, "reset", "--hard"], layout.projectRoot), ["git", "-C", layout.checkoutRoot, "reset", "--hard"]);
+  ensureGitSuccess2(runGit2(["git", "-C", layout.checkoutRoot, "clean", "-fd"], layout.projectRoot), ["git", "-C", layout.checkoutRoot, "clean", "-fd"]);
+  ensureGitSuccess2(runGit2([
+    "git",
+    "-C",
+    layout.checkoutRoot,
+    "checkout",
+    "--force",
+    "-B",
+    layout.defaultBranch,
+    `origin/${layout.defaultBranch}`
+  ], layout.projectRoot), [
+    "git",
+    "-C",
+    layout.checkoutRoot,
+    "checkout",
+    "--force",
+    "-B",
+    layout.defaultBranch,
+    `origin/${layout.defaultBranch}`
+  ]);
+  ensureGitSuccess2(runGit2(["git", "-C", layout.checkoutRoot, "reset", "--hard", `origin/${layout.defaultBranch}`], layout.projectRoot), ["git", "-C", layout.checkoutRoot, "reset", "--hard", `origin/${layout.defaultBranch}`]);
+  ensureGitSuccess2(runGit2(["git", "-C", layout.checkoutRoot, "clean", "-fd"], layout.projectRoot), ["git", "-C", layout.checkoutRoot, "clean", "-fd"]);
+  return ensureGitSuccess2(runGit2(["git", "-C", layout.checkoutRoot, "rev-parse", "HEAD"], layout.projectRoot), ["git", "-C", layout.checkoutRoot, "rev-parse", "HEAD"]);
+}
+function syncManagedRepo(projectRoot, repoId) {
+  const { layout, headCommit } = refreshManagedRepoMirror(projectRoot, repoId);
+  const checkoutCommit = ensureCheckoutFromMirror(layout);
+  if (checkoutCommit !== headCommit) {
+    throw new Error(`Managed repo checkout ${layout.alias} is out of sync with mirror: expected ${headCommit}, got ${checkoutCommit}.`);
+  }
+  return { layout, headCommit };
+}
+var init_refresh = __esm(() => {
+  init_bootstrap();
+  init_state();
+});
+
+// packages/repos-plugin/src/service.ts
+var exports_service = {};
+__export(exports_service, {
+  svc: () => svc,
+  managedRepoService: () => managedRepoService
+});
+var managedRepoService, svc;
+var init_service = __esm(() => {
+  init_registry();
+  init_layout();
+  init_refresh();
+  managedRepoService = {
+    setManagedRepos,
+    listManagedRepoEntries,
+    resolveManagedRepoIdByAlias,
+    repoRegistrationToManagedEntry,
+    createRepoRegistry,
+    resolveManagedRepoLayoutByAlias,
+    resolveMonorepoRepoLayout,
+    syncManagedRepo
+  };
+  svc = managedRepoService;
+});
+
+// packages/repos-plugin/src/index.ts
+init_registry();
+init_layout();
+init_state();
+init_bootstrap();
+init_refresh();
+init_service();
+
+// packages/repos-plugin/src/plugin.ts
+import { definePlugin } from "@rig/core/config";
+import { MANAGED_REPO_SERVICE_CAPABILITY_ID } from "@rig/contracts";
+var REPOS_PLUGIN_NAME = "@rig/repos-plugin";
+var reposPlugin = definePlugin({
+  name: REPOS_PLUGIN_NAME,
+  version: "0.0.0-alpha.1",
+  contributes: {
+    capabilities: [
+      {
+        id: MANAGED_REPO_SERVICE_CAPABILITY_ID,
+        title: "Managed repositories",
+        description: "Registry, on-disk layout, and mirror/sync for plugin-contributed managed repos.",
+        run: async () => (await Promise.resolve().then(() => (init_service(), exports_service))).svc
+      }
+    ]
+  }
+});
+function createReposPlugin() {
+  return reposPlugin;
+}
+export {
+  writeManagedRepoMirrorState,
+  tryGetManagedRepoEntry,
+  syncManagedRepo,
+  svc,
+  setManagedRepos,
+  resolveMonorepoRepoLayout,
+  resolveManagedRepoLayoutByAlias,
+  resolveManagedRepoLayout,
+  resolveManagedRepoIdByAlias,
+  reposPlugin,
+  repoRegistrationToManagedEntry,
+  refreshManagedRepoMirror,
+  readManagedRepoMirrorState,
+  managedRepoService,
+  listManagedRepoEntries,
+  isManagedRepoAlias,
+  getManagedRepoEntry,
+  ensureManagedRepoMirror,
+  createReposPlugin,
+  createRepoRegistry,
+  clearManagedRepos,
+  REPOS_PLUGIN_NAME
+};

package/dist/src/layout.d.ts

@@ -0,0 +1,10 @@
+import type { ManagedRepoAlias, ManagedRepoId, ManagedRepoLayout } from "@rig/contracts";
+export declare function resolveManagedRepoLayout(projectRoot: string, repoId: ManagedRepoId): ManagedRepoLayout;
+export declare function resolveManagedRepoLayoutByAlias(projectRoot: string, alias: ManagedRepoAlias | string): ManagedRepoLayout | null;
+/**
+ * Resolve the layout for the project's primary monorepo. Picks the first
+ * managed repo entry; throws if none are registered. New projects without
+ * a separate managed monorepo don't call this — they live in the flat
+ * layout where the project root IS the monorepo.
+ */
+export declare function resolveMonorepoRepoLayout(projectRoot: string): ManagedRepoLayout;

package/dist/src/layout.js

@@ -0,0 +1,83 @@
+// @bun
+// packages/repos-plugin/src/layout.ts
+import { existsSync } from "fs";
+import { basename, dirname, join, resolve } from "path";
+import { resolveMonorepoRoot } from "@rig/runtime/layout";
+
+// packages/repos-plugin/src/registry.ts
+var MANAGED_REPOS = new Map;
+function getManagedRepoEntry(repoId) {
+  const entry = MANAGED_REPOS.get(repoId);
+  if (!entry) {
+    throw new Error(`managed repo not registered: ${repoId}. Plugins contribute repos via RigPlugin.contributes.repoSources; ` + `make sure a plugin declares this id and the plugin host has been initialized.`);
+  }
+  return entry;
+}
+function listManagedRepoEntries() {
+  return Array.from(MANAGED_REPOS.values());
+}
+function resolveManagedRepoIdByAlias(alias) {
+  for (const entry of MANAGED_REPOS.values()) {
+    if (entry.alias === alias) {
+      return entry.id;
+    }
+  }
+  return null;
+}
+
+// packages/repos-plugin/src/layout.ts
+function resolveRepoStateDir(projectRoot) {
+  const normalizedProjectRoot = resolve(projectRoot);
+  const projectParent = dirname(normalizedProjectRoot);
+  if (basename(projectParent) === ".worktrees") {
+    const ownerRoot = dirname(projectParent);
+    const ownerHasRepoMarkers = existsSync(resolve(ownerRoot, ".git")) || existsSync(resolve(ownerRoot, ".rig", "state"));
+    if (ownerHasRepoMarkers) {
+      return resolve(ownerRoot, ".rig", "state");
+    }
+  }
+  return resolve(projectRoot, ".rig", "state");
+}
+function resolveManagedRepoLayout(projectRoot, repoId) {
+  const normalizedProjectRoot = resolve(projectRoot);
+  const entry = getManagedRepoEntry(repoId);
+  const stateDir = resolveRepoStateDir(normalizedProjectRoot);
+  const metadataRelativePath = join("repos", entry.id);
+  const metadataRoot = resolve(stateDir, metadataRelativePath);
+  const runtimeWorkspace = process.env.RIG_TASK_WORKSPACE?.trim();
+  const runsInsideTaskWorktree = runtimeWorkspace && resolve(runtimeWorkspace) === normalizedProjectRoot || basename(dirname(normalizedProjectRoot)) === ".worktrees";
+  const isPrimaryManagedRepo = listManagedRepoEntries()[0]?.id === repoId;
+  const checkoutRoot = isPrimaryManagedRepo && runsInsideTaskWorktree ? resolveMonorepoRoot(normalizedProjectRoot) : entry.checkoutEnvVar && process.env[entry.checkoutEnvVar]?.trim() ? resolve(process.env[entry.checkoutEnvVar].trim()) : resolve(normalizedProjectRoot, entry.alias);
+  return {
+    projectRoot: normalizedProjectRoot,
+    repoId: entry.id,
+    alias: entry.alias,
+    defaultBranch: entry.defaultBranch,
+    remoteUrl: entry.remoteEnvVar && process.env[entry.remoteEnvVar]?.trim() ? process.env[entry.remoteEnvVar].trim() : entry.defaultRemoteUrl,
+    checkoutRoot,
+    worktreesRoot: resolve(checkoutRoot, ".worktrees"),
+    stateDir,
+    metadataRoot,
+    metadataRelativePath,
+    mirrorRoot: resolve(metadataRoot, "mirror.git"),
+    mirrorStatePath: resolve(metadataRoot, "mirror-state.json"),
+    mirrorStateRelativePath: join(metadataRelativePath, "mirror-state.json")
+  };
+}
+function resolveManagedRepoLayoutByAlias(projectRoot, alias) {
+  const repoId = resolveManagedRepoIdByAlias(alias);
+  return repoId ? resolveManagedRepoLayout(projectRoot, repoId) : null;
+}
+function resolveMonorepoRepoLayout(projectRoot) {
+  const entries = listManagedRepoEntries();
+  if (entries.length === 0) {
+    throw new Error("resolveMonorepoRepoLayout: no managed repos registered. Either contribute one via " + "RigPlugin.contributes.repoSources (with defaultBranch set), or avoid calling this " + "function for projects where the project root IS the monorepo.");
+  }
+  const primary = entries[0];
+  return resolveManagedRepoLayout(projectRoot, primary.id);
+}
+export {
+  resolveMonorepoRepoLayout,
+  resolveManagedRepoLayoutByAlias,
+  resolveManagedRepoLayout
+};

package/dist/src/mirror/bootstrap.d.ts

@@ -0,0 +1,2 @@
+import type { ManagedRepoId, ManagedRepoLayout } from "@rig/contracts";
+export declare function ensureManagedRepoMirror(projectRoot: string, repoId: ManagedRepoId): ManagedRepoLayout;