@brainervirus/workit-core 1.0.3 → 1.0.5

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@brainervirus/workit-core",
-  "version": "1.0.3",
+  "version": "1.0.5",
   "private": false,
   "description": "Workit shared core — task, policy, evidence, review, decision, worker, and writer state for agentic coding workflows",
   "keywords": [

package/src/core/doctor.ts

@@ -9,7 +9,16 @@
 // header for a login lookup — token bytes never enter the report, any fix
 // text, or any log event.
 import { spawnSync } from "node:child_process";
-import { existsSync, mkdirSync, readFileSync, statSync, unlinkSync, writeFileSync } from "node:fs";
+import {
+  existsSync,
+  lstatSync,
+  mkdirSync,
+  readFileSync,
+  readlinkSync,
+  statSync,
+  unlinkSync,
+  writeFileSync,
+} from "node:fs";
 import os from "node:os";
 import path from "node:path";
 import { SUPPORT_MATRIX } from "./support-matrix";
@@ -18,6 +27,7 @@ import { getDiagnosticLogger, isConfigObject } from "./config";
 import { packageRoot } from "./package-root";
 import {
   CURSOR_RUNTIME_PACKAGE,
+  OPENCODE_NPM_PIN,
   cursorHookDrift,
   cursorHooksEntry,
   cursorMcpServerEntry,
@@ -102,6 +112,8 @@ export type DoctorOptions = {
   dev?: string;
   cwd?: string;
   opencodeConfig?: string;
+  /** OpenCode npm `@latest` package cache root (test seam). */
+  opencodePackageCacheDir?: string;
   cursorSettings?: string;
   cursorMcp?: string;
   cursorPluginDir?: string;
@@ -120,6 +132,7 @@ type Resolved = {
   cwd: string;
   dev: string | null;
   opencodeConfig: string;
+  opencodePackageCacheDir: string;
   cursorSettings: string;
   cursorMcp: string;
   cursorPluginDir: string;
@@ -170,6 +183,9 @@ const resolve = (options: DoctorOptions): Resolved => {
     dev,
     opencodeConfig:
       options.opencodeConfig ?? path.join(home, ".config", "opencode", "opencode.json"),
+    opencodePackageCacheDir:
+      options.opencodePackageCacheDir ??
+      path.join(home, ".cache", "opencode", "packages", "@brainervirus", "workit-opencode@latest"),
     cursorSettings: options.cursorSettings ?? path.join(home, ".cursor", "settings.json"),
     cursorMcp: options.cursorMcp ?? path.join(home, ".cursor", "mcp.json"),
     cursorPluginDir:
@@ -661,15 +677,28 @@ const checkUtility = (res: Resolved): DoctorCheck => {
   };
 };
 
-const staleEntry = (entry: string): "ok" | "stale" | "missing-file" => {
+/** file:// pins into package-manager ephemeral caches (pnpm dlx, npx). */
+const isFragileCachePin = (entry: string): boolean => {
+  const n = entry.replaceAll("\\", "/").toLowerCase();
+  if (!n.startsWith("file:")) return false;
+  return (
+    n.includes("/caches/pnpm/dlx/") ||
+    n.includes("/_npx/") ||
+    n.includes("/.pacquet/") ||
+    n.includes("/library/caches/pnpm/")
+  );
+};
+
+const staleEntry = (entry: string): "ok" | "stale" | "missing-file" | "fragile-cache" => {
   if (!entry) return "stale";
   if (entry.includes("git+file")) return "stale";
+  if (isFragileCachePin(entry)) return "fragile-cache";
   if (entry.startsWith("file:")) {
     const target = entry.replace(/^file:\/\//, "").replace(/^file:/, "");
     return existsSync(target) ? "ok" : "missing-file";
   }
-  // registry/ssh/git pins are not the canonical file pin, but are left to the
-  // duplicate/versions checks rather than being labelled stale.
+  // Registry package names (e.g. @brainervirus/workit-opencode) are the
+  // published pin shape — OpenCode resolves them; not labelled stale.
   return "ok";
 };
 
@@ -695,7 +724,7 @@ const checkStalePin = (res: Resolved): DoctorCheck => {
       id: "stale_pin",
       status: "fail",
       detail: "no workit plugin registered in the opencode config",
-      fix: "Run install-opencode-plugin.sh to pin the workit plugin entry",
+      fix: 'Run `workit init` and select OpenCode — pin "@brainervirus/workit-opencode"',
     };
   }
   const first = staleEntry(entries[0]);
@@ -704,7 +733,15 @@ const checkStalePin = (res: Resolved): DoctorCheck => {
       id: "stale_pin",
       status: "fail",
       detail: `stale workit pin: ${entries[0]}`,
-      fix: "Re-run install-opencode-plugin.sh — the pin points at a git+file or non-file source",
+      fix: "Run `workit init` (or install-opencode-plugin.sh for a checkout) — replace git+file pins",
+    };
+  }
+  if (first === "fragile-cache") {
+    return {
+      id: "stale_pin",
+      status: "fail",
+      detail: `workit pin points at a package-manager cache path: ${entries[0]}`,
+      fix: 'Run `workit init` and select OpenCode — pin should be "@brainervirus/workit-opencode"',
     };
   }
   if (first === "missing-file") {
@@ -712,7 +749,7 @@ const checkStalePin = (res: Resolved): DoctorCheck => {
       id: "stale_pin",
       status: "fail",
       detail: `workit pin points at a missing file: ${entries[0]}`,
-      fix: "Re-run install-opencode-plugin.sh after restoring the checkout the pin references",
+      fix: "Run `workit init` (or restore the checkout and re-run install-opencode-plugin.sh)",
     };
   }
   return { id: "stale_pin", status: "pass", detail: "opencode pin resolves" };
@@ -741,6 +778,13 @@ const checkStalePin = (res: Resolved): DoctorCheck => {
 //     `@latest` installs skip the probe entirely: the selector resolves fresh
 //     at launch, so the installed package.json version is metadata, not a
 //     freshness signal.
+// OpenCode npm pins (`@brainervirus/workit-opencode` / `@…@latest`) are different:
+// OpenCode freezes the first resolved version under
+// `~/.cache/opencode/packages/@brainervirus/workit-opencode@latest` and does not
+// re-resolve on later launches. Doctor compares that cache to the published
+// package (same CA-04 fail-open seam) and tells the user to delete the cache
+// directory so OpenCode can resolve `@latest` again. Exact `@version` pins and
+// `file://` checkout pins skip the comparison.
 // Test seams (no spawns on the canonical path): WORKIT_DOCTOR_STALE_REGISTRY_VERSION
 // short-circuits the probe with the resolved latest version; the optional
 // WORKIT_DOCTOR_STALE_REGISTRY_CMD replaces the `npm view` binary (a
@@ -756,7 +800,15 @@ const pluginMcpSelectors = (res: Resolved): string[] | null => {
   return args.map(String).filter((a) => a.startsWith("--package="));
 };
 
-const registryLatestVersion = (res: Resolved): string | null => {
+const isFloatingOpenCodeNpmPin = (entry: string): boolean => {
+  const s = entry.trim();
+  return s === OPENCODE_NPM_PIN || s === `${OPENCODE_NPM_PIN}@latest`;
+};
+
+const registryLatestVersion = (
+  res: Resolved,
+  pkgName: string = CURSOR_RUNTIME_PACKAGE,
+): string | null => {
   const seam = res.env.WORKIT_DOCTOR_STALE_REGISTRY_VERSION;
   if (typeof seam === "string" && seam) {
     return /^\d+(?:\.\d+){1,2}$/.test(seam) ? seam : null;
@@ -765,7 +817,7 @@ const registryLatestVersion = (res: Resolved): string | null => {
     res.env.WORKIT_DOCTOR_STALE_REGISTRY_CMD ?? (commandOnPath("npm", res.env) ? "npm" : null);
   if (!cmd) return null;
   try {
-    const r = spawnSync(cmd, ["view", CURSOR_RUNTIME_PACKAGE, "version"], {
+    const r = spawnSync(cmd, ["view", pkgName, "version"], {
       encoding: "utf8",
       timeout: 20_000,
       env: res.env,
@@ -782,12 +834,120 @@ const installedPluginVersion = (res: Resolved): string | null => {
   return typeof pkg?.version === "string" && pkg.version ? pkg.version : null;
 };
 
+const installedOpenCodeCacheVersion = (res: Resolved): string | null => {
+  const pkg = readJson(
+    path.join(
+      res.opencodePackageCacheDir,
+      "node_modules",
+      "@brainervirus",
+      "workit-opencode",
+      "package.json",
+    ),
+  );
+  return typeof pkg?.version === "string" && pkg.version ? pkg.version : null;
+};
+
+/** OpenCode freezes the first `@latest` resolve in its package cache — detect lag. */
+const checkOpenCodePackageCache = (res: Resolved): DoctorCheck & { registryProbed?: boolean } => {
+  if (!existsSync(res.opencodeConfig)) {
+    return {
+      id: "stale_install",
+      status: "pass",
+      detail: "no opencode config — package cache not inspected",
+    };
+  }
+  const entries = pluginEntries(readJson(res.opencodeConfig));
+  if (entries.length === 0) {
+    return {
+      id: "stale_install",
+      status: "pass",
+      detail: "no workit opencode pin — package cache not inspected",
+    };
+  }
+  const pin = entries[0]!;
+  if (pin.startsWith("file:") || pin.startsWith("git+file:")) {
+    return {
+      id: "stale_install",
+      status: "pass",
+      detail: "opencode checkout pin — package cache not used for npm resolution",
+    };
+  }
+  if (!isFloatingOpenCodeNpmPin(pin)) {
+    return {
+      id: "stale_install",
+      status: "pass",
+      detail: `opencode pin ${pin} is an exact version — not compared to registry latest`,
+    };
+  }
+  const installed = installedOpenCodeCacheVersion(res);
+  if (installed === null) {
+    return {
+      id: "stale_install",
+      status: "pass",
+      detail: "opencode @latest package cache empty — OpenCode will resolve on next launch",
+    };
+  }
+  const expected = registryLatestVersion(res, OPENCODE_NPM_PIN);
+  if (expected === null) {
+    return {
+      id: "registry_unreachable",
+      status: "warn",
+      registryProbed: true,
+      detail:
+        "registry_unreachable: cannot compare OpenCode @latest cache against published workit-opencode",
+      fix: `Retry when npm is reachable, or remove ${res.opencodePackageCacheDir} and restart OpenCode to re-resolve`,
+    };
+  }
+  if (!semverAtLeast(installed, expected)) {
+    return {
+      id: "stale_install",
+      status: "fail",
+      registryProbed: true,
+      detail: `stale_install: OpenCode @latest cache has workit-opencode ${installed} behind published ${expected}`,
+      fix: `Remove ${res.opencodePackageCacheDir} and restart OpenCode — it re-resolves @latest on the next launch`,
+    };
+  }
+  return {
+    id: "stale_install",
+    status: "pass",
+    registryProbed: true,
+    detail: `OpenCode @latest cache workit-opencode ${installed} matches published ${expected}`,
+  };
+};
+
 const checkStaleInstall = (res: Resolved): DoctorCheck & { registryProbed?: boolean } => {
+  if (res.host === "opencode") {
+    return checkOpenCodePackageCache(res);
+  }
   if (res.host !== "cursor" && res.host !== "cli") {
     return {
       id: "stale_install",
       status: "pass",
-      detail: "cursor plugin not inspected on the opencode host",
+      detail: "cursor plugin not inspected on this host",
+    };
+  }
+  // Symlink installs into pnpm dlx / _npx caches break when the cache is cleared.
+  // MCP launchers may still be canonical; the plugin dir itself must be real.
+  if (existsSync(res.cursorPluginDir) && lstatSync(res.cursorPluginDir).isSymbolicLink()) {
+    let target = "";
+    try {
+      target = readlinkSync(res.cursorPluginDir);
+    } catch {
+      target = "(unreadable)";
+    }
+    const n = target.replaceAll("\\", "/").toLowerCase();
+    const fragile =
+      n.includes("/caches/pnpm/dlx/") ||
+      n.includes("/_npx/") ||
+      n.includes("/.pacquet/") ||
+      n.includes("/library/caches/pnpm/");
+    return {
+      id: "stale_install",
+      status: "fail",
+      detail: fragile
+        ? `stale_install: cursor plugin dir is a symlink into a package-manager cache (${target})`
+        : `stale_install: cursor plugin dir is a symlink (${target}) — expected a real directory copy`,
+      fix: "Run `workit init` and select Cursor — install must copy into ~/.cursor/plugins/local/workit",
     };
   }
   const canonicalMcp = cursorMcpServerEntry("").args.find((a) => a.startsWith("--package="));
@@ -876,21 +1036,31 @@ const checkStaleInstall = (res: Resolved): DoctorCheck & { registryProbed?: bool
         fix: "Re-run install-cursor-plugin.sh — it refreshes the plugin directory with the current build",
       };
     }
-    return {
-      id: "stale_install",
-      status: "pass",
+    const cursorOk = {
+      id: "stale_install" as const,
+      status: "pass" as const,
       registryProbed: true,
       detail: `installed local-dist workit-cursor ${installed} matches the published runtime ${expected}`,
     };
+    if (res.host === "cli") {
+      const oc = checkOpenCodePackageCache(res);
+      if (oc.status !== "pass") return oc;
+    }
+    return cursorOk;
   }
-  return {
-    id: "stale_install",
-    status: "pass",
+  const cursorOk = {
+    id: "stale_install" as const,
+    status: "pass" as const,
     detail:
       installed === null
         ? "installed workit-cursor selectors are canonical"
         : `installed workit-cursor ${installed} is metadata on the canonical @latest install (fresh at launch)`,
   };
+  if (res.host === "cli") {
+    const oc = checkOpenCodePackageCache(res);
+    if (oc.status !== "pass") return oc;
+  }
+  return cursorOk;
 };
 
 const checkDuplicateRegistration = (res: Resolved): DoctorCheck => {
@@ -1035,7 +1205,16 @@ const checkCredentialMetadata = (res: Resolved): DoctorCheck => {
   }
 
   const vcsJson = readJson(path.join(res.configDir, "vcs.json"));
-  for (const key of ["gitlab", "github"] as const) {
+  // Only the active VCS provider's token is required. vcs.json scaffolds both
+  // github and gitlab blocks for switching later — inactive tokenFile paths
+  // must not fail the doctor when provider is set to the other host.
+  const active =
+    typeof vcsJson?.provider === "string" ? vcsJson.provider.trim().toLowerCase() : null;
+  const vcsKeys =
+    active === "gitlab" || active === "github"
+      ? ([active] as const)
+      : (["gitlab", "github"] as const);
+  for (const key of vcsKeys) {
     const provider = vcsJson?.[key];
     if (provider && typeof provider === "object") {
       const tf = provider.tokenFile;

package/src/core/registration.ts

@@ -6,6 +6,9 @@
 // there is exactly one source of truth for registration merging.
 import path from "node:path";
 
+/** Canonical published OpenCode plugin identity (OpenCode resolves from npm). */
+export const OPENCODE_NPM_PIN = "@brainervirus/workit-opencode";
+
 export interface MergeResult<T> {
   config: T;
   changed: string[];

package/src/core/setup.ts

@@ -2,10 +2,12 @@ import {
   copyFileSync,
   cpSync,
   existsSync,
+  lstatSync,
   mkdirSync,
   mkdtempSync,
   readFileSync,
   readdirSync,
+  realpathSync,
   renameSync,
   rmSync,
   statSync,
@@ -38,6 +40,7 @@ import {
   mergeCursorMcp,
   mergeCursorSettings,
   mergeOpenCodeConfig,
+  OPENCODE_NPM_PIN,
 } from "./registration";
 import { runDoctor, type DoctorReport } from "./doctor";
 import { writeFileExclusive } from "./safe-write";
@@ -750,7 +753,19 @@ function adapterRoot(platform: Platform, res: ResolvedApply): string | null {
   return null;
 }
 
-const opencodePin = (root: string): string | null => {
+/** True when the adapter root is a monorepo checkout (dev pin), not a packed node_modules install. */
+export const isDevOpenCodeAdapterRoot = (root: string, dev: string | null | undefined): boolean => {
+  if (dev) return true;
+  const norm = root.replaceAll("\\", "/");
+  return /\/packages\/workit-opencode\/?$/.test(norm);
+};
+
+/** Published installs pin the npm package; checkout installs pin file:// entry. */
+export const resolveOpenCodePin = (
+  root: string,
+  opts: { dev?: string | null } = {},
+): string | null => {
+  if (!isDevOpenCodeAdapterRoot(root, opts.dev)) return OPENCODE_NPM_PIN;
   for (const rel of ["src/plugin.ts", "dist/plugin.js"]) {
     const entry = path.join(root, rel);
     if (existsSync(entry)) return `file://${entry}`;
@@ -758,8 +773,11 @@ const opencodePin = (root: string): string | null => {
   return null;
 };
 
+const opencodePin = (root: string, res: ResolvedApply): string | null =>
+  resolveOpenCodePin(root, { dev: res.dev });
+
 function applyOpenCode(root: string, res: ResolvedApply): SetupResultEntry {
-  const pin = opencodePin(root);
+  const pin = opencodePin(root, res);
   if (!pin) {
     return {
       platform: "opencode",
@@ -853,28 +871,39 @@ const preservedCursorRules = (src: string, dest: string): Map<string, Buffer> =>
   return preserved;
 };
 
-function copyPluginDir(src: string, dest: string): SetupResultStatus {
+/** Install Cursor plugin files as a real directory (never a symlink into a package cache). */
+export function copyPluginDir(src: string, dest: string): SetupResultStatus {
+  // pnpm dlx/pacquet (and similar) expose packages as symlinks into a content
+  // store. Node's cpSync copies a symlink *root* as a symlink, so the installed
+  // plugin would point into an ephemeral cache. Always materialize from the
+  // realpath so ~/.cursor/plugins/local/workit is a real directory.
+  const realSrc = realpathSync(src);
   const marker = path.join(dest, ".workit-root");
-  const synced = readFileSafe(marker)?.trim() === src && samePluginContent(src, dest);
+  const destIsLink = existsSync(dest) && lstatSync(dest).isSymbolicLink();
+  const synced =
+    !destIsLink && readFileSafe(marker)?.trim() === realSrc && samePluginContent(realSrc, dest);
   if (synced) return "Skipped";
   const hadDir = existsSync(dest);
-  const rules = preservedCursorRules(src, dest);
+  const rules = preservedCursorRules(realSrc, dest);
   const parent = path.dirname(dest);
   mkdirSync(parent, { recursive: true });
   const swap = mkdtempSync(path.join(parent, `.${path.basename(dest)}.swap-`));
   const stage = path.join(swap, "stage");
   const backup = path.join(swap, "backup");
   try {
-    cpSync(src, stage, {
+    cpSync(realSrc, stage, {
       recursive: true,
-      filter: (entry) => !path.relative(src, entry).split(path.sep).includes("node_modules"),
+      filter: (entry) => !path.relative(realSrc, entry).split(path.sep).includes("node_modules"),
     });
     for (const [name, content] of rules) {
       mkdirSync(path.join(stage, "rules"), { recursive: true });
       writeFileSync(path.join(stage, "rules", name), content);
     }
-    writeFileSync(path.join(stage, ".workit-root"), src + "\n", "utf8");
-    if (!samePluginContent(src, stage)) throw new Error("staged adapter content is incomplete");
+    writeFileSync(path.join(stage, ".workit-root"), realSrc + "\n", "utf8");
+    if (!samePluginContent(realSrc, stage)) throw new Error("staged adapter content is incomplete");
+    if (lstatSync(stage).isSymbolicLink()) {
+      throw new Error("staged adapter resolved to a symlink — refusing fragile cache install");
+    }
     if (hadDir) renameSync(dest, backup);
     try {
       renameSync(stage, dest);