@uniqbit/mate-core 0.18.3-canary.1 → 0.18.4

package/src/lib/runtime-directory-refresh.ts

@@ -0,0 +1,186 @@
+import crypto from "node:crypto";
+import fsSync from "node:fs";
+import fs from "node:fs/promises";
+import path from "node:path";
+
+import { FRAMEWORK_NAME } from "../framework";
+import {
+  runtimeDirectoryPath,
+  runtimeClaudePluginRoot,
+  runtimeMateBin,
+  runtimeOpenCodePluginRoot,
+  runtimeWrapperBinPath,
+} from "../runtime/runtime-directory";
+import { writeAtomic } from "../runtime/write-atomic";
+import { realLinkTarget, realOrResolved } from "./fs-utils";
+import { getClaudePluginRoot, getOpenCodePluginRoot, getWrapperBinPath } from "./package-paths";
+
+export interface RuntimeDirectoryTargets {
+  pluginRoot: string;
+  claudePluginRoot: string;
+  /** The resolved `wrappers/bin`; its parent is what the `wrappers` link names. */
+  wrapperBinPath: string;
+  /** The interpreter running this CLI, written into the launcher. */
+  execPath: string;
+  cliEntry: string;
+}
+
+export interface RuntimeDirectoryRefresh {
+  /** Entries rewritten by this run, relative to the runtime directory. */
+  changed: string[];
+}
+
+/**
+ * `process.execPath` is the resolved, often versioned, binary (Homebrew's
+ * `Cellar/bun/<version>/bin/bun`), which an upgrade deletes. A `PATH` entry of
+ * the same name that is a link to it survives the upgrade; without one the
+ * resolved path is all there is.
+ */
+export function stableInterpreterPath(
+  execPath: string,
+  pathValue: string | undefined = process.env.PATH,
+): string {
+  let real: string;
+  try {
+    real = fsSync.realpathSync(execPath);
+  } catch {
+    return execPath;
+  }
+  const name = path.basename(execPath);
+  for (const dir of (pathValue ?? "").split(path.delimiter).filter(Boolean)) {
+    const candidate = path.join(dir, name);
+    if (candidate === real) continue;
+    try {
+      if (fsSync.realpathSync(candidate) === real) return candidate;
+    } catch {
+      /* not on this PATH entry */
+    }
+  }
+  return execPath;
+}
+
+function currentRuntimeDirectoryTargets(): RuntimeDirectoryTargets {
+  return {
+    pluginRoot: getOpenCodePluginRoot(),
+    claudePluginRoot: getClaudePluginRoot(),
+    wrapperBinPath: getWrapperBinPath(),
+    execPath: stableInterpreterPath(process.execPath),
+    cliEntry: path.resolve(process.argv[1] ?? ""),
+  };
+}
+
+/** The link's {@link realLinkTarget}; `""` when not a link, `null` when absent. */
+async function readLinkTarget(linkPath: string): Promise<string | null> {
+  try {
+    const stat = await fs.lstat(linkPath);
+    if (!stat.isSymbolicLink()) return "";
+    return await realLinkTarget(linkPath, await fs.readlink(linkPath));
+  } catch (error) {
+    if ((error as NodeJS.ErrnoException).code === "ENOENT") return null;
+    throw error;
+  }
+}
+
+/**
+ * Junctions on Windows need no admin rights or Developer Mode. On POSIX a
+ * sibling link renamed over the old one keeps concurrent runs from ever seeing
+ * the entry missing.
+ */
+async function pointLink(linkPath: string, target: string): Promise<boolean> {
+  const [current, wanted] = await Promise.all([readLinkTarget(linkPath), realOrResolved(target)]);
+  if (current === wanted) return false;
+  await fs.mkdir(path.dirname(linkPath), { recursive: true });
+  if (process.platform === "win32") {
+    await fs.rm(linkPath, { recursive: true, force: true });
+    await fs.symlink(target, linkPath, "junction");
+    return true;
+  }
+  /** A rename cannot replace a real directory or file. */
+  if (current === "") await fs.rm(linkPath, { recursive: true, force: true });
+  const tempPath = `${linkPath}.${crypto.randomUUID()}.tmp`;
+  try {
+    await fs.symlink(target, tempPath, "dir");
+    await fs.rename(tempPath, linkPath);
+  } catch (error) {
+    await fs.rm(tempPath, { force: true }).catch(() => {});
+    throw error;
+  }
+  return true;
+}
+
+function shellQuote(value: string): string {
+  return `'${value.replaceAll("'", `'\\''`)}'`;
+}
+
+function launcherContent(targets: RuntimeDirectoryTargets, platform: NodeJS.Platform): string {
+  if (platform === "win32") {
+    return `@echo off\r\n"${targets.execPath}" "${targets.cliEntry}" %*\r\n`;
+  }
+  return `#!/bin/sh\nexec ${shellQuote(targets.execPath)} ${shellQuote(targets.cliEntry)} "$@"\n`;
+}
+
+async function writeLauncher(
+  launcherPath: string,
+  targets: RuntimeDirectoryTargets,
+): Promise<boolean> {
+  const next = launcherContent(targets, process.platform);
+  const existing = await fs.readFile(launcherPath, "utf8").catch(() => null);
+  if (existing === next) return false;
+  await fs.mkdir(path.dirname(launcherPath), { recursive: true });
+  await writeAtomic(launcherPath, next, 0o755);
+  return true;
+}
+
+/** Re-points or rewrites only the entries whose target differs from `targets`. */
+export async function refreshRuntimeDirectory(
+  targets: RuntimeDirectoryTargets = currentRuntimeDirectoryTargets(),
+  homeDir?: string,
+): Promise<RuntimeDirectoryRefresh> {
+  const root = runtimeDirectoryPath(homeDir);
+  const launcherPath = runtimeMateBin(homeDir);
+  const changed: string[] = [];
+  if (await pointLink(runtimeOpenCodePluginRoot(homeDir), targets.pluginRoot)) {
+    changed.push("opencode-plugin");
+  }
+  if (await pointLink(runtimeClaudePluginRoot(homeDir), targets.claudePluginRoot)) {
+    changed.push("claude-plugin");
+  }
+  const wrappersLink = path.dirname(runtimeWrapperBinPath(homeDir));
+  if (await pointLink(wrappersLink, path.dirname(targets.wrapperBinPath))) {
+    changed.push("wrappers");
+  }
+  if (await writeLauncher(launcherPath, targets)) {
+    changed.push(path.relative(root, launcherPath).split(path.sep).join("/"));
+  }
+  return { changed };
+}
+
+/** Commands whose output names runtime-directory paths cannot run without it. */
+const RUNTIME_DIRECTORY_COMMANDS = new Set(["wrap", "opencode", "session"]);
+
+function runtimeDirectoryRequired(command: string | undefined): boolean {
+  return command !== undefined && RUNTIME_DIRECTORY_COMMANDS.has(command);
+}
+
+/**
+ * Startup refresh: a failure warns, except for the commands that write or
+ * consume runtime-directory paths, where it is returned as fatal.
+ */
+export async function ensureRuntimeDirectory(
+  command: string | undefined,
+  refresh: () => Promise<RuntimeDirectoryRefresh> = () => refreshRuntimeDirectory(),
+): Promise<boolean> {
+  try {
+    await refresh();
+    return true;
+  } catch (error) {
+    const detail = error instanceof Error ? error.message : String(error);
+    const message = `failed to update ${runtimeDirectoryPath()}: ${detail}`;
+    if (runtimeDirectoryRequired(command)) {
+      console.error(`${FRAMEWORK_NAME}: ${message}`);
+      return false;
+    }
+    console.error(`${FRAMEWORK_NAME}: warning: ${message}`);
+    return true;
+  }
+}

package/src/lib/update-checker.ts

@@ -99,6 +99,11 @@ export function isCanaryVersion(version: string = getCurrentVersion()): boolean
   return version.includes("-canary");
 }
 
+/** Versions packed by `pack-local.sh` (`x.y.z-local.n`) are local test builds. */
+export function isLocalVersion(version: string = getCurrentVersion()): boolean {
+  return version.includes("-local");
+}
+
 export type UpdateChannel = "latest" | "canary";
 
 export function getUpdateChannel(version: string = getCurrentVersion()): UpdateChannel {
@@ -134,6 +139,7 @@ export async function showUpdateBannerIfAvailable(store: UpdateStateStore): Prom
 export async function enforceUpdateIfRequired(store: UpdateStateStore): Promise<boolean> {
   if (isPinnedDeployment()) return false;
   if (!getUpdateConfig().enforce) return false;
+  if (isLocalVersion()) return false;
   try {
     const state = await store.load();
     if (!state.latestVersion) return false;

package/src/opencode/companion-hooks.ts

@@ -1,8 +1,6 @@
-import { spawn } from "node:child_process";
-import fs from "node:fs";
 import path from "node:path";
 
-import type { Cleanup, Context } from "@opencode/plugin/promise/plugin";
+import type { Context } from "@opencode/plugin/promise/plugin";
 
 import {
   companionForkRefusal,
@@ -11,6 +9,8 @@ import {
 } from "../runtime/companion-sync";
 import { hasLaunchEnvironment } from "../runtime/env";
 import { MATE_ENV } from "../runtime/env-names";
+import { resolveProjection } from "../runtime/projection";
+import { readWrapStateSync } from "../runtime/wrap-state";
 import {
   buildArtifactError,
   extractPatchPaths,
@@ -20,103 +20,13 @@ import {
   type CompanionContext,
 } from "./companion-policy";
 
-const REACT_DOCTOR_VERSION = "0.9.13";
-
-const REACT_DOCTOR_NON_LINT_FAILURES = [
-  /No React dependency found/i,
-  /Could not resolve config/i,
-  /is not a git repository/i,
-];
-
-const REACT_DOCTOR_EDIT_TOOLS = new Set(["write", "edit", "apply_patch"]);
-const REACT_DOCTOR_ARGS = [
-  "--yes",
-  "--verbose",
-  "--scope",
-  "changed",
-  "--base",
-  "HEAD",
-  "--blocking",
-  "warning",
-  "--no-score",
-  "--max-duration",
-  "30",
-];
-
-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],
-      };
-}
-
-/**
- * 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>();
-
-  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);
-      }
-    },
-  };
+/** The Working Repository above `directory`, when it is wrapped for OpenCode. */
+export function repositoryWrappedForOpenCode(directory: string): string | undefined {
+  const projection = resolveProjection(directory);
+  if (!projection || !readWrapStateSync(projection.repoRoot).runtimes.has("opencode")) {
+    return undefined;
+  }
+  return projection.repoRoot;
 }
 
 /**
@@ -126,14 +36,17 @@ export function createReactDoctorScanner(
 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.
+ * A fetch at session start, for a location Session Prepare does not serve.
+ * In a repository wrapped for OpenCode the plugin's background sync performs
+ * the same unattended operation, so this one steps aside. Elsewhere it only
+ * tries the companion lock: a held lock means another sync is already on it.
+ * 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,
   env: Record<string, string | undefined> = process.env,
+  directory?: string,
 ): Promise<string[]> {
   if (
     !context.companionPath ||
@@ -141,6 +54,7 @@ export async function repairCompanionGitOnce(
       (env[MATE_ENV.repositoryPath] !== undefined || env[MATE_ENV.gitAutoMode] !== "1"))
   )
     return [];
+  if (directory && repositoryWrappedForOpenCode(directory)) return [];
   if (repairedCompanions.has(context.companionPath)) return [];
   repairedCompanions.add(context.companionPath);
 
@@ -149,7 +63,10 @@ export async function repairCompanionGitOnce(
    * unattended. The V2 server API has no toast; the notes reach the operator
    * through the persisted record and the TUI's staleness lines.
    */
-  return unattendedSyncStalenessLines(await syncCompanionUnattended(context.companionPath));
+  return unattendedSyncStalenessLines(
+    await syncCompanionUnattended(context.companionPath, { lock: "try" }),
+    "opencode",
+  );
 }
 
 /** Test seam: the once-per-session guard is process-wide by design. */
@@ -182,6 +99,7 @@ export async function guardToolInput(
   context: CompanionContext,
   tool: string,
   input: unknown,
+  env: Record<string, string | undefined> = process.env,
 ): Promise<void> {
   const args = (input ?? {}) as Record<string, unknown>;
   const filePaths =
@@ -196,50 +114,27 @@ export async function guardToolInput(
       throw new Error(buildArtifactError(context, filePath));
     }
     // oxlint-disable-next-line no-await-in-loop -- the first refusal wins
-    await refuseForkedCompanionWrite(context, filePath);
+    await refuseForkedCompanionWrite(context, filePath, env);
   }
 }
 
-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.
+ * The caller resolves `context` and skips this when no companion resolved;
+ * `env` is the launch environment the caller decided to trust.
  */
 export async function registerCompanionHooks(
   api: Context,
   context: CompanionContext,
-  options: CompanionHooksOptions = {},
-): Promise<Cleanup | undefined> {
+  env: Record<string, string | undefined> = process.env,
+): Promise<void> {
   /**
    * Anything escaping the repair would cost the session every guardrail
    * below to save a synchronization that is optional by design.
    */
-  await repairCompanionGitOnce(context).catch(() => []);
+  await repairCompanionGitOnce(context, env, api.location.directory).catch(() => []);
 
   await api.tool.hook("execute.before", (event) =>
-    guardToolInput(context, event.tool, event.input),
+    guardToolInput(context, event.tool, event.input, env),
   );
-
-  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);
-  });
-
-  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/companion-policy.ts

@@ -5,6 +5,7 @@ import path from "node:path";
 import { persistedCompanionGitStalenessLines } from "../runtime/companion-sync";
 import { resolveCompanionRuntime, type CompanionRuntimeContext } from "../runtime/env";
 import { projectionFreshness, projectionStalenessLines } from "../runtime/freshness";
+import { readSessionNotes } from "./session-notes";
 
 export type CompanionContext = CompanionRuntimeContext & {
   agentsMd: string;
@@ -189,14 +190,29 @@ export function readContext(
     }
   }
 
-  return {
-    ...context,
-    agentsMd,
-    stalenessLines: projection
-      ? [
-          ...projectionStalenessLines(projection, projectionFreshness(projection)),
-          ...persistedCompanionGitStalenessLines(context.companionPath),
-        ]
-      : [],
-  };
+  return { ...context, agentsMd, stalenessLines: stalenessLinesFor(context, projection) };
+}
+
+function stalenessLinesFor(
+  context: CompanionRuntimeContext,
+  projection: ReturnType<typeof resolveCompanionRuntime>["projection"],
+): string[] {
+  if (!projection) return [];
+  /** A sync note repeats the persisted Git line it came from. */
+  return [
+    ...new Set([
+      ...projectionStalenessLines(projection, projectionFreshness(projection)),
+      ...persistedCompanionGitStalenessLines(context.companionPath, undefined, "opencode"),
+      ...(context.repositoryPath ? readSessionNotes(context.repositoryPath) : []),
+    ]),
+  ];
+}
+
+/** The session state alone, cheap enough for the TUI to poll: no `AGENTS.md` read, no Git. */
+export function readStalenessLines(
+  env: Record<string, string | undefined> = process.env,
+  cwd: string = process.cwd(),
+): string[] {
+  const { context, projection } = resolveCompanionRuntime(env, cwd);
+  return stalenessLinesFor(context, projection);
 }

package/src/opencode/index.ts

@@ -5,12 +5,6 @@
  * test). Must not reach OpenTUI or Solid: the Mate TUI plugin lives on the
  * `./opencode/tui` subpath.
  */
-export {
-  createReactDoctorScanner,
-  guardToolInput,
-  registerCompanionHooks,
-  type CommandRunner,
-  type CompanionHooksOptions,
-} from "./companion-hooks";
+export { guardToolInput, registerCompanionHooks } from "./companion-hooks";
 export { resolveOpenCodeGuidance, type OpenCodeGuidanceResolution } from "./projected-guidance";
 export * from "./companion-policy";

package/src/opencode/projected-guidance.ts

@@ -1,14 +1,13 @@
 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.
+ * the plugin contributes nothing. Errors are startup failures: a payload that
+ * does not parse, or projected guidance that cannot be built.
  */
 export interface OpenCodeGuidanceResolution {
   guidance: MateGuidanceFile | null;
@@ -26,9 +25,10 @@ export interface OpenCodeGuidanceResolution {
  * 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.
+ * Without a payload the projection decides, whatever other `MATE_*` variables
+ * `env` carries: those are inherited by every descendant of a Mate session and
+ * do not mark a managed launch. A present but malformed payload stays a hard
+ * error.
  */
 export function resolveOpenCodeGuidance(
   env: Record<string, string | undefined> = process.env,
@@ -40,13 +40,6 @@ export function resolveOpenCodeGuidance(
     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: [] };
 

package/src/opencode/session-notes.ts

@@ -0,0 +1,76 @@
+import fs from "node:fs";
+import fsp from "node:fs/promises";
+import path from "node:path";
+
+import { repoLocalDirPath } from "../runtime/repo-local";
+import { writeAtomic } from "../runtime/write-atomic";
+
+/**
+ * The last plugin prepare's operator notes, per phase. The V2 server API has
+ * no toast, so the TUI reads them with its staleness lines and toasts new ones.
+ */
+export type SessionNotePhase = "prepare" | "sync";
+
+type SessionNotes = Partial<Record<SessionNotePhase, string[]>>;
+
+function notesPath(repoPath: string): string {
+  return path.join(repoLocalDirPath(repoPath), "session-notes.json");
+}
+
+function readAll(repoPath: string): SessionNotes {
+  try {
+    const parsed = JSON.parse(fs.readFileSync(notesPath(repoPath), "utf8")) as unknown;
+    return typeof parsed === "object" && parsed !== null ? (parsed as SessionNotes) : {};
+  } catch {
+    return {};
+  }
+}
+
+/**
+ * Per notes file, the record still in flight. Each record reads the file and
+ * writes it back; the background sync's report can overlap the next prepare's,
+ * and an unordered write would bring back notes the other just cleared.
+ */
+const inFlight = new Map<string, Promise<void>>();
+
+/** Replaces one phase's notes; an empty list clears them. Best-effort. */
+export function recordSessionNotes(
+  repoPath: string,
+  phase: SessionNotePhase,
+  notes: readonly string[],
+): Promise<void> {
+  const target = notesPath(repoPath);
+  const recorded = (inFlight.get(target) ?? Promise.resolve()).then(() =>
+    writeNotes(repoPath, target, phase, notes),
+  );
+  inFlight.set(target, recorded);
+  void recorded.then(() => {
+    if (inFlight.get(target) === recorded) inFlight.delete(target);
+  });
+  return recorded;
+}
+
+async function writeNotes(
+  repoPath: string,
+  target: string,
+  phase: SessionNotePhase,
+  notes: readonly string[],
+): Promise<void> {
+  const next: SessionNotes = { ...readAll(repoPath), [phase]: [...notes] };
+  try {
+    if (Object.values(next).every((lines) => !lines?.length)) {
+      await fsp.rm(target, { force: true });
+      return;
+    }
+    await fsp.mkdir(path.dirname(target), { recursive: true });
+    await writeAtomic(target, `${JSON.stringify(next, null, 2)}\n`);
+  } catch {
+    /* the log already carries the notes */
+  }
+}
+
+export function readSessionNotes(repoPath: string): string[] {
+  return Object.values(readAll(repoPath)).flatMap((lines) =>
+    Array.isArray(lines) ? lines.filter((line) => typeof line === "string") : [],
+  );
+}