Add sidecar plugin version doctor check

chenbo · chenbo · commit 868a34de2f5d · 2026-06-20T19:45:31.000+08:00
diff --git a/README.en.md b/README.en.md
@@ -65,7 +65,7 @@ It stays quiet by default and only interrupts the TUI when blockers are found.
 opencode-plusplus          # OpenCode chat mode with the OpenCode++ sidecar
 opencode-plusplus report   # show the latest sidecar check
 opencode-plusplus status   # show whether the sidecar is active
-opencode-plusplus doctor   # diagnose OpenCode / auth / git / context / plugin
+opencode-plusplus doctor   # diagnose OpenCode / auth / git / context / plugin version
 opencode-plusplus --pure   # plain OpenCode without OpenCode++
 ```
 
diff --git a/README.md b/README.md
@@ -64,7 +64,7 @@ OpenCode++ 会在外层安静运行：
 opencode-plusplus          # 进入 OpenCode 聊天模式，并自动启用 OpenCode++ sidecar
 opencode-plusplus report   # 查看最近一次检查结果
 opencode-plusplus status   # 查看 sidecar 是否 active
-opencode-plusplus doctor   # 诊断 OpenCode / auth / git / context / plugin
+opencode-plusplus doctor   # 诊断 OpenCode / auth / git / context / plugin version
 opencode-plusplus --pure   # 纯 OpenCode，不启用 OpenCode++
 ```
 
diff --git a/docs/integrations/opencode-sidecar.md b/docs/integrations/opencode-sidecar.md
@@ -130,7 +130,7 @@ opencode-plusplus sidecar verify
 
 `opencode-plusplus report` opens `.agent-context/sidecar/latest.md`.
 
-`opencode-plusplus doctor` checks OpenCode, auth, git, context, plugin, and sidecar readiness.
+`opencode-plusplus doctor` checks OpenCode, auth, git, context, sidecar plugin readiness, and CLI/plugin version consistency.
 
 `opencode-plusplus sidecar verify` runs the shared guard stack and writes the latest sidecar report. It is also what the plugin runs automatically on idle when the repository is dirty.
 
diff --git a/docs/reference/cli-help-snapshot.md b/docs/reference/cli-help-snapshot.md
@@ -22,7 +22,7 @@ Commands:
   sidecar                                   Inspect and verify OpenCode++ sidecar integrations.
   report [options] [repo]                   Show the latest OpenCode++ sidecar report.
   status [options] [repo]                   Show whether the OpenCode++ OpenCode sidecar is active.
-  doctor [options] [repo]                   Check OpenCode, auth, git, context, and OpenCode++ sidecar readiness.
+  doctor [options] [repo]                   Check OpenCode, auth, git, context, plugin version, and OpenCode++ sidecar readiness.
   opencode                                  OpenCode preset commands.
   oc                                        Shortcut for OpenCode preset commands.
   build [options] [repo]                    Generate AGENTS.md and .agent-context outputs.
@@ -206,7 +206,8 @@ Options:
 ```txt
 Usage: opencode-plusplus doctor [options] [repo]
 
-Check OpenCode, auth, git, context, and OpenCode++ sidecar readiness.
+Check OpenCode, auth, git, context, plugin version, and OpenCode++ sidecar
+readiness.
 
 Arguments:
   repo        repository path (default: ".")
@@ -231,8 +232,8 @@ Commands:
                            opencode run -> trace/policy/verify -> decision.
   init [options] [repo]    Initialize OpenCode commands and agent files for
                            OpenCode++.
-  doctor [options] [repo]  Check whether OpenCode and the current repository are
-                           ready for the OpenCode preset.
+  doctor [options] [repo]  Check whether OpenCode, plugin version, and the
+                           current repository are ready for the OpenCode preset.
   report [options] [repo]  Show the latest OpenCode orchestrator report without
                            opening .agent-context manually.
   repair [options] [repo]  Print repair guidance from the latest OpenCode
@@ -303,8 +304,8 @@ Options:
 ```txt
 Usage: opencode-plusplus opencode doctor [options] [repo]
 
-Check whether OpenCode and the current repository are ready for the OpenCode
-preset.
+Check whether OpenCode, plugin version, and the current repository are ready for
+the OpenCode preset.
 
 Arguments:
   repo        repository path (default: ".")
@@ -365,8 +366,8 @@ Commands:
   run [options] <args...>  Alias for `opencode-plusplus opencode run`.
   init [options] [repo]    Initialize OpenCode commands and agent files for
                            OpenCode++.
-  doctor [options] [repo]  Check whether OpenCode and the current repository are
-                           ready for the OpenCode preset.
+  doctor [options] [repo]  Check whether OpenCode, plugin version, and the
+                           current repository are ready for the OpenCode preset.
   report [options] [repo]  Show the latest OpenCode orchestrator report without
                            opening .agent-context manually.
   repair [options] [repo]  Print repair guidance from the latest OpenCode
@@ -436,8 +437,8 @@ Options:
 ```txt
 Usage: opencode-plusplus oc doctor [options] [repo]
 
-Check whether OpenCode and the current repository are ready for the OpenCode
-preset.
+Check whether OpenCode, plugin version, and the current repository are ready for
+the OpenCode preset.
 
 Arguments:
   repo        repository path (default: ".")
diff --git a/docs/reference/cli-reference.md b/docs/reference/cli-reference.md
@@ -34,17 +34,17 @@ opencode-plusplus orchestrate "task" .
 | `opencode-plusplus sidecar record-tool`   | Record OpenCode tool.execute.after evidence into sidecar event logs and execution traces.                      |
 | `opencode-plusplus report`                | Show the latest OpenCode++ sidecar report.                                                                     |
 | `opencode-plusplus status`                | Show whether the OpenCode++ OpenCode sidecar is active.                                                        |
-| `opencode-plusplus doctor`                | Check OpenCode, auth, git, context, and OpenCode++ sidecar readiness.                                          |
+| `opencode-plusplus doctor`                | Check OpenCode, auth, git, context, plugin version, and OpenCode++ sidecar readiness.                          |
 | `opencode-plusplus opencode`              | OpenCode preset commands.                                                                                      |
 | `opencode-plusplus opencode run`          | Run the harness-led OpenCode preset: plan/pack -> opencode run -> trace/policy/verify -> decision.             |
 | `opencode-plusplus opencode init`         | Initialize OpenCode commands and agent files for OpenCode++.                                                   |
-| `opencode-plusplus opencode doctor`       | Check whether OpenCode and the current repository are ready for the OpenCode preset.                           |
+| `opencode-plusplus opencode doctor`       | Check whether OpenCode, plugin version, and the current repository are ready for the OpenCode preset.          |
 | `opencode-plusplus opencode report`       | Show the latest OpenCode orchestrator report without opening .agent-context manually.                          |
 | `opencode-plusplus opencode repair`       | Print repair guidance from the latest OpenCode decision.                                                       |
 | `opencode-plusplus oc`                    | Shortcut for OpenCode preset commands.                                                                         |
 | `opencode-plusplus oc run`                | Alias for `opencode-plusplus opencode run`.                                                                    |
 | `opencode-plusplus oc init`               | Initialize OpenCode commands and agent files for OpenCode++.                                                   |
-| `opencode-plusplus oc doctor`             | Check whether OpenCode and the current repository are ready for the OpenCode preset.                           |
+| `opencode-plusplus oc doctor`             | Check whether OpenCode, plugin version, and the current repository are ready for the OpenCode preset.          |
 | `opencode-plusplus oc report`             | Show the latest OpenCode orchestrator report without opening .agent-context manually.                          |
 | `opencode-plusplus oc repair`             | Print repair guidance from the latest OpenCode decision.                                                       |
 | `opencode-plusplus build`                 | Generate AGENTS.md and .agent-context outputs.                                                                 |
@@ -113,7 +113,7 @@ Commands:
   sidecar                                   Inspect and verify OpenCode++ sidecar integrations.
   report [options] [repo]                   Show the latest OpenCode++ sidecar report.
   status [options] [repo]                   Show whether the OpenCode++ OpenCode sidecar is active.
-  doctor [options] [repo]                   Check OpenCode, auth, git, context, and OpenCode++ sidecar readiness.
+  doctor [options] [repo]                   Check OpenCode, auth, git, context, plugin version, and OpenCode++ sidecar readiness.
   opencode                                  OpenCode preset commands.
   oc                                        Shortcut for OpenCode preset commands.
   build [options] [repo]                    Generate AGENTS.md and .agent-context outputs.
@@ -297,7 +297,8 @@ Options:
 ```txt
 Usage: opencode-plusplus doctor [options] [repo]
 
-Check OpenCode, auth, git, context, and OpenCode++ sidecar readiness.
+Check OpenCode, auth, git, context, plugin version, and OpenCode++ sidecar
+readiness.
 
 Arguments:
   repo        repository path (default: ".")
@@ -322,8 +323,8 @@ Commands:
                            opencode run -> trace/policy/verify -> decision.
   init [options] [repo]    Initialize OpenCode commands and agent files for
                            OpenCode++.
-  doctor [options] [repo]  Check whether OpenCode and the current repository are
-                           ready for the OpenCode preset.
+  doctor [options] [repo]  Check whether OpenCode, plugin version, and the
+                           current repository are ready for the OpenCode preset.
   report [options] [repo]  Show the latest OpenCode orchestrator report without
                            opening .agent-context manually.
   repair [options] [repo]  Print repair guidance from the latest OpenCode
@@ -394,8 +395,8 @@ Options:
 ```txt
 Usage: opencode-plusplus opencode doctor [options] [repo]
 
-Check whether OpenCode and the current repository are ready for the OpenCode
-preset.
+Check whether OpenCode, plugin version, and the current repository are ready for
+the OpenCode preset.
 
 Arguments:
   repo        repository path (default: ".")
@@ -456,8 +457,8 @@ Commands:
   run [options] <args...>  Alias for `opencode-plusplus opencode run`.
   init [options] [repo]    Initialize OpenCode commands and agent files for
                            OpenCode++.
-  doctor [options] [repo]  Check whether OpenCode and the current repository are
-                           ready for the OpenCode preset.
+  doctor [options] [repo]  Check whether OpenCode, plugin version, and the
+                           current repository are ready for the OpenCode preset.
   report [options] [repo]  Show the latest OpenCode orchestrator report without
                            opening .agent-context manually.
   repair [options] [repo]  Print repair guidance from the latest OpenCode
@@ -527,8 +528,8 @@ Options:
 ```txt
 Usage: opencode-plusplus oc doctor [options] [repo]
 
-Check whether OpenCode and the current repository are ready for the OpenCode
-preset.
+Check whether OpenCode, plugin version, and the current repository are ready for
+the OpenCode preset.
 
 Arguments:
   repo        repository path (default: ".")
diff --git a/src/cli/commands/doctor.ts b/src/cli/commands/doctor.ts
@@ -6,7 +6,7 @@ export function registerDoctorCommand(program: Command): void {
     .command("doctor")
     .argument("[repo]", "repository path", ".")
     .option("--json", "print machine-readable doctor report")
-    .description("Check OpenCode, auth, git, context, and OpenCode++ sidecar readiness.")
+    .description("Check OpenCode, auth, git, context, plugin version, and OpenCode++ sidecar readiness.")
     .action(async (repo: string, options: { json?: boolean }) => {
       const report = await runOpenCodePlusplusDoctor(repo);
       console.log(options.json ? JSON.stringify(report, null, 2) : renderOpenCodePlusplusDoctor(report));
diff --git a/src/cli/commands/opencode.ts b/src/cli/commands/opencode.ts
@@ -119,7 +119,7 @@ function addOpencodeDoctorCommand(parent: Command): void {
     .command("doctor")
     .argument("[repo]", "repository path", ".")
     .option("--json", "print machine-readable doctor report")
-    .description("Check whether OpenCode and the current repository are ready for the OpenCode preset.")
+    .description("Check whether OpenCode, plugin version, and the current repository are ready for the OpenCode preset.")
     .action((repo: string, options: { json?: boolean }) => {
       const report = runOpencodeDoctor(repo);
       console.log(options.json ? JSON.stringify(report, null, 2) : renderOpencodeDoctorReport(report));
diff --git a/src/cli/opencode-plusplus-commands.ts b/src/cli/opencode-plusplus-commands.ts
@@ -1,5 +1,6 @@
 import { existsSync, readFileSync, statSync } from "node:fs";
 import path from "node:path";
+import { getOpenCodePlusplusPackageVersion, OPENCODE_PLUSPLUS_PACKAGE_NAME } from "../core/package-info.js";
 import { runOpencodeDoctor, type OpencodeDoctorCheck } from "./opencode-preset.js";
 import { OPENCODE_SIDECAR_PLUGIN_PATH } from "../integrations/opencode/plugin-template.js";
 import { verifyOpencodeSidecar } from "../integrations/opencode/sidecar.js";
@@ -69,7 +70,10 @@ export async function runOpenCodePlusplusDoctor(repo = "."): Promise<OpenCodePlu
   const opencode = runOpencodeDoctor(root);
   const sidecar = await verifyOpencodeSidecar(root);
   const sidecarPluginCheck = sidecar.checks.find((check) => check.name.endsWith("opencode-plusplus.ts"));
+  const pluginPath = path.join(root, OPENCODE_SIDECAR_PLUGIN_PATH);
+  const versionCheck = buildOpenCodePlusplusVersionCheck(pluginPath);
   const sidecarChecks: OpencodeDoctorCheck[] = [
+    versionCheck,
     {
       id: "sidecar-plugin",
       label: "OpenCode++ sidecar plugin",
@@ -97,6 +101,49 @@ export async function runOpenCodePlusplusDoctor(repo = "."): Promise<OpenCodePlu
   return { repo: root, ok: checks.every((check) => check.status !== "fail"), checks };
 }
 
+export interface OpenCodePlusplusPluginMetadata {
+  generatedBy?: string;
+  headerVersion?: string;
+  constantVersion?: string;
+  generatedAt?: string;
+}
+
+export function readOpenCodePlusplusPluginMetadata(pluginPath: string): OpenCodePlusplusPluginMetadata | undefined {
+  if (!existsSync(pluginPath)) return undefined;
+  const source = readFileSync(pluginPath, "utf8");
+  return {
+    generatedBy: matchSource(source, /Generated by:\s*([^\r\n*]+)/),
+    headerVersion: matchSource(source, /Package version:\s*([^\r\n*]+)/),
+    generatedAt: matchSource(source, /(?:Generated at:\s*([^\r\n*]+)|OPENCODE_PLUSPLUS_GENERATED_AT\s*=\s*["']([^"']+)["'])/),
+    constantVersion: matchSource(source, /OPENCODE_PLUSPLUS_PLUGIN_VERSION\s*=\s*["']([^"']+)["']/)
+  };
+}
+
+function buildOpenCodePlusplusVersionCheck(pluginPath: string): OpencodeDoctorCheck {
+  const cliVersion = getOpenCodePlusplusPackageVersion();
+  const metadata = readOpenCodePlusplusPluginMetadata(pluginPath);
+  if (!metadata) {
+    return {
+      id: "opencode-plusplus-version",
+      label: "CLI/plugin version",
+      status: "warn",
+      details: `CLI ${cliVersion}; sidecar plugin not generated yet`
+    };
+  }
+
+  const pluginVersion = metadata.constantVersion ?? metadata.headerVersion ?? "unknown";
+  const generatedByCurrentCli =
+    metadata.generatedBy === OPENCODE_PLUSPLUS_PACKAGE_NAME && metadata.headerVersion === cliVersion && metadata.constantVersion === cliVersion;
+  return {
+    id: "opencode-plusplus-version",
+    label: "CLI/plugin version",
+    status: generatedByCurrentCli ? "pass" : "warn",
+    details: generatedByCurrentCli
+      ? `${cliVersion} (generated at ${metadata.generatedAt ?? "unknown"})`
+      : `CLI ${cliVersion}; plugin ${pluginVersion}; generatedBy ${metadata.generatedBy ?? "unknown"}; generatedAt ${metadata.generatedAt ?? "unknown"}`
+  };
+}
+
 export function renderOpenCodePlusplusStatus(report: OpenCodePlusplusStatusReport): string {
   return [
     "OpenCode++ Status",
@@ -143,3 +190,8 @@ function readLatestJson(filePath: string): { blockers?: unknown } | null {
     return null;
   }
 }
+
+function matchSource(source: string, pattern: RegExp): string | undefined {
+  const match = source.match(pattern);
+  return (match?.[1] ?? match?.[2])?.trim();
+}
diff --git a/src/core/package-info.ts b/src/core/package-info.ts
@@ -0,0 +1,30 @@
+import { existsSync, readFileSync } from "node:fs";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+
+export const OPENCODE_PLUSPLUS_PACKAGE_NAME = "opencode-plusplus";
+
+export function getOpenCodePlusplusPackageVersion(): string {
+  const start = path.dirname(fileURLToPath(import.meta.url));
+  const packagePath = findPackageJson(start);
+  if (!packagePath) return "unknown";
+
+  try {
+    const parsed = JSON.parse(readFileSync(packagePath, "utf8")) as { name?: unknown; version?: unknown };
+    if (parsed.name === OPENCODE_PLUSPLUS_PACKAGE_NAME && typeof parsed.version === "string") return parsed.version;
+  } catch {
+    return "unknown";
+  }
+  return "unknown";
+}
+
+function findPackageJson(start: string): string | undefined {
+  let current = start;
+  while (true) {
+    const candidate = path.join(current, "package.json");
+    if (existsSync(candidate)) return candidate;
+    const parent = path.dirname(current);
+    if (parent === current) return undefined;
+    current = parent;
+  }
+}
diff --git a/src/integrations/opencode/plugin-template.ts b/src/integrations/opencode/plugin-template.ts
@@ -1,15 +1,30 @@
+import { getOpenCodePlusplusPackageVersion, OPENCODE_PLUSPLUS_PACKAGE_NAME } from "../../core/package-info.js";
+
 export const OPENCODE_SIDECAR_PLUGIN_PATH = ".opencode/plugins/opencode-plusplus.ts";
 
-export function opencodeSidecarPluginTemplate(runtimeImport = opencodeSidecarRuntimeImport()): string {
+export interface OpenCodeSidecarPluginTemplateOptions {
+  version?: string;
+  generatedAt?: string;
+}
+
+export function opencodeSidecarPluginTemplate(runtimeImport = opencodeSidecarRuntimeImport(), options: OpenCodeSidecarPluginTemplateOptions = {}): string {
+  const version = options.version ?? getOpenCodePlusplusPackageVersion();
+  const generatedAt = options.generatedAt ?? new Date().toISOString();
   return `/**
  * OpenCode++ OpenCode Sidecar Plugin
  *
- * Generated by \`opencode-plusplus\`. Edit only when you want to customize how OpenCode
+ * Generated by: ${OPENCODE_PLUSPLUS_PACKAGE_NAME}
+ * Package version: ${version}
+ * Generated at: ${generatedAt}
+ *
+ * Edit only when you want to customize how OpenCode
  * presents the OpenCode++ harness inside this repository.
  */
 
 import { createOpenCodePlusPlusSidecar } from ${JSON.stringify(runtimeImport)};
 
+export const OPENCODE_PLUSPLUS_PLUGIN_VERSION = ${JSON.stringify(version)};
+export const OPENCODE_PLUSPLUS_GENERATED_AT = ${JSON.stringify(generatedAt)};
 export const OpenCodePlusPlusSidecar = createOpenCodePlusPlusSidecar;
 export default OpenCodePlusPlusSidecar;
 `;
diff --git a/test/opencode-launcher.test.ts b/test/opencode-launcher.test.ts
