opencode-agent-kit 1.0.0

package/bin/commands/init.mjs

@@ -0,0 +1,221 @@
+import { readFileSync, existsSync, copyFileSync, mkdirSync, writeFileSync, readdirSync, statSync } from 'fs';
+import { join, dirname } from 'path';
+import { fileURLToPath } from 'url';
+import { execSync } from 'child_process';
+
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = dirname(__filename);
+const PKG_ROOT = join(__dirname, '..', '..');
+const TEMPLATE_DIR = join(PKG_ROOT, 'template');
+
+function copyRecursive(src, dest) {
+  if (!existsSync(src)) return;
+  const entries = readdirSync(src, { withFileTypes: true });
+  mkdirSync(dest, { recursive: true });
+  for (const entry of entries) {
+    if (entry.name === '.DS_Store') continue;
+    const srcPath = join(src, entry.name);
+    const destPath = join(dest, entry.name);
+    if (entry.isDirectory()) {
+      copyRecursive(srcPath, destPath);
+    } else {
+      copyFileSync(srcPath, destPath);
+    }
+  }
+}
+
+function detectPackageManager(cwd) {
+  if (existsSync(join(cwd, 'bun.lock'))) return 'bun';
+  if (existsSync(join(cwd, 'pnpm-lock.yaml'))) return 'pnpm';
+  if (existsSync(join(cwd, 'yarn.lock'))) return 'yarn';
+  return 'npm';
+}
+
+function mergeJson(target, source, strategy = {}) {
+  const merged = JSON.parse(JSON.stringify(target));
+
+  for (const [key, value] of Object.entries(source)) {
+    if (!(key in merged)) {
+      merged[key] = JSON.parse(JSON.stringify(value));
+      continue;
+    }
+
+    const rule = strategy[key] || 'default';
+
+    if (rule === 'keep-target') {
+      // Keep user's existing value
+      continue;
+    }
+
+    if (rule === 'source-wins') {
+      merged[key] = JSON.parse(JSON.stringify(value));
+      continue;
+    }
+
+    if (rule === 'merge-agents') {
+      merged[key] = merged[key] || {};
+      for (const [agentKey, agentVal] of Object.entries(value)) {
+        if (!(agentKey in merged[key])) {
+          merged[key][agentKey] = JSON.parse(JSON.stringify(agentVal));
+        }
+        // else: keep user's existing agent (unless --force)
+      }
+      continue;
+    }
+
+    if (rule === 'merge-mcp') {
+      merged[key] = merged[key] || {};
+      for (const [mcpKey, mcpVal] of Object.entries(value)) {
+        if (!(mcpKey in merged[key])) {
+          merged[key][mcpKey] = JSON.parse(JSON.stringify(mcpVal));
+        }
+      }
+      continue;
+    }
+
+    if (rule === 'merge-instructions') {
+      const existing = merged[key] || [];
+      const srcArr = Array.isArray(value) ? value : [value];
+      for (const item of srcArr) {
+        if (!existing.includes(item)) {
+          existing.push(item);
+        }
+      }
+      merged[key] = existing;
+      continue;
+    }
+
+    if (rule === 'merge-permissions') {
+      merged[key] = merged[key] || {};
+      for (const [permKey, permVal] of Object.entries(value)) {
+        if (!(permKey in merged[key])) {
+          merged[key][permKey] = JSON.parse(JSON.stringify(permVal));
+        }
+      }
+      continue;
+    }
+
+    // default: source wins for top-level, but merge nested objects
+    if (typeof value === 'object' && value !== null && !Array.isArray(value) &&
+        typeof merged[key] === 'object' && merged[key] !== null && !Array.isArray(merged[key])) {
+      merged[key] = { ...merged[key], ...value };
+    } else {
+      merged[key] = value;
+    }
+  }
+
+  return merged;
+}
+
+function mergeOencodeConfig(templateConfigPath, userConfigPath, force) {
+  const templateConfig = JSON.parse(readFileSync(templateConfigPath, 'utf-8'));
+  const userConfig = existsSync(userConfigPath)
+    ? JSON.parse(readFileSync(userConfigPath, 'utf-8'))
+    : {};
+
+  const strategy = {
+    '$schema': 'source-wins',
+    'formatter': 'keep-target',
+    'permission': 'keep-target',
+    'instructions': 'merge-instructions',
+    'mcp': 'merge-mcp',
+    'agent': force ? 'source-wins' : 'merge-agents',
+    'plugin': 'merge-instructions',
+  };
+
+  const merged = mergeJson(userConfig, templateConfig, strategy);
+  return merged;
+}
+
+export async function init(options) {
+  const targetDir = options.dir;
+  const force = options.force;
+  const skipInstall = options.skipInstall;
+
+  console.log(`\n  opencode-agent-kit init`);
+
+  // 1. Validate target
+  if (!existsSync(targetDir)) {
+    console.error(`  ✗ Target directory does not exist: ${targetDir}`);
+    process.exit(1);
+  }
+
+  // 2. Check if .opencode already exists
+  const opencodeDir = join(targetDir, '.opencode');
+  const userConfigPath = join(targetDir, 'opencode.json');
+
+  if (existsSync(opencodeDir) && !force) {
+    console.log(`  \n  ⚠  .opencode/ already exists in ${targetDir}`);
+    const rl = await import('readline/promises');
+    const readline = rl.createInterface({ input: process.stdin, output: process.stdout });
+    const answer = await readline.question(`  ? Overwrite existing files? [y/N] `);
+    readline.close();
+    if (answer.toLowerCase() !== 'y') {
+      console.log(`  ✗ Aborted.`);
+      process.exit(0);
+    }
+  }
+
+  // 3. Validate template exists
+  if (!existsSync(TEMPLATE_DIR)) {
+    console.error(`  ✗ Template directory not found at ${TEMPLATE_DIR}`);
+    console.error(`    This is a bug. Please reinstall the package.`);
+    process.exit(1);
+  }
+
+  // 4. Copy .opencode/ from template
+  console.log(`  \n  📁 Copying .opencode/ configuration...`);
+  copyRecursive(join(TEMPLATE_DIR, '.opencode'), opencodeDir);
+
+  // 5. Merge opencode.json
+  const templateConfigPath = join(TEMPLATE_DIR, 'opencode.json');
+  if (existsSync(templateConfigPath)) {
+    console.log(`  📝 Merging opencode.json...`);
+    const merged = mergeOencodeConfig(templateConfigPath, userConfigPath, force);
+    writeFileSync(userConfigPath, JSON.stringify(merged, null, 2) + '\n', 'utf-8');
+  }
+
+  // 6. Handle AGENTS.md (append)
+  const templateAgentsPath = join(TEMPLATE_DIR, 'AGENTS.md');
+  const userAgentsPath = join(targetDir, 'AGENTS.md');
+  if (existsSync(templateAgentsPath)) {
+    const templateContent = readFileSync(templateAgentsPath, 'utf-8');
+    if (existsSync(userAgentsPath) && !force) {
+      const existingContent = readFileSync(userAgentsPath, 'utf-8');
+      if (!existingContent.includes('# opencode-agent-kit')) {
+        console.log(`  📄 Appending to existing AGENTS.md...`);
+        writeFileSync(userAgentsPath, existingContent.trimEnd() + '\n\n' + templateContent, 'utf-8');
+      }
+    } else {
+      console.log(`  📄 Writing AGENTS.md...`);
+      writeFileSync(userAgentsPath, templateContent, 'utf-8');
+    }
+  }
+
+  // 7. Install dependencies
+  if (!skipInstall) {
+    const pm = detectPackageManager(opencodeDir);
+    console.log(`  📦 Installing .opencode/ dependencies with ${pm}...`);
+    try {
+      execSync(`${pm} install`, { cwd: opencodeDir, stdio: 'pipe' });
+    } catch (err) {
+      console.error(`  ⚠  Dependency install failed: ${err.message}`);
+      console.error(`    You can run "${pm} install" manually in .opencode/`);
+    }
+  }
+
+  // 8. Done
+  console.log(`\n  ✅ opencode-agent-kit installed!\n`);
+  console.log(`     Location: ${targetDir}`);
+  console.log(`     What you got:`);
+  console.log(`       • opencode.json        — 13 agents config with MCP servers`);
+  console.log(`       • .opencode/agents/    — 14 agent prompt files`);
+  console.log(`       • .opencode/skills/    — 60+ skill playbooks`);
+  console.log(`       • .opencode/commands/  — 35+ slash commands`);
+  console.log(`       • .opencode/rules/     — Scoped coding rules`);
+  console.log(`       • .opencode/contexts/  — Dev/review/research contexts`);
+  console.log(`       • .opencode/agent-docs/— Agent documentation`);
+  console.log(`\n     Next steps:`);
+  console.log(`       cd ${targetDir}`);
+  console.log(`       opencode\n`);
+}

package/bin/init.mjs

@@ -0,0 +1,21 @@
+#!/usr/bin/env node
+
+import { Command } from 'commander';
+import { init } from './commands/init.mjs';
+
+const program = new Command();
+
+program
+  .name('opencode-agent-kit')
+  .description('Install OpenCode multi-agent toolkit into your project')
+  .version('1.0.0');
+
+program
+  .command('init')
+  .description('Initialize .opencode/ configuration in current project')
+  .option('-f, --force', 'Overwrite existing files without prompt')
+  .option('-d, --dir <path>', 'Target project directory', process.cwd())
+  .option('--skip-install', 'Skip npm/bun install step in .opencode/')
+  .action(init);
+
+program.parse();

package/package.json

@@ -0,0 +1,22 @@
+{
+  "name": "opencode-agent-kit",
+  "version": "1.0.0",
+  "description": "Multi-stack OpenCode agent toolkit — 1 orchestrator + 12 specialized subagents for Nuxt, React, Node.js, Laravel, CI3, Android, Flutter, DevOps, SEO, and more",
+  "type": "module",
+  "bin": {
+    "opencode-agent-kit": "./bin/init.mjs"
+  },
+  "files": [
+    "bin/",
+    "template/"
+  ],
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/defuj/frontend-developer-nuxt"
+  },
+  "dependencies": {
+    "commander": "^13.0.0",
+    "fs-extra": "^11.0.0"
+  }
+}

package/template/.opencode/agent-docs/backend/node/BACKEND_PATTERNS.md

@@ -0,0 +1,82 @@
+# Backend Patterns (Enterprise, Portable)
+
+Use these patterns as baseline across backend services with Node.js + TypeScript + Express + Prisma.
+
+## Standard Module Layout
+
+- Controllers: request orchestration and response mapping
+- Routes: endpoint registration and middleware chain
+- DTOs: request validation and response exposure contracts
+- Middlewares: auth, validation, upload, limiter, etc.
+- Utilities/services: reusable domain/business logic
+
+## DTO Conventions
+
+- Request DTO suffix: `*.dto.ts`
+- Response DTO suffix: `*.response.dto.ts`
+- Explicit field exposure with `@Expose()`
+- Route-level validation middleware uses request DTO class
+- Response serialization maps through response DTO with extraneous field exclusion
+
+Example mapping:
+
+```ts
+const result = plainToInstance(ResponseDTO, payload, {
+  excludeExtraneousValues: true,
+});
+```
+
+## API Response Conventions
+
+- Use one centralized response helper for success and error envelopes
+- Keep status/message/data structure consistent across endpoints
+- Avoid ad-hoc response shapes in controllers
+
+## Error Handling Conventions
+
+- Wrap controller logic in try/catch
+- Delegate catch to centralized error handler
+- Provide predictable business error mappings
+- Log unexpected errors once, near boundary layer
+
+## Route and Middleware Conventions
+
+- Register specific paths before parameterized paths
+- Place auth middleware before validation and handler
+- Keep middleware order deterministic and explicit
+- For multipart endpoints, apply upload middleware before DTO validation when needed
+
+## Data Access Conventions
+
+- Use transactions for multi-step state mutations
+- Keep write paths idempotent where practical (especially webhook/event handlers)
+- Query only fields/relations needed for output
+- Maintain tenant/ownership scoping where service model requires it
+
+## Security Conventions
+
+- Validate all external input via DTOs
+- Enforce auth and resource-level authorization consistently
+- Keep error responses safe (no stack traces/internal details)
+- Restrict upload MIME types, size, and destination path
+- Never leak secret values in logs or API responses
+
+## Pagination and List Conventions
+
+- Normalize paging params and cap upper bounds
+- Apply filters and sorting through deterministic query builder logic
+- Return pagination metadata alongside items
+
+## Mutation Conventions
+
+- Validate request payload and preconditions first
+- Apply domain mutation in transaction
+- Emit domain/audit log entries for critical operations
+- Return mapped response DTO from committed state
+
+## Test and Verification Conventions
+
+- Tiny changes: one focused check
+- Small changes: type-check plus one targeted check
+- Medium+ changes: type-check, lint, and relevant tests
+- Contract changes: include endpoint behavior validation

package/template/.opencode/agent-docs/backend/node/BACKEND_QUICK_START.md

@@ -0,0 +1,49 @@
+# Backend Agent Quick Start (Enterprise)
+
+This guide is portable across services that share the same backend stack style.
+
+## Agent Name
+
+- `backend`
+
+## Activate the Agent
+
+```text
+@backend Analyze this backend service and align implementation with existing DTO, route, middleware, and controller patterns.
+```
+
+## High-Value Prompt Templates
+
+```text
+@backend Add endpoint <METHOD> <path> with request/response DTOs, validation middleware, and standardized error handling.
+```
+
+```text
+@backend Implement transaction-safe <business operation> with audit logging and predictable response mapping.
+```
+
+```text
+@backend Review this module for auth boundary, tenant scoping, validation, and API contract consistency.
+```
+
+```text
+@backend Refactor this controller to reduce complexity while preserving behavior and response shape.
+```
+
+## What the agent is optimized for
+
+- Node.js + TypeScript + Express + Prisma services
+- DTO-driven validation and response mapping
+- Consistent route/middleware layering
+- Transaction-safe data mutations
+- Security and tenant/ownership boundaries
+
+## Recommended verification commands
+
+```bash
+npm run type-check
+npm run lint
+npm run test:run
+```
+
+If command names differ in a service, use that service's equivalents.