@uniqbit/mate-core 0.18.4 → 0.18.5

package/src/tools/setup/audience-isolation.fixture.ts

@@ -1,325 +0,0 @@
-// oxlint-disable no-await-in-loop
-import type { Dirent } from "node:fs";
-import fs from "node:fs/promises";
-import os from "node:os";
-import path from "node:path";
-
-import type { FrameworkConfig } from "../../lib/orchestrator/types";
-import { pluginPackageRoot } from "./dynamic-plugins/paths";
-import type {
-  CapabilityPlugin,
-  PluginRegistration,
-  ProviderPlugin,
-  RuntimeContributions,
-} from "./plugin";
-
-/**
- * Audience isolation harness: one companion whose base plugin and audience
- * `ba` and `qa` plugins each declare every contribution kind, every value
- * carrying its owner's marker. A test runs a pass, then asserts which markers
- * a surface holds — a marker found where it must not be is a leak.
- */
-
-export type FixtureOwner = "base" | "ba" | "qa";
-
-export const AUDIENCE_MARKERS: Record<FixtureOwner, string> = {
-  base: "BASEMARK7",
-  ba: "BAMARK7",
-  qa: "QAMARK7",
-};
-
-export const FIXTURE_AUDIENCES = ["ba", "qa"] as const;
-
-export function fixturePluginId(owner: FixtureOwner): string {
-  return `${owner}-plugin`;
-}
-
-export function fixturePackage(owner: FixtureOwner): string {
-  return `@fixture/${owner}`;
-}
-
-export interface FixtureCapabilityOptions {
-  apply?: () => Promise<void>;
-  teardown?: () => Promise<void>;
-  forProvider?: CapabilityPlugin["forProvider"];
-  pluginReference?: string;
-}
-
-function contributionsFor(
-  owner: FixtureOwner,
-  skillSourceDir: string,
-  runtime: "claude" | "opencode",
-  options: FixtureCapabilityOptions,
-): RuntimeContributions {
-  const marker = AUDIENCE_MARKERS[owner];
-  const contributions: RuntimeContributions = {
-    mcpServers: [{ name: `${owner}-mcp`, command: `${marker}-server`, args: ["serve"] }],
-    guidanceSections: [{ content: `${marker} guidance for ${owner}.` }],
-    skillTrees: [{ name: `${owner}-skill`, sourceDir: skillSourceDir }],
-    agentDefinitions: [
-      {
-        name: `${owner}-agent`,
-        content: `---\nname: ${owner}-agent\ndescription: ${owner} agent\n---\n${marker} agent prompt.\n`,
-      },
-    ],
-    permissionEntries: [`Bash(${marker}:*)`],
-  };
-  if (runtime === "claude") {
-    contributions.hookGroups = [
-      {
-        event: "PreToolUse",
-        marker: `${marker}-hook.sh`,
-        group: { matcher: "Bash", hooks: [{ type: "command", command: `${marker}-hook.sh` }] },
-      },
-    ];
-  }
-  if (runtime === "opencode" && options.pluginReference) {
-    const reference = options.pluginReference;
-    contributions.pluginReferences = [
-      { reference, isManagedReference: (entry) => entry === reference },
-    ];
-  }
-  return contributions;
-}
-
-/** A capability declaring every contribution kind, each value carrying the owner's marker. */
-export function markedCapability(
-  owner: FixtureOwner,
-  skillSourceDir: string,
-  options: FixtureCapabilityOptions = {},
-): CapabilityPlugin {
-  return {
-    id: fixturePluginId(owner),
-    kind: "capability",
-    label: owner,
-    description: `${owner} fixture capability`,
-    defaultSelected: true,
-    isEnabled: () => true,
-    apply: options.apply ?? (async () => {}),
-    teardown: options.teardown ?? (async () => {}),
-    ...(options.forProvider ? { forProvider: options.forProvider } : {}),
-    getRuntimeContributions() {
-      return {
-        claude: contributionsFor(owner, skillSourceDir, "claude", options),
-        opencode: contributionsFor(owner, skillSourceDir, "opencode", options),
-      };
-    },
-  };
-}
-
-export function fixtureProvider(id: "claude" | "opencode"): ProviderPlugin {
-  return {
-    id,
-    kind: "provider",
-    label: id,
-    description: id,
-    defaultSelected: true,
-    isEnabled: () => true,
-    async apply() {},
-    async teardown() {},
-  };
-}
-
-export interface AudienceFixture {
-  root: string;
-  companionPath: string;
-  repoPath: string;
-  config: FrameworkConfig;
-  skillSources: Record<FixtureOwner, string>;
-  /** Providers, the base plugin, and both audiences' plugins, tagged with their source. */
-  registrations(
-    options?: Partial<Record<FixtureOwner, FixtureCapabilityOptions>>,
-  ): PluginRegistration[];
-  cleanup(): Promise<void>;
-}
-
-const FRAMEWORK_YAML = [
-  "type: companion",
-  "allowedAgents:",
-  "  - claude",
-  "  - opencode",
-  "plugins:",
-  '  - package: "@fixture/base"',
-  '    version: "1.0.0"',
-  "audiences:",
-  "  ba:",
-  "    plugins:",
-  '      - package: "@fixture/ba"',
-  '        version: "1.0.0"',
-  "  qa:",
-  "    plugins:",
-  '      - package: "@fixture/qa"',
-  '        version: "1.0.0"',
-  "",
-].join("\n");
-
-export async function makeAudienceFixture(): Promise<AudienceFixture> {
-  const root = await fs.realpath(await fs.mkdtemp(path.join(os.tmpdir(), "audience-isolation-")));
-  const companionPath = path.join(root, "companion");
-  const repoPath = path.join(root, "repo");
-  await fs.mkdir(path.join(companionPath, ".mate", "config"), { recursive: true });
-  await fs.mkdir(repoPath, { recursive: true });
-  await fs.writeFile(
-    path.join(companionPath, ".mate", "config", "framework.yaml"),
-    FRAMEWORK_YAML,
-    "utf8",
-  );
-
-  const skillSources = {} as Record<FixtureOwner, string>;
-  for (const owner of ["base", "ba", "qa"] as const) {
-    const dir = path.join(root, "skill-sources", `${owner}-skill`);
-    await fs.mkdir(dir, { recursive: true });
-    await fs.writeFile(
-      path.join(dir, "SKILL.md"),
-      `---\nname: ${owner}-skill\ndescription: ${owner} skill\n---\n${AUDIENCE_MARKERS[owner]} skill body.\n`,
-      "utf8",
-    );
-    skillSources[owner] = dir;
-  }
-
-  const config: FrameworkConfig = {
-    type: "companion",
-    allowedAgents: ["claude", "opencode"],
-    capabilities: [],
-    plugins: [{ package: "@fixture/base", version: "1.0.0" }],
-    audiences: {
-      ba: { plugins: [{ package: "@fixture/ba", version: "1.0.0" }] },
-      qa: { plugins: [{ package: "@fixture/qa", version: "1.0.0" }] },
-    },
-  } as FrameworkConfig;
-
-  return {
-    root,
-    companionPath,
-    repoPath,
-    config,
-    skillSources,
-    registrations(options = {}) {
-      return [
-        { plugin: fixtureProvider("claude"), policy: "required" },
-        { plugin: fixtureProvider("opencode"), policy: "required" },
-        {
-          plugin: markedCapability("base", skillSources.base, options.base),
-          policy: "required",
-          audience: null,
-          packageName: fixturePackage("base"),
-        },
-        {
-          plugin: markedCapability("ba", skillSources.ba, options.ba),
-          policy: "optional",
-          audience: "ba",
-          packageName: fixturePackage("ba"),
-        },
-        {
-          plugin: markedCapability("qa", skillSources.qa, options.qa),
-          policy: "optional",
-          audience: "qa",
-          packageName: fixturePackage("qa"),
-        },
-      ];
-    },
-    cleanup: () => fs.rm(root, { recursive: true, force: true }),
-  };
-}
-
-/** Every regular file under `root` (symlinks followed), as relative path → text. Missing root: none. */
-export async function readTree(root: string): Promise<Map<string, string>> {
-  const files = new Map<string, string>();
-  async function walk(dir: string): Promise<void> {
-    let entries: Dirent[];
-    try {
-      entries = await fs.readdir(dir, { withFileTypes: true });
-    } catch {
-      return;
-    }
-    for (const entry of entries) {
-      const full = path.join(dir, entry.name);
-      const stat = await fs.stat(full).catch(() => null);
-      if (!stat) continue;
-      if (stat.isDirectory()) await walk(full);
-      else if (stat.isFile()) files.set(path.relative(root, full), await fs.readFile(full, "utf8"));
-    }
-  }
-  await walk(root);
-  return files;
-}
-
-/** `<where>: <marker>` for every marker of `owners` found in `text`. */
-export function markerHits(where: string, text: string, owners: readonly FixtureOwner[]): string[] {
-  return owners
-    .filter((owner) => text.includes(AUDIENCE_MARKERS[owner]) || ownerIdentityIn(text, owner))
-    .map((owner) => `${where}: ${owner}`);
-}
-
-/** Identities without the marker (MCP, skill, agent names) still count as the owner's. */
-function ownerIdentityIn(text: string, owner: FixtureOwner): boolean {
-  return [`${owner}-mcp`, `${owner}-skill`, `${owner}-agent`, `${owner}-plugin`].some((identity) =>
-    text.includes(identity),
-  );
-}
-
-/** The installed plugin packages: what a plugin is, not what a session loads. */
-const PLUGIN_WORKSPACE = `${path.join(".mate", "plugins")}${path.sep}`;
-
-/** Marker hits of `owners` in every file (path and content) under `root`, the plugin workspace aside. */
-export async function markerHitsInTree(
-  root: string,
-  owners: readonly FixtureOwner[],
-  skip: readonly string[] = [],
-): Promise<string[]> {
-  const hits: string[] = [];
-  for (const [relative, text] of await readTree(root)) {
-    if (relative.startsWith(PLUGIN_WORKSPACE)) continue;
-    if (skip.some((prefix) => relative.startsWith(prefix))) continue;
-    hits.push(...markerHits(relative, `${relative}\n${text}`, owners));
-  }
-  return hits;
-}
-
-/** Marker hits of `owners` in any JSON-serializable value: rendered documents, launch arguments. */
-export function markerHitsInValue(
-  where: string,
-  value: unknown,
-  owners: readonly FixtureOwner[],
-): string[] {
-  return markerHits(where, JSON.stringify(value), owners);
-}
-
-/**
- * Installs `owner`'s fixture plugin into the companion's plugin workspace, so
- * a pass can load it from its declaration alone. Declares exactly what
- * `markedCapability` declares, hook groups and all.
- */
-export async function installFixturePackage(
-  fixture: AudienceFixture,
-  owner: FixtureOwner,
-): Promise<void> {
-  const name = fixturePackage(owner);
-  const root = pluginPackageRoot(fixture.companionPath, name);
-  await fs.mkdir(root, { recursive: true });
-  await fs.writeFile(
-    path.join(root, "package.json"),
-    JSON.stringify({ name, version: "1.0.0", type: "module", main: "index.js" }),
-    "utf8",
-  );
-  const declared = markedCapability(owner, fixture.skillSources[owner]).getRuntimeContributions!(
-    {} as never,
-  );
-  const source = `
-const contributions = ${JSON.stringify(declared)};
-export default function createPlugin() {
-  return {
-    id: ${JSON.stringify(fixturePluginId(owner))},
-    kind: "capability",
-    label: ${JSON.stringify(owner)},
-    description: "installed fixture",
-    defaultSelected: true,
-    isEnabled: () => true,
-    apply: async () => {},
-    teardown: async () => {},
-    getRuntimeContributions: () => contributions,
-  };
-}
-`;
-  await fs.writeFile(path.join(root, "index.js"), source, "utf8");
-}

package/src/tools/setup/audience-layer.ts

@@ -1,207 +0,0 @@
-// oxlint-disable no-await-in-loop
-import crypto from "node:crypto";
-import fs from "node:fs/promises";
-import path from "node:path";
-
-import { getActiveDistribution } from "../../distribution";
-import type { FrameworkConfig } from "../../lib/orchestrator/types";
-import {
-  audienceLayerDir,
-  audienceLayersRoot,
-  CURRENT_LAYER_LINK,
-} from "../../runtime/audience-layer";
-import {
-  dynamicPluginsWorkspaceRoot,
-  pluginLocalOverridesPath,
-  pluginPackageRoot,
-} from "./dynamic-plugins/paths";
-import { collectAudienceInputs, RUNTIME_SURFACE_RECONCILERS } from "./engine";
-import type { PluginRegistration, SetupContext } from "./plugin";
-import { projectionTarget } from "./surface-target";
-
-/**
- * Writes the active audience's layer through each runtime's Runtime Surface,
- * under the pass's layer root only. Refuses any other target, and a pass that
- * names no audience.
- */
-export async function reconcileAudienceLayer(
-  ctx: SetupContext,
-  registrations: PluginRegistration[],
-): Promise<void> {
-  if (projectionTarget(ctx) !== "audience-layer") {
-    throw new Error("an audience layer is reconciled with the audience-layer target only");
-  }
-  for (const [runtimeId, inputs] of await collectAudienceInputs(
-    ctx,
-    registrations,
-    ctx.audience!,
-  )) {
-    const reconcile = RUNTIME_SURFACE_RECONCILERS[runtimeId];
-    if (!reconcile || inputs.length === 0) continue;
-    await reconcile(ctx, inputs);
-  }
-}
-
-/** Bumped when the layout a layer pass writes changes, so old layers are re-rendered. */
-const LAYER_FORMAT = 1;
-
-/** A render that never finished, or a superseded layer, is left this long for sessions still reading it. */
-const STALE_LAYER_MS = 24 * 60 * 60 * 1000;
-
-const FINGERPRINT_FILE = ".fingerprint";
-
-export interface AudienceLayerRequest {
-  companionPath: string;
-  config: FrameworkConfig;
-  audience: string;
-  /** The Agent Runtimes the layer is rendered for. */
-  activeProviders: string[];
-  /** The process's registrations; only the audience's own are rendered. */
-  registrations: PluginRegistration[];
-  homeDir?: string;
-}
-
-export interface RenderedAudienceLayer {
-  audience: string;
-  /** The complete layer a launch attaches; never changed once in place. */
-  root: string;
-  /** False when an unchanged layer was reused. */
-  rendered: boolean;
-}
-
-function isRecord(value: unknown): value is Record<string, unknown> {
-  return typeof value === "object" && value !== null && !Array.isArray(value);
-}
-
-/** The installed version of each package, from the committed lockfile, else the installed manifest. */
-async function lockedVersions(
-  companionPath: string,
-  packages: string[],
-): Promise<Record<string, string | null>> {
-  const lock = await fs
-    .readFile(path.join(dynamicPluginsWorkspaceRoot(companionPath), "package-lock.json"), "utf8")
-    .then((text) => JSON.parse(text) as unknown)
-    .catch(() => null);
-  const lockPackages = isRecord(lock) && isRecord(lock.packages) ? lock.packages : {};
-  const versions: Record<string, string | null> = {};
-  for (const name of packages.toSorted()) {
-    const locked = lockPackages[`node_modules/${name}`];
-    if (isRecord(locked) && typeof locked.version === "string") {
-      versions[name] = locked.version;
-      continue;
-    }
-    const manifest = await fs
-      .readFile(path.join(pluginPackageRoot(companionPath, name), "package.json"), "utf8")
-      .then((text) => JSON.parse(text) as unknown)
-      .catch(() => null);
-    versions[name] =
-      isRecord(manifest) && typeof manifest.version === "string" ? manifest.version : null;
-  }
-  return versions;
-}
-
-/**
- * What a layer depends on: the audience's declaration, the installed versions
- * of its packages, the local plugin overrides, the Mate version and the active
- * runtimes. Anything else changing leaves the layer as it is.
- */
-export async function audienceLayerFingerprint(request: AudienceLayerRequest): Promise<string> {
-  const entry = request.config.audiences?.[request.audience] ?? null;
-  const packages = (entry?.plugins ?? []).map((declaration) => declaration.package);
-  const overrides = await fs
-    .readFile(pluginLocalOverridesPath(request.companionPath), "utf8")
-    .catch(() => null);
-  const inputs = {
-    format: LAYER_FORMAT,
-    audience: request.audience,
-    entry,
-    versions: await lockedVersions(request.companionPath, packages),
-    overrides,
-    mate: getActiveDistribution().config.version,
-    runtimes: [...new Set(request.activeProviders)].toSorted(),
-  };
-  return crypto.createHash("sha256").update(JSON.stringify(inputs)).digest("hex").slice(0, 24);
-}
-
-async function exists(target: string): Promise<boolean> {
-  return fs
-    .access(target)
-    .then(() => true)
-    .catch(() => false);
-}
-
-/** Points `current` at `fingerprint` with one rename, so a reader never finds it missing. */
-async function pointCurrentAt(dir: string, fingerprint: string): Promise<void> {
-  const link = path.join(dir, CURRENT_LAYER_LINK);
-  if ((await fs.readlink(link).catch(() => null)) === fingerprint) return;
-  const staged = path.join(dir, `.${CURRENT_LAYER_LINK}-${crypto.randomUUID()}`);
-  await fs.symlink(fingerprint, staged);
-  await fs.rename(staged, link);
-}
-
-/** Superseded layers and abandoned renders, once no session can still be starting from them. */
-async function pruneStaleLayers(dir: string, keep: string): Promise<void> {
-  const now = Date.now();
-  for (const name of await fs.readdir(dir).catch(() => [])) {
-    /** Launch settings files live here too; each launch rewrites its own. */
-    if (name === keep || name === CURRENT_LAYER_LINK || name.startsWith("launch-")) continue;
-    const target = path.join(dir, name);
-    const stat = await fs.lstat(target).catch(() => null);
-    if (!stat || now - stat.mtimeMs < STALE_LAYER_MS) continue;
-    await fs.rm(target, { recursive: true, force: true });
-  }
-}
-
-/** Creates the layers root and every level below it for the current user only. */
-async function ensurePrivateDir(root: string, dir: string): Promise<void> {
-  await fs.mkdir(dir, { recursive: true, mode: 0o700 });
-  for (let level = dir; level.startsWith(root); level = path.dirname(level)) {
-    await fs.chmod(level, 0o700);
-    if (level === root) break;
-  }
-}
-
-/**
- * Renders the audience's layer, or reuses it when nothing it depends on
- * changed. A render is built in a private staging directory and renamed into a
- * directory named by its fingerprint, so a reader sees a complete layer or
- * none; concurrent renders of the same inputs agree on one result.
- */
-export async function renderAudienceLayer(
-  request: AudienceLayerRequest,
-): Promise<RenderedAudienceLayer> {
-  const dir = audienceLayerDir(request.companionPath, request.audience, request.homeDir);
-  const fingerprint = await audienceLayerFingerprint(request);
-  const root = path.join(dir, fingerprint);
-
-  await ensurePrivateDir(audienceLayersRoot(request.homeDir), dir);
-  if (await exists(path.join(root, FINGERPRINT_FILE))) {
-    await pointCurrentAt(dir, fingerprint);
-    return { audience: request.audience, root, rendered: false };
-  }
-
-  const staging = await fs.mkdtemp(path.join(dir, ".render-"));
-  try {
-    await reconcileAudienceLayer(
-      {
-        companionPath: request.companionPath,
-        config: request.config,
-        mode: "sync",
-        activeProviders: request.activeProviders,
-        target: "audience-layer",
-        audience: request.audience,
-        layerRoot: staging,
-      },
-      request.registrations,
-    );
-    await fs.writeFile(path.join(staging, FINGERPRINT_FILE), `${fingerprint}\n`, "utf8");
-    await fs.rename(staging, root);
-  } catch (error) {
-    await fs.rm(staging, { recursive: true, force: true });
-    /** Another launch renamed the same inputs into place first: its layer is this one. */
-    if (!(await exists(path.join(root, FINGERPRINT_FILE)))) throw error;
-  }
-  await pointCurrentAt(dir, fingerprint);
-  await pruneStaleLayers(dir, fingerprint);
-  return { audience: request.audience, root, rendered: true };
-}

package/src/tools/setup/audience-registrations.ts

@@ -1,52 +0,0 @@
-// oxlint-disable no-await-in-loop
-import { getActiveDistribution } from "../../distribution";
-import type { FrameworkConfig } from "../../lib/orchestrator/types";
-import { validateDeclaration } from "./dynamic-plugins/declarations";
-import { loadDynamicPlugin, type DynamicPluginLoadDeps } from "./dynamic-plugins/loader";
-import type { PluginRegistry, NormalizedRegistration } from "./registry";
-
-export interface LoadedAudience {
-  registrations: NormalizedRegistration[];
-  warnings: string[];
-}
-
-/**
- * The registrations of one named audience, independent of `MATE_AUDIENCE`: a
- * plugin this process already hydrated is reused, any other is loaded for its
- * declarations only — never activated, no lifecycle hook run. Used where the
- * audience comes from a checkout's wrap rather than the environment.
- */
-export async function loadAudienceRegistrations(
-  companionPath: string,
-  config: FrameworkConfig,
-  audience: string,
-  registry: PluginRegistry = getActiveDistribution().registry,
-  deps: DynamicPluginLoadDeps = {},
-): Promise<LoadedAudience> {
-  const loaded: LoadedAudience = { registrations: [], warnings: [] };
-  const hydrated = registry.getEntries();
-  for (const entry of config.audiences?.[audience]?.plugins ?? []) {
-    const { declaration, error } = validateDeclaration(entry);
-    if (!declaration) {
-      if (error) loaded.warnings.push(error);
-      continue;
-    }
-    const known = hydrated.find((candidate) => candidate.packageName === declaration.package);
-    if (known) {
-      loaded.registrations.push({ ...known, audience });
-      continue;
-    }
-    const result = await loadDynamicPlugin(companionPath, declaration, deps);
-    if (!result.ok) {
-      loaded.warnings.push(`audience "${audience}": ${result.warning}`);
-      continue;
-    }
-    loaded.registrations.push({
-      plugin: result.plugin,
-      policy: "required",
-      audience,
-      packageName: declaration.package,
-    });
-  }
-  return loaded;
-}