@itzptk/ocps 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 itzptk
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,106 @@
+# ocps
+
+[![npm version](https://img.shields.io/npm/v/ocps.svg?logo=npm&style=flat-square)](https://www.npmjs.com/package/ocps)
+[![npm downloads](https://img.shields.io/npm/dm/ocps.svg?style=flat-square)](https://www.npmjs.com/package/ocps)
+[![license](https://img.shields.io/github/license/itzptk/ocps.svg?style=flat-square)](./LICENSE)
+[![CI](https://img.shields.io/github/actions/workflow/status/itzptk/ocps/ci.yml?branch=main&label=ci&style=flat-square)](https://github.com/itzptk/ocps/actions/workflows/ci.yml)
+[![Bun](https://img.shields.io/badge/powered%20by-bun-f9f1e1?style=flat-square&logo=bun)](https://bun.sh)
+[![opencode](https://img.shields.io/badge/opencode-plugin-0ea5e9?style=flat-square)](https://opencode.ai)
+
+> **ocps** = **o**pencode **c**reate **p**lugin **s**tarter
+
+Scaffold a new [opencode](https://opencode.ai) plugin project with a single command. Generate a clean, typed, test-driven TypeScript plugin boilerplate — ready to develop, test, and publish to npm.
+
+## Quickstart
+
+```bash
+npx ocps init my-plugin --name opencode-greeter
+```
+
+This creates an `opencode-greeter/` directory with a working plugin, installs dependencies, and prints the next steps.
+
+## Usage
+
+```text
+ocps init [directory] --name <package-name> [options]
+
+Options:
+  --name <name>           npm package name for the plugin (required)
+  --description <text>    Short description for package.json and README
+  --author <name>          Copyright author name for LICENSE
+  --force                 Write into a non-empty directory (does not delete existing files)
+  --no-install            Skip running bun install after scaffolding
+  -h, --help              Show help
+
+Examples:
+  ocps init my-plugin --name opencode-greeter
+  ocps init --name @scope/opencode-greeter --author "Jane Doe"
+```
+
+## What it creates
+
+```text
+opencode-greeter/
+  package.json
+  tsconfig.json
+  .gitignore
+  README.md
+  LICENSE
+  src/
+    index.ts        # plugin entry exporting the hook function
+    index.test.ts   # initialization + hook test
+  .github/workflows/
+    ci.yml
+    release-please.yml
+```
+
+The generated `src/index.ts` exports a typed opencode plugin that:
+
+- logs to `client.app.log` on load,
+- subscribes to `session.idle` events,
+- and short-circuits when `enabled: false`.
+
+Register the published plugin in `opencode.json`:
+
+```jsonc
+{
+  "$schema": "https://opencode.ai/config.json",
+  "plugin": ["opencode-greeter"]
+}
+```
+
+Restart opencode after changing config. See the [opencode plugin docs](https://opencode.ai/docs/plugins/) for the full hook surface.
+
+## Develop this scaffolder
+
+```bash
+bun install
+bun test
+bun run typecheck
+```
+
+Scripts:
+
+| Script              | Description                              |
+| ------------------- | ---------------------------------------- |
+| `bun test`          | Run the test suite                       |
+| `bun run typecheck` | Type-check source without emitting       |
+
+## Contributing
+
+Contributions are welcome! Please:
+
+1. Fork the repository
+2. Create a feature branch (`git checkout -b feat/my-feature`)
+3. Commit with [conventional commits](https://www.conventionalcommits.org/) (`feat: ...`, `fix: ...`, `docs: ...`)
+4. Open a pull request against `main`
+
+Make sure `bun test` and `bun run typecheck` pass locally before submitting.
+
+## Releasing
+
+Releases are automated via [release-please](https://github.com/googleapis/release-please). Merge commits to `main` with conventional-commit titles to trigger release PRs. Publishing to npm uses provenance and the `NPM_TOKEN` secret.
+
+## License
+
+[MIT](./LICENSE) © itzptk

package/package.json

@@ -0,0 +1,47 @@
+{
+  "name": "@itzptk/ocps",
+  "version": "1.0.0",
+  "description": "opencode plugin starter — scaffold a new opencode plugin project via `npx ocps init`",
+  "type": "module",
+  "bin": {
+    "ocps": "./src/cli.ts"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "exports": "./src/index.ts",
+  "files": [
+    "src",
+    "templates",
+    "README.md"
+  ],
+  "scripts": {
+    "test": "bun test",
+    "typecheck": "tsc -p tsconfig.json --noEmit"
+  },
+  "devDependencies": {
+    "@types/node": "latest",
+    "bun-types": "^1.3.14",
+    "typescript": "latest"
+  },
+  "keywords": [
+    "opencode",
+    "opencode-plugin",
+    "plugin",
+    "scaffold",
+    "template",
+    "boilerplate",
+    "starter",
+    "generator",
+    "create"
+  ],
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/itzptk/ocps.git"
+  },
+  "bugs": {
+    "url": "https://github.com/itzptk/ocps/issues"
+  },
+  "homepage": "https://github.com/itzptk/ocps#readme"
+}

package/src/cli.ts

@@ -0,0 +1,190 @@
+#!/usr/bin/env node
+
+import { existsSync, readdirSync, statSync } from "node:fs";
+import { dirname, join, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+import { spawnSync } from "node:child_process";
+import { scaffold, ScaffoldError, type ScaffoldOptions } from "./scaffold";
+
+const SCRIPT_DIR = typeof __dirname !== "undefined"
+  ? __dirname
+  : dirname(fileURLToPath(import.meta.url));
+const PACKAGE_ROOT = join(SCRIPT_DIR, "..");
+
+type ParsedArgs = {
+  command: string | null;
+  directory?: string;
+  name?: string;
+  description?: string;
+  author?: string;
+  force: boolean;
+  noInstall: boolean;
+  help: boolean;
+};
+
+function parseArgs(argv: string[]): ParsedArgs {
+  const out: ParsedArgs = {
+    command: null,
+    force: false,
+    noInstall: false,
+    help: false,
+  };
+  const positional: string[] = [];
+  for (let i = 0; i < argv.length; i++) {
+    const arg = argv[i]!;
+    if (arg === "-h" || arg === "--help") {
+      out.help = true;
+    } else if (arg === "--force") {
+      out.force = true;
+    } else if (arg === "--no-install") {
+      out.noInstall = true;
+    } else if (arg === "--name") {
+      out.name = argv[++i];
+    } else if (arg.startsWith("--name=")) {
+      out.name = arg.slice("--name=".length);
+    } else if (arg === "--description") {
+      out.description = argv[++i];
+    } else if (arg.startsWith("--description=")) {
+      out.description = arg.slice("--description=".length);
+    } else if (arg === "--author") {
+      out.author = argv[++i];
+    } else if (arg.startsWith("--author=")) {
+      out.author = arg.slice("--author=".length);
+    } else if (arg.startsWith("--")) {
+      throw new CliError(`Unknown option: ${arg}`);
+    } else {
+      positional.push(arg);
+    }
+  }
+  if (positional.length > 0) out.command = positional[0]!;
+  if (positional.length > 1) out.directory = positional[1];
+  return out;
+}
+
+class CliError extends Error {}
+
+function printHelp(): void {
+  const lines = [
+    "ocps - scaffold a new opencode plugin",
+    "",
+    "Usage:",
+    "  ocps init [directory] --name <package-name> [options]",
+    "",
+    "Options:",
+    "  --name <name>           npm package name for the plugin (required)",
+    "  --description <text>    Short description for package.json and README",
+    "  --author <name>          Copyright author name for LICENSE",
+    "  --force                 Write into a non-empty directory (does not delete existing files)",
+    "  --no-install            Skip running bun install after scaffolding",
+    "  -h, --help              Show this help",
+    "",
+    "Examples:",
+    "  ocps init my-plugin --name opencode-greeter",
+    "  ocps init --name @scope/opencode-greeter --author \"Jane Doe\"",
+  ];
+  process.stdout.write(lines.join("\n") + "\n");
+}
+
+function detectBun(): string | null {
+  const r = spawnSync("bun", ["--version"], { stdio: "ignore" });
+  return r.status === 0 ? "bun" : null;
+}
+
+function runInstall(directory: string, noInstall: boolean): void {
+  if (noInstall) {
+    printNext(directory, false);
+    return;
+  }
+  const bun = detectBun();
+  if (!bun) {
+    process.stdout.write("\nBun was not detected. Next step:\n  cd " + directory + " && bun install\n");
+    return;
+  }
+  process.stdout.write("\nRunning bun install...\n");
+  const r = spawnSync(bun, ["install"], { cwd: directory, stdio: "inherit" });
+  if (r.status !== 0) {
+    process.stdout.write("\nbun install exited with code " + String(r.status) + ". You can retry manually.\n");
+    return;
+  }
+  printNext(directory, true);
+}
+
+function printNext(directory: string, installed: boolean): void {
+  const cd = directory === process.cwd() ? "" : `cd ${directory}\n`;
+  const installLine = installed ? "" : "bun install\n";
+  process.stdout.write(
+    [
+      "",
+      "Done. Next steps:",
+      cd ? "  " + cd.replace(/\n$/, "") : null,
+      "  " + installLine.replace(/\n$/, ""),
+      "  bun test",
+      "  bun run typecheck",
+      "",
+      "Then register the plugin in your opencode.json:",
+      '  { "$schema": "https://opencode.ai/config.json", "plugin": ["<name>"] }',
+      "",
+    ]
+      .filter((l) => l !== null && l !== "" || l === "")
+      .join("\n") + "\n",
+  );
+}
+
+function runInit(args: ParsedArgs): void {
+  if (!args.name) {
+    throw new CliError("Missing required option: --name <package-name>");
+  }
+  const opts: ScaffoldOptions = {
+    name: args.name,
+    directory: args.directory,
+    description: args.description,
+    authorName: args.author,
+    force: args.force,
+  };
+  const result = scaffold(opts, PACKAGE_ROOT);
+  process.stdout.write(
+    `Created ${result.written.length} files in ${result.directory}\n` +
+    `  package:  ${result.name}\n` +
+    `  export:   ${result.exportName}\n`,
+  );
+  runInstall(result.directory, args.noInstall);
+}
+
+function main(): void {
+  let args: ParsedArgs;
+  try {
+    args = parseArgs(process.argv.slice(2));
+  } catch (err) {
+    if (err instanceof CliError) {
+      process.stderr.write(`Error: ${err.message}\n`);
+      process.exitCode = 1;
+      return;
+    }
+    throw err;
+  }
+
+  if (args.help || args.command === null) {
+    printHelp();
+    return;
+  }
+
+  if (args.command !== "init") {
+    process.stderr.write(`Unknown command: ${args.command}\n`);
+    process.stderr.write("Run with --help for usage.\n");
+    process.exitCode = 2;
+    return;
+  }
+
+  try {
+    runInit(args);
+  } catch (err) {
+    if (err instanceof ScaffoldError || err instanceof CliError) {
+      process.stderr.write(`Error: ${err.message}\n`);
+      process.exitCode = 1;
+      return;
+    }
+    throw err;
+  }
+}
+
+main();

package/src/index.ts

@@ -0,0 +1,10 @@
+export { scaffold, ScaffoldError, resolveDirectory, type ScaffoldOptions, type ScaffoldResult } from "./scaffold";
+export {
+  parseName,
+  isValidName,
+  toPascalCase,
+  deriveExportName,
+  derivePluginExportName,
+  type ParsedName,
+} from "./name";
+export { render, listTemplateFiles, defaultTemplateDir, type TemplateVars, type TemplateFile } from "./template-files";

package/src/name.ts

@@ -0,0 +1,71 @@
+/**
+ * npm package name validation and TypeScript export name derivation.
+ */
+
+const NAME_RE = /^(?:@([a-z0-9][a-z0-9._-]*)\/)?([a-z0-9][a-z0-9._-]*)$/;
+
+export type ParsedName = {
+  raw: string;
+  scope: string | null;
+  local: string;
+};
+
+export function parseName(raw: string): ParsedName | null {
+  const trimmed = raw.trim();
+  if (trimmed.length === 0) return null;
+  if (trimmed.length > 214) return null;
+  const match = NAME_RE.exec(trimmed);
+  if (!match) return null;
+  const scope = match[1] ?? null;
+  const local = match[2]!;
+  if (scope !== null && scope.length > 214) return null;
+  if (local.length > 214) return null;
+  if (trimmed.toLowerCase() === "node_modules" || trimmed.toLowerCase() === "favicon.ico") return null;
+  return { raw: trimmed, scope, local };
+}
+
+export function isValidName(raw: string): boolean {
+  return parseName(raw) !== null;
+}
+
+const RESERVED_WORDS = new Set([
+  "abstract", "await", "boolean", "break", "byte", "case", "catch", "char",
+  "class", "const", "continue", "debugger", "default", "delete", "do", "double",
+  "else", "enum", "export", "extends", "false", "final", "finally", "float",
+  "for", "function", "goto", "if", "implements", "import", "in", "instanceof",
+  "int", "interface", "let", "long", "native", "new", "null", "package", "private",
+  "protected", "public", "return", "short", "static", "super", "switch",
+  "synchronized", "this", "throw", "throws", "transient", "true", "try",
+  "typeof", "var", "void", "volatile", "while", "with", "yield",
+]);
+
+export function toPascalCase(input: string): string {
+  const cleaned = input.replace(/[^a-zA-Z0-9]+/g, " ").trim();
+  if (cleaned.length === 0) return "Plugin";
+  const parts = cleaned.split(/\s+/).filter(Boolean);
+  const pascal = parts
+    .map((p) => p.charAt(0).toUpperCase() + p.slice(1))
+    .join("");
+  if (RESERVED_WORDS.has(pascal.toLowerCase())) return `${pascal}Plugin`;
+  if (/^[0-9]/.test(pascal)) return `Plugin${pascal}`;
+  return pascal;
+}
+
+export function deriveExportName(raw: string, opts: { stripScope?: boolean } = {}): string {
+  const parsed = parseName(raw);
+  if (!parsed) return "MyPlugin";
+  const source = opts.stripScope ? parsed.local : (parsed.scope ? `${parsed.scope}-${parsed.local}` : parsed.local);
+  return `${toPascalCase(source)}Plugin`;
+}
+
+export function derivePluginExportName(raw: string): string {
+  const parsed = parseName(raw);
+  if (!parsed) return "MyPlugin";
+  return `${toPascalCase(parsed.local)}Plugin`;
+}
+
+export function sanitizePathSegment(raw: string): string {
+  const parsed = parseName(raw);
+  if (!parsed) return "opencode-plugin";
+  return parsed.scope ? `${parsed.scope}/${parsed.local}` : parsed.local;
+}

package/src/scaffold.ts

@@ -0,0 +1,94 @@
+import { existsSync, mkdirSync, readdirSync, statSync, writeFileSync } from "node:fs";
+import { dirname, join, resolve } from "node:path";
+import {
+  derivePluginExportName,
+  parseName,
+  type ParsedName,
+} from "./name";
+import { defaultTemplateDir, listTemplateFiles, render, type TemplateVars } from "./template-files";
+
+export type ScaffoldOptions = {
+  name: string;
+  directory?: string;
+  description?: string;
+  authorName?: string;
+  force?: boolean;
+};
+
+export type ScaffoldResult = {
+  directory: string;
+  written: string[];
+  name: string;
+  exportName: string;
+};
+
+export class ScaffoldError extends Error {}
+
+const IGNORED_EXISTING = new Set([".git", ".DS_Store"]);
+
+function dirIsEmptyOrVcsOnly(dir: string): boolean {
+  if (!existsSync(dir)) return true;
+  const entries = readdirSync(dir).filter((e) => !IGNORED_EXISTING.has(e));
+  return entries.length === 0;
+}
+
+export function resolveDirectory(opts: ScaffoldOptions, parsed: ParsedName): string {
+  if (opts.directory && opts.directory.trim().length > 0) {
+    return resolve(opts.directory);
+  }
+  return resolve(parsed.local);
+}
+
+export function scaffold(
+  opts: ScaffoldOptions,
+  templateRootDir: string,
+  now: Date = new Date(),
+): ScaffoldResult {
+  const parsed = parseName(opts.name);
+  if (!parsed) {
+    throw new ScaffoldError(`Invalid package name: "${opts.name}". Use a valid npm name like "opencode-foo" or "@scope/opencode-foo".`);
+  }
+
+  const directory = resolveDirectory(opts, parsed);
+  if (existsSync(directory) && statSync(directory).isFile()) {
+    throw new ScaffoldError(`Target path exists and is a file: ${directory}`);
+  }
+  if (existsSync(directory) && !statSync(directory).isDirectory()) {
+    throw new ScaffoldError(`Target path is not a directory: ${directory}`);
+  }
+  if (!opts.force && existsSync(directory) && !dirIsEmptyOrVcsOnly(directory)) {
+    throw new ScaffoldError(
+      `Target directory is not empty: ${directory}. Pass --force to overwrite, or choose an empty directory.`,
+    );
+  }
+
+  const exportName = derivePluginExportName(opts.name);
+  const description = (opts.description ?? "An opencode plugin").trim();
+  const year = String(now.getFullYear());
+
+  const vars: TemplateVars = {
+    name: parsed.raw,
+    exportName,
+    description,
+    year,
+    authorName: opts.authorName ?? parsed.local,
+  };
+
+  const templateDir = defaultTemplateDir(templateRootDir);
+  if (!existsSync(templateDir)) {
+    throw new ScaffoldError(`Template directory not found: ${templateDir}`);
+  }
+
+  const files = listTemplateFiles(templateDir);
+  const written: string[] = [];
+
+  for (const file of files) {
+    const target = join(directory, file.relative);
+    mkdirSync(dirname(target), { recursive: true });
+    const body = render(file.content, vars);
+    writeFileSync(target, body);
+    written.push(file.relative);
+  }
+
+  return { directory, written, name: parsed.raw, exportName };
+}

package/src/template-files.ts

@@ -0,0 +1,55 @@
+import { readdirSync, readFileSync, statSync } from "node:fs";
+import { join, relative, sep } from "node:path";
+
+export type TemplateVars = {
+  name: string;
+  exportName: string;
+  description: string;
+  year: string;
+  repository?: string;
+  authorName?: string;
+};
+
+const PLACEHOLDER_RE = /\{\{\s*([a-zA-Z0-9_]+)\s*\}\}/g;
+
+export function render(content: string, vars: TemplateVars): string {
+  return content.replace(PLACEHOLDER_RE, (match, key: string) => {
+    if (key === "name") return vars.name;
+    if (key === "exportName") return vars.exportName;
+    if (key === "description") return vars.description;
+    if (key === "year") return vars.year;
+    if (key === "repository") return vars.repository ?? "";
+    if (key === "authorName") return vars.authorName ?? "";
+    return match;
+  });
+}
+
+export type TemplateFile = {
+  relative: string;
+  content: string;
+};
+
+export function listTemplateFiles(templateDir: string): TemplateFile[] {
+  const results: TemplateFile[] = [];
+  const walk = (dir: string) => {
+    for (const entry of readdirSync(dir)) {
+      const full = join(dir, entry);
+      const st = statSync(full);
+      if (st.isDirectory()) {
+        walk(full);
+        continue;
+      }
+      const rel = relative(templateDir, full).split(sep).join("/");
+      const content = readFileSync(full, "utf-8");
+      const stripped = rel.endsWith(".tpl") ? rel.slice(0, -".tpl".length) : rel;
+      const target = stripped === "gitignore" ? ".gitignore" : stripped;
+      results.push({ relative: target, content });
+    }
+  };
+  walk(templateDir);
+  return results.sort((a, b) => a.relative.localeCompare(b.relative));
+}
+
+export function defaultTemplateDir(rootDir: string): string {
+  return join(rootDir, "templates", "default");
+}

package/templates/default/.github/workflows/ci.yml

@@ -0,0 +1,27 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Setup Bun
+        uses: oven-sh/setup-bun@v2
+        with:
+          bun-version: latest
+
+      - name: Install dependencies
+        run: bun install --frozen-lockfile
+
+      - name: Typecheck
+        run: bun run typecheck
+
+      - name: Test
+        run: bun test

package/templates/default/.github/workflows/release-please.yml

@@ -0,0 +1,37 @@
+name: Release
+
+on:
+  push:
+    branches: [main]
+
+permissions:
+  contents: write
+  pull-requests: write
+  id-token: write
+
+jobs:
+  release-please:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Release Please
+        id: release
+        uses: googleapis/release-please-action@v5
+        with:
+          release-type: node
+
+      - name: Checkout
+        if: ${{ steps.release.outputs.release_created }}
+        uses: actions/checkout@v5
+
+      - name: Setup Node
+        if: ${{ steps.release.outputs.release_created }}
+        uses: actions/setup-node@v5
+        with:
+          node-version: lts/*
+          registry-url: https://registry.npmjs.org
+
+      - name: Publish to npm
+        if: ${{ steps.release.outputs.release_created }}
+        run: npm publish --access public --provenance
+        env:
+          NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}

package/templates/default/LICENSE.tpl

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) {{year}} {{authorName}}
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/templates/default/README.md.tpl

@@ -0,0 +1,48 @@
+# {{name}}
+
+{{description}}
+
+## Install
+
+Add the plugin to your OpenCode config:
+
+```jsonc
+{
+  "$schema": "https://opencode.ai/config.json",
+  "plugin": ["{{name}}"]
+}
+```
+
+Restart OpenCode after changing config.
+
+## Configure with options
+
+You can also pass options inline:
+
+```jsonc
+{
+  "$schema": "https://opencode.ai/config.json",
+  "plugin": [
+    ["{{name}}", { "enabled": true }]
+  ]
+}
+```
+
+## Development
+
+```bash
+bun install
+bun test
+bun run typecheck
+```
+
+## Plugin structure
+
+- `src/index.ts` exports the plugin function. Edit the hooks here.
+- `src/index.test.ts` verifies the plugin initializes and returns hooks.
+
+See the [opencode plugin docs](https://opencode.ai/docs/plugins/) for the full hook surface.
+
+## License
+
+[MIT](./LICENSE) © {{year}}

package/templates/default/gitignore.tpl

@@ -0,0 +1,5 @@
+node_modules/
+*.tgz
+.DS_Store
+.env
+.env.*

package/templates/default/package.json.tpl

@@ -0,0 +1,35 @@
+{
+  "name": "{{name}}",
+  "version": "0.1.0",
+  "description": "{{description}}",
+  "type": "module",
+  "main": "src/index.ts",
+  "exports": "./src/index.ts",
+  "files": [
+    "src",
+    "README.md"
+  ],
+  "scripts": {
+    "test": "bun test",
+    "typecheck": "tsc -p tsconfig.json --noEmit"
+  },
+  "peerDependencies": {
+    "@opencode-ai/plugin": "*"
+  },
+  "devDependencies": {
+    "@opencode-ai/plugin": "latest",
+    "@types/node": "latest",
+    "bun-types": "^1.3.14",
+    "typescript": "latest"
+  },
+  "keywords": [
+    "opencode",
+    "plugin"
+  ],
+  "license": "MIT",
+  "homepage": "https://opencode.ai/docs/plugins/",
+  "repository": {
+    "type": "git",
+    "url": ""
+  }
+}

package/templates/default/src/index.test.ts.tpl

@@ -0,0 +1,60 @@
+/// <reference types="bun-types" />
+
+import { expect, test, mock } from "bun:test";
+import { {{exportName}} } from "./index";
+import type { PluginInput, Hooks } from "@opencode-ai/plugin";
+
+function makeFakeCtx(): { ctx: PluginInput; logCalls: Array<Record<string, unknown>> } {
+  const logCalls: Array<Record<string, unknown>> = [];
+  const ctx = {
+    client: {
+      app: {
+        log: mock((opts: unknown) => {
+          logCalls.push(opts as Record<string, unknown>);
+        }),
+      },
+      session: {},
+      tui: {},
+    },
+    directory: "/test",
+    worktree: "/test",
+    project: { id: "proj-1" },
+    serverUrl: new URL("http://localhost"),
+    $: {} as PluginInput["$"],
+    experimental_workspace: {} as PluginInput["experimental_workspace"],
+  } as unknown as PluginInput;
+  return { ctx, logCalls };
+}
+
+test("plugin initializes, logs, and returns hooks", async () => {
+  const { ctx, logCalls } = makeFakeCtx();
+  const hooks: Hooks = await {{exportName}}(ctx, {});
+
+  expect(hooks.event).toBeDefined();
+  expect(hooks.dispose).toBeDefined();
+  expect(logCalls.length).toBe(1);
+  expect((logCalls[0]!.body as Record<string, unknown>).service).toBe("{{name}}");
+});
+
+test("disabled plugin returns no-op hooks without logging", async () => {
+  const { ctx, logCalls } = makeFakeCtx();
+  const hooks: Hooks = await {{exportName}}(ctx, { enabled: false });
+
+  expect(hooks.event).toBeUndefined();
+  expect(logCalls.length).toBe(0);
+  await hooks.dispose?.();
+});
+
+test("event hook logs session.idle", async () => {
+  const { ctx, logCalls } = makeFakeCtx();
+  const hooks: Hooks = await {{exportName}}(ctx, {});
+
+  await hooks.event?.({ event: { type: "session.idle", properties: {} } as never });
+  for (let i = 0; i < 4; i++) await Promise.resolve();
+
+  const idleLog = logCalls.find(
+    (c) => (c.body as Record<string, unknown>).message === "session idle",
+  );
+  expect(idleLog).toBeDefined();
+  await hooks.dispose?.();
+});

package/templates/default/src/index.ts.tpl

@@ -0,0 +1,45 @@
+import type { Hooks, Plugin } from "@opencode-ai/plugin";
+
+export type {{exportName}}Options = {
+  enabled?: boolean;
+};
+
+const DEFAULT_OPTIONS: {{exportName}}Options = {
+  enabled: true,
+};
+
+export const {{exportName}}: Plugin = async (ctx, rawOptions = {}): Promise<Hooks> => {
+  const options: {{exportName}}Options = {
+    ...DEFAULT_OPTIONS,
+    ...(rawOptions as {{exportName}}Options),
+  };
+
+  if (!options.enabled) {
+    return { dispose: async () => {} };
+  }
+
+  await ctx.client.app.log({
+    body: {
+      service: "{{name}}",
+      level: "info",
+      message: "plugin loaded",
+    },
+  });
+
+  return {
+    event: async ({ event }) => {
+      if (event.type === "session.idle") {
+        await ctx.client.app.log({
+          body: {
+            service: "{{name}}",
+            level: "debug",
+            message: "session idle",
+          },
+        });
+      }
+    },
+    dispose: async () => {},
+  };
+};
+
+export default {{exportName}};

package/templates/default/tsconfig.json

@@ -0,0 +1,11 @@
+{
+  "compilerOptions": {
+    "target": "ES2022",
+    "module": "ESNext",
+    "moduleResolution": "Bundler",
+    "strict": true,
+    "noEmit": true,
+    "types": ["node"]
+  },
+  "include": ["src/**/*.ts"]
+}