@uniqbit/mate-core 0.17.0-canary.3 → 0.17.0-canary.6

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@uniqbit/mate-core",
-  "version": "0.17.0-canary.3",
+  "version": "0.17.0-canary.6",
   "description": "Core framework and plugin APIs for Mate.",
   "license": "MIT",
   "files": [

package/src/lib/orchestrator/adapters/opencode.ts

@@ -8,7 +8,9 @@ import { validateGuidanceData, type MateGuidanceFile } from "../../../runtime/gu
 import {
   getOpenCodePluginPackageReference,
   isMateOpenCodePluginReference,
+  OPENCODE_PLUGIN_PACKAGE_NAME,
 } from "../../opencode-plugin-package";
+import { installedVersionAt, isPreinstalledPluginPath } from "../../preinstalled-plugins";
 import {
   getOpenCodePluginReferences,
   mergeOpenCodeConfigContent,
@@ -129,6 +131,27 @@ export class OpenCodeAdapter extends LaunchAdapter {
       return [];
     }
 
+    // Setup writes one of two spellings, and both are current: the published
+    // spec on an ordinary workstation, and an absolute path into the
+    // machine-local workspace where the distribution supplied an installed
+    // copy. Comparing only against the spec would refuse the launch on exactly
+    // the deployments preinstalled binding exists for.
+    //
+    // A bound reference carries its version in the package it points at rather
+    // than in the string, so staleness is read off disk. It is still caught,
+    // and now names the version actually installed.
+    const expectedVersion = expectedPluginReference.slice(OPENCODE_PLUGIN_PACKAGE_NAME.length + 1);
+    const bound = mateReferences.find((reference) =>
+      isPreinstalledPluginPath(reference, OPENCODE_PLUGIN_PACKAGE_NAME),
+    );
+    if (bound !== undefined) {
+      const version = await installedVersionAt(bound);
+      if (version === expectedVersion) return [];
+      return [
+        `Stale Mate plugin package reference in ${configFile}: it points at ${bound}, which is ${version ?? "not installed"} rather than ${expectedVersion}.`,
+      ];
+    }
+
     if (mateReferences.length > 0) {
       return [
         `Stale Mate plugin package reference in ${configFile}: found ${mateReferences.join(", ")}.`,

package/src/lib/preinstalled-plugins.ts

@@ -36,6 +36,25 @@ export function isPreinstalledPluginPath(entry: unknown, packageName: string): b
   return normalized.endsWith(`/${packageName}`);
 }
 
+/**
+ * The version behind a reference bound to an installed copy.
+ *
+ * A published reference carries its version in the string; a bound one carries
+ * it in the package it points at, so staleness has to be read off disk. Shared
+ * by every site that validates a bound reference, so they cannot disagree about
+ * what "stale" means.
+ */
+export async function installedVersionAt(packageRoot: string): Promise<string | undefined> {
+  try {
+    const manifest = JSON.parse(
+      await fs.readFile(path.join(packageRoot, "package.json"), "utf8"),
+    ) as { version?: string };
+    return manifest.version;
+  } catch {
+    return undefined;
+  }
+}
+
 export class PreinstalledPluginMismatchError extends Error {}
 
 /**

package/src/tools/setup/capabilities/context-mode.ts

@@ -11,6 +11,7 @@ import {
   validateContextModePackage,
 } from "../../../lib/context-mode-package";
 import { warmOpenCodePackageCache } from "../../../lib/opencode-plugin-package";
+import { installedVersionAt, isPreinstalledPluginPath } from "../../../lib/preinstalled-plugins";
 import type {
   CapabilityPlugin,
   LaunchPreflightContext,
@@ -70,17 +71,43 @@ async function assertNoMcpConflict(ctx: SetupContext, provider: "claude" | "open
   }
 }
 
+/**
+ * Both spellings of a current reference are accepted, because the Runtime
+ * Surface writes either one: the published spec on an ordinary workstation, and
+ * an absolute path into the machine-local workspace where the distribution
+ * supplied an installed copy. Accepting only the first would refuse the launch
+ * on exactly the deployments preinstalled binding exists for.
+ *
+ * Staleness is still caught in both cases — a published reference by its
+ * version, a bound one by the version of the copy it points at — so this is not
+ * the looser check it might look like.
+ */
 async function validateOpenCodeReferences(ctx: LaunchPreflightContext): Promise<string[]> {
   const expected = getContextModePackageReference();
   const diagnostics: string[] = [];
   for (const name of ["opencode.json", "tui.json"]) {
     const configPath = path.join(ctx.companionPath, ".opencode", name);
     const { config } = await readOpenCodeConfig(configPath);
-    if (!getOpenCodePluginReferences(config).includes(expected)) {
+    const references = getOpenCodePluginReferences(config);
+    if (references.includes(expected)) continue;
+
+    const bound = references.find(
+      (reference): reference is string =>
+        typeof reference === "string" &&
+        isPreinstalledPluginPath(reference, CONTEXT_MODE_PACKAGE_NAME),
+    );
+    if (bound !== undefined) {
+      const version = await installedVersionAt(bound);
+      if (version === CONTEXT_MODE_VERSION) continue;
       diagnostics.push(
-        `Missing or stale context-mode package reference in ${configPath}; expected ${expected}.`,
+        `Stale context-mode package reference in ${configPath}; it points at ${bound}, which is ${version ?? "not installed"} rather than ${CONTEXT_MODE_VERSION}.`,
       );
+      continue;
     }
+
+    diagnostics.push(
+      `Missing or stale context-mode package reference in ${configPath}; expected ${expected}.`,
+    );
   }
   return diagnostics;
 }

package/src/tools/setup/capabilities/openspec.ts

@@ -6,7 +6,7 @@ import { promisify } from "node:util";
 import { getOpenSpecSchemaSelection } from "../../../lib/orchestrator/setup-compatibilities";
 import { getWrapperBinPath } from "../../../lib/package-paths";
 import { fetchPublicPackageVersion } from "../../../lib/public-npm";
-import { isNewer } from "../../../lib/update-checker";
+import { isNewer, isPinnedDeployment } from "../../../lib/update-checker";
 import { FRAMEWORK_NAME } from "../../../framework";
 import { confirm } from "../../../cli/confirm";
 import type { CapabilityPlugin, RuntimeContributionsByRuntime, SetupContext } from "../plugin";
@@ -63,6 +63,7 @@ export interface OpenSpecPluginDeps {
   wrapperBinPath?: () => string;
   getInstalledVersion?: (pathValue: string) => Promise<string | undefined>;
   fetchLatestVersion?: () => Promise<string | undefined>;
+  isPinnedDeployment?: () => boolean;
 }
 
 const OPEN_SPEC_SUPPORTED_TOOLS = Object.keys(OPENSPEC_TOOL_DIRS) as OpenSpecTool[];
@@ -170,10 +171,17 @@ async function updateOpenSpecIfOutdated(
   deps: Required<
     Pick<
       OpenSpecPluginDeps,
-      "installCommand" | "pathValue" | "getInstalledVersion" | "fetchLatestVersion"
+      | "installCommand"
+      | "pathValue"
+      | "getInstalledVersion"
+      | "fetchLatestVersion"
+      | "isPinnedDeployment"
     >
   >,
 ): Promise<void> {
+  /** Pinned artifacts change tool versions by replacement, never reconciliation. */
+  if (deps.isPinnedDeployment()) return;
+
   const installed = await deps.getInstalledVersion(deps.pathValue());
   if (!installed) return;
 
@@ -204,6 +212,7 @@ async function ensureOpenSpecInstalled(
       | "pathValue"
       | "getInstalledVersion"
       | "fetchLatestVersion"
+      | "isPinnedDeployment"
     >
   >,
 ): Promise<boolean> {
@@ -326,6 +335,7 @@ export function createOpenspecPlugin(deps: OpenSpecPluginDeps = {}): CapabilityP
     wrapperBinPath: deps.wrapperBinPath ?? getWrapperBinPath,
     getInstalledVersion: deps.getInstalledVersion ?? defaultGetInstalledVersion,
     fetchLatestVersion: deps.fetchLatestVersion ?? defaultFetchLatestVersion,
+    isPinnedDeployment: deps.isPinnedDeployment ?? (() => isPinnedDeployment()),
   };
 
   return {