@objctp/opencode-shell-routines 1.3.0 → 1.3.2

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@objctp/opencode-shell-routines",
-  "version": "1.3.0",
+  "version": "1.3.2",
   "description": "Shell script development toolkit — automated scaffolding, best practices, and quality enforcement for OpenCode and Claude Code",
   "author": {
     "name": "objct",

package/plugins/shell-hooks.ts

@@ -6,13 +6,10 @@ import type {
   PluginInput,
   PluginOptions,
 } from "@opencode-ai/plugin";
-import { syncContent } from "./setup-content.ts";
-
-const SHELL_EXTENSIONS = new Set(["sh", "bash", "zsh", "ksh"]);
-const SHEBANG_PATTERN = /^#!.*\b(bash|sh|zsh|ksh)\b/;
-const DASH_PATTERN = /#!.*\bdash\b/;
-const SH_ONLY_PATTERN = /#!.*\bsh\b/;
-const BASH_FAMILY_PATTERN = /#!.*\b(bash|zsh|ksh)\b/;
+import { detectDialect, isShellFile } from "./shell-routines/dialect";
+import { runQualityChecks } from "./shell-routines/quality-checks";
+import { syncContent } from "./shell-routines/setup-content";
+import type { ShellToolInput, ShellToolOutput } from "./shell-routines/types";
 
 async function hasCmd($: PluginInput["$"], cmd: string): Promise<boolean> {
   const r = await $`command -v ${cmd}`.nothrow();
@@ -23,9 +20,12 @@ export const ShellHooksPlugin: Plugin = async (
   { $, client, directory }: PluginInput,
   options?: PluginOptions,
 ): Promise<Hooks> => {
-  // Self-install bundled skills/commands/agents/scripts into the OpenCode config
-  // directory so OpenCode discovers them (npm plugins only). Failures are logged
-  // and swallowed — they must never block the quality-check hook below.
+  // :::: Self-install bundled content (npm plugins only) :::: //////////////
+  // Failures are logged and swallowed — they must never block the hook below.
+  const explicitScope =
+    options?.scope === "project" || options?.scope === "global"
+      ? options.scope
+      : undefined;
   try {
     const packageRoot = path.resolve(import.meta.dirname, "..");
     const pkg = JSON.parse(
@@ -34,8 +34,9 @@ export const ShellHooksPlugin: Plugin = async (
     syncContent({
       packageRoot,
       version: pkg.version,
+      packageName: pkg.name,
       client,
-      scope: options?.scope === "project" ? "project" : "global",
+      scope: explicitScope,
       directory,
     });
   } catch (error) {
@@ -52,17 +53,14 @@ export const ShellHooksPlugin: Plugin = async (
     } catch {}
   }
 
+  // :::: Detect available quality tools :::: ///////////////////////////////
   const hasShellcheck = await hasCmd($, "shellcheck");
   const hasCheckbashisms = await hasCmd($, "checkbashisms");
+
   return {
     "tool.execute.after": async (
-      input: {
-        tool: string;
-        sessionID: string;
-        callID: string;
-        args: { file_path?: string; filePath?: string; [key: string]: unknown };
-      },
-      output: { title: string; output: string; metadata: unknown },
+      input: ShellToolInput,
+      output: ShellToolOutput,
     ) => {
       if (input.tool !== "write" && input.tool !== "edit") return;
 
@@ -70,7 +68,7 @@ export const ShellHooksPlugin: Plugin = async (
         input.args?.filePath;
       if (!filePath) return;
 
-      // Canonicalise and verify file exists
+      // Canonicalise and verify the file exists.
       let resolved: string;
       try {
         resolved = await $`realpath ${filePath}`.nothrow().text();
@@ -85,7 +83,7 @@ export const ShellHooksPlugin: Plugin = async (
 
       const ext = resolved.split(".").pop()?.toLowerCase() ?? "";
 
-      // Read first line once — needed for shebang check and dialect detection
+      // Read first line once — needed for shebang check and dialect detection.
       let firstLine: string;
       try {
         firstLine = await $`head -1 ${resolved}`.nothrow().text();
@@ -93,91 +91,18 @@ export const ShellHooksPlugin: Plugin = async (
         return;
       }
 
-      if (!SHELL_EXTENSIONS.has(ext) && !SHEBANG_PATTERN.test(firstLine)) {
-        return;
-      }
-
-      let dialect = "bash";
-      let isPosix = false;
-      if (DASH_PATTERN.test(firstLine)) {
-        dialect = "dash";
-        isPosix = true;
-      } else if (
-        SH_ONLY_PATTERN.test(firstLine) && !BASH_FAMILY_PATTERN.test(firstLine)
-      ) {
-        dialect = "sh";
-        isPosix = true;
-      }
-
-      const findings: string[] = [];
-
-      // ShellCheck — findings on stdout, exits non-zero on issues
-      if (hasShellcheck) {
-        try {
-          const sc = await $`shellcheck -s ${dialect} ${resolved} 2>&1`
-            .nothrow().text();
-          if (sc.trim()) {
-            findings.push(
-              `ShellCheck findings in ${resolved} (shell=${dialect}):\n${sc.trim()}`,
-            );
-          }
-          // deno-lint-ignore no-empty
-        } catch {}
-      }
-
-      if (!isPosix) {
-        try {
-          const syntax = await $`bash -n ${resolved} 2>&1`.nothrow().text();
-          if (syntax.trim()) {
-            findings.push(`Syntax error in ${resolved}: ${syntax.trim()}`);
-          }
-          // deno-lint-ignore no-empty
-        } catch {}
-      }
-
-      if (isPosix && hasCheckbashisms) {
-        try {
-          const bashisms = await $`checkbashisms ${resolved} 2>&1`.nothrow()
-            .text();
-          if (bashisms.trim()) {
-            findings.push(
-              `POSIX compatibility issue in ${resolved} — bashisms detected:\n${bashisms.trim()}\n` +
-                "Note: /bin/sh is dash on Ubuntu/Debian. These will fail at runtime.",
-            );
-          }
-          // deno-lint-ignore no-empty
-        } catch {}
-      }
+      if (!isShellFile(ext, firstLine)) return;
 
-      // TODO/FIXME/HACK/XXX/BUG markers
-      try {
-        const todos =
-          await $`grep -n -E '(^|[^[:alnum:]_])(TODO|FIXME|HACK|XXX|BUG):' ${resolved}`
-            .nothrow()
-            .text();
-        if (todos.trim()) {
-          findings.push(`Unresolved markers in ${resolved}:\n${todos.trim()}`);
-        }
-        // deno-lint-ignore no-empty
-      } catch {}
+      const { dialect, isPosix } = detectDialect(firstLine);
 
-      // Batch script pattern validation
-      try {
-        const content = await $`cat ${resolved}`.nothrow().text();
-        if (content.includes("lib-batch.sh")) {
-          if (!content.includes("batch_output")) {
-            findings.push(
-              `Batch script detected in ${resolved}: ensure batch_output() is called to return JSON results`,
-            );
-          }
-          if (!content.includes("declare -A RESULTS")) {
-            findings.push(
-              `Batch script detected in ${resolved}: declare RESULTS array with: declare -A RESULTS`,
-            );
-          }
-        }
-        // deno-lint-ignore no-empty
-      } catch {}
+      const findings = await runQualityChecks({
+        $,
+        resolved,
+        dialect,
+        isPosix,
+        hasShellcheck,
+        hasCheckbashisms,
+      });
 
       if (findings.length > 0) {
         output.output += "\n\n---\n**Shell quality checks:**\n" +
@@ -188,8 +113,7 @@ export const ShellHooksPlugin: Plugin = async (
 };
 
 // OpenCode resolves the `exports["./server"]` entry in dist/package.json and
-// expects a V1 plugin module that default-exports `{ id, server }`. The named
-// export above is kept for direct imports and tests.
+// expects a V1 plugin module that default-exports `{ id, server }`.
 export default {
   id: "shell-routines",
   server: ShellHooksPlugin,

package/plugins/shell-routines/dialect.ts

@@ -0,0 +1,25 @@
+import type { DialectResult } from "./types";
+
+// :::: Shell classification :::: ///////////////////////////
+
+const SHELL_EXTENSIONS = new Set(["sh", "bash", "zsh", "ksh"]);
+const SHEBANG_PATTERN = /^#!.*\b(bash|sh|zsh|ksh)\b/;
+const DASH_PATTERN = /#!.*\bdash\b/;
+const SH_ONLY_PATTERN = /#!.*\bsh\b/;
+const BASH_FAMILY_PATTERN = /#!.*\b(bash|zsh|ksh)\b/;
+
+/** A shell file if the extension matches or the shebang names a shell. */
+export function isShellFile(ext: string, firstLine: string): boolean {
+  return SHELL_EXTENSIONS.has(ext) || SHEBANG_PATTERN.test(firstLine);
+}
+
+/** Classify the shell dialect from the shebang. Defaults to bash. */
+export function detectDialect(firstLine: string): DialectResult {
+  if (DASH_PATTERN.test(firstLine)) {
+    return { dialect: "dash", isPosix: true };
+  }
+  if (SH_ONLY_PATTERN.test(firstLine) && !BASH_FAMILY_PATTERN.test(firstLine)) {
+    return { dialect: "sh", isPosix: true };
+  }
+  return { dialect: "bash", isPosix: false };
+}

package/plugins/shell-routines/quality-checks.ts

@@ -0,0 +1,97 @@
+import type { PluginInput } from "@opencode-ai/plugin";
+import type { Dialect } from "./types";
+
+export interface QualityCheckDeps {
+  $: PluginInput["$"];
+  /** Absolute, verified-existing path to the shell file. */
+  resolved: string;
+  dialect: Dialect;
+  isPosix: boolean;
+  hasShellcheck: boolean;
+  hasCheckbashisms: boolean;
+}
+
+/**
+ * Run all enabled quality checks against a resolved shell file and return the
+ * human-readable findings (empty if clean). Each check is independently
+ * fault-tolerant — a missing tool or failed command never aborts the others.
+ */
+export async function runQualityChecks(
+  deps: QualityCheckDeps,
+): Promise<string[]> {
+  const { $, resolved, dialect, isPosix, hasShellcheck, hasCheckbashisms } =
+    deps;
+  const findings: string[] = [];
+
+  // :::: ShellCheck — findings on stdout, exits non-zero on issues :::: /////
+  if (hasShellcheck) {
+    try {
+      const sc = await $`shellcheck -s ${dialect} ${resolved} 2>&1`
+        .nothrow().text();
+      if (sc.trim()) {
+        findings.push(
+          `ShellCheck findings in ${resolved} (shell=${dialect}):\n${sc.trim()}`,
+        );
+      }
+      // deno-lint-ignore no-empty
+    } catch {}
+  }
+
+  // :::: Syntax — bash -n (skipped for POSIX shells) :::: //////////////////
+  if (!isPosix) {
+    try {
+      const syntax = await $`bash -n ${resolved} 2>&1`.nothrow().text();
+      if (syntax.trim()) {
+        findings.push(`Syntax error in ${resolved}: ${syntax.trim()}`);
+      }
+      // deno-lint-ignore no-empty
+    } catch {}
+  }
+
+  // :::: POSIX bashisms — only for dash/sh shebangs :::: ////////////////////
+  if (isPosix && hasCheckbashisms) {
+    try {
+      const bashisms = await $`checkbashisms ${resolved} 2>&1`.nothrow()
+        .text();
+      if (bashisms.trim()) {
+        findings.push(
+          `POSIX compatibility issue in ${resolved} — bashisms detected:\n${bashisms.trim()}\n` +
+            "Note: /bin/sh is dash on Ubuntu/Debian. These will fail at runtime.",
+        );
+      }
+      // deno-lint-ignore no-empty
+    } catch {}
+  }
+
+  // :::: Unresolved markers — TODO/FIXME/HACK/XXX/BUG :::: //////////////////
+  try {
+    const todos =
+      await $`grep -n -E '(^|[^[:alnum:]_])(TODO|FIXME|HACK|XXX|BUG):' ${resolved}`
+        .nothrow()
+        .text();
+    if (todos.trim()) {
+      findings.push(`Unresolved markers in ${resolved}:\n${todos.trim()}`);
+    }
+    // deno-lint-ignore no-empty
+  } catch {}
+
+  // :::: Batch script patterns — lib-batch.sh contracts :::: ///////////////
+  try {
+    const content = await $`cat ${resolved}`.nothrow().text();
+    if (content.includes("lib-batch.sh")) {
+      if (!content.includes("batch_output")) {
+        findings.push(
+          `Batch script detected in ${resolved}: ensure batch_output() is called to return JSON results`,
+        );
+      }
+      if (!content.includes("declare -A RESULTS")) {
+        findings.push(
+          `Batch script detected in ${resolved}: declare RESULTS array with: declare -A RESULTS`,
+        );
+      }
+    }
+    // deno-lint-ignore no-empty
+  } catch {}
+
+  return findings;
+}

package/plugins/shell-routines/setup-content.ts

@@ -0,0 +1,262 @@
+// OpenCode loads only a plugin's `./server` entrypoint — it does not discover
+// the bundled agents/commands/skills/scripts (separate scanners read config
+// dirs only), and `postinstall` can't run (OpenCode installs with
+// ignoreScripts). So on load the plugin copies its own content into the config
+// dir matching the install scope, rewriting ${CLAUDE_PLUGIN_ROOT} → that dir.
+//
+// All work is synchronous FS I/O; logging is fire-and-forget. Never throws.
+
+import {
+  chmodSync,
+  cpSync,
+  existsSync,
+  lstatSync,
+  mkdirSync,
+  readdirSync,
+  readFileSync,
+  readlinkSync,
+  unlinkSync,
+  writeFileSync,
+} from "node:fs";
+import path from "node:path";
+import os from "node:os";
+import type { PluginInput } from "@opencode-ai/plugin";
+
+// scripts/ isn't scanned by OpenCode — synced only so the rewritten
+// ${CLAUDE_PLUGIN_ROOT}/scripts/lib-*.sh references resolve.
+const DIRS = ["agents", "commands", "skills", "scripts"] as const;
+
+const TEXT_EXT = new Set(["md", "sh", "bash", "zsh", "ksh", "txt", "json"]);
+
+// Replace the defaulted variant first, or the plain token leaves a stray `:-}`.
+const TOKEN_DEFAULTED = "${CLAUDE_PLUGIN_ROOT:-}";
+const TOKEN_PLAIN = "${CLAUDE_PLUGIN_ROOT}";
+
+// State lives in OpenCode's state dir (next to plugin-meta.json), not the config
+// dir, so it never pollutes ~/.config/opencode or a project's .opencode/.
+// Keyed by destination dir: global and each project-local sync are independent.
+const STATE_DIR = path.join(
+  os.homedir(),
+  ".local",
+  "state",
+  "opencode",
+  "shell-routines",
+);
+const STATE_FILE = "sync-state.json";
+
+// <=1.3.1 wrote this into the config dir; remove on sight to migrate.
+const LEGACY_MARKER = ".shell-routines.version";
+
+const PROJECT_CONFIGS = [
+  "opencode.json",
+  "opencode.jsonc",
+  ".opencode/opencode.json",
+  ".opencode/opencode.jsonc",
+];
+
+export type SyncScope = "global" | "project";
+
+export interface SyncOptions {
+  packageRoot: string;
+  version: string;
+  /** Used to auto-detect scope from the project's config files. */
+  packageName: string;
+  client: PluginInput["client"];
+  /** Overrides auto-detected scope. */
+  scope?: SyncScope;
+  /** Project directory; required when scope resolves to "project". */
+  directory?: string;
+  /** Override the destination config directory (tests). */
+  configDirOverride?: string;
+  /** Override the state directory (tests). */
+  stateDirOverride?: string;
+}
+
+/**
+ * Copy agents/commands/skills/scripts into the config dir matching the install
+ * scope (auto-detected: listed in a project config ⇒ project-local, else
+ * global), rewriting ${CLAUDE_PLUGIN_ROOT} → that dir. Idempotent via a
+ * per-target version record in the state dir. Never throws.
+ */
+export function syncContent(opts: SyncOptions): void {
+  const {
+    packageRoot,
+    version,
+    packageName,
+    client,
+    directory,
+    configDirOverride,
+    stateDirOverride,
+  } = opts;
+
+  const log = (
+    level: "debug" | "info" | "warn" | "error",
+    message: string,
+    extra?: Record<string, unknown>,
+  ) => {
+    try {
+      const ret = client.app.log({
+        body: { service: "shell-routines", level, message, extra },
+      });
+      if (ret && typeof ret.catch === "function") ret.catch(() => {});
+    } catch {
+      // Logging must never break the plugin.
+    }
+  };
+
+  // File-plugin/dev mode already exposes content where OpenCode finds it, and
+  // its layout differs (no sibling scripts/).
+  if (!packageRoot.includes("node_modules")) {
+    log("debug", "content sync skipped (not an npm install)");
+    return;
+  }
+
+  if (!existsSync(path.join(packageRoot, "scripts"))) {
+    log("warn", "content sync skipped (unexpected package layout)", {
+      packageRoot,
+    });
+    return;
+  }
+
+  const scope = opts.scope ?? detectInstallScope(directory, packageName);
+  const configDir = configDirOverride ??
+    (scope === "project" && directory
+      ? path.join(directory, ".opencode")
+      : path.join(os.homedir(), ".config", "opencode"));
+
+  const stateDir = stateDirOverride ?? STATE_DIR;
+  const stateFile = path.join(stateDir, STATE_FILE);
+  const synced: Record<string, string> = readState(stateFile);
+  if (synced[configDir] === version) {
+    log("debug", "content sync skipped (already up to date)", {
+      configDir,
+      version,
+    });
+    return;
+  }
+
+  mkdirSync(configDir, { recursive: true });
+  removeLegacyMarker(configDir);
+
+  try {
+    for (const dir of DIRS) {
+      syncDir(path.join(packageRoot, dir), path.join(configDir, dir), configDir);
+    }
+  } catch (error) {
+    log("error", "content sync failed", { error: String(error), configDir });
+    return; // state untouched → next load retries
+  }
+
+  synced[configDir] = version;
+  mkdirSync(stateDir, { recursive: true });
+  writeFileSync(stateFile, JSON.stringify(synced, null, 2) + "\n");
+  log("info", "synced shell-routines skills/commands/agents/scripts", {
+    configDir,
+    scope,
+    version,
+  });
+}
+
+/** "project" if packageName is in any project config's `plugin` array, else "global". */
+function detectInstallScope(
+  directory: string | undefined,
+  packageName: string,
+): SyncScope {
+  if (!directory) return "global";
+  for (const rel of PROJECT_CONFIGS) {
+    const file = path.join(directory, rel);
+    if (!existsSync(file)) continue;
+    try {
+      const cfg = JSON.parse(stripJsonc(readFileSync(file, "utf8"))) as {
+        plugin?: unknown[];
+      };
+      if (
+        Array.isArray(cfg.plugin) &&
+        cfg.plugin.some((e) => matchesPlugin(e, packageName))
+      ) {
+        return "project";
+      }
+    } catch {
+      // Unreadable config — keep checking the rest.
+    }
+  }
+  return "global";
+}
+
+function matchesPlugin(entry: unknown, packageName: string): boolean {
+  const spec = Array.isArray(entry) ? entry[0] : entry;
+  return typeof spec === "string" && spec.startsWith(packageName);
+}
+
+function stripJsonc(text: string): string {
+  return text
+    .replace(/\/\*[\s\S]*?\*\//g, "")
+    .replace(/(^|[^:\\])\/\/.*$/gm, "$1");
+}
+
+function readState(stateFile: string): Record<string, string> {
+  try {
+    if (existsSync(stateFile)) {
+      return JSON.parse(readFileSync(stateFile, "utf8")) as Record<
+        string,
+        string
+      >;
+    }
+  } catch {
+    // Corrupt state — empty so a re-sync repairs it.
+  }
+  return {};
+}
+
+function removeLegacyMarker(configDir: string): void {
+  const legacy = path.join(configDir, LEGACY_MARKER);
+  try {
+    if (existsSync(legacy)) unlinkSync(legacy);
+  } catch {
+    // best effort
+  }
+}
+
+function syncDir(src: string, dest: string, configDir: string): void {
+  if (!existsSync(src)) return;
+  mkdirSync(dest, { recursive: true });
+  for (const entry of readdirSync(src)) {
+    const srcPath = path.join(src, entry);
+    const destPath = path.join(dest, entry);
+    const stat = lstatSync(srcPath);
+
+    if (stat.isSymbolicLink()) {
+      // Dereference — defensive; dist files are real but repo sources symlink.
+      const target = path.resolve(
+        path.dirname(srcPath),
+        readlinkSync(srcPath),
+      );
+      syncDir(target, destPath, configDir);
+    } else if (stat.isDirectory()) {
+      syncDir(srcPath, destPath, configDir);
+    } else {
+      syncFile(srcPath, destPath, stat.mode, configDir);
+    }
+  }
+}
+
+function syncFile(
+  src: string,
+  dest: string,
+  mode: number,
+  configDir: string,
+): void {
+  const ext = path.extname(src).slice(1).toLowerCase();
+  if (TEXT_EXT.has(ext)) {
+    const rewritten = readFileSync(src, "utf8")
+      .split(TOKEN_DEFAULTED)
+      .join(configDir)
+      .split(TOKEN_PLAIN)
+      .join(configDir);
+    writeFileSync(dest, rewritten);
+  } else {
+    cpSync(src, dest);
+  }
+  // Preserve source mode: examples stay 0644, runtime libs 0755.
+  chmodSync(dest, mode & 0o777);
+}

package/plugins/shell-routines/types.ts

@@ -0,0 +1,25 @@
+// Shared types for the shell-routines plugin.
+
+// :::: Tool hook shapes :::: ///////////////////////////////
+
+export type ShellToolInput = {
+  tool: string;
+  sessionID: string;
+  callID: string;
+  args: { file_path?: string; filePath?: string; [key: string]: unknown };
+};
+
+export type ShellToolOutput = {
+  title: string;
+  output: string;
+  metadata: unknown;
+};
+
+// :::: Dialect classification :::: /////////////////////////
+
+export type Dialect = "bash" | "dash" | "sh";
+
+export type DialectResult = {
+  dialect: Dialect;
+  isPosix: boolean;
+};

package/plugins/setup-content.ts

@@ -1,181 +0,0 @@
-// Self-install bundled content for OpenCode consumers.
-//
-// OpenCode's plugin loader imports only the `./server` entrypoint of an npm
-// plugin; it does not discover the bundled `agents/ commands/ skills/ scripts/`
-// directories (those come from separate scanners that read config dirs only),
-// and npm `postinstall` cannot run (OpenCode installs with `ignoreScripts`).
-// So on load the plugin copies its own content into the OpenCode config
-// directory, rewriting `${CLAUDE_PLUGIN_ROOT}` references to that directory so
-// script-sourcing resolves to the copied location.
-//
-// All real work here is synchronous filesystem I/O; logging is fire-and-forget.
-// `syncContent` never throws — any failure is logged and swallowed.
-
-import {
-  chmodSync,
-  cpSync,
-  existsSync,
-  lstatSync,
-  mkdirSync,
-  readdirSync,
-  readFileSync,
-  readlinkSync,
-  writeFileSync,
-} from "node:fs";
-import path from "node:path";
-import os from "node:os";
-import type { PluginInput } from "@opencode-ai/plugin";
-
-// `scripts/` is not scanned by OpenCode — it is synced only so the rewritten
-// `${CLAUDE_PLUGIN_ROOT}/scripts/lib-*.sh` references resolve.
-const DIRS = ["agents", "commands", "skills", "scripts"] as const;
-
-// Text files whose `${CLAUDE_PLUGIN_ROOT}` tokens are rewritten at copy time.
-// Everything else is copied verbatim.
-const TEXT_EXT = new Set(["md", "sh", "bash", "zsh", "ksh", "txt", "json"]);
-
-// The defaulted variant must be replaced first, otherwise the plain token would
-// leave a stray `:-}` behind.
-const TOKEN_DEFAULTED = "${CLAUDE_PLUGIN_ROOT:-}";
-const TOKEN_PLAIN = "${CLAUDE_PLUGIN_ROOT}";
-
-// Records the package version last synced into the config directory. Absent or
-// mismatched ⇒ re-sync. Written only after a complete successful copy so a
-// partial failure self-heals on the next load.
-const MARKER_FILE = ".shell-routines.version";
-
-export type SyncScope = "global" | "project";
-
-export interface SyncOptions {
-  /** Absolute path to the installed package directory (sibling of agents/commands/skills/scripts). */
-  packageRoot: string;
-  /** Package version, read from `<packageRoot>/package.json`. */
-  version: string;
-  /** OpenCode client, used for structured logging. */
-  client: PluginInput["client"];
-  /** Sync scope. Defaults to "global". */
-  scope?: SyncScope;
-  /** Project directory; required when scope is "project". */
-  directory?: string;
-  /** Override the destination config directory (used by tests). */
-  configDirOverride?: string;
-}
-
-/**
- * Copy the plugin's bundled agents/commands/skills/scripts into the OpenCode
- * config directory so OpenCode's content scanners discover them, rewriting
- * `${CLAUDE_PLUGIN_ROOT}` references to the resolved config directory.
- *
- * Idempotent via a version marker written only after a complete, successful
- * sync. Never throws.
- */
-export function syncContent(opts: SyncOptions): void {
-  const { packageRoot, version, client, scope = "global", directory } = opts;
-
-  const log = (
-    level: "debug" | "info" | "warn" | "error",
-    message: string,
-    extra?: Record<string, unknown>,
-  ) => {
-    try {
-      const ret = client.app.log({
-        body: { service: "shell-routines", level, message, extra },
-      });
-      if (ret && typeof ret.catch === "function") ret.catch(() => {});
-    } catch {
-      // Logging must never break the plugin.
-    }
-  };
-
-  // npm-installed plugins only. In file-plugin/dev mode the content already
-  // lives where OpenCode discovers it, and the layout differs (no sibling
-  // scripts/), so copying would produce a broken tree.
-  if (!packageRoot.includes("node_modules")) {
-    log("debug", "content sync skipped (not an npm install)");
-    return;
-  }
-
-  // Fail safe on an unexpected package layout.
-  if (!existsSync(path.join(packageRoot, "scripts"))) {
-    log("warn", "content sync skipped (unexpected package layout)", {
-      packageRoot,
-    });
-    return;
-  }
-
-  const configDir =
-    opts.configDirOverride ??
-    (scope === "project" && directory
-      ? path.join(directory, ".opencode")
-      : path.join(os.homedir(), ".config", "opencode"));
-
-  const marker = path.join(configDir, MARKER_FILE);
-  if (
-    existsSync(marker) &&
-    readFileSync(marker, "utf8").trim() === version
-  ) {
-    log("debug", "content sync skipped (already up to date)", { version });
-    return;
-  }
-
-  mkdirSync(configDir, { recursive: true });
-
-  try {
-    for (const dir of DIRS) {
-      syncDir(path.join(packageRoot, dir), path.join(configDir, dir), configDir);
-    }
-  } catch (error) {
-    log("error", "content sync failed", { error: String(error) });
-    return; // marker untouched → next load retries
-  }
-
-  writeFileSync(marker, version);
-  log("info", "synced shell-routines skills/commands/agents/scripts", {
-    configDir,
-    version,
-  });
-}
-
-function syncDir(src: string, dest: string, configDir: string): void {
-  if (!existsSync(src)) return;
-  mkdirSync(dest, { recursive: true });
-  for (const entry of readdirSync(src)) {
-    const srcPath = path.join(src, entry);
-    const destPath = path.join(dest, entry);
-    const stat = lstatSync(srcPath);
-
-    if (stat.isSymbolicLink()) {
-      // Dereference — defensive, since dist files are real but repo sources symlink.
-      const target = path.resolve(
-        path.dirname(srcPath),
-        readlinkSync(srcPath),
-      );
-      syncDir(target, destPath, configDir);
-    } else if (stat.isDirectory()) {
-      syncDir(srcPath, destPath, configDir);
-    } else {
-      syncFile(srcPath, destPath, stat.mode, configDir);
-    }
-  }
-}
-
-function syncFile(
-  src: string,
-  dest: string,
-  mode: number,
-  configDir: string,
-): void {
-  const ext = path.extname(src).slice(1).toLowerCase();
-  if (TEXT_EXT.has(ext)) {
-    const rewritten = readFileSync(src, "utf8")
-      .split(TOKEN_DEFAULTED)
-      .join(configDir)
-      .split(TOKEN_PLAIN)
-      .join(configDir);
-    writeFileSync(dest, rewritten);
-  } else {
-    cpSync(src, dest);
-  }
-  // Preserve the source mode (exec bit): batch examples stay 0644, runtime libs 0755.
-  chmodSync(dest, mode & 0o777);
-}