@brainervirus/workit-core 1.0.2 → 1.0.4

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@brainervirus/workit-core",
-  "version": "1.0.2",
+  "version": "1.0.4",
   "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";
@@ -661,15 +670,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 +717,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 +726,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 +742,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" };
@@ -790,6 +820,30 @@ const checkStaleInstall = (res: Resolved): DoctorCheck & { registryProbed?: bool
       detail: "cursor plugin not inspected on the opencode 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="));
   const mcpSelectors = pluginMcpSelectors(res);
   const legacyPin = (mcpSelectors ?? []).find(
@@ -1035,7 +1089,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);