@uniqbit/mate-core 0.15.5 → 0.16.0-canary.0

package/src/opencode/companion-hooks.ts

@@ -3,229 +3,23 @@ import path from "node:path";
 
 import type { Hooks, Plugin, PluginInput } from "@opencode-ai/plugin";
 
+import {
+  companionForkRefusal,
+  syncCompanionUnattended,
+  unattendedSyncStalenessLines,
+} from "../runtime/companion-sync";
+import { hasLaunchEnvironment } from "../runtime/env";
 import {
   buildArtifactError,
   extractPatchPaths,
+  isArtifactPath,
+  normalizeTargetPath,
   readContext,
   shouldBlockArtifactWrite,
   type CompanionContext,
 } from "./companion-policy";
 
-const ARCHIVE_ENTRY_PATTERN = /^\d{4}-\d{2}-\d{2}-.+$/;
-const ARCHIVE_PATH_PATTERN =
-  /(?:^|[\s/"'`,(])openspec\/changes\/archive\/(\d{4}-\d{2}-\d{2}-[^/\s"'`,)]+)/;
-
-function readArchiveEntries(archiveDir: string): Set<string> {
-  try {
-    const entries = new Set<string>();
-    for (const entry of fs.readdirSync(archiveDir, { withFileTypes: true })) {
-      if (entry.isDirectory() && ARCHIVE_ENTRY_PATTERN.test(entry.name)) entries.add(entry.name);
-    }
-    return entries;
-  } catch {
-    return new Set();
-  }
-}
-
-function shellSplit(command: string): string[] {
-  const parts: string[] = [];
-  let current = "";
-  let quote: "'" | '"' | null = null;
-  let escaping = false;
-
-  for (let index = 0; index < command.length; index += 1) {
-    const char = command[index];
-    if (escaping) {
-      current += char;
-      escaping = false;
-      continue;
-    }
-    if (char === "\\" && quote !== "'") {
-      const next = command[index + 1] ?? "";
-      if (/^[\\\s'"]$/.test(next)) {
-        escaping = true;
-        continue;
-      }
-      current += char;
-      continue;
-    }
-    if ((char === "'" || char === '"') && !quote) {
-      quote = char;
-      continue;
-    }
-    if (quote === char) {
-      quote = null;
-      continue;
-    }
-    if (!quote && /\s/.test(char)) {
-      if (current) {
-        parts.push(current);
-        current = "";
-      }
-      continue;
-    }
-    current += char;
-  }
-
-  if (current) parts.push(current);
-  return parts;
-}
-
-function extractArchivedChangeFromPath(value: string): string | null {
-  const normalized = value.replace(/\\/g, "/");
-  const match = normalized.match(ARCHIVE_PATH_PATTERN);
-  return match ? match[1].replace(/^\d{4}-\d{2}-\d{2}-/, "") : null;
-}
-
-function extractArchiveCommandChange(command: string): string | null {
-  const parts = shellSplit(command);
-  const archiveIndex = parts.findIndex(
-    (part, index) =>
-      part === "archive" &&
-      index > 0 &&
-      (parts[index - 1] === "openspec" || parts[index - 1].endsWith("/openspec")),
-  );
-  if (archiveIndex < 0) return null;
-
-  for (let index = archiveIndex + 1; index < parts.length; index += 1) {
-    const part = parts[index];
-    if (!part || part === "--") continue;
-    if (part.startsWith("-")) {
-      if (part === "--store") index += 1;
-      continue;
-    }
-    return part;
-  }
-  return null;
-}
-
-function extractMoveArchiveChange(commandText: string): string | null {
-  const parts = shellSplit(commandText);
-  const moveCommands = new Set([
-    "mv",
-    "move",
-    "move-item",
-    "cmd",
-    "cmd.exe",
-    "powershell",
-    "powershell.exe",
-    "pwsh",
-    "pwsh.exe",
-  ]);
-  const isPython = (part: string) =>
-    /^python(?:\d(?:\.\d+)*)?(?:\.exe)?$/i.test(part.split(/[\\/]/).pop() ?? part);
-
-  for (let index = 0; index < parts.length; index += 1) {
-    const command = parts[index].toLowerCase();
-    if (moveCommands.has(command)) {
-      for (const part of parts.slice(index + 1)) {
-        const change = extractArchivedChangeFromPath(part);
-        if (change) return change;
-      }
-    }
-    if (isPython(parts[index]) && /(?:shutil\.move|os\.rename|\.rename\s*\()/.test(commandText)) {
-      return extractArchivedChangeFromPath(commandText);
-    }
-  }
-  return null;
-}
-
-function collectCommands(value: unknown): string[] {
-  if (!value || typeof value !== "object") return [];
-  const record = value as Record<string, unknown>;
-  const commands: string[] = [];
-  if (typeof record.command === "string") commands.push(record.command);
-  for (const key of ["args", "tool_input"] as const) {
-    const nested = record[key];
-    if (nested && typeof nested === "object") {
-      const command = (nested as Record<string, unknown>).command;
-      if (typeof command === "string") commands.push(command);
-    }
-  }
-  return commands;
-}
-
-function commandSucceeded(value: unknown): boolean {
-  if (!value || typeof value !== "object") return true;
-  const record = value as Record<string, unknown>;
-  const candidates = [
-    record,
-    record.result,
-    record.output,
-    record.tool_output,
-    record.tool_response,
-  ];
-  for (const candidate of candidates) {
-    if (!candidate || typeof candidate !== "object") continue;
-    const result = candidate as Record<string, unknown>;
-    if (typeof result.success === "boolean") return result.success;
-    for (const key of ["exitCode", "exit_code", "status", "statusCode", "status_code"] as const) {
-      const status = result[key];
-      if (typeof status === "number") return status === 0;
-      if (typeof status === "string" && status.trim()) return Number(status) === 0;
-    }
-  }
-  return true;
-}
-
-function detectCommandArchive(input: unknown, output: unknown): string | null {
-  if (!commandSucceeded(input) || !commandSucceeded(output)) return null;
-  for (const command of [...collectCommands(input), ...collectCommands(output)]) {
-    const change = extractArchiveCommandChange(command) ?? extractMoveArchiveChange(command);
-    if (change) return change;
-  }
-  return null;
-}
-
-function detectNewlyArchivedChanges(archiveDir: string, snapshot: Set<string>): string[] {
-  const current = readArchiveEntries(archiveDir);
-  return [...current].filter((entry) => !snapshot.has(entry)).toSorted();
-}
-
-function appendOpenSpecFinishNudge(
-  context: CompanionContext,
-  archiveSnapshot: Set<string> | undefined,
-  nudgedCommandChanges: Set<string>,
-  input: { tool?: unknown },
-  output: { output?: string },
-): void {
-  if (!context.gitAutoModeEnabled) return;
-
-  const archiveDir = path.join(context.companionPath, "openspec", "changes", "archive");
-  const changes: string[] = [];
-  if (archiveSnapshot) {
-    for (const entry of detectNewlyArchivedChanges(archiveDir, archiveSnapshot)) {
-      changes.push(entry.slice("YYYY-MM-DD-".length));
-    }
-  }
-  const commandChange =
-    String(input.tool ?? "").toLowerCase() === "bash" ? detectCommandArchive(input, output) : null;
-  if (commandChange && !nudgedCommandChanges.has(commandChange)) {
-    changes.push(commandChange);
-    nudgedCommandChanges.add(commandChange);
-  }
-
-  const uniqueChanges = [...new Set(changes)];
-  if (uniqueChanges.length === 0) return;
-  const nudges = uniqueChanges.map(
-    (change) =>
-      `ACTION REQUIRED: An openspec change (${change}) was just archived. ` +
-      `Immediately invoke the mate-artifact-finish skill to complete the finish pipeline ` +
-      "(invoke the CLI as `mate`, never through a companion-local wrapper path or as `" +
-      "$MATE_COMPANION_BIN_PATH/mate`). " +
-      "`mate artifact finish` resumes from the already-archived change and completes the commit, dated tag, and push itself — " +
-      "do not hand-commit, do not hand-tag, and do not re-apply delta specs manually. " +
-      `Follow the skill's guardrails, completing the non-interactive happy path without asking for confirmation.`,
-  );
-  output.output = [output.output, ...nudges]
-    .flatMap((part) => {
-      const trimmed = (part ?? "").trim();
-      return trimmed ? [trimmed] : [];
-    })
-    .join("\n\n");
-}
-
-const REACT_DOCTOR_VERSION = "0.8.1";
+const REACT_DOCTOR_VERSION = "0.9.13";
 
 const REACT_DOCTOR_NON_LINT_FAILURES = [
   /No React dependency found/i,
@@ -311,37 +105,97 @@ async function runReactDoctorScan(
   }
 }
 
+/**
+ * Keyed by companion so a double-loaded plugin repairs at most once per
+ * session, which is the guarantee the spec asks for.
+ */
+const repairedCompanions = new Set<string>();
+
+/**
+ * Session start is the only point at which the companion may move without
+ * invalidating a read the session has already taken. The launch-environment
+ * gate comes first so a Managed Session does no Git work at all; the consent
+ * gate is the operation's own.
+ */
+export async function repairCompanionGitOnce(
+  context: CompanionContext,
+  client: PluginInput["client"] | undefined,
+  env: Record<string, string | undefined> = process.env,
+): Promise<string[]> {
+  if (!context.companionPath || hasLaunchEnvironment(env)) return [];
+  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.
+   */
+  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;
+}
+
+/** Test seam: the once-per-session guard is process-wide by design. */
+export function resetCompanionGitRepairGuard(): void {
+  repairedCompanions.clear();
+}
+
+/**
+ * Writing artifacts on top of a forked companion is the state in which the
+ * eventual reconciliation destroys work. The verdict comes from `runtime/`, so
+ * the Claude hook and this middleware refuse the same writes for the same
+ * reason — including the launch-environment gate that keeps a Managed
+ * Launch's Git decision authoritative for the session it started.
+ */
+export function refuseForkedCompanionWrite(
+  context: CompanionContext,
+  filePath: string,
+  env: Record<string, string | undefined> = process.env,
+): void {
+  if (!filePath || !isArtifactPath(filePath)) return;
+  if (!normalizeTargetPath(context, filePath).startsWith(path.normalize(context.companionPath))) {
+    return;
+  }
+  const refusal = companionForkRefusal(env, context.companionPath);
+  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];
-type ToolAfterOutput = Parameters<NonNullable<Hooks["tool.execute.after"]>>[1];
-
-interface ArchiveCallSnapshot {
-  sessionID: string;
-  entries: Set<string>;
-}
 
 export const CompanionHooksPlugin: Plugin = async (pluginInput = {} as PluginInput) => {
   const { client, $ } = pluginInput;
-  const context = readContext(process.env.MATE_ARTIFACT_PATH ?? "");
+  const context = readContext();
   if (!context.companionPath || !context.repositoryPath) return {};
 
-  const archiveDir = path.join(context.companionPath, "openspec", "changes", "archive");
-  const archiveCallSnapshots = new Map<string, ArchiveCallSnapshot>();
-  const nudgedCommandChanges = new Set<string>();
+  /**
+   * 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.
+   */
+  await repairCompanionGitOnce(context, client).catch(() => []);
+
   const dirtyReactDoctorSessions = new Set<string>();
   const reactDoctorScansInFlight = new Set<string>();
 
   return {
     event: async ({ event }: PluginEventInput) => {
-      if (event.type === "session.deleted") {
-        const sessionID = event.properties.info.id;
-        for (const [callID, snapshot] of archiveCallSnapshots) {
-          if (snapshot.sessionID === sessionID) archiveCallSnapshots.delete(callID);
-        }
-        return;
-      }
       if (event.type !== "session.idle") return;
       const sessionID = event.properties.sessionID;
       if (
@@ -361,31 +215,21 @@ export const CompanionHooksPlugin: Plugin = async (pluginInput = {} as PluginInp
         if (filePath && shouldBlockArtifactWrite(context, filePath)) {
           throw new Error(buildArtifactError(context, filePath));
         }
+        refuseForkedCompanionWrite(context, filePath);
       }
       if (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.gitAutoModeEnabled) {
-        archiveCallSnapshots.set(input.callID, {
-          sessionID: input.sessionID,
-          entries: readArchiveEntries(archiveDir),
-        });
-      }
     },
-    "tool.execute.after": async (input: ToolAfterInput, output: ToolAfterOutput) => {
+    "tool.execute.after": async (input: ToolAfterInput) => {
       if (context.reactDoctorEnabled && REACT_DOCTOR_EDIT_TOOLS.has(input.tool)) {
         dirtyReactDoctorSessions.add(input.sessionID);
       }
-      const archiveSnapshot = archiveCallSnapshots.get(input.callID)?.entries;
-      archiveCallSnapshots.delete(input.callID);
-      appendOpenSpecFinishNudge(context, archiveSnapshot, nudgedCommandChanges, input, output);
-    },
-    dispose: async () => {
-      archiveCallSnapshots.clear();
     },
   };
 };

package/src/opencode/companion-policy.ts

@@ -2,10 +2,18 @@ import { spawnSync } from "node:child_process";
 import fs from "node:fs";
 import path from "node:path";
 
-import { readCompanionRuntimeContext, type CompanionRuntimeContext } from "../runtime/env";
+import { persistedCompanionGitStalenessLines } from "../runtime/companion-sync";
+import { resolveCompanionRuntime, type CompanionRuntimeContext } from "../runtime/env";
+import { projectionFreshness, projectionStalenessLines } from "../runtime/freshness";
 
 export type CompanionContext = CompanionRuntimeContext & {
   agentsMd: string;
+  /**
+   * Operator-facing session state: a stale projection, and an unfinished
+   * companion Git synchronization. Never reaches a model payload — the TUI is
+   * its only reader.
+   */
+  stalenessLines: string[];
 };
 
 const ARTIFACT_BASENAMES = new Set([
@@ -158,20 +166,37 @@ export function buildArtifactError(context: CompanionContext, filePath: string):
   ].join("\n");
 }
 
-export function readContext(companionPath: string): CompanionContext {
-  const agentsMdPath = path.join(companionPath, "AGENTS.md");
+/**
+ * Resolves its own companion — launch environment first, Projection Root
+ * second — rather than taking one from the caller. `AGENTS.md` follows the
+ * resolved companion so the two cannot name different repositories.
+ */
+export function readContext(
+  env: Record<string, string | undefined> = process.env,
+  cwd: string = process.cwd(),
+): CompanionContext {
+  const { context, projection } = resolveCompanionRuntime(env, cwd);
+
   let agentsMd = "";
-  try {
-    if (fs.existsSync(agentsMdPath)) {
-      agentsMd = fs.readFileSync(agentsMdPath, "utf8");
+  if (context.companionPath) {
+    const agentsMdPath = path.join(context.companionPath, "AGENTS.md");
+    try {
+      if (fs.existsSync(agentsMdPath)) {
+        agentsMd = fs.readFileSync(agentsMdPath, "utf8");
+      }
+    } catch {
+      // Ignore read errors; AGENTS.md is optional
     }
-  } catch {
-    // Ignore read errors; AGENTS.md is optional
   }
 
   return {
-    ...readCompanionRuntimeContext(process.env),
-    companionPath,
+    ...context,
     agentsMd,
+    stalenessLines: projection
+      ? [
+          ...projectionStalenessLines(projection, projectionFreshness(projection)),
+          ...persistedCompanionGitStalenessLines(context.companionPath),
+        ]
+      : [],
   };
 }

package/src/opencode/index.ts

@@ -6,4 +6,5 @@
  */
 export { default as tuiPlugin } from "./tui";
 export { CompanionHooksPlugin } from "./companion-hooks";
+export { resolveOpenCodeGuidance, type OpenCodeGuidanceResolution } from "./projected-guidance";
 export * from "./companion-policy";

package/src/opencode/projected-guidance.ts

@@ -0,0 +1,56 @@
+import { buildOpenCodeGuidance } from "../runtime/companion-guidance";
+import { MATE_ENV } from "../runtime/env-names";
+import { hasLaunchEnvironment } from "../runtime/env";
+import { parseGuidanceContent, type MateGuidanceFile } from "../runtime/guidance";
+import { readCompanionPolicy } from "../runtime/policy";
+import { resolveProjection } from "../runtime/projection";
+
+/**
+ * `null` guidance with no errors is the inert case — no companion resolves, so
+ * the plugin contributes nothing. Errors are startup failures: a managed launch
+ * that failed to inject its payload is broken and must say so.
+ */
+export interface OpenCodeGuidanceResolution {
+  guidance: MateGuidanceFile | null;
+  errors: string[];
+}
+
+/**
+ * The OpenCode guidance payload, from the launch environment when Mate started
+ * the session and from the Projection Root otherwise — the same env-first,
+ * projection-second contract `readCompanionRuntimeContext` already follows.
+ *
+ * The projected branch needs nothing but the enabled Capability names: the
+ * payload carries `$MATE_*` placeholders that the plugin materializes from its
+ * own resolved context, so no path is resolved here. Reading the names live
+ * means a Capability toggled after a wrap changes the guidance on the next
+ * session with no re-wrap.
+ *
+ * A missing payload while a launch environment *is* present stays a hard error.
+ * That combination means a managed launch failed to inject, which the projection
+ * must not paper over.
+ */
+export function resolveOpenCodeGuidance(
+  env: Record<string, string | undefined> = process.env,
+  cwd: string = process.cwd(),
+): OpenCodeGuidanceResolution {
+  const raw = env[MATE_ENV.guidanceJson];
+  if (raw?.trim()) {
+    const { guidance, errors } = parseGuidanceContent(raw);
+    return { guidance: errors.length > 0 ? null : guidance, errors };
+  }
+
+  if (hasLaunchEnvironment(env)) {
+    return {
+      guidance: null,
+      errors: [`missing ${MATE_ENV.guidanceJson} in the launch environment`],
+    };
+  }
+
+  const projection = resolveProjection(cwd);
+  if (!projection) return { guidance: null, errors: [] };
+
+  const policy = readCompanionPolicy(projection.companionPath);
+  const guidance = buildOpenCodeGuidance(policy.enabledCapabilities.map((name) => ({ name })));
+  return { guidance: guidance.errors.length > 0 ? null : guidance, errors: guidance.errors };
+}

package/src/opencode/tui.tsx

@@ -1,12 +1,18 @@
 /** @jsxImportSource @opentui/solid */
-/* oxlint-disable react/no-unknown-property, react/react-in-jsx-scope */
+/* oxlint-disable react/no-unknown-property, react/react-in-jsx-scope, react/jsx-key, react-doctor/jsx-key */
+/**
+ * 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";
 
 const MIDNIGHT_PURPLE_BRIGHT = "#c084fc";
 const NARROW_TERMINAL_WIDTH = 80;
-const MATE_VERSION = process.env.MATE_VERSION ?? "unknown";
+const MATE_VERSION = process.env.MATE_VERSION ?? mateVersion();
 
 function SessionContext({
   api,
@@ -17,7 +23,7 @@ function SessionContext({
   compact?: boolean;
   sidebar?: boolean;
 }) {
-  const context = readContext(process.env.MATE_ARTIFACT_PATH ?? "");
+  const context = readContext();
   const theme = api.theme.current;
 
   if (compact) {
@@ -35,12 +41,15 @@ function SessionContext({
       <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>
+      {context.stalenessLines.map((note) => (
+        <text fg={theme.warning ?? theme.textMuted}>{note}</text>
+      ))}
     </box>
   );
 }
 
 const tui: TuiPlugin = async (api) => {
-  const context = readContext(process.env.MATE_ARTIFACT_PATH ?? "");
+  const context = readContext();
   if (!context.companionPath || !context.repositoryPath) {
     return;
   }