@uniqbit/mate-core 0.15.3 → 0.15.4-canary.10

package/src/lib/orchestrator/companion-hub.ts

@@ -0,0 +1,380 @@
+import { spawnSync } from "node:child_process";
+import fs from "node:fs/promises";
+import path from "node:path";
+
+import { parse } from "yaml";
+
+import { FRAMEWORK_NAME } from "../../framework";
+import { ConfigStore, validateHubConfig } from "./config-store";
+import { GlobalConfigStore } from "./global-config-store";
+import type { FrameworkConfig, HubMember, HubMemberSource } from "./types";
+import {
+  installDeclaredPlugins,
+  type PluginInstallDeps,
+  type PluginInstallResult,
+} from "../../tools/setup/dynamic-plugins/install";
+import { hydrateDynamicPlugins } from "../../tools/setup/dynamic-plugins/hydrate";
+import { findRepoLocalRegistryFile } from "./repo-local-registry";
+
+export interface GitCommandResult {
+  status: number | null;
+  stdout: string;
+  stderr: string;
+}
+
+export type GitCommand = (cwd: string, args: string[]) => GitCommandResult;
+
+export interface HubSource {
+  kind: "git" | "local";
+  path?: string;
+  url?: string;
+  ref?: string;
+}
+
+export interface HubSyncResult {
+  id: string;
+  status: "updated" | "up-to-date" | "local-only" | "dirty" | "divergent" | "failed";
+  message: string;
+  materializedCommit?: string;
+}
+
+export interface HubPluginSyncDeps {
+  installDeps?: PluginInstallDeps;
+  hydrate?: (options: { companionPath: string }) => Promise<void>;
+}
+
+export function defaultGitCommand(cwd: string, args: string[]): GitCommandResult {
+  const result = spawnSync("git", ["-C", cwd, ...args], {
+    encoding: "utf8",
+    stdio: ["ignore", "pipe", "pipe"],
+  });
+  return {
+    status: result.status,
+    stdout: String(result.stdout ?? "").trim(),
+    stderr: String(result.stderr ?? "").trim(),
+  };
+}
+
+function isInsideDir(parent: string, candidate: string): boolean {
+  const relative = path.relative(path.resolve(parent), path.resolve(candidate));
+  return relative !== "" && !relative.startsWith(`..${path.sep}`) && !path.isAbsolute(relative);
+}
+
+export function normalizeHubMemberId(value: string): string {
+  const normalized = value
+    .replace(/\.git$/i, "")
+    .replace(/[^a-zA-Z0-9._-]+/g, "-")
+    .replace(/^-+|-+$/g, "");
+  if (!normalized) throw new Error(`Cannot derive a hub member id from: ${value}`);
+  return normalized;
+}
+
+export function validateHubMemberPath(hubPath: string, memberPath: string): string {
+  if (!memberPath || path.isAbsolute(memberPath)) {
+    throw new Error("Hub member path must be relative to the hub root.");
+  }
+  const resolved = path.resolve(hubPath, memberPath);
+  if (!isInsideDir(hubPath, resolved)) {
+    throw new Error(`Hub member path resolves outside the hub root: ${memberPath}`);
+  }
+  return resolved;
+}
+
+function frameworkConfigPath(root: string): string {
+  return path.join(root, `.${FRAMEWORK_NAME}`, "config", "framework.yaml");
+}
+
+function memberPathForId(id: string): string {
+  return path.join("companions", id);
+}
+
+async function assertHubRoot(
+  hubPath: string,
+): Promise<{ config: FrameworkConfig; store: ConfigStore }> {
+  const resolved = path.resolve(hubPath);
+  const configStore = new ConfigStore(frameworkConfigPath(resolved));
+  const config = await configStore.load();
+  if (config.type !== "hub") {
+    throw new Error(`Not a companion hub: ${resolved}`);
+  }
+  validateHubConfig(config);
+  return { config, store: configStore };
+}
+
+export async function initializeCompanionHub(
+  folder: string,
+  globalConfigStore = new GlobalConfigStore(),
+): Promise<string> {
+  const hubPath = path.resolve(folder);
+  const linkedRepo = await findRepoLocalRegistryFile(hubPath);
+  if (linkedRepo) {
+    throw new Error(
+      `Cannot initialize a hub inside linked working repository: ${linkedRepo.repoRoot}`,
+    );
+  }
+  await fs.mkdir(hubPath, { recursive: true });
+  const configStore = new ConfigStore(frameworkConfigPath(hubPath));
+  const existing = await fs.stat(configStore.configPath).catch(() => null);
+  if (existing) {
+    const current = await configStore.load();
+    if (current.type !== "hub") {
+      throw new Error(`Cannot initialize hub over an existing non-hub framework: ${hubPath}`);
+    }
+  } else {
+    const config: FrameworkConfig = {
+      type: "hub",
+      allowedAgents: [],
+      packageManagers: [],
+      capabilities: [],
+      hub: { companions: [] },
+    };
+    await configStore.save(config);
+  }
+  await globalConfigStore.register(hubPath);
+  return hubPath;
+}
+
+export function discoverGitSource(
+  sourcePath: string,
+  git: GitCommand = defaultGitCommand,
+): HubSource {
+  const root = git(sourcePath, ["rev-parse", "--show-toplevel"]);
+  if (root.status !== 0 || !root.stdout) return { kind: "local", path: path.resolve(sourcePath) };
+
+  const remote = git(sourcePath, ["config", "--get", "remote.origin.url"]);
+  if (remote.status !== 0 || !remote.stdout)
+    return { kind: "local", path: path.resolve(sourcePath) };
+
+  const branch = git(sourcePath, ["symbolic-ref", "--short", "HEAD"]);
+  return {
+    kind: "git",
+    path: path.resolve(sourcePath),
+    url: remote.stdout,
+    ref: branch.status === 0 && branch.stdout ? branch.stdout : undefined,
+  };
+}
+
+export function discoverHubSource(source: string, git: GitCommand = defaultGitCommand): HubSource {
+  const trimmed = source.trim();
+  if (/^(?:https?|ssh|git):\/\//i.test(trimmed) || trimmed.startsWith("git@")) {
+    return { kind: "git", url: trimmed };
+  }
+  return discoverGitSource(path.resolve(trimmed), git);
+}
+
+function sourceForManifest(source: HubSource, fallbackPath: string): HubMemberSource {
+  if (source.kind === "git") {
+    return { kind: "git", url: source.url, ref: source.ref };
+  }
+  return { kind: "local", path: source.path ?? fallbackPath };
+}
+
+function gitOutputOrThrow(result: GitCommandResult, operation: string): string {
+  if (result.status !== 0) {
+    throw new Error(
+      `${operation} failed: ${result.stderr || result.stdout || "unknown Git error"}`,
+    );
+  }
+  return result.stdout;
+}
+
+async function copyWithoutGit(sourcePath: string, destination: string): Promise<void> {
+  await fs.cp(sourcePath, destination, {
+    recursive: true,
+    filter: (candidate) => path.basename(candidate) !== ".git",
+  });
+}
+
+async function assertMaterializedCompanion(memberPath: string): Promise<void> {
+  const configPath = frameworkConfigPath(memberPath);
+  const raw = await fs.readFile(configPath, "utf8").catch(() => "");
+  const config = parse(raw) as { type?: unknown } | null;
+  if (config?.type !== "companion") {
+    throw new Error(`Materialized child must declare type: companion: ${memberPath}`);
+  }
+}
+
+async function currentCommit(memberPath: string, git: GitCommand): Promise<string> {
+  return gitOutputOrThrow(git(memberPath, ["rev-parse", "HEAD"]), `Reading ${memberPath} commit`);
+}
+
+export async function materializeHubMember(
+  hubPath: string,
+  source: HubSource,
+  options: { id?: string; memberPath?: string; git?: GitCommand } = {},
+): Promise<HubMember> {
+  const git = options.git ?? defaultGitCommand;
+  const sourceName = source.url ?? source.path ?? "companion";
+  const id = normalizeHubMemberId(options.id ?? path.basename(sourceName));
+  const relativePath = options.memberPath ?? memberPathForId(id);
+  const destination = validateHubMemberPath(hubPath, relativePath);
+  const target = await fs.stat(destination).catch(() => null);
+  if (target) throw new Error(`Hub member destination already exists: ${relativePath}`);
+
+  await fs.mkdir(path.dirname(destination), { recursive: true });
+  try {
+    if (source.kind === "git") {
+      const args = ["clone"];
+      if (source.ref) args.push("--branch", source.ref);
+      args.push(source.url!, destination);
+      gitOutputOrThrow(git(hubPath, args), `Cloning ${source.url}`);
+    } else {
+      await copyWithoutGit(source.path!, destination);
+    }
+
+    await assertMaterializedCompanion(destination);
+    const member: HubMember = {
+      id,
+      path: relativePath,
+      source: sourceForManifest(source, source.path ?? relativePath),
+    };
+    if (source.kind === "git") member.materializedCommit = await currentCommit(destination, git);
+    return member;
+  } catch (error) {
+    await fs.rm(destination, { recursive: true, force: true });
+    throw error;
+  }
+}
+
+export async function addHubMember(
+  hubPath: string,
+  source: HubSource,
+  options: { id?: string; memberPath?: string; git?: GitCommand } = {},
+): Promise<HubMember> {
+  const { config, store } = await assertHubRoot(hubPath);
+  const member = await materializeHubMember(hubPath, source, options);
+  if (config.hub!.companions.some((candidate) => candidate.id === member.id)) {
+    await fs.rm(path.resolve(hubPath, member.path), { recursive: true, force: true });
+    throw new Error(`Hub member id already exists: ${member.id}`);
+  }
+  config.hub!.companions.push(member);
+  await store.save(config);
+  return member;
+}
+
+function syncTarget(memberPath: string, git: GitCommand): string | null {
+  const upstream = git(memberPath, [
+    "rev-parse",
+    "--abbrev-ref",
+    "--symbolic-full-name",
+    "@{upstream}",
+  ]);
+  if (upstream.status !== 0 || !upstream.stdout) return null;
+  return upstream.stdout;
+}
+
+export async function syncHubMember(
+  hubPath: string,
+  member: HubMember,
+  git: GitCommand = defaultGitCommand,
+): Promise<HubSyncResult> {
+  const memberPath = path.resolve(hubPath, member.path);
+  if (member.source.kind === "local") {
+    return { id: member.id, status: "local-only", message: "local-only child has no Git source" };
+  }
+
+  const dirty = git(memberPath, ["status", "--porcelain=v1", "--untracked-files=all"]);
+  if (dirty.status !== 0) {
+    return {
+      id: member.id,
+      status: "failed",
+      message: dirty.stderr || "unable to inspect Git state",
+    };
+  }
+  if (dirty.stdout) {
+    return { id: member.id, status: "dirty", message: "local changes must be resolved first" };
+  }
+
+  const fetch = git(memberPath, ["fetch", "origin"]);
+  if (fetch.status !== 0) {
+    return { id: member.id, status: "failed", message: fetch.stderr || "fetch failed" };
+  }
+  const target = syncTarget(memberPath, git);
+  if (!target) {
+    return { id: member.id, status: "failed", message: "no tracked upstream branch" };
+  }
+  const counts = git(memberPath, ["rev-list", "--left-right", "--count", `HEAD...${target}`]);
+  if (counts.status !== 0) {
+    return {
+      id: member.id,
+      status: "failed",
+      message: counts.stderr || "unable to compare branches",
+    };
+  }
+  const [ahead, behind] = counts.stdout.split(/\s+/).map(Number);
+  if (ahead > 0 && behind > 0) {
+    return {
+      id: member.id,
+      status: "divergent",
+      message: "local and remote branches have diverged",
+    };
+  }
+  if (behind === 0) {
+    const commit = await currentCommit(memberPath, git);
+    return {
+      id: member.id,
+      status: "up-to-date",
+      message: "already up to date",
+      materializedCommit: commit,
+    };
+  }
+
+  const readTree = git(memberPath, ["read-tree", "-u", "-m", target]);
+  if (readTree.status !== 0) {
+    return {
+      id: member.id,
+      status: "failed",
+      message: readTree.stderr || "fast-forward worktree update failed",
+    };
+  }
+  const branch = git(memberPath, ["symbolic-ref", "--quiet", "--short", "HEAD"]);
+  if (branch.status !== 0 || !branch.stdout) {
+    return { id: member.id, status: "failed", message: "cannot advance a detached HEAD" };
+  }
+  const updateRef = git(memberPath, ["update-ref", `refs/heads/${branch.stdout}`, target, "HEAD"]);
+  if (updateRef.status !== 0) {
+    return {
+      id: member.id,
+      status: "failed",
+      message: updateRef.stderr || "fast-forward ref update failed",
+    };
+  }
+  const commit = await currentCommit(memberPath, git);
+  return {
+    id: member.id,
+    status: "updated",
+    message: `fast-forwarded to ${commit}`,
+    materializedCommit: commit,
+  };
+}
+
+export async function syncHub(
+  hubPath: string,
+  git: GitCommand = defaultGitCommand,
+): Promise<HubSyncResult[]> {
+  const { config, store } = await assertHubRoot(hubPath);
+  const results: HubSyncResult[] = [];
+  for (const member of config.hub!.companions) {
+    const result = await syncHubMember(hubPath, member, git);
+    results.push(result);
+    if (result.materializedCommit && result.status === "updated") {
+      member.materializedCommit = result.materializedCommit;
+    }
+  }
+  if (results.some((result) => result.status === "updated")) await store.save(config);
+  return results;
+}
+
+export async function updateHubPlugins(
+  hubPath: string,
+  deps: HubPluginSyncDeps = {},
+): Promise<PluginInstallResult[]> {
+  const { config } = await assertHubRoot(hubPath);
+  const declarations = config.plugins ?? [];
+  if (declarations.length === 0) return [];
+
+  const resolvedHubPath = path.resolve(hubPath);
+  const results = await installDeclaredPlugins(resolvedHubPath, declarations, deps.installDeps);
+  await (deps.hydrate ?? hydrateDynamicPlugins)({ companionPath: resolvedHubPath });
+  return results;
+}

package/src/lib/orchestrator/companion-store.ts

@@ -3,13 +3,7 @@ import path from "node:path";
 
 import { ConfigStore } from "./config-store";
 import { writeRepoLocalRegistryEntry } from "./repo-local-registry";
-import {
-  type CompanionSource,
-  ConfigError,
-  type FrameworkConfig,
-  type LinkedRepository,
-  type PolicySettings,
-} from "./types";
+import { type CompanionSource, ConfigError, type LinkedRepository } from "./types";
 import { WorkingRepoStore } from "./working-repo-store";
 
 export class CompanionStore {
@@ -68,32 +62,4 @@ export class CompanionStore {
     const working = await this.workingRepoStore.load();
     return working.repos;
   }
-
-  async resolvePolicy(repositoryId: string): Promise<PolicySettings> {
-    const [config, working] = await Promise.all([
-      this.configStore.load(),
-      this.workingRepoStore.load(),
-    ]);
-    return resolvePolicyFromConfig(config, working.repos, repositoryId);
-  }
-}
-
-export function resolvePolicyFromConfig(
-  config: FrameworkConfig,
-  repos: LinkedRepository[],
-  repositoryId: string,
-): PolicySettings {
-  const repository = repos.find((r) => r.id === repositoryId);
-  if (!repository) {
-    throw new ConfigError(`Unknown linked repository: ${repositoryId}`);
-  }
-
-  const profile = config.profiles[repository.profile];
-  if (!profile) {
-    throw new ConfigError(`Unknown policy profile: ${repository.profile}`);
-  }
-
-  return {
-    allowedAgents: repository.overrides?.allowedAgents ?? profile.allowedAgents,
-  };
 }

package/src/lib/orchestrator/config-store.ts

@@ -7,6 +7,8 @@ import { ConfigError, type FrameworkConfig } from "./types";
 
 export const RTK_CAPABILITY_SPLIT_MIGRATION = "rtk-capability-split-v1";
 
+const HUB_MEMBER_SOURCE_KINDS = ["git", "local"] as const;
+
 function defaultConfigPath(): string {
   return `.${FRAMEWORK_NAME}/config/framework.yaml`;
 }
@@ -15,22 +17,37 @@ export function defaultConfig(): FrameworkConfig {
   const defaults = getDefaultSetupSelections();
   return {
     type: "companion",
-    profiles: {
-      default: {
-        name: "default",
-        allowedAgents: defaults.allowedAgents,
-      },
-    },
+    allowedAgents: defaults.allowedAgents,
     packageManagers: defaults.packageManagers,
     capabilities: defaults.capabilities,
   };
 }
 
+interface LegacyProfilesShape {
+  profiles?: Record<string, { name?: string; allowedAgents?: string[] }>;
+}
+
+/**
+ * Silently collapses the legacy `profiles` map into the flat `allowedAgents`
+ * list (`profiles.default.allowedAgents` wins; other profiles are dropped).
+ * The new shape persists on the next save.
+ */
+export function migrateProfilesToAllowedAgents(config: FrameworkConfig): FrameworkConfig {
+  const legacy = config as FrameworkConfig & LegacyProfilesShape;
+  if (!legacy.profiles) return config;
+  const { profiles, ...rest } = legacy;
+  return {
+    ...rest,
+    allowedAgents: rest.allowedAgents ?? profiles.default?.allowedAgents ?? [],
+  };
+}
+
 export function mergeWithDefaults(existing: FrameworkConfig): FrameworkConfig {
   const defaults = defaultConfig();
   return {
     ...existing,
     type: existing.type ?? defaults.type,
+    allowedAgents: existing.allowedAgents ?? [],
     packageManagers: existing.packageManagers ?? defaults.packageManagers,
     // Only backfill capabilities for legacy configs that predate the field
     // entirely. Once a capabilities array has been persisted, it reflects the
@@ -54,6 +71,75 @@ export function migrateRtkCapabilitySplit(config: FrameworkConfig): FrameworkCon
   };
 }
 
+/** Validates the shape of a hub manifest before it is used. */
+export function validateHubConfig(config: FrameworkConfig): void {
+  if (config.type !== "hub") {
+    if (config.hub !== undefined) {
+      throw new ConfigError('Only a framework with type "hub" may define hub.companions.');
+    }
+    return;
+  }
+
+  const members = config.hub?.companions;
+  if (!Array.isArray(members)) {
+    throw new ConfigError('A "hub" framework requires a hub.companions array.');
+  }
+
+  const ids = new Set<string>();
+  for (const member of members) {
+    if (!member || typeof member !== "object") {
+      throw new ConfigError("Each hub member must be an object.");
+    }
+
+    if (typeof member.id !== "string" || member.id.trim() === "") {
+      throw new ConfigError("Each hub member requires a non-empty id.");
+    }
+    if (ids.has(member.id)) {
+      throw new ConfigError(`Hub member id is duplicated: ${member.id}`);
+    }
+    ids.add(member.id);
+
+    if (
+      typeof member.path !== "string" ||
+      member.path.trim() === "" ||
+      path.isAbsolute(member.path) ||
+      path.normalize(member.path) === "." ||
+      path.normalize(member.path) === ".." ||
+      path.normalize(member.path).startsWith(`..${path.sep}`)
+    ) {
+      throw new ConfigError(`Hub member "${member.id}" path must be a relative child path.`);
+    }
+
+    const source = member.source;
+    if (!source || typeof source !== "object") {
+      throw new ConfigError(`Hub member "${member.id}" requires source provenance.`);
+    }
+    if (!HUB_MEMBER_SOURCE_KINDS.includes(source.kind)) {
+      throw new ConfigError(
+        `Hub member "${member.id}" source kind must be one of: ${HUB_MEMBER_SOURCE_KINDS.join(", ")}.`,
+      );
+    }
+    if (source.kind === "git" && (typeof source.url !== "string" || source.url.trim() === "")) {
+      throw new ConfigError(`Git-backed hub member "${member.id}" requires a source URL.`);
+    }
+    if (source.ref !== undefined && (typeof source.ref !== "string" || source.ref.trim() === "")) {
+      throw new ConfigError(`Hub member "${member.id}" source ref must be a non-empty string.`);
+    }
+    if (
+      source.kind === "git" &&
+      (typeof member.materializedCommit !== "string" || member.materializedCommit.trim() === "")
+    ) {
+      throw new ConfigError(`Git-backed hub member "${member.id}" requires materializedCommit.`);
+    }
+    if (
+      member.materializedCommit !== undefined &&
+      (typeof member.materializedCommit !== "string" || member.materializedCommit.trim() === "")
+    ) {
+      throw new ConfigError(`Hub member "${member.id}" materializedCommit must be non-empty.`);
+    }
+  }
+}
+
 export const PLUGIN_DECLARATION_POLICIES = ["default", "optional"] as const;
 
 /**
@@ -77,7 +163,8 @@ export class ConfigStore extends YamlFileStore<FrameworkConfig> {
   }
 
   override async load(): Promise<FrameworkConfig> {
-    const merged = mergeWithDefaults(await super.load());
+    const merged = mergeWithDefaults(migrateProfilesToAllowedAgents(await super.load()));
+    validateHubConfig(merged);
     validatePluginDeclarations(merged);
     const needsMigration = !(merged.migrations ?? []).includes(RTK_CAPABILITY_SPLIT_MIGRATION);
     const config = migrateRtkCapabilitySplit(merged);

package/src/lib/orchestrator/editor.ts

@@ -141,7 +141,7 @@ export function detectEditorWorkspaceState(
 }
 
 export async function injectEditorFolder(
-  companionPath: string | string[],
+  companionPath: string,
   repoPath: string,
   cli = "code",
   spawnProcess: SpawnLike = spawn,
@@ -163,9 +163,7 @@ export async function injectEditorFolder(
 
   const { cli: resolvedCli, binary } = resolved;
 
-  const companionPaths = (Array.isArray(companionPath) ? companionPath : [companionPath]).map(
-    (candidate) => path.resolve(candidate),
-  );
+  const workspaceFolders = [path.resolve(repoPath), path.resolve(companionPath)];
 
   const workspacePath = editorWorkspacePath(repoPath);
   await fs.mkdir(path.dirname(workspacePath), { recursive: true });
@@ -173,10 +171,7 @@ export async function injectEditorFolder(
     workspacePath,
     `${JSON.stringify(
       {
-        folders: [
-          { path: path.resolve(repoPath) },
-          ...companionPaths.map((candidate) => ({ path: candidate })),
-        ],
+        folders: workspaceFolders.map((candidate) => ({ path: candidate })),
       },
       null,
       2,
@@ -186,7 +181,7 @@ export async function injectEditorFolder(
 
   if (detectWorkspace(workspacePath, resolvedCli) === "open") return true;
 
-  const child = spawnProcess(binary, ["--add", path.resolve(repoPath), ...companionPaths], {
+  const child = spawnProcess(binary, ["--add", ...workspaceFolders], {
     stdio: "ignore",
     detached: true,
   });
@@ -197,14 +192,3 @@ export async function injectEditorFolder(
 
   return true;
 }
-
-export function openEditorWorkspace(paths: string[], cli: string): boolean {
-  const binary = resolveEditorBinary(cli);
-  if (!binary) {
-    writeMissingEditorCliGuidance(cli);
-    return false;
-  }
-
-  execFileSync(binary, paths, { stdio: "ignore" });
-  return true;
-}