@objctp/opencode-shell-routines 1.2.1 → 1.3.1

package/README.md

@@ -56,6 +56,20 @@ Add to your config — OpenCode auto-installs npm plugins via Bun at startup.
 git clone https://github.com/objctp/shell-routines && cd shell-routines && opencode
 ```
 
+> **How the OpenCode plugin registers its content:** OpenCode loads only the
+> plugin's server entrypoint from the npm package, so on first load the plugin
+> copies its bundled `agents/ commands/ skills/ scripts/` into
+> `~/.config/opencode/`, where OpenCode's scanners discover them. **Restart
+> OpenCode once after installing** for skills, commands, and agents to register.
+> The copies are re-synced automatically when the package version changes
+> (overwriting the synced files) — to customise, edit copies under your
+> project's `.opencode/` instead. For project-local scope, configure the plugin
+> with options:
+>
+> ```jsonc
+> { "plugin": [["@objctp/opencode-shell-routines", { "scope": "project" }]] }
+> ```
+
 ## Components
 
 | Component    | Purpose                                    | Trigger                           |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@objctp/opencode-shell-routines",
-  "version": "1.2.1",
+  "version": "1.3.1",
   "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

@@ -1,10 +1,15 @@
-import type { Hooks, Plugin, PluginInput } from "@opencode-ai/plugin";
-
-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 { readFileSync } from "node:fs";
+import path from "node:path";
+import type {
+  Hooks,
+  Plugin,
+  PluginInput,
+  PluginOptions,
+} from "@opencode-ai/plugin";
+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();
@@ -12,19 +17,47 @@ async function hasCmd($: PluginInput["$"], cmd: string): Promise<boolean> {
 }
 
 export const ShellHooksPlugin: Plugin = async (
-  { $ }: PluginInput,
+  { $, client, directory }: PluginInput,
+  options?: PluginOptions,
 ): Promise<Hooks> => {
+  // :::: Self-install bundled content (npm plugins only) :::: //////////////
+  // Copy skills/commands/agents/scripts into the OpenCode config dir so
+  // OpenCode discovers them. Failures are logged and swallowed — they must
+  // never block the quality-check hook below.
+  try {
+    const packageRoot = path.resolve(import.meta.dirname, "..");
+    const pkg = JSON.parse(
+      readFileSync(path.join(packageRoot, "package.json"), "utf8"),
+    );
+    syncContent({
+      packageRoot,
+      version: pkg.version,
+      client,
+      scope: options?.scope === "project" ? "project" : "global",
+      directory,
+    });
+  } catch (error) {
+    try {
+      void client.app.log({
+        body: {
+          service: "shell-routines",
+          level: "warn",
+          message: "content sync failed",
+          extra: { error: String(error) },
+        },
+      });
+      // deno-lint-ignore no-empty
+    } 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;
 
@@ -32,7 +65,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();
@@ -47,7 +80,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();
@@ -55,91 +88,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[] = [];
+      if (!isShellFile(ext, firstLine)) return;
 
-      // 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 {}
-      }
+      const { dialect, isPosix } = detectDialect(firstLine);
 
-      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 {}
-      }
-
-      // 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 {}
-
-      // 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" +
@@ -150,8 +110,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,181 @@
+// 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);
+}

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;
+};