@uniqbit/mate-core 0.18.4 → 0.18.5

package/src/tools/setup/contribution-ledger.ts

@@ -1,207 +0,0 @@
-import fs from "node:fs/promises";
-import path from "node:path";
-
-import { FRAMEWORK_NAME } from "../../framework";
-import { writeAtomic } from "../../runtime/write-atomic";
-import { instructionBlockKey } from "./context-services";
-import type { CapabilityContributionInput, RuntimeContributions } from "./plugin";
-
-/**
- * Contribution Ledger: which plugin owns each contribution a persisted pass
- * applied to the companion, per Agent Runtime. Committed with the companion,
- * because it describes committed files: a clone that never loaded a plugin
- * must still be able to remove what another clone committed. It records
- * identities only (names, block keys, markers, entries), never a value, so it
- * carries no secret.
- */
-
-export const CONTRIBUTION_LEDGER_VERSION = 1;
-
-/** The identities one owner applied on one runtime. Absent kinds are none. */
-export interface LedgerIdentities {
-  mcpServers?: string[];
-  guidanceKeys?: string[];
-  skillTrees?: string[];
-  agentDefinitions?: string[];
-  hookMarkers?: string[];
-  permissionEntries?: string[];
-  pluginReferences?: string[];
-}
-
-export interface ContributionLedger {
-  version: number;
-  /** Runtime id → owning plugin id → identities. */
-  runtimes: Record<string, Record<string, LedgerIdentities>>;
-  /** Audience plugin packages the upgrade sweep could not load; retried by every pass. */
-  unswept?: string[];
-}
-
-export function contributionLedgerPath(companionPath: string): string {
-  return path.join(companionPath, `.${FRAMEWORK_NAME}`, "config", "contribution-ledger.json");
-}
-
-function isRecord(value: unknown): value is Record<string, unknown> {
-  return typeof value === "object" && value !== null && !Array.isArray(value);
-}
-
-function stringList(value: unknown): string[] {
-  return Array.isArray(value) ? value.filter((entry) => typeof entry === "string") : [];
-}
-
-const IDENTITY_KINDS = [
-  "agentDefinitions",
-  "guidanceKeys",
-  "hookMarkers",
-  "mcpServers",
-  "permissionEntries",
-  "pluginReferences",
-  "skillTrees",
-] as const satisfies readonly (keyof LedgerIdentities)[];
-
-function sortedUnique(values: Iterable<string>): string[] {
-  return [...new Set(values)].toSorted();
-}
-
-/** Sorted kinds and values, empty kinds dropped; `null` when nothing is left. */
-function normalizeIdentities(identities: LedgerIdentities): LedgerIdentities | null {
-  const normalized: LedgerIdentities = {};
-  for (const kind of IDENTITY_KINDS) {
-    const values = sortedUnique(identities[kind] ?? []);
-    if (values.length > 0) normalized[kind] = values;
-  }
-  return Object.keys(normalized).length > 0 ? normalized : null;
-}
-
-/** Sorted runtimes and owners; empty owners and runtimes dropped. */
-function normalizeLedger(ledger: ContributionLedger): ContributionLedger {
-  const runtimes: ContributionLedger["runtimes"] = {};
-  for (const runtimeId of Object.keys(ledger.runtimes).toSorted()) {
-    const owners: Record<string, LedgerIdentities> = {};
-    for (const owner of Object.keys(ledger.runtimes[runtimeId] ?? {}).toSorted()) {
-      const identities = normalizeIdentities(ledger.runtimes[runtimeId]![owner]!);
-      if (identities) owners[owner] = identities;
-    }
-    if (Object.keys(owners).length > 0) runtimes[runtimeId] = owners;
-  }
-  const unswept = sortedUnique(ledger.unswept ?? []);
-  return {
-    version: CONTRIBUTION_LEDGER_VERSION,
-    runtimes,
-    ...(unswept.length > 0 ? { unswept } : {}),
-  };
-}
-
-/** The companion's ledger; `null` when absent or unreadable, which a pass treats as never recorded. */
-export async function readContributionLedger(
-  companionPath: string,
-): Promise<ContributionLedger | null> {
-  let parsed: unknown;
-  try {
-    parsed = JSON.parse(await fs.readFile(contributionLedgerPath(companionPath), "utf8"));
-  } catch {
-    return null;
-  }
-  if (!isRecord(parsed) || !isRecord(parsed.runtimes)) return null;
-  const runtimes: ContributionLedger["runtimes"] = {};
-  for (const [runtimeId, owners] of Object.entries(parsed.runtimes)) {
-    if (!isRecord(owners)) continue;
-    runtimes[runtimeId] = {};
-    for (const [owner, identities] of Object.entries(owners)) {
-      if (!isRecord(identities)) continue;
-      const read: LedgerIdentities = {};
-      for (const kind of IDENTITY_KINDS) read[kind] = stringList(identities[kind]);
-      runtimes[runtimeId][owner] = read;
-    }
-  }
-  return normalizeLedger({
-    version: CONTRIBUTION_LEDGER_VERSION,
-    runtimes,
-    unswept: stringList(parsed.unswept),
-  });
-}
-
-/** Writes the ledger in its stable form; an unchanged ledger leaves the file untouched. */
-export async function writeContributionLedger(
-  companionPath: string,
-  ledger: ContributionLedger,
-): Promise<void> {
-  const target = contributionLedgerPath(companionPath);
-  const text = `${JSON.stringify(normalizeLedger(ledger), null, 2)}\n`;
-  const existing = await fs.readFile(target, "utf8").catch(() => null);
-  if (existing === text) return;
-  await fs.mkdir(path.dirname(target), { recursive: true });
-  await writeAtomic(target, text);
-}
-
-/** The identities a contribution set applies for `pluginId`. */
-export function identitiesOf(
-  pluginId: string,
-  contributions: RuntimeContributions,
-): LedgerIdentities {
-  return {
-    mcpServers: (contributions.mcpServers ?? []).map((server) => server.name),
-    guidanceKeys: (contributions.guidanceSections ?? []).map((section) =>
-      instructionBlockKey(pluginId, section.content),
-    ),
-    skillTrees: (contributions.skillTrees ?? []).map((tree) => tree.name),
-    agentDefinitions: (contributions.agentDefinitions ?? []).map((agent) => agent.name),
-    hookMarkers: (contributions.hookGroups ?? []).map((hook) => hook.marker),
-    permissionEntries: [...(contributions.permissionEntries ?? [])],
-    pluginReferences: (contributions.pluginReferences ?? []).map((entry) => entry.reference),
-  };
-}
-
-/** The ledger a pass leaves: what its enabled inputs applied, per runtime and owner. */
-export function ledgerFromInputs(
-  inputsByRuntime: ReadonlyMap<string, readonly CapabilityContributionInput[]>,
-  unswept: readonly string[] = [],
-): ContributionLedger {
-  const runtimes: ContributionLedger["runtimes"] = {};
-  for (const [runtimeId, inputs] of inputsByRuntime) {
-    const owners: Record<string, LedgerIdentities> = {};
-    for (const input of inputs) {
-      if (!input.enabled) continue;
-      const identities = identitiesOf(input.pluginId, input.contributions);
-      const merged = owners[input.pluginId] ?? {};
-      for (const kind of IDENTITY_KINDS) {
-        merged[kind] = [...(merged[kind] ?? []), ...(identities[kind] ?? [])];
-      }
-      owners[input.pluginId] = merged;
-    }
-    runtimes[runtimeId] = owners;
-  }
-  return normalizeLedger({ version: CONTRIBUTION_LEDGER_VERSION, runtimes, unswept: [...unswept] });
-}
-
-/**
- * A disabled input naming every recorded identity of `owner`, so each Runtime
- * Surface removes them through its existing disabled-input path. Removal keys
- * on identity only, so no value is needed: guidance is stripped by owner, a
- * hook group by its marker, a plugin reference by its exact entry.
- */
-export function ledgerTeardownInput(
-  owner: string,
-  identities: LedgerIdentities,
-): CapabilityContributionInput {
-  return {
-    pluginId: owner,
-    enabled: false,
-    capabilityEnabled: false,
-    contributions: {
-      mcpServers: (identities.mcpServers ?? []).map((name) => ({ name })),
-      guidanceSections: (identities.guidanceKeys ?? []).length > 0 ? [{ content: "" }] : [],
-      skillTrees: (identities.skillTrees ?? []).map((name) => ({ name, sourceDir: "" })),
-      agentDefinitions: (identities.agentDefinitions ?? []).map((name) => ({ name, content: "" })),
-      hookGroups: (identities.hookMarkers ?? []).map((marker) => ({
-        event: "",
-        marker,
-        group: {},
-      })),
-      permissionEntries: [...(identities.permissionEntries ?? [])],
-      pluginReferences: (identities.pluginReferences ?? []).map((reference) => ({
-        reference,
-        isManagedReference: (entry: unknown) => entry === reference,
-      })),
-    },
-  };
-}

package/src/tools/setup/isolation-diagnostics.ts

@@ -1,139 +0,0 @@
-// oxlint-disable no-await-in-loop
-import path from "node:path";
-
-import type { FrameworkConfig } from "../../lib/orchestrator/types";
-import {
-  readContributionLedger,
-  type ContributionLedger,
-  type LedgerIdentities,
-} from "./contribution-ledger";
-import type { CapabilityPlugin, SetupContext } from "./plugin";
-import type { PluginRegistry } from "./registry";
-import { managedGuidanceOwners } from "./upgrade-sweep";
-
-/**
- * What `mate doctor` reports about audience isolation: contributions on the
- * companion's persisted surfaces that no base plugin owns, audience plugins
- * the upgrade sweep could not load, and the active audience's plugins whose
- * imperative parts a launch layer cannot deliver.
- */
-
-export interface LeakedContribution {
-  /** Companion-relative file or directory. */
-  surface: string;
-  kind: string;
-  /** The entry's name; absent where the surface entry is the owner's block. */
-  identity?: string;
-  owner: string;
-}
-
-export interface UndeliveredAudiencePlugin {
-  pluginId: string;
-  /** `apply`, `teardown`, `forProvider` or `pluginReferences`. */
-  parts: string[];
-}
-
-export interface AudienceIsolationReport {
-  leaked: LeakedContribution[];
-  unswept: string[];
-  undelivered: UndeliveredAudiencePlugin[];
-}
-
-/** Ledger kinds by where each runtime keeps them; guidance is read from the files themselves. */
-const LEDGER_SURFACES: Record<string, Partial<Record<keyof LedgerIdentities, string>>> = {
-  claude: {
-    mcpServers: ".mcp.json",
-    skillTrees: path.join(".claude", "skills"),
-    agentDefinitions: path.join(".claude", "agents"),
-    hookMarkers: path.join(".claude", "settings.local.json"),
-    permissionEntries: path.join(".claude", "settings.local.json"),
-  },
-  opencode: {
-    mcpServers: path.join(".opencode", "opencode.json"),
-    pluginReferences: path.join(".opencode", "opencode.json"),
-    skillTrees: path.join(".agents", "skills"),
-    agentDefinitions: path.join(".opencode", "agents"),
-  },
-};
-
-function leakedLedgerContributions(
-  ledger: ContributionLedger | null,
-  baseIds: ReadonlySet<string>,
-): LeakedContribution[] {
-  const leaked: LeakedContribution[] = [];
-  for (const [runtimeId, owners] of Object.entries(ledger?.runtimes ?? {})) {
-    for (const [owner, identities] of Object.entries(owners)) {
-      if (baseIds.has(owner)) continue;
-      for (const [kind, surface] of Object.entries(LEDGER_SURFACES[runtimeId] ?? {})) {
-        for (const identity of identities[kind as keyof LedgerIdentities] ?? []) {
-          leaked.push({ surface: surface!, kind, identity, owner });
-        }
-      }
-    }
-  }
-  return leaked;
-}
-
-/**
- * Whether a lifecycle hook does anything. `apply` and `teardown` are required
- * members, so a declarative plugin carries empty ones; only a body counts.
- */
-function hasBody(hook: unknown): boolean {
-  if (typeof hook !== "function") return false;
-  const source = Function.prototype.toString.call(hook);
-  const open = source.indexOf("{");
-  const close = source.lastIndexOf("}");
-  if (open === -1 || close <= open) return true;
-  const body = source
-    .slice(open + 1, close)
-    .replace(/\/\*[\s\S]*?\*\/|\/\/[^\n]*/g, "")
-    .trim();
-  return body.length > 0;
-}
-
-async function undeliveredParts(plugin: CapabilityPlugin, ctx: SetupContext): Promise<string[]> {
-  const parts: string[] = [];
-  if (hasBody(plugin.apply)) parts.push("apply");
-  if (hasBody(plugin.teardown)) parts.push("teardown");
-  if (plugin.forProvider && Object.keys(plugin.forProvider).length > 0) parts.push("forProvider");
-  try {
-    const byRuntime = (await plugin.getRuntimeContributions?.(ctx)) ?? {};
-    if (Object.values(byRuntime).some((runtime) => (runtime?.pluginReferences ?? []).length > 0)) {
-      parts.push("pluginReferences");
-    }
-  } catch {
-    /** A plugin whose declarations fail is the plugin checks' finding, not this one. */
-  }
-  return parts;
-}
-
-export async function inspectAudienceIsolation(
-  companionPath: string,
-  config: FrameworkConfig,
-  registry: PluginRegistry,
-  activeAudience: string | null,
-): Promise<AudienceIsolationReport> {
-  const baseIds = new Set(registry.baseRegistrations().map((entry) => entry.plugin.id));
-  const leaked: LeakedContribution[] = [];
-
-  for (const [surface, owners] of await managedGuidanceOwners(companionPath)) {
-    for (const owner of owners) {
-      if (!baseIds.has(owner)) leaked.push({ surface, kind: "guidance", owner });
-    }
-  }
-
-  const ledger = await readContributionLedger(companionPath);
-  leaked.push(...leakedLedgerContributions(ledger, baseIds));
-
-  const undelivered: UndeliveredAudiencePlugin[] = [];
-  if (activeAudience) {
-    const ctx: SetupContext = { companionPath, config, mode: "sync", activeProviders: [] };
-    for (const { plugin } of registry.audienceRegistrations(activeAudience)) {
-      if (plugin.kind !== "capability") continue;
-      const parts = await undeliveredParts(plugin as CapabilityPlugin, ctx);
-      if (parts.length > 0) undelivered.push({ pluginId: plugin.id, parts });
-    }
-  }
-
-  return { leaked, unswept: ledger?.unswept ?? [], undelivered };
-}

package/src/tools/setup/upgrade-sweep.ts

@@ -1,153 +0,0 @@
-// oxlint-disable no-await-in-loop
-import fs from "node:fs/promises";
-import path from "node:path";
-
-import { FRAMEWORK_NAME } from "../../framework";
-import { removeManagedBlocksForPlugin } from "./context-services";
-import {
-  audiencePluginDeclarations,
-  declaredAudiences,
-  effectivePluginDeclarations,
-  readFrameworkRaw,
-} from "./dynamic-plugins/audiences";
-import { validateDeclaration } from "./dynamic-plugins/declarations";
-import { loadDynamicPlugin, type DynamicPluginLoadDeps } from "./dynamic-plugins/loader";
-import type { CapabilityContributionInput, CapabilityPlugin, Plugin, SetupContext } from "./plugin";
-import type { NormalizedRegistration } from "./registry";
-
-/**
- * Upgrade Sweep: removes what audience plugins leaked into a companion before
- * the contribution ledger existed. Runs once, when a persisted pass finds no
- * ledger, and again only for the packages it could not load then.
- */
-
-/** The companion files Mate's managed guidance blocks live in. */
-const GUIDANCE_FILES = ["CLAUDE.md", "AGENTS.md", path.join(".opencode", "AGENTS.md")];
-
-const MANAGED_BLOCK_START = new RegExp(
-  `<!-- ${FRAMEWORK_NAME}:managed:([^\\n]+):[0-9a-f]+ start -->`,
-  "g",
-);
-
-/** Plugin ids owning a managed guidance block in `text`. */
-export function managedBlockOwners(text: string): string[] {
-  return [...new Set([...text.matchAll(MANAGED_BLOCK_START)].map((match) => match[1]!))];
-}
-
-/** `relative path → owners` for every managed guidance block under `root`. */
-export async function managedGuidanceOwners(root: string): Promise<Map<string, string[]>> {
-  const owners = new Map<string, string[]>();
-  for (const file of GUIDANCE_FILES) {
-    const text = await fs.readFile(path.join(root, file), "utf8").catch(() => null);
-    if (text === null) continue;
-    const found = managedBlockOwners(text);
-    if (found.length > 0) owners.set(file, found);
-  }
-  return owners;
-}
-
-/**
- * Guidance blocks name their owner, so this needs no plugin loaded: every
- * block whose owner is not a base registration goes.
- */
-export async function removeForeignGuidanceBlocks(
-  root: string,
-  baseIds: ReadonlySet<string>,
-): Promise<void> {
-  for (const [file, owners] of await managedGuidanceOwners(root)) {
-    for (const owner of owners) {
-      if (baseIds.has(owner)) continue;
-      await removeManagedBlocksForPlugin(path.join(root, file), FRAMEWORK_NAME, owner);
-    }
-  }
-}
-
-export interface AudienceSweep {
-  /** Disabled inputs for every swept plugin, per runtime. */
-  teardown: Map<string, CapabilityContributionInput[]>;
-  /** Packages that could not be loaded; their non-guidance entries stay until a retry. */
-  unswept: string[];
-  warnings: string[];
-}
-
-export interface AudienceSweepOptions {
-  /** Every registration of the process; an audience plugin already loaded is reused, not reloaded. */
-  registrations: readonly NormalizedRegistration[];
-  /** Restrict the sweep to these packages; every audience declaration when absent. */
-  packages?: ReadonlySet<string>;
-  deps?: DynamicPluginLoadDeps;
-}
-
-/** One distinct package per audience declaration, base packages excluded. */
-function audiencePackages(raw: unknown): Map<string, ReturnType<typeof validateDeclaration>> {
-  const basePackages = new Set(
-    effectivePluginDeclarations(raw, null).flatMap((entry) => {
-      const { declaration } = validateDeclaration(entry);
-      return declaration ? [declaration.package] : [];
-    }),
-  );
-  const found = new Map<string, ReturnType<typeof validateDeclaration>>();
-  for (const audience of declaredAudiences(raw)) {
-    for (const entry of audiencePluginDeclarations(raw, audience)) {
-      const validated = validateDeclaration(entry);
-      const name = validated.declaration?.package;
-      if (!name || basePackages.has(name) || found.has(name)) continue;
-      found.set(name, validated);
-    }
-  }
-  return found;
-}
-
-/**
- * Collects the declarations of every audience plugin as disabled inputs:
- * loaded for its declarations only — never activated, no lifecycle hook run.
- * An unloadable plugin is reported, never fatal.
- */
-export async function sweepAudienceDeclarations(
-  ctx: SetupContext,
-  options: AudienceSweepOptions,
-): Promise<AudienceSweep> {
-  const sweep: AudienceSweep = { teardown: new Map(), unswept: [], warnings: [] };
-  const raw = await readFrameworkRaw(ctx.companionPath);
-
-  for (const [name, { declaration }] of audiencePackages(raw)) {
-    if (options.packages && !options.packages.has(name)) continue;
-    let plugin: Plugin | undefined = options.registrations.find(
-      (entry) => entry.packageName === name,
-    )?.plugin;
-    if (!plugin) {
-      const loaded = await loadDynamicPlugin(ctx.companionPath, declaration!, options.deps);
-      if (!loaded.ok) {
-        sweep.unswept.push(name);
-        sweep.warnings.push(
-          `audience plugin "${name}" was not swept from the companion: ${loaded.warning} Its entries stay until a pass can load it.`,
-        );
-        continue;
-      }
-      plugin = loaded.plugin;
-    }
-
-    const capability = plugin as CapabilityPlugin;
-    if (plugin.kind !== "capability" || !capability.getRuntimeContributions) continue;
-    try {
-      const byRuntime = await capability.getRuntimeContributions(ctx);
-      for (const [runtimeId, contributions] of Object.entries(byRuntime)) {
-        if (!contributions) continue;
-        const inputs = sweep.teardown.get(runtimeId) ?? [];
-        inputs.push({
-          pluginId: plugin.id,
-          enabled: false,
-          capabilityEnabled: false,
-          contributions,
-        });
-        sweep.teardown.set(runtimeId, inputs);
-      }
-    } catch (error) {
-      sweep.unswept.push(name);
-      sweep.warnings.push(
-        `audience plugin "${name}" was not swept from the companion: ${error instanceof Error ? error.message : String(error)}`,
-      );
-    }
-  }
-  return sweep;
-}