@uniqbit/mate-core 0.17.0-canary.9 → 0.17.1

package/src/opencode/companion-hooks.ts

@@ -1,7 +1,8 @@
+import { spawn } from "node:child_process";
 import fs from "node:fs";
 import path from "node:path";
 
-import type { Hooks, Plugin, PluginInput } from "@opencode-ai/plugin";
+import type { Cleanup, Context } from "@opencode/plugin/promise/plugin";
 
 import {
   companionForkRefusal,
@@ -15,7 +16,6 @@ import {
   extractPatchPaths,
   isArtifactPath,
   normalizeTargetPath,
-  readContext,
   shouldBlockArtifactWrite,
   type CompanionContext,
 } from "./companion-policy";
@@ -43,67 +43,80 @@ const REACT_DOCTOR_ARGS = [
   "30",
 ];
 
-async function runReactDoctorScan(
-  context: CompanionContext,
-  client: PluginInput["client"],
-  $: PluginInput["$"],
-  sessionID: string,
-  scansInFlight: Set<string>,
-): Promise<void> {
-  const repo = context.repositoryPath;
-  if (!repo || scansInFlight.has(sessionID)) return;
-  scansInFlight.add(sessionID);
-  try {
-    const localBin = path.join(repo, "node_modules", ".bin", "react-doctor");
-    const mateBin = process.env.MATE_REACT_DOCTOR_BIN_PATH;
-    const doctorBin = mateBin && fs.existsSync(mateBin) ? mateBin : localBin;
-
-    const result = fs.existsSync(doctorBin)
-      ? await $`${doctorBin} ${REACT_DOCTOR_ARGS}`.cwd(repo).nothrow().quiet()
-      : await $`npx --yes ${`react-doctor@${REACT_DOCTOR_VERSION}`} ${REACT_DOCTOR_ARGS}`
-          .cwd(repo)
-          .nothrow()
-          .quiet();
-
-    if (result.exitCode === 0) return;
+export type CommandResult = { exitCode: number | null; output: string };
+export type CommandRunner = (
+  command: string,
+  args: string[],
+  cwd: string,
+) => Promise<CommandResult>;
+type SessionPrompt = Pick<Context["session"], "prompt">;
+
+/** Combined stdout and stderr; rejects only when the process cannot be spawned. */
+export const runCommand: CommandRunner = (command, args, cwd) =>
+  new Promise((resolve, reject) => {
+    const child = spawn(command, args, { cwd, stdio: ["ignore", "pipe", "pipe"] });
+    let output = "";
+    child.stdout.setEncoding("utf8").on("data", (chunk: string) => (output += chunk));
+    child.stderr.setEncoding("utf8").on("data", (chunk: string) => (output += chunk));
+    child.once("error", reject);
+    child.once("close", (exitCode) => resolve({ exitCode, output: output.trim() }));
+  });
+
+function reactDoctorCommand(repo: string): { command: string; args: string[] } {
+  const localBin = path.join(repo, "node_modules", ".bin", "react-doctor");
+  const mateBin = process.env.MATE_REACT_DOCTOR_BIN_PATH;
+  const doctorBin = mateBin && fs.existsSync(mateBin) ? mateBin : localBin;
+  return fs.existsSync(doctorBin)
+    ? { command: doctorBin, args: REACT_DOCTOR_ARGS }
+    : {
+        command: "npx",
+        args: ["--yes", `react-doctor@${REACT_DOCTOR_VERSION}`, ...REACT_DOCTOR_ARGS],
+      };
+}
 
-    const output = `${result.stdout?.toString() ?? ""}${result.stderr?.toString() ?? ""}`.trim();
-    if (!output || REACT_DOCTOR_NON_LINT_FAILURES.some((re) => re.test(output))) return;
+/**
+ * Tracks edited sessions and scans each at most once per idle, never twice
+ * concurrently for the same session.
+ */
+export function createReactDoctorScanner(
+  context: CompanionContext,
+  session: SessionPrompt,
+  run: CommandRunner = runCommand,
+) {
+  const dirtySessions = new Set<string>();
+  const scansInFlight = new Set<string>();
 
-    await client.tui
-      .showToast({
-        query: { directory: repo },
-        body: {
-          title: "React Doctor",
-          message: "Found issues in the changed files — review before finishing.",
-          variant: "warning",
-        },
-      })
-      .catch(() => {});
-    await client.session
-      .promptAsync({
-        path: { id: sessionID },
-        query: { directory: repo },
-        body: {
-          parts: [
-            {
-              type: "text",
-              synthetic: true,
-              text:
-                "React Doctor found issues in the changed files. Review this output and fix " +
-                "the regressions before finishing. For confirmed issues that cannot be fixed " +
-                "now, create GitHub issues with the rule, file/line, confidence, impact, and " +
-                `proposed fix.\n\n${output}`,
-            },
-          ],
-        },
-      })
-      .catch(() => {});
-  } catch {
-    // Never break the session because a diagnostic scan failed.
-  } finally {
-    scansInFlight.delete(sessionID);
-  }
+  return {
+    markEdited(tool: string, sessionID: string): void {
+      if (REACT_DOCTOR_EDIT_TOOLS.has(tool)) dirtySessions.add(sessionID);
+    },
+    async idle(sessionID: string): Promise<void> {
+      const repo = context.repositoryPath;
+      if (!repo || scansInFlight.has(sessionID) || !dirtySessions.delete(sessionID)) return;
+      scansInFlight.add(sessionID);
+      try {
+        const { command, args } = reactDoctorCommand(repo);
+        const { exitCode, output } = await run(command, args, repo);
+        if (exitCode === 0 || !output) return;
+        if (REACT_DOCTOR_NON_LINT_FAILURES.some((re) => re.test(output))) return;
+
+        await session
+          .prompt({
+            sessionID,
+            text:
+              "React Doctor found issues in the changed files. Review this output and fix " +
+              "the regressions before finishing. For confirmed issues that cannot be fixed " +
+              "now, create GitHub issues with the rule, file/line, confidence, impact, and " +
+              `proposed fix.\n\n${output}`,
+          } as never)
+          .catch(() => {});
+      } catch {
+        /** Never break the session because a diagnostic scan failed. */
+      } finally {
+        scansInFlight.delete(sessionID);
+      }
+    },
+  };
 }
 
 /**
@@ -120,7 +133,6 @@ const repairedCompanions = new Set<string>();
  */
 export async function repairCompanionGitOnce(
   context: CompanionContext,
-  client: PluginInput["client"] | undefined,
   env: Record<string, string | undefined> = process.env,
 ): Promise<string[]> {
   if (
@@ -132,27 +144,12 @@ export async function repairCompanionGitOnce(
   if (repairedCompanions.has(context.companionPath)) return [];
   repairedCompanions.add(context.companionPath);
 
-  const notes = unattendedSyncStalenessLines(syncCompanionUnattended(context.companionPath));
-  if (notes.length === 0) return [];
-
   /**
    * Operator-facing only: a model told to run the command would run it
-   * unattended. Delivery is best-effort in both directions — a client that
-   * throws rather than rejecting must not cost the caller its notes.
+   * unattended. The V2 server API has no toast; the notes reach the operator
+   * through the persisted record and the TUI's staleness lines.
    */
-  try {
-    await client?.tui?.showToast({
-      query: { directory: context.repositoryPath },
-      body: {
-        title: `${context.frameworkName} companion`,
-        message: notes.join("\n"),
-        variant: "warning",
-      },
-    });
-  } catch {
-    /** The note survives in the persisted record and the TUI's staleness lines. */
-  }
-  return notes;
+  return unattendedSyncStalenessLines(syncCompanionUnattended(context.companionPath));
 }
 
 /** Test seam: the once-per-session guard is process-wide by design. */
@@ -180,83 +177,64 @@ export function refuseForkedCompanionWrite(
   if (refusal) throw new Error(refusal);
 }
 
-type PluginEventInput = Parameters<NonNullable<Hooks["event"]>>[0];
-type ToolBeforeInput = Parameters<NonNullable<Hooks["tool.execute.before"]>>[0];
-type ToolBeforeOutput = Parameters<NonNullable<Hooks["tool.execute.before"]>>[1];
-type ToolAfterInput = Parameters<NonNullable<Hooks["tool.execute.after"]>>[0];
+/** Throws when the tool call would write an artifact outside the companion. */
+export function guardToolInput(context: CompanionContext, tool: string, input: unknown): void {
+  const args = (input ?? {}) as Record<string, unknown>;
+  const filePaths =
+    tool === "write" || tool === "edit"
+      ? [String(args.filePath ?? "")]
+      : tool === "apply_patch"
+        ? extractPatchPaths(String(args.patchText ?? ""))
+        : [];
+
+  for (const filePath of filePaths) {
+    if (context.repositoryPath && filePath && shouldBlockArtifactWrite(context, filePath)) {
+      throw new Error(buildArtifactError(context, filePath));
+    }
+    refuseForkedCompanionWrite(context, filePath);
+  }
+}
 
-export const CompanionHooksPlugin: Plugin = async (pluginInput = {} as PluginInput) => {
-  const { client, $ } = pluginInput;
-  const context = readContext();
-  if (!context.companionPath) return {};
+export type CompanionHooksOptions = {
+  /** Test seam for the React Doctor process. */
+  run?: CommandRunner;
+};
 
+/**
+ * Registers the companion guardrails on an OpenCode V2 plugin context.
+ * The caller resolves `context` and skips this when no companion resolved.
+ */
+export async function registerCompanionHooks(
+  api: Context,
+  context: CompanionContext,
+  options: CompanionHooksOptions = {},
+): Promise<Cleanup | undefined> {
   /**
-   * The repair sits above the returned hooks, so anything escaping it would
-   * cost the session every guardrail below — the artifact guard, the React
-   * Doctor scan — to save a synchronization that is optional by design.
+   * Anything escaping the repair would cost the session every guardrail
+   * below to save a synchronization that is optional by design.
    */
-  await repairCompanionGitOnce(context, client).catch(() => []);
+  await repairCompanionGitOnce(context).catch(() => []);
 
-  const dirtyReactDoctorSessions = new Set<string>();
-  const reactDoctorScansInFlight = new Set<string>();
+  await api.tool.hook("execute.before", (event) => {
+    guardToolInput(context, event.tool, event.input);
+  });
 
-  return {
-    ...(context.repositoryPath
-      ? {
-          event: async ({ event }: PluginEventInput) => {
-            if (event.type !== "session.idle") return;
-            const sessionID = event.properties.sessionID;
-            if (
-              !context.reactDoctorEnabled ||
-              reactDoctorScansInFlight.has(sessionID) ||
-              !dirtyReactDoctorSessions.delete(sessionID)
-            ) {
-              return;
-            }
-            await runReactDoctorScan(context, client, $, sessionID, reactDoctorScansInFlight);
-          },
-        }
-      : {}),
-    "tool.execute.before": async (input: ToolBeforeInput, output: ToolBeforeOutput) => {
-      const toolName = String(input.tool ?? "");
-      const args = output.args ?? {};
-      if (context.repositoryPath && ["write", "edit"].includes(toolName)) {
-        const filePath = String(args.filePath ?? "");
-        if (filePath && shouldBlockArtifactWrite(context, filePath)) {
-          throw new Error(buildArtifactError(context, filePath));
-        }
-        refuseForkedCompanionWrite(context, filePath);
-      }
-      if (context.repositoryPath && toolName === "apply_patch") {
-        for (const filePath of extractPatchPaths(String(args.patchText ?? ""))) {
-          if (shouldBlockArtifactWrite(context, filePath)) {
-            throw new Error(buildArtifactError(context, filePath));
-          }
-          refuseForkedCompanionWrite(context, filePath);
-        }
-      }
-      if (!context.repositoryPath && toolName === "write") {
-        refuseForkedCompanionWrite(context, String(args.filePath ?? ""));
-      }
-      if (!context.repositoryPath && toolName === "edit") {
-        refuseForkedCompanionWrite(context, String(args.filePath ?? ""));
-      }
-      if (!context.repositoryPath && toolName === "apply_patch") {
-        for (const filePath of extractPatchPaths(String(args.patchText ?? ""))) {
-          refuseForkedCompanionWrite(context, filePath);
-        }
-      }
-    },
-    ...(context.repositoryPath
-      ? {
-          "tool.execute.after": async (input: ToolAfterInput) => {
-            if (context.reactDoctorEnabled && REACT_DOCTOR_EDIT_TOOLS.has(input.tool)) {
-              dirtyReactDoctorSessions.add(input.sessionID);
-            }
-          },
-        }
-      : {}),
-  };
-};
+  if (!context.repositoryPath || !context.reactDoctorEnabled) return;
+
+  const scanner = createReactDoctorScanner(context, api.session, options.run);
+  await api.tool.hook("execute.after", (event) => {
+    if (event.status === "completed") scanner.markEdited(event.tool, event.sessionID);
+  });
 
-export default CompanionHooksPlugin;
+  const controller = new AbortController();
+  void (async () => {
+    try {
+      for await (const event of api.event.subscribe({ signal: controller.signal })) {
+        if (event.type === "session.idle") await scanner.idle(event.data.sessionID);
+      }
+    } catch {
+      /** Plugin shutdown aborts the subscription; event delivery is best effort. */
+    }
+  })();
+  return () => controller.abort();
+}

package/src/opencode/index.ts

@@ -1,10 +1,16 @@
 /**
- * Building blocks for authoring OpenCode plugins: the Mate TUI plugin, the
- * companion guidance hooks, and the companion policy helpers. Session-runtime
- * only — modules here must not import framework internals (see the
- * import-isolation test).
+ * Server-side building blocks for authoring OpenCode plugins: the companion
+ * guidance hooks and the companion policy helpers. Session-runtime only —
+ * modules here must not import framework internals (see the import-isolation
+ * test). Must not reach OpenTUI or Solid: the Mate TUI plugin lives on the
+ * `./opencode/tui` subpath.
  */
-export { default as tuiPlugin } from "./tui";
-export { CompanionHooksPlugin } from "./companion-hooks";
+export {
+  createReactDoctorScanner,
+  guardToolInput,
+  registerCompanionHooks,
+  type CommandRunner,
+  type CompanionHooksOptions,
+} from "./companion-hooks";
 export { resolveOpenCodeGuidance, type OpenCodeGuidanceResolution } from "./projected-guidance";
 export * from "./companion-policy";

package/src/opencode/tui.tsx

@@ -1,82 +1,79 @@
 /** @jsxImportSource @opentui/solid */
 /* oxlint-disable react/no-unknown-property, react/react-in-jsx-scope, react/jsx-key, react-doctor/jsx-key */
 /**
+ * OpenCode V2 TUI plugin module (`{ id, setup }`), OpenCode 2.x only.
  * Solid JSX, not React: `key` is not a reconciliation prop here and `TextProps`
  * does not accept it, so the jsx-key rules cannot be satisfied — only suppressed.
  * Static arrays render through `.map`; a reactive one would need `<For>`.
  */
-import type { TuiPlugin, TuiPluginApi, TuiPluginModule } from "@opencode-ai/plugin/tui";
-
 import { mateVersion } from "../runtime/install";
 import { readContext } from "./companion-policy";
 
+/** Minimal structural slice of the OpenCode V2 TUI API; the published SDK ships no V2 TUI types. */
+export type MateTuiApi = {
+  /** Host getter: returns the current theme tokens on every read. */
+  readonly theme: {
+    text: {
+      muted: string;
+      feedback?: { warning?: { base: string } };
+    };
+  };
+  ui: {
+    slot(claim: MateSlotClaim): () => void;
+  };
+};
+
+export type MateSlotClaim = {
+  prepend?: "home.footer";
+  append?: "sidebar.content";
+  render: () => unknown;
+};
+
+export type MateTuiPluginModule = {
+  id: string;
+  setup(api: MateTuiApi): void | Promise<void>;
+};
+
 const MIDNIGHT_PURPLE_BRIGHT = "#c084fc";
-const NARROW_TERMINAL_WIDTH = 80;
 const MATE_VERSION = process.env.MATE_VERSION ?? mateVersion();
 
-function SessionContext({
-  api,
-  compact = false,
-  sidebar = false,
-}: {
-  api: TuiPluginApi;
-  compact?: boolean;
-  sidebar?: boolean;
-}) {
+function SessionContext({ api, sidebar = false }: { api: MateTuiApi; sidebar?: boolean }) {
   const context = readContext();
-  const theme = api.theme.current;
-
-  if (compact) {
-    return (
-      <box width="100%" paddingTop={0} flexShrink={0}>
-        <text fg={theme.textMuted}>
-          mate v{MATE_VERSION} | repo: {context.repositoryPath} | mate: {context.companionPath}
-        </text>
-      </box>
-    );
-  }
+  const text = api.theme.text;
+  const warning = text.feedback?.warning?.base ?? text.muted;
 
   return (
-    <box width="100%" maxWidth={75} paddingTop={sidebar ? 0 : 2} paddingBottom={1} flexShrink={0}>
+    <box
+      width="100%"
+      maxWidth={sidebar ? undefined : 75}
+      paddingLeft={sidebar ? 0 : 2}
+      paddingRight={sidebar ? 0 : 2}
+      paddingBottom={sidebar ? 1 : 0}
+      flexShrink={0}
+    >
       <text fg={MIDNIGHT_PURPLE_BRIGHT}>mate v{MATE_VERSION}</text>
-      <text fg={theme.textMuted}>repo: {context.repositoryPath}</text>
-      <text fg={theme.textMuted}>mate: {context.companionPath}</text>
+      <text fg={text.muted}>repo: {context.repositoryPath}</text>
+      <text fg={text.muted}>mate: {context.companionPath}</text>
       {context.stalenessLines.map((note) => (
-        <text fg={theme.warning ?? theme.textMuted}>{note}</text>
+        <text fg={warning}>{note}</text>
       ))}
     </box>
   );
 }
 
-const tui: TuiPlugin = async (api) => {
+function setup(api: MateTuiApi): void {
   const context = readContext();
   if (!context.companionPath || !context.repositoryPath) {
     return;
   }
 
-  api.slots.register({
-    order: 0,
-    slots: {
-      home_bottom() {
-        return <SessionContext api={api} />;
-      },
-      sidebar_content() {
-        return <SessionContext api={api} sidebar />;
-      },
-      app_bottom() {
-        if (api.renderer.width >= NARROW_TERMINAL_WIDTH || api.route.current.name !== "session") {
-          return null;
-        }
-
-        return <SessionContext api={api} compact />;
-      },
-    },
-  });
-};
+  api.ui.slot({ prepend: "home.footer", render: () => <SessionContext api={api} /> });
+  api.ui.slot({ append: "sidebar.content", render: () => <SessionContext api={api} sidebar /> });
+}
 
-const plugin: TuiPluginModule & { id: string } = {
+const plugin: MateTuiPluginModule = {
   id: "mate-companion-tui",
-  tui,
+  setup,
 };
 
 export default plugin;

package/src/playbooks/companion-guidance.ts

@@ -1,6 +1,5 @@
 import {
   buildCompanionGuidance as buildCompanionGuidanceWith,
-  buildCompanionPolicyXml as buildCompanionPolicyXmlWith,
   type GuidanceContext,
 } from "../runtime/companion-guidance";
 import { getWrapperBinPath } from "../lib/package-paths";
@@ -16,33 +15,7 @@ import { getWrapperBinPath } from "../lib/package-paths";
  * passes the projected path instead, and so calls the runtime builders direct.
  */
 
-export {
-  GRAPHIFY_SHARED_COMPANION_PATH_CONTRACT,
-  GRAPHIFY_COMPANION_PATH_CONTRACT,
-  buildCodebaseExplorationGuidanceSection,
-  hasGraphifyCapability,
-  hasOpenspecCapability,
-  hasTokensaveCapability,
-  type GuidanceCapability,
-  type GuidanceContext,
-} from "../runtime/companion-guidance";
-
-/**
- * Build just the `<companion-policy>` XML block: paths, CLI tools, and
- * mandatory rules (including the capability-gated `openspec-publish` rule).
- * Does not include codebase-exploration guidance — see
- * `buildCompanionGuidance` for the merged single-string form, or call
- * `buildCodebaseExplorationGuidanceSection` directly when that guidance is
- * delivered through its own channel (as OpenCode's guidance contract does).
- */
-export function buildCompanionPolicyXml(
-  context: GuidanceContext,
-  options: { wrapperBinPath?: string } = {},
-): string {
-  return buildCompanionPolicyXmlWith(context, {
-    wrapperBinPath: options.wrapperBinPath ?? getWrapperBinPath(),
-  });
-}
+export { GRAPHIFY_SHARED_COMPANION_PATH_CONTRACT } from "../runtime/companion-guidance";
 
 /**
  * Build the merged single-string guidance: the companion-policy XML plus

package/src/runtime/companion-sync.ts

@@ -12,7 +12,6 @@ import fs from "node:fs";
 import path from "node:path";
 
 import {
-  companionGitStatePath,
   COMPANION_SYNC_TTL_MS,
   FORK_VERDICT_TTL_MS,
   isCompanionSyncDue,
@@ -294,5 +293,3 @@ export function forkRefusalMessage(companionPath: string, fork: CompanionForkSta
     `Writing artifacts now risks losing work in the reconciliation. Run \`${COMPANION_SYNC_COMMAND}\` first.`,
   ].join("\n");
 }
-
-export { companionGitStatePath };

package/src/templates/capabilities/openspec-cap/mate-minimal/schema.yaml

@@ -39,7 +39,8 @@ artifacts:
     template: tasks.md
     instruction: |
       Create a flat implementation checklist that satisfies the delta specs. Keep it short: this
-      workflow intentionally has no explore, proposal, or design artifact.
+      profile uses the shared `/openspec-explore` and `/openspec-propose` planning steps but
+      intentionally writes no explore, proposal, or design artifact.
 
       Number tasks `N.M` and group them under `## N. <group>` headers so apply tracking can address them individually.
       Read `openspec/mate-conventions.yaml` before writing the artifact and preserve its scope rules.

package/src/templates/providers/opencode/opencode.json

@@ -2,12 +2,14 @@
   "$schema": "https://opencode.ai/config.json",
   "compaction": {
     "auto": true,
-    "prune": true,
-    "reserved": 15000
+    "buffer": 20000,
+    "keep": {
+      "tokens": 15000
+    }
   },
   "tool_output": {
-    "max_lines": 500,
-    "max_bytes": 20000
+    "max_lines": 1000,
+    "max_bytes": 40000
   },
   "references": {
     "mate": ".."