@h-rig/core 0.0.6-alpha.157 → 0.0.6-alpha.158

package/dist/src/remote-config.js

@@ -0,0 +1,568 @@
+// @bun
+// packages/core/src/remote-config.ts
+import { randomUUID } from "crypto";
+import { chmodSync, existsSync as existsSync2, mkdirSync, mkdtempSync, readFileSync, writeFileSync } from "fs";
+import { homedir, tmpdir } from "os";
+import { dirname as dirname2, join, resolve as resolve2 } from "path";
+import { parse as parseToml, stringify as stringifyToml } from "smol-toml";
+
+// packages/core/src/authority-paths.ts
+import { existsSync } from "fs";
+import { dirname, resolve } from "path";
+function normalizeOptionalString(value) {
+  return typeof value === "string" && value.trim().length > 0 ? value.trim() : null;
+}
+function resolveAuthorityPaths(projectRoot) {
+  const normalizedRoot = resolve(projectRoot);
+  const stateRoot = resolveAuthorityStateRoot(normalizedRoot);
+  const stateDir = resolveAuthorityStateDir(normalizedRoot);
+  return {
+    projectRoot: normalizedRoot,
+    harnessRoot: resolve(normalizedRoot, "rig"),
+    runsDir: resolve(stateRoot, "runs"),
+    remoteDir: resolve(stateRoot, "remote"),
+    stateDir,
+    remoteEndpointsPath: resolve(stateRoot, "remote", "endpoints.toml"),
+    remoteSecretsPath: resolve(stateDir, "remote-secrets.toml")
+  };
+}
+function resolveAuthorityStateRoot(projectRoot) {
+  const normalizedRoot = resolve(projectRoot);
+  const taskWorkspace = normalizeOptionalString(process.env.RIG_TASK_WORKSPACE);
+  if (taskWorkspace) {
+    return resolve(taskWorkspace, ".rig");
+  }
+  const stateDir = normalizeOptionalString(process.env.RIG_STATE_DIR);
+  if (stateDir) {
+    return dirname(resolve(stateDir));
+  }
+  const logsDir = normalizeOptionalString(process.env.RIG_LOGS_DIR);
+  if (logsDir) {
+    return dirname(resolve(logsDir));
+  }
+  const sessionFile = normalizeOptionalString(process.env.RIG_SESSION_FILE);
+  if (sessionFile) {
+    return dirname(dirname(resolve(sessionFile)));
+  }
+  const projectStateRoot = resolve(normalizedRoot, ".rig");
+  if (existsSync(projectStateRoot)) {
+    return projectStateRoot;
+  }
+  return resolve(normalizedRoot, ".rig");
+}
+function resolveAuthorityStateDir(projectRoot) {
+  const explicit = normalizeOptionalString(process.env.RIG_STATE_DIR);
+  if (explicit) {
+    return resolve(explicit);
+  }
+  return resolve(resolveAuthorityStateRoot(projectRoot), "state");
+}
+
+// packages/core/src/remote-config.ts
+var DEFAULT_REMOTE_PORT = 7890;
+var BACKBONE_DEFAULTS_KEY = Symbol.for("rig.remote-config.backbone-defaults");
+function backboneDefaultsState() {
+  const global = globalThis;
+  return global[BACKBONE_DEFAULTS_KEY] ??= {};
+}
+function registerBackboneDefaults(defaults) {
+  const relayUrl = normalizeString(defaults.relayUrl);
+  const registryBaseUrl = normalizeString(defaults.registryBaseUrl);
+  const sshTarget = normalizeString(defaults.sshTarget);
+  const state = backboneDefaultsState();
+  if (relayUrl)
+    state.relayUrl = relayUrl;
+  if (registryBaseUrl)
+    state.registryBaseUrl = registryBaseUrl;
+  if (sshTarget)
+    state.sshTarget = sshTarget;
+}
+function resolveRelayUrl(env = process.env) {
+  return normalizeString(env.RIG_COLLAB_RELAY) || normalizeString(env.RIG_SPIKE_RELAY) || backboneDefaultsState().relayUrl || "";
+}
+function resolveSshTarget(env = process.env) {
+  return normalizeString(env.RIG_SSH_TARGET) || backboneDefaultsState().sshTarget || "";
+}
+var REMOTES_CONFIG_PATH = join(homedir(), ".config", "rig", "remotes.toml");
+
+class RemoteCliError extends Error {
+  code;
+  exitCode;
+  details;
+  constructor(code, message, exitCode = 1, details) {
+    super(message);
+    this.name = "RemoteCliError";
+    this.code = code;
+    this.exitCode = exitCode;
+    this.details = details;
+  }
+}
+function loadRemotesConfig(configPath = REMOTES_CONFIG_PATH) {
+  if (!existsSync2(configPath)) {
+    return { version: 1, remotes: {} };
+  }
+  try {
+    const content = readFileSync(configPath, "utf-8");
+    if (!content.trim()) {
+      return { version: 1, remotes: {} };
+    }
+    const parsed = parseToml(content);
+    return {
+      version: parsed.version ?? 1,
+      remotes: parsed.remotes ?? {}
+    };
+  } catch (error) {
+    throw new RemoteCliError("RIG_REMOTE_CONFIG_PARSE_ERROR", `Failed to parse remotes config at ${configPath}: ${error instanceof Error ? error.message : String(error)}`, 2, { configPath });
+  }
+}
+function saveRemotesConfig(config, configPath = REMOTES_CONFIG_PATH) {
+  mkdirSync(dirname2(configPath), { recursive: true });
+  writeFileSync(configPath, `${stringifyToml(config).trimEnd()}
+`, "utf-8");
+  try {
+    chmodSync(configPath, 384);
+  } catch {}
+}
+function readTomlFile(path, fallback) {
+  if (!existsSync2(path))
+    return fallback;
+  const raw = readFileSync(path, "utf8");
+  if (!raw.trim())
+    return fallback;
+  return parseToml(raw);
+}
+function writeTomlFile(path, value) {
+  mkdirSync(dirname2(path), { recursive: true });
+  writeFileSync(path, `${stringifyToml(value).trimEnd()}
+`, "utf8");
+}
+function normalizeStringArray(value) {
+  if (!Array.isArray(value))
+    return [];
+  return value.map((entry) => normalizeString(entry)).filter((entry) => entry !== "");
+}
+function normalizePort(value) {
+  const port = typeof value === "number" ? value : Number(value);
+  return Number.isInteger(port) && port > 0 && port <= 65535 ? port : DEFAULT_REMOTE_PORT;
+}
+function normalizeRegistryBaseUrl(raw) {
+  const trimmed = raw.replace(/\/+$/, "");
+  if (!trimmed)
+    return trimmed;
+  return /\/registry$/.test(trimmed) ? trimmed : `${trimmed}/registry`;
+}
+function loadRemoteEndpointsToml(projectRoot) {
+  const paths = resolveAuthorityPaths(projectRoot);
+  const parsed = readTomlFile(paths.remoteEndpointsPath, { version: 1, endpoints: {} });
+  return {
+    version: parsed.version ?? 1,
+    endpoints: parsed.endpoints ?? {}
+  };
+}
+function loadRemoteSecretsToml(projectRoot) {
+  const paths = resolveAuthorityPaths(projectRoot);
+  const parsed = readTomlFile(paths.remoteSecretsPath, { version: 1, secrets: {} });
+  return {
+    version: parsed.version ?? 1,
+    secrets: parsed.secrets ?? {}
+  };
+}
+function readJsonRecordFile(path) {
+  try {
+    if (!existsSync2(path))
+      return {};
+    const raw = readFileSync(path, "utf8");
+    if (!raw.trim())
+      return {};
+    const parsed = JSON.parse(raw);
+    return parsed && typeof parsed === "object" ? parsed : {};
+  } catch {
+    return {};
+  }
+}
+function coerceString(value) {
+  return typeof value === "string" ? value.trim() : "";
+}
+function resolveOwnerNamespaceKey(projectRoot, env = process.env) {
+  const fromEnv = normalizeString(env.RIG_GITHUB_NAMESPACE_KEY);
+  if (fromEnv)
+    return fromEnv;
+  const stateDir = resolveAuthorityPaths(projectRoot).stateDir;
+  const auth = readJsonRecordFile(resolve2(stateDir, "github-auth.json"));
+  const namespaceKey = coerceString(auth.userNamespaceKey);
+  if (namespaceKey)
+    return namespaceKey;
+  const userId = coerceString(auth.userId);
+  return userId ? `gh:${userId}` : undefined;
+}
+function forceLocalTransport(env) {
+  return env.RIG_FORCE_LOCAL === "1" || env.RIG_FORCE_LOCAL === "true";
+}
+function resolveDispatchTransportPlacement(projectRoot, env = process.env) {
+  if (forceLocalTransport(env)) {
+    return { kind: "local", alias: "local", sshTarget: null, selected: null };
+  }
+  const selected = resolveSelectedRemote(projectRoot, env);
+  const sshTarget = selected?.sshTarget ?? resolveSshTarget(env);
+  if (!sshTarget) {
+    return { kind: "local", alias: "local", sshTarget: null, selected: null };
+  }
+  return { kind: "remote", alias: selected?.alias ?? sshTarget, sshTarget, selected };
+}
+function resolveSelectedRemote(projectRoot, env = process.env) {
+  const stateDir = resolveAuthorityPaths(projectRoot).stateDir;
+  const conn = readJsonRecordFile(resolve2(stateDir, "connection.json"));
+  const selected = normalizeString(env.RIG_REMOTE_ALIAS) || coerceString(conn.selected);
+  if (!selected || selected === "local")
+    return null;
+  const endpoints = Object.values(loadRemoteEndpointsToml(projectRoot).endpoints ?? {});
+  const match = endpoints.find((entry) => normalizeString(entry.alias) === selected);
+  if (!match) {
+    if (selected === "remote") {
+      const sshTarget = resolveSshTarget(env);
+      if (!sshTarget)
+        return null;
+      return {
+        alias: "remote",
+        host: sshTarget,
+        port: 22,
+        sshTarget,
+        checkout: coerceString(conn.serverProjectRoot) || null,
+        registryBaseUrl: null,
+        secretRef: null
+      };
+    }
+    return null;
+  }
+  const host = normalizeString(match.host) || selected;
+  const explicitRegistryUrl = normalizeString(env.RIG_REGISTRY_URL) || normalizeString(env.REGISTRY_URL);
+  const registryBaseUrl = explicitRegistryUrl ? normalizeRegistryBaseUrl(explicitRegistryUrl) : null;
+  return {
+    alias: selected,
+    host,
+    port: normalizePort(match.port),
+    sshTarget: host || normalizeString(match.alias) || coerceString(conn.serverProjectRootAlias),
+    checkout: coerceString(conn.serverProjectRoot) || null,
+    registryBaseUrl,
+    secretRef: normalizeString(match.secret_ref) || null
+  };
+}
+function resolveRegistryBaseUrl(projectRoot, env = process.env) {
+  return normalizeRegistryBaseUrl(normalizeString(env.RIG_REGISTRY_URL) || normalizeString(env.REGISTRY_URL) || resolveSelectedRemote(projectRoot, env)?.registryBaseUrl || backboneDefaultsState().registryBaseUrl || "");
+}
+var rigOmpConfigOverlayPath = null;
+function resolveRigOmpConfigOverlayPath(projectRoot = process.cwd()) {
+  if (rigOmpConfigOverlayPath && existsSync2(rigOmpConfigOverlayPath))
+    return rigOmpConfigOverlayPath;
+  const overlay = [
+    `collab.relayUrl: ${resolveRelayUrl()}`,
+    `registry.url: ${resolveRegistryBaseUrl(projectRoot)}`,
+    "# Cockpit owns the screen: skip OMP's welcome/startup so the drone board renders cleanly.",
+    "startup.quiet: true",
+    ""
+  ].join(`
+`);
+  const base = tmpdir();
+  mkdirSync(base, { recursive: true });
+  const dir = mkdtempSync(join(base, "rig-config-"));
+  const file = join(dir, "rig-default-config.yml");
+  writeFileSync(file, overlay);
+  rigOmpConfigOverlayPath = file;
+  return file;
+}
+function saveRemoteEndpointsToml(projectRoot, payload) {
+  writeTomlFile(resolveAuthorityPaths(projectRoot).remoteEndpointsPath, payload);
+}
+function saveRemoteSecretsToml(projectRoot, payload) {
+  const paths = resolveAuthorityPaths(projectRoot);
+  writeTomlFile(paths.remoteSecretsPath, payload);
+  try {
+    chmodSync(paths.remoteSecretsPath, 384);
+  } catch {}
+}
+function listAuthorityRemoteEndpoints(projectRoot) {
+  const endpoints = loadRemoteEndpointsToml(projectRoot).endpoints ?? {};
+  const secrets = loadRemoteSecretsToml(projectRoot).secrets ?? {};
+  return Object.values(endpoints).map((entry) => {
+    const token = secrets[entry.secret_ref] ?? "";
+    return {
+      id: entry.id,
+      alias: entry.alias,
+      host: entry.host,
+      port: normalizePort(entry.port),
+      token,
+      autoConnect: Boolean(entry.auto_connect),
+      addedAt: entry.created_at,
+      updatedAt: entry.updated_at,
+      lastConnectedAt: normalizeString(entry.last_connected_at) || null,
+      labels: normalizeStringArray(entry.labels),
+      capabilities: normalizeStringArray(entry.capabilities),
+      transport: normalizeString(entry.transport) || "websocket",
+      secretRef: entry.secret_ref
+    };
+  }).sort((left, right) => left.alias.localeCompare(right.alias));
+}
+function nextRemoteEndpointRecord(input) {
+  const timestamp = new Date().toISOString();
+  const secretRef = input.existing?.secret_ref ?? randomUUID();
+  return {
+    record: {
+      id: input.endpointId ?? input.existing?.id ?? randomUUID(),
+      alias: input.alias,
+      host: input.host,
+      port: normalizePort(input.port),
+      transport: normalizeString(input.transport) || normalizeString(input.existing?.transport) || "websocket",
+      auto_connect: input.autoConnect ?? input.existing?.auto_connect ?? false,
+      labels: input.labels ?? normalizeStringArray(input.existing?.labels),
+      capabilities: input.capabilities ?? normalizeStringArray(input.existing?.capabilities),
+      secret_ref: secretRef,
+      created_at: input.existing?.created_at ?? timestamp,
+      updated_at: timestamp,
+      last_connected_at: input.existing?.last_connected_at ?? null
+    },
+    secretRef
+  };
+}
+function upsertAuthorityRemoteEndpoint(projectRoot, input) {
+  const endpointsToml = loadRemoteEndpointsToml(projectRoot);
+  const secretsToml = loadRemoteSecretsToml(projectRoot);
+  const existing = Object.values(endpointsToml.endpoints ?? {}).find((entry) => entry.alias === input.alias) ?? null;
+  const { record, secretRef } = nextRemoteEndpointRecord({
+    existing,
+    alias: input.alias,
+    host: input.host,
+    port: input.port,
+    token: input.token,
+    ...input.endpointId !== undefined ? { endpointId: input.endpointId } : {},
+    ...input.autoConnect !== undefined ? { autoConnect: input.autoConnect } : {},
+    ...input.transport !== undefined ? { transport: input.transport } : {},
+    ...input.labels !== undefined ? { labels: input.labels } : {},
+    ...input.capabilities !== undefined ? { capabilities: input.capabilities } : {}
+  });
+  endpointsToml.endpoints = {
+    ...endpointsToml.endpoints ?? {},
+    [record.id]: record
+  };
+  secretsToml.secrets = {
+    ...secretsToml.secrets ?? {},
+    [secretRef]: input.token
+  };
+  saveRemoteEndpointsToml(projectRoot, endpointsToml);
+  saveRemoteSecretsToml(projectRoot, secretsToml);
+  return listAuthorityRemoteEndpoints(projectRoot).find((entry) => entry.id === record.id);
+}
+function updateAuthorityRemoteEndpoint(projectRoot, input) {
+  const endpointsToml = loadRemoteEndpointsToml(projectRoot);
+  const secretsToml = loadRemoteSecretsToml(projectRoot);
+  const current = Object.values(endpointsToml.endpoints ?? {}).find((entry) => input.endpointId && entry.id === input.endpointId || input.alias && entry.alias === input.alias);
+  if (!current)
+    return null;
+  const record = {
+    ...current,
+    alias: normalizeString(input.alias) || current.alias,
+    host: normalizeString(input.host) || current.host,
+    port: input.port !== undefined ? normalizePort(input.port) : current.port,
+    auto_connect: input.autoConnect ?? current.auto_connect,
+    transport: normalizeString(input.transport) || current.transport,
+    labels: input.labels ?? normalizeStringArray(current.labels),
+    capabilities: input.capabilities ?? normalizeStringArray(current.capabilities),
+    updated_at: new Date().toISOString()
+  };
+  endpointsToml.endpoints = {
+    ...endpointsToml.endpoints ?? {},
+    [record.id]: record
+  };
+  if (input.token !== undefined) {
+    secretsToml.secrets = {
+      ...secretsToml.secrets ?? {},
+      [record.secret_ref]: input.token
+    };
+  }
+  saveRemoteEndpointsToml(projectRoot, endpointsToml);
+  saveRemoteSecretsToml(projectRoot, secretsToml);
+  return listAuthorityRemoteEndpoints(projectRoot).find((entry) => entry.id === record.id) ?? null;
+}
+function removeAuthorityRemoteEndpoint(projectRoot, endpointIdOrAlias) {
+  const endpointsToml = loadRemoteEndpointsToml(projectRoot);
+  const secretsToml = loadRemoteSecretsToml(projectRoot);
+  const entry = Object.values(endpointsToml.endpoints ?? {}).find((candidate) => candidate.id === endpointIdOrAlias || candidate.alias === endpointIdOrAlias);
+  if (!entry)
+    return false;
+  const nextEndpoints = { ...endpointsToml.endpoints ?? {} };
+  delete nextEndpoints[entry.id];
+  const nextSecrets = { ...secretsToml.secrets ?? {} };
+  delete nextSecrets[entry.secret_ref];
+  saveRemoteEndpointsToml(projectRoot, { version: endpointsToml.version ?? 1, endpoints: nextEndpoints });
+  saveRemoteSecretsToml(projectRoot, { version: secretsToml.version ?? 1, secrets: nextSecrets });
+  return true;
+}
+function markAuthorityRemoteEndpointConnected(projectRoot, endpointId, connectedAt = new Date().toISOString()) {
+  const endpointsToml = loadRemoteEndpointsToml(projectRoot);
+  const entry = endpointsToml.endpoints?.[endpointId];
+  if (!entry)
+    return;
+  endpointsToml.endpoints = {
+    ...endpointsToml.endpoints ?? {},
+    [endpointId]: {
+      ...entry,
+      last_connected_at: connectedAt,
+      updated_at: connectedAt
+    }
+  };
+  saveRemoteEndpointsToml(projectRoot, endpointsToml);
+}
+function importLegacyRemoteEndpoints(projectRoot, legacyPath = REMOTES_CONFIG_PATH) {
+  if (!existsSync2(legacyPath)) {
+    return { imported: 0, skipped: 0, sourcePath: legacyPath };
+  }
+  const parsed = readTomlFile(legacyPath, { version: 1, remotes: {} });
+  let imported = 0;
+  let skipped = 0;
+  for (const [alias, entry] of Object.entries(parsed.remotes ?? {})) {
+    const host = normalizeString(entry.host);
+    const token = normalizeString(entry.token);
+    if (!host || !token) {
+      skipped += 1;
+      continue;
+    }
+    upsertAuthorityRemoteEndpoint(projectRoot, {
+      alias,
+      host,
+      port: normalizePort(entry.port),
+      token
+    });
+    imported += 1;
+  }
+  return { imported, skipped, sourcePath: legacyPath };
+}
+function doctorAuthorityRemoteEndpoints(projectRoot) {
+  const paths = resolveAuthorityPaths(projectRoot);
+  const endpoints = loadRemoteEndpointsToml(projectRoot).endpoints ?? {};
+  const secrets = loadRemoteSecretsToml(projectRoot).secrets ?? {};
+  const missingSecrets = Object.values(endpoints).filter((entry) => !normalizeString(secrets[entry.secret_ref])).map((entry) => entry.alias);
+  const warnings = [];
+  if (!existsSync2(paths.remoteEndpointsPath)) {
+    warnings.push("Remote endpoint manifest is missing.");
+  }
+  if (!existsSync2(paths.remoteSecretsPath)) {
+    warnings.push("Remote secret store is missing.");
+  }
+  return {
+    manifestPath: paths.remoteEndpointsPath,
+    secretsPath: paths.remoteSecretsPath,
+    endpointCount: Object.keys(endpoints).length,
+    missingSecrets,
+    warnings
+  };
+}
+function listManagedRemoteEndpoints(configPath = REMOTES_CONFIG_PATH, projectRoot) {
+  if (projectRoot) {
+    return listAuthorityRemoteEndpoints(projectRoot).map((entry) => ({
+      id: entry.id,
+      alias: entry.alias,
+      host: entry.host,
+      port: entry.port,
+      token: entry.token,
+      addedAt: entry.addedAt,
+      lastConnected: entry.lastConnectedAt
+    }));
+  }
+  const config = loadRemotesConfig(configPath);
+  return Object.entries(config.remotes ?? {}).map(([alias, entry]) => ({
+    id: alias,
+    alias,
+    host: normalizeString(entry.host) || "",
+    port: Number.isFinite(entry.port) ? Number(entry.port) : DEFAULT_REMOTE_PORT,
+    token: normalizeString(entry.token) || "",
+    addedAt: normalizeString(entry.addedAt) || null,
+    lastConnected: normalizeString(entry.lastConnected) || null
+  })).sort((left, right) => left.alias.localeCompare(right.alias));
+}
+function upsertManagedRemoteEndpoint(input, configPath = REMOTES_CONFIG_PATH, projectRoot) {
+  if (projectRoot) {
+    const saved = upsertAuthorityRemoteEndpoint(projectRoot, {
+      ...input,
+      token: input.token ?? ""
+    });
+    return {
+      id: saved.id,
+      alias: saved.alias,
+      host: saved.host,
+      port: saved.port,
+      token: saved.token,
+      addedAt: saved.addedAt,
+      lastConnected: saved.lastConnectedAt
+    };
+  }
+  const config = loadRemotesConfig(configPath);
+  const existing = config.remotes?.[input.alias];
+  const nextEntry = {
+    host: input.host,
+    port: input.port,
+    ...input.token !== undefined ? { token: input.token } : {},
+    addedAt: normalizeString(existing?.addedAt) || new Date().toISOString(),
+    ...normalizeString(existing?.lastConnected) ? { lastConnected: normalizeString(existing?.lastConnected) } : {}
+  };
+  const nextConfig = {
+    version: config.version ?? 1,
+    remotes: {
+      ...config.remotes ?? {},
+      [input.alias]: nextEntry
+    }
+  };
+  saveRemotesConfig(nextConfig, configPath);
+  return {
+    id: input.alias,
+    alias: input.alias,
+    host: input.host,
+    port: input.port,
+    token: input.token ?? "",
+    addedAt: nextEntry.addedAt ?? null,
+    lastConnected: nextEntry.lastConnected ?? null
+  };
+}
+function removeManagedRemoteEndpoint(alias, configPath = REMOTES_CONFIG_PATH, projectRoot) {
+  if (projectRoot) {
+    return removeAuthorityRemoteEndpoint(projectRoot, alias);
+  }
+  const config = loadRemotesConfig(configPath);
+  if (!config.remotes?.[alias]) {
+    return false;
+  }
+  const nextRemotes = { ...config.remotes ?? {} };
+  delete nextRemotes[alias];
+  saveRemotesConfig({
+    version: config.version ?? 1,
+    remotes: nextRemotes
+  }, configPath);
+  return true;
+}
+function normalizeString(value) {
+  if (!value) {
+    return "";
+  }
+  return value.trim();
+}
+export {
+  upsertManagedRemoteEndpoint,
+  updateAuthorityRemoteEndpoint,
+  resolveSshTarget,
+  resolveSelectedRemote,
+  resolveRigOmpConfigOverlayPath,
+  resolveRelayUrl,
+  resolveRegistryBaseUrl,
+  resolveOwnerNamespaceKey,
+  resolveDispatchTransportPlacement,
+  removeManagedRemoteEndpoint,
+  registerBackboneDefaults,
+  normalizeString,
+  markAuthorityRemoteEndpointConnected,
+  loadRemotesConfig,
+  listManagedRemoteEndpoints,
+  listAuthorityRemoteEndpoints,
+  importLegacyRemoteEndpoints,
+  doctorAuthorityRemoteEndpoints,
+  RemoteCliError,
+  REMOTES_CONFIG_PATH,
+  DEFAULT_REMOTE_PORT
+};

package/dist/src/root-resolver.d.ts

@@ -0,0 +1,5 @@
+export declare function resolveProjectRoot(options?: {
+    cwd?: string;
+    projectRootEnv?: string;
+    fallbackFromDir?: string;
+}): string;

package/dist/src/root-resolver.js

@@ -0,0 +1,69 @@
+// @bun
+// packages/core/src/root-resolver.ts
+import { existsSync, readFileSync } from "fs";
+import { dirname, parse, resolve } from "path";
+
+// packages/core/src/layout.ts
+import {
+  RIG_ARTIFACTS_DIRNAME,
+  RIG_DEFINITION_DIRNAME,
+  RIG_STATE_DIRNAME
+} from "@rig/contracts";
+
+// packages/core/src/root-resolver.ts
+function hasProjectMarker(candidate) {
+  return existsSync(resolve(candidate, RIG_DEFINITION_DIRNAME)) || existsSync(resolve(candidate, RIG_STATE_DIRNAME));
+}
+function resolveProjectRoot(options) {
+  const cwd = options?.cwd || process.cwd();
+  const envRoot = options?.projectRootEnv || process.env.PROJECT_RIG_ROOT || "";
+  const fallbackFromDir = options?.fallbackFromDir || cwd;
+  if (envRoot && hasProjectMarker(envRoot)) {
+    return envRoot;
+  }
+  const walked = walkUpForRoot(cwd);
+  if (walked) {
+    return walked;
+  }
+  const configRoot = readConfiguredRoot();
+  if (configRoot && hasProjectMarker(configRoot)) {
+    return configRoot;
+  }
+  let fileDir = resolve(fallbackFromDir);
+  for (let i = 0;i < 5; i += 1) {
+    if (hasProjectMarker(fileDir)) {
+      return fileDir;
+    }
+    fileDir = dirname(fileDir);
+  }
+  return cwd;
+}
+function walkUpForRoot(start) {
+  let searchDir = resolve(start);
+  const root = parse(searchDir).root || "/";
+  while (searchDir !== root) {
+    if (hasProjectMarker(searchDir)) {
+      return searchDir;
+    }
+    searchDir = dirname(searchDir);
+  }
+  if (hasProjectMarker(root)) {
+    return root;
+  }
+  return "";
+}
+function readConfiguredRoot() {
+  const configPath = resolve(process.env.HOME || "~", ".config", "project-rig", "root");
+  if (!existsSync(configPath)) {
+    return "";
+  }
+  try {
+    const value = readFileSync(configPath, "utf-8").split(/\r?\n/)[0]?.trim() || "";
+    return value;
+  } catch {
+    return "";
+  }
+}
+export {
+  resolveProjectRoot
+};

package/dist/src/run-provisioning.d.ts

@@ -0,0 +1,58 @@
+export declare const RUN_WORKSPACE_ISOLATION_MODE: "worktree";
+export declare const RUN_WORKSPACE_PROVIDER: "pi";
+export declare const REMOTE_RIG_RUN_COMMAND: "rig-run";
+export declare const REMOTE_RESOLVED_RIG_RUN_COMMAND: "\"$__RIG_RUN_BIN\"";
+export type RunWorkspaceProvisioningOptions = {
+    readonly projectRoot: string;
+    readonly id: string;
+    readonly taskId: string;
+    readonly mode: typeof RUN_WORKSPACE_ISOLATION_MODE;
+    readonly provider: typeof RUN_WORKSPACE_PROVIDER;
+};
+export type RigRunLaunchOptions = {
+    readonly taskId: string;
+    readonly title?: string | null | undefined;
+    readonly model?: string | null | undefined;
+    readonly prompt?: string | null | undefined;
+    readonly forceSteerOnce?: boolean | undefined;
+};
+export type RemoteCheckoutPlan = {
+    readonly mode: "configured" | "managed";
+    readonly repoName: string;
+    readonly checkoutPath: string;
+    readonly checkoutPathKind: "literal" | "home-relative";
+    readonly originUrl: string | null;
+};
+export type RunGithubAuthMaterialization = {
+    readonly operatorAuthPath: string;
+    readonly operatorStateDir: string;
+    readonly remoteAuthPath: string;
+    readonly remoteStateDir: string;
+};
+export declare function buildRunWorkspaceProvisioningOptions(input: {
+    readonly projectRoot: string;
+    readonly runId: string;
+    readonly taskId: string;
+}): RunWorkspaceProvisioningOptions;
+export declare function buildRigRunLaunchArgs(input: RigRunLaunchOptions, runId: string, projectRoot: string): string[];
+export declare function resolveRemoteCheckoutPlan(input: {
+    readonly selectedCheckout?: string | null;
+    readonly projectSlug?: string | null;
+}): RemoteCheckoutPlan;
+export declare function resolveRunGithubAuthMaterialization(projectRoot: string, checkoutExpression?: string): RunGithubAuthMaterialization;
+export declare function readGithubAuthStateBase64(operatorAuthPath: string): string;
+export declare function buildRemoteRigRunResolutionShell(installUrl: string, command?: "rig-run"): string[];
+export declare function isCompiledBunBinary(importMetaUrl: string): boolean;
+export declare function resolveCompiledRigRunSiblingPath(execPath: string, platform?: NodeJS.Platform): string;
+export declare function ensureRigRunSiblingCurrent(rigBin: string, rigRun: string): void;
+export declare function resolveLocalDispatchRigRunBin(input: {
+    readonly importMetaUrl: string;
+    readonly sourceRigRunPath: string;
+    readonly execPath?: string;
+    readonly platform?: NodeJS.Platform;
+}): string;
+export declare function resolveInProcessRigRunBin(input: {
+    readonly importMetaUrl: string;
+    readonly sourceRigRunPath: string;
+    readonly execPath?: string;
+}): string;