@uniqbit/mate-core 0.18.3 → 0.18.4

package/src/runtime/opencode-audience-layer.ts

@@ -0,0 +1,176 @@
+import fs from "node:fs/promises";
+import path from "node:path";
+
+import { layerGuidanceText } from "./audience-layer";
+import { OPENCODE_MCP_SERVERS_AT } from "./runtime-document-manifest";
+
+/**
+ * Reads an audience layer the OpenCode Runtime Surface wrote, as what the Mate
+ * OpenCode plugin applies through the plugin API. The surface re-exports it as
+ * its own reader; it lives under `runtime/` only so the import-isolated plugin
+ * can reach it. The plugin parses no OpenCode document itself.
+ */
+
+export interface LayerMcpServer {
+  name: string;
+  /** The entry exactly as the surface wrote it under `mcp.servers`. */
+  config: Record<string, unknown>;
+}
+
+export interface LayerSkill {
+  id: string;
+  name: string;
+  description?: string;
+  /** The skill's `SKILL.md`. */
+  path: string;
+  content: string;
+}
+
+export type LayerAgentMode = "subagent" | "primary" | "all";
+
+export interface LayerAgent {
+  id: string;
+  description?: string;
+  mode: LayerAgentMode;
+  /** The agent's prompt: the definition's body. */
+  system: string;
+}
+
+export interface OpenCodeLayerContents {
+  mcpServers: LayerMcpServer[];
+  skills: LayerSkill[];
+  agents: LayerAgent[];
+  /** The layer's guidance sections, managed-block markers removed. */
+  guidance: string;
+}
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+
+function splitFrontmatter(content: string): { fields: string; body: string } {
+  const match = content.match(/^---\s*\r?\n([\s\S]*?)\r?\n---(?:\r?\n|$)/);
+  return match
+    ? { fields: match[1]!, body: content.slice(match[0].length) }
+    : { fields: "", body: content };
+}
+
+function frontmatterScalarFromFields(fields: string, key: string): string | undefined {
+  const value = fields.match(new RegExp(`^${key}:\\s*(.+)$`, "m"))?.[1]?.trim();
+  return value?.replace(
+    /^(?:"([\s\S]*)"|'([\s\S]*)')$/,
+    (_all, doubleQuoted?: string, singleQuoted?: string) => doubleQuoted ?? singleQuoted ?? "",
+  );
+}
+
+/** One scalar of a simple YAML frontmatter, quotes removed. */
+export function frontmatterScalar(content: string, key: string): string | undefined {
+  return frontmatterScalarFromFields(splitFrontmatter(content).fields, key);
+}
+
+/** An id OpenCode accepts for a skill or agent name. */
+export function contributionId(name: string, fallback: string): string {
+  return (
+    name
+      .toLowerCase()
+      .replace(/[^a-z0-9_-]+/g, "-")
+      .replace(/^-+|-+$/g, "") || fallback
+  );
+}
+
+async function findSkillFiles(directory: string): Promise<string[]> {
+  try {
+    const entries = await fs.readdir(directory, { withFileTypes: true });
+    const nested = await Promise.all(
+      entries.map((entry) => {
+        const entryPath = path.join(directory, entry.name);
+        if (entry.isFile() && entry.name === "SKILL.md") return Promise.resolve([entryPath]);
+        return entry.isDirectory() ? findSkillFiles(entryPath) : Promise.resolve([]);
+      }),
+    );
+    return nested.flat().toSorted();
+  } catch {
+    return [];
+  }
+}
+
+/** Every `SKILL.md` under `roots`; an unreadable skill is skipped, never fatal. */
+export async function loadSkillInfos(roots: readonly string[]): Promise<LayerSkill[]> {
+  const files = (await Promise.all(roots.map(findSkillFiles))).flat();
+  const skills = await Promise.all(
+    files.map(async (filePath): Promise<LayerSkill | null> => {
+      try {
+        const content = await fs.readFile(filePath, "utf8");
+        const { fields } = splitFrontmatter(content);
+        const name =
+          frontmatterScalarFromFields(fields, "name") || path.basename(path.dirname(filePath));
+        const description = frontmatterScalarFromFields(fields, "description");
+        return {
+          id: contributionId(name, "mate-skill"),
+          name,
+          ...(description ? { description } : {}),
+          path: filePath,
+          content,
+        };
+      } catch {
+        return null;
+      }
+    }),
+  );
+  return skills.filter((skill) => skill !== null);
+}
+
+async function readMcpServers(root: string): Promise<LayerMcpServer[]> {
+  const parsed = await fs
+    .readFile(path.join(root, ".opencode", "opencode.json"), "utf8")
+    .then((text) => JSON.parse(text) as unknown)
+    .catch(() => null);
+  let servers: unknown = parsed;
+  for (const key of OPENCODE_MCP_SERVERS_AT) servers = isRecord(servers) ? servers[key] : undefined;
+  if (!isRecord(servers)) return [];
+  return Object.entries(servers)
+    .filter((entry): entry is [string, Record<string, unknown>] => isRecord(entry[1]))
+    .map(([name, config]) => ({ name, config }))
+    .toSorted((left, right) => left.name.localeCompare(right.name));
+}
+
+function agentMode(value: string | undefined): LayerAgentMode {
+  return value === "subagent" || value === "primary" ? value : "all";
+}
+
+async function readAgents(root: string): Promise<LayerAgent[]> {
+  const dir = path.join(root, ".opencode", "agents");
+  const names = await fs.readdir(dir).catch(() => [] as string[]);
+  const agents = await Promise.all(
+    names
+      .filter((name) => name.endsWith(".md"))
+      .toSorted()
+      .map(async (name): Promise<LayerAgent | null> => {
+        const content = await fs.readFile(path.join(dir, name), "utf8").catch(() => null);
+        if (content === null) return null;
+        const { fields, body } = splitFrontmatter(content);
+        const description = frontmatterScalarFromFields(fields, "description");
+        return {
+          id: contributionId(path.basename(name, ".md"), "mate-agent"),
+          ...(description ? { description } : {}),
+          mode: agentMode(frontmatterScalarFromFields(fields, "mode")),
+          system: body.trim(),
+        };
+      }),
+  );
+  return agents.filter((agent) => agent !== null);
+}
+
+async function readGuidance(root: string): Promise<string> {
+  return layerGuidanceText(await fs.readFile(path.join(root, "AGENTS.md"), "utf8").catch(() => ""));
+}
+
+export async function readOpenCodeAudienceLayer(root: string): Promise<OpenCodeLayerContents> {
+  const [mcpServers, skills, agents, guidance] = await Promise.all([
+    readMcpServers(root),
+    loadSkillInfos([path.join(root, ".agents", "skills")]),
+    readAgents(root),
+    readGuidance(root),
+  ]);
+  return { mcpServers, skills, agents, guidance };
+}

package/src/runtime/policy.ts

@@ -40,6 +40,17 @@ function capabilityNames(value: unknown): string[] {
     .filter((name): name is string => typeof name === "string");
 }
 
+/**
+ * A base-set key from `audiences.base`, the shape a companion is saved in. The
+ * lenient twin of the setup normalizer, which `runtime/` cannot import.
+ */
+function baseAudienceKey(config: Record<string, unknown>, key: string): unknown {
+  const audiences = config.audiences;
+  if (!audiences || typeof audiences !== "object") return undefined;
+  const base = (audiences as Record<string, unknown>).base;
+  return base && typeof base === "object" ? (base as Record<string, unknown>)[key] : undefined;
+}
+
 /**
  * Synchronous so it composes into `readCompanionRuntimeContext`. A missing or
  * unparseable companion config yields an inert policy rather than throwing.
@@ -56,7 +67,9 @@ export function readCompanionPolicy(companionPath: string): CompanionPolicy {
   const config = parsed as Record<string, unknown>;
   return {
     allowedAgents: stringList(config.allowedAgents),
-    enabledCapabilities: capabilityNames(config.capabilities),
+    enabledCapabilities: capabilityNames(
+      config.capabilities ?? baseAudienceKey(config, "capabilities"),
+    ),
     gitAutoMode: config.git === "auto",
   };
 }

package/src/runtime/projection.ts

@@ -88,7 +88,7 @@ export function projectionEnvPath(repoRoot: string): string {
   return path.join(repoLocalDirPath(repoRoot), PROJECTION_ENV_FILE);
 }
 
-const generatedHeader = () => `# generated by ${FRAMEWORK_NAME} — do not edit`;
+export const generatedHeader = (): string => `# generated by ${FRAMEWORK_NAME} — do not edit`;
 
 export function renderProjectionYaml(file: ProjectionFile): string {
   const document: Record<string, string> = { stamp: file.stamp };

package/src/runtime/runtime-document-manifest.ts

@@ -80,6 +80,8 @@ export interface Manifest {
   readonly runtimes: Readonly<Record<string, WrapRuntime>>;
   readonly copies: Readonly<Record<string, CopyRecord>>;
   readonly links: Readonly<Record<string, LinkRecord>>;
+  /** The audience `mate wrap --audience` recorded; the only source of a bare session's audience. */
+  readonly audience?: string;
 }
 
 export const EMPTY_MANIFEST: Manifest = Object.freeze({
@@ -124,9 +126,23 @@ function manifestOf(parsed: Record<string, unknown>): Manifest {
     runtimes: isRecord(parsed.runtimes) ? (parsed.runtimes as Manifest["runtimes"]) : {},
     copies: isRecord(parsed.copies) ? (parsed.copies as Manifest["copies"]) : {},
     links: isRecord(parsed.links) ? (parsed.links as Manifest["links"]) : {},
+    ...(typeof parsed.audience === "string" && parsed.audience
+      ? { audience: parsed.audience }
+      : {}),
   };
 }
 
+/** The audience the checkout is wrapped for; `null` for base only. */
+export function recordedAudience(manifest: Manifest): string | null {
+  return manifest.audience ?? null;
+}
+
+/** Records the checkout's audience, or none with `null`. */
+export function withAudience(manifest: Manifest, audience: string | null): Manifest {
+  const { audience: _previous, ...rest } = manifest;
+  return audience ? { ...rest, audience } : rest;
+}
+
 function recordedRuntime(manifest: Manifest, documentPath: string): WrapRuntime {
   return manifest.runtimes[documentPath] ?? documentRuntime(documentPath);
 }
@@ -150,6 +166,7 @@ export function serializeManifest(manifest: Manifest): string | null {
       ...(recorded.length > 0 ? { runtimes } : {}),
       ...(copied.length > 0 ? { copies: manifest.copies } : {}),
       ...(linked.length > 0 ? { links: manifest.links } : {}),
+      ...(manifest.audience ? { audience: manifest.audience } : {}),
     },
     null,
     2,

package/src/runtime/wrap-state.ts

@@ -14,6 +14,7 @@ import {
   parseManifestStrict,
   readManifestText,
   recordedListValues,
+  recordedAudience,
   recordedMapKeys,
   type Manifest,
   type WrapRuntime,
@@ -30,6 +31,8 @@ export interface WrapState {
   carriesClaudeHookGroup(group: ClaudeHookGroup): boolean;
   /** MCP server names the wrap declared in `.opencode/opencode.json`; user servers are not listed. */
   readonly openCodeMcpServers: readonly string[];
+  /** The audience the checkout is wrapped for; `null` for base only. */
+  readonly audience: string | null;
 }
 
 export const WRAP_RUNTIMES: readonly WrapRuntime[] = ["claude", "opencode"];
@@ -61,6 +64,7 @@ export function wrapStateOf(manifest: Manifest): WrapState {
       OPENCODE_CONFIG_DOCUMENT,
       OPENCODE_MCP_SERVERS_AT,
     ),
+    audience: recordedAudience(manifest),
   };
 }
 

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

@@ -0,0 +1,325 @@
+// 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");
+}