bobs-workshop 0.3.3 → 3.1.1

package/dist/tools/manual/manual-update.js

@@ -0,0 +1,190 @@
+import { tool } from "@opencode-ai/plugin/tool";
+const MANUAL_TEMPLATE = `# 📘 MANUAL: [Feature Name]
+
+> Created: MAN-YYMMDD-[feature-name].md
+
+## 📊 Executive Summary
+
+High-level overview of what we're building and why.
+
+**Example:**
+- What problem does this solve?
+- Who are the users?
+- What's the success criteria?
+- What are the core features?
+
+---
+
+## 📝 Product Specifications
+
+Detailed requirements and acceptance criteria.
+
+**Example:**
+- User stories / Use cases
+- Functional requirements
+- Non-functional requirements (performance, security, etc.)
+- Edge cases and error handling
+- Success metrics
+
+---
+
+## 🏗️ Architecture Analysis
+
+Technical design decisions and system architecture.
+
+**Example:**
+- System diagram / architecture overview
+- Data models and schemas
+- API endpoints and contracts
+- Database design (indexes, relationships)
+- Authentication/authorization approach
+- Technology choices and trade-offs
+- Security considerations
+
+---
+
+## 🚀 Implementation Plan
+
+Breakdown of tasks with dependencies.
+
+**Example:**
+1. Setup and scaffolding
+2. Database schema migrations
+3. Core business logic
+4. API endpoint implementation
+5. Frontend components
+6. Integration testing
+7. Documentation
+
+Mark completed tasks with ✅, in-progress with 🔄, blocked with 🚫
+
+---
+
+## 📈 Execution Logs
+
+Chronological progress as tasks are completed.
+
+**Format:**
+\`\`\`
+[YYYY-MM-DD HH:MM] - Agent: task description
+  - Output: results / artifacts
+  - Files modified: list of files
+  - Dependencies: what blocked this or what it enables
+\`\`\`
+
+---
+
+## 🔍 Review Notes
+
+Findings from code reviews, architectural reviews, or peer reviews.
+
+**Example:**
+- Code quality observations
+- Performance concerns
+- Security vulnerabilities
+- Suggestions for improvements
+- Action items from reviews
+
+---
+
+## 🐛 Debug Logs
+
+Troubleshooting sessions and root cause analysis.
+
+**Format:**
+\`\`\`
+[YYYY-MM-DD HH:MM] - Issue description
+  - Symptoms: what went wrong
+  - Investigation: steps taken
+  - Root cause: underlying problem
+  - Resolution: fix applied
+  - Prevention: how to avoid recurrence
+\`\`\`
+
+---
+
+## ✅ Verification Logs
+
+Test results and quality assurance checks.
+
+**Example:**
+- Unit test results
+- Integration test results
+- E2E test results
+- Performance benchmarks
+- Security scan results
+- Manual QA checklists
+
+Each verification should include:
+- PASS/FAIL status
+- Evidence (screenshots, logs, metrics)
+- Coverage percentage
+- Blockers for release
+
+---
+
+## 🤝 Agent Handoffs
+
+Context transfers between different agents.
+
+**Format:**
+\`\`\`
+[YYYY-MM-DD HH:MM] - alice → bob
+  - Context: architectural decisions, design docs
+  - Artifacts: MAN-xxx.md, schema.sql
+  - Next steps: implement authentication flow
+\`\`\`
+
+This ensures smooth handoffs between agents and maintains continuity across sessions.
+`;
+const ManualUpdateTool = tool({
+    description: "Update a specific section in a MANUAL file. Creates file/section if missing.",
+    args: {
+        manual_path: tool.schema.string().describe("Path to MANUAL file (e.g., manuals/MAN-260127-auth.md)"),
+        section: tool.schema.string().describe("Section header to update (e.g., '📊 Executive Summary', '📈 Execution Logs')"),
+        content: tool.schema.string().describe("Content to append to the section"),
+        create_if_missing: tool.schema.boolean().default(true)
+            .describe("Create section if it doesn't exist (default: true)"),
+    },
+    async execute(args) {
+        const { readFileSync, writeFileSync, existsSync, mkdirSync } = await import("node:fs");
+        const { dirname } = await import("node:path");
+        const manualPath = args.manual_path;
+        if (!manualPath.match(/^manuals\/MAN-\d{6}-.+\.md$/)) {
+            return `❌ Invalid path. Expected format: manuals/MAN-YYMMDD-<feature>.md`;
+        }
+        const manualsDir = dirname(manualPath);
+        if (!existsSync(manualsDir)) {
+            mkdirSync(manualsDir, { recursive: true });
+        }
+        let content = "";
+        if (existsSync(manualPath)) {
+            content = readFileSync(manualPath, "utf8");
+        }
+        else {
+            content = MANUAL_TEMPLATE;
+            writeFileSync(manualPath, content, "utf8");
+        }
+        const lines = content.split('\n');
+        let sectionIndex = lines.findIndex(l => l.trim() === args.section);
+        if (sectionIndex === -1) {
+            if (!args.create_if_missing) {
+                return `❌ Section '${args.section}' not found in ${manualPath}`;
+            }
+            content = `${content}\n${args.section}\n${args.content}\n`;
+        }
+        else {
+            const insertPosition = sectionIndex + 1;
+            if (lines[insertPosition] && !lines[insertPosition].startsWith('##')) {
+                lines[insertPosition] = `${lines[insertPosition]}\n${args.content}`;
+            }
+            else {
+                lines.splice(insertPosition, 0, args.content);
+            }
+            content = lines.join('\n');
+        }
+        writeFileSync(manualPath, content, "utf8");
+        return `✅ Updated section '${args.section}' in ${manualPath}`;
+    },
+});
+export default ManualUpdateTool;

package/dist/tools/manual/verify-manual.d.ts

@@ -0,0 +1,4 @@
+import { type ToolDefinition } from "@opencode-ai/plugin/tool";
+declare const VerifyManualTool: ToolDefinition;
+export default VerifyManualTool;
+//# sourceMappingURL=verify-manual.d.ts.map

package/dist/tools/manual/verify-manual.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"verify-manual.d.ts","sourceRoot":"","sources":["../../../src/tools/manual/verify-manual.ts"],"names":[],"mappings":"AAAA,OAAO,EAAQ,KAAK,cAAc,EAAE,MAAM,0BAA0B,CAAC;AAErE,QAAA,MAAM,gBAAgB,EAAE,cAuDtB,CAAC;AAEH,eAAe,gBAAgB,CAAC"}

package/dist/tools/manual/verify-manual.js

@@ -0,0 +1,51 @@
+import { tool } from "@opencode-ai/plugin/tool";
+const VerifyManualTool = tool({
+    description: "Run bob-rev verification in background for a MANUAL",
+    args: {
+        manual_path: tool.schema.string().describe("Path to MANUAL file (e.g., manuals/MAN-260127-auth.md)"),
+    },
+    async execute(args, context) {
+        const { client, directory, sessionID } = context;
+        const createResult = await client.session.create({
+            body: {
+                parentID: sessionID,
+                title: `Verification: ${args.manual_path.split('/').pop()}`,
+            },
+            query: { directory },
+        });
+        const createData = createResult;
+        if (createData.error) {
+            throw new Error(`Failed to create verification session: ${createData.error}`);
+        }
+        const { readFileSync, existsSync } = await import("node:fs");
+        const { join } = await import("node:path");
+        let manualContent = "";
+        if (existsSync(args.manual_path)) {
+            manualContent = readFileSync(args.manual_path, "utf8");
+            // Sanitize content to prevent JSON parsing issues with kimi model
+            manualContent = manualContent
+                .replace(/[\x00-\x08\x0B-\x0C\x0E-\x1F]/g, '') // Remove control chars except \n, \r, \t
+                .replace(/\u2028/g, '\n') // Replace line separator with newline
+                .replace(/\u2029/g, '\n'); // Replace paragraph separator with newline
+        }
+        const skillPath = join(directory, ".opencode", "agent", "bobs-workshop", "bob-rev.md");
+        let agentPrompt = "You are bob-rev, a reviewer agent that verifies implementation against MANUAL requirements.";
+        if (existsSync(skillPath)) {
+            agentPrompt = readFileSync(skillPath, "utf8");
+        }
+        await client.session.prompt({
+            path: { id: createData.data.id },
+            body: {
+                agent: "bob-rev",
+                system: `${agentPrompt}\n\n## MANUAL to Verify:\n${manualContent}`,
+                tools: {
+                    task: false,
+                    delegate_task: false,
+                },
+                parts: [{ type: "text", text: "Verify this MANUAL and provide PASS/FAIL decision with reasoning." }],
+            },
+        });
+        return `✅ Started verification for ${args.manual_path} in session ${createData.data.id}`;
+    },
+});
+export default VerifyManualTool;

package/package.json

@@ -1,86 +1,54 @@
 {
   "name": "bobs-workshop",
-  "version": "0.3.3",
-  "description": "Bob's Workshop — agentic development helper with observability, guard rails, research, and review capabilities",
+  "version": "3.1.1",
+  "description": "MANUAL-driven development with background agents for OpenCode",
   "type": "module",
-  "main": "dist/index.js",
+  "main": "./dist/plugins/bobs-workshop.js",
+  "types": "./dist/plugins/bobs-workshop.d.ts",
+  "files": [
+    "src/agents",
+    "src/skills",
+    "src/tools",
+    "src/plugins",
+    "dist/tools",
+    "dist/plugins",
+    "config",
+    "postinstall.js",
+    "uninstall.js"
+  ],
   "bin": {
-    "bobs-mcp": "dist/index.js",
-    "bobs": "bin/bobs-mcp.js"
+    "bobs-workshop": "bin/bobs-workshop.js"
   },
   "scripts": {
-    "dev": "tsx src/index.ts",
-    "build": "tsc",
-    "start": "node dist/index.js",
-    "test": "jest",
-    "lint": "eslint src --ext .ts",
-    "dashboard": "node dist/dashboard/server.js",
-    "postinstall": "node scripts/install-search-tools.js && node scripts/init-workspace.js",
-    "install-search-tools": "node scripts/install-search-tools.js",
-    "cleanup:system-logs": "tsx scripts/cleanup-system-logs.ts"
+    "build": "tsc && node scripts/copy-plugin.js",
+    "prepublishOnly": "node scripts/prepublish.js",
+    "postinstall": "node postinstall.js",
+    "test": "bun test",
+    "test:watch": "bun test --watch"
   },
   "dependencies": {
-    "@modelcontextprotocol/sdk": "^1.0.0",
-    "@types/multer": "^2.0.0",
-    "bobs-workshop": "^0.2.0",
-    "chokidar": "^4.0.3",
-    "express": "^4.x",
-    "fs-extra": "^11.x",
-    "glob": "^10.3.10",
-    "lru-cache": "^10.1.0",
-    "minimatch": "^9.0.3",
-    "multer": "^2.0.2",
-    "simple-git": "^3.x",
-    "ts-morph": "^23.0.0",
-    "uuid": "^9.x",
-    "zod": "^3.x",
-    "@vscode/ripgrep": "^1.15.14"
+    "@opencode-ai/plugin": "^1.1.36",
+    "jsonc-parser": "^3.2.1"
   },
   "devDependencies": {
-    "@types/chokidar": "^1.7.5",
-    "@types/express": "^5.0.3",
-    "@types/fs-extra": "^11.0.4",
-    "@types/jest": "^29.x",
-    "@types/node": "^20.x",
-    "@types/uuid": "^10.0.0",
-    "eslint": "^8.x",
-    "jest": "^29.x",
-    "ts-jest": "^29.x",
-    "tsx": "^4.x",
-    "typescript": "^5.x"
+    "@types/node": "^20.0.0",
+    "typescript": "^5.7.2"
   },
   "keywords": [
-    "mcp",
-    "model-context-protocol",
-    "developer-tools",
-    "workshop",
-    "cli",
-    "dashboard",
-    "spec-driven",
-    "development",
-    "typescript",
-    "developer-experience"
+    "opencode",
+    "plugin",
+    "agents",
+    "manual-driven",
+    "background-tasks"
   ],
-  "author": "Bob's Workshop Contributors",
+  "author": "pwnk77",
   "license": "MIT",
   "repository": {
     "type": "git",
-    "url": "git+https://github.com/your-org/bobs-workshop.git"
+    "url": "git+https://github.com/pwnk77/bobs-workshop.git"
   },
-  "homepage": "https://github.com/your-org/bobs-workshop#readme",
   "bugs": {
-    "url": "https://github.com/your-org/bobs-workshop/issues"
+    "url": "https://github.com/pwnk77/bobs-workshop/issues"
   },
-  "engines": {
-    "node": ">=18.0.0"
-  },
-  "files": [
-    "dist/**/*",
-    "bin/**/*",
-    "scripts/**/*",
-    "public/**/*",
-    "README.md",
-    "LICENSE",
-    "Claude.md"
-  ]
+  "homepage": "https://github.com/pwnk77/bobs-workshop#readme"
 }

package/postinstall.js

@@ -0,0 +1,193 @@
+/**
+ * postinstall.js — runs only when this package is installed as a dependency in a repo.
+ * Skips when: npm install inside bobs-workshop itself, or global npm update (e.g. npm update -g @opencode/cli).
+ */
+import jsonc, { parse } from 'jsonc-parser';
+import { readFileSync, writeFileSync, existsSync, mkdirSync, copyFileSync, cpSync, readdirSync } from 'fs';
+import { dirname, join } from 'path';
+import { fileURLToPath } from 'url';
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+
+const PACKAGE_NAME = 'bobs-workshop';
+
+/**
+ * Only run when bobs-workshop is installed as a dependency in this repo (npm install at repo level).
+ * Skip when: global npm update, or running from within bobs-workshop repo itself.
+ */
+function isInstalledAsDependencyInThisRepo() {
+  // Use INIT_CWD which npm sets to the directory where 'npm install' was invoked
+  // process.cwd() returns the package directory (node_modules/bobs-workshop/) during postinstall
+  const projectRoot = process.env.INIT_CWD || process.cwd();
+  const pkgPath = join(projectRoot, 'package.json');
+  if (!existsSync(pkgPath)) return false;
+  let pkg;
+  try {
+    pkg = JSON.parse(readFileSync(pkgPath, 'utf8'));
+  } catch {
+    return false;
+  }
+  const deps = { ...pkg.dependencies, ...pkg.devDependencies };
+  return typeof deps[PACKAGE_NAME] === 'string';
+}
+
+function checkConflicts(opencodeDir) {
+  const conflicts = [];
+
+  const agentsDir = join(opencodeDir, 'agents');
+  if (existsSync(agentsDir)) {
+    const ourAgents = ['alice.md', 'bob.md', 'bob-rev.md', 'trace.md', 'bob-send.md'];
+    const existingAgents = readdirSync(agentsDir).filter(f => f.endsWith('.md'));
+
+    existingAgents.forEach(agent => {
+      if (ourAgents.includes(agent)) {
+        conflicts.push({ path: join(agentsDir, agent), type: 'agent' });
+      }
+    });
+  }
+
+  const skillsDir = join(opencodeDir, 'skills');
+  if (existsSync(skillsDir)) {
+    const skillNames = ['architecture', 'exploration', 'api-patterns',
+      'brainstorming', 'clean-code', 'code-review-checklist',
+      'database-design', 'frontend-ui-ux', 'git-master',
+      'performance', 'plan-writing', 'security', 'simplification',
+      'systematic-debugging', 'testing-patterns', 'verification'];
+
+    skillNames.forEach(skill => {
+      const skillPath = join(skillsDir, skill);
+      if (existsSync(skillPath)) {
+        conflicts.push({ path: skillPath, type: 'skill' });
+      }
+    });
+  }
+
+  return conflicts;
+}
+
+function postinstall() {
+  if (!isInstalledAsDependencyInThisRepo()) {
+    return; // Not a repo that depends on bobs-workshop (e.g. global update or bobs-workshop repo itself)
+  }
+
+  // Use INIT_CWD to get the actual project directory where npm install was run
+  const projectRoot = process.env.INIT_CWD || process.cwd();
+  const opencodeDir = join(projectRoot, '.opencode');
+
+  console.log('🔧 Installing bobs-workshop...');
+
+  const conflicts = checkConflicts(opencodeDir);
+  if (conflicts.length > 0) {
+    console.error('❌ Installation aborted: Conflicts detected');
+    console.error('');
+    console.error('The following items already exist and would be overwritten:');
+    conflicts.forEach(c => console.error(`  - ${c.path} (${c.type})`));
+    console.error('');
+    console.error('Please rename these items to resolve conflicts:');
+    console.error('  Agents: Rename .opencode/agents/<name>.md files');
+    console.error('  Skills: Rename .opencode/skills/<name>/SKILL.md directories');
+    console.error('');
+    console.error('Run npm install again after resolving conflicts.');
+    process.exit(1);
+  }
+
+  const dirsToCreate = [
+    join(opencodeDir, 'plugins/bobs-workshop'),
+    join(opencodeDir, 'agents'),
+    join(opencodeDir, 'tools/bobs-workshop'),
+    join(projectRoot, 'manuals')
+  ];
+
+  dirsToCreate.forEach(dir => {
+    if (!existsSync(dir)) {
+      mkdirSync(dir, { recursive: true });
+      console.log(`✅ Created: ${dir}`);
+    }
+  });
+
+  const pluginSrc = join(__dirname, 'dist/plugins/bobs-workshop.js');
+  const pluginDest = join(opencodeDir, 'plugins/bobs-workshop/plugin.js');
+
+  if (existsSync(pluginSrc)) {
+    copyFileSync(pluginSrc, pluginDest);
+    console.log(`✅ Copied plugin to: ${pluginDest}`);
+  } else {
+    console.warn('⚠️  Plugin file not found. Did you run npm run build?');
+  }
+
+  const agentSrcDir = join(__dirname, 'src/agents');
+  const agentDestDir = join(opencodeDir, 'agents');
+
+  if (existsSync(agentSrcDir)) {
+    cpSync(agentSrcDir, agentDestDir, { recursive: true });
+    console.log('✅ Copied agent definitions');
+  }
+
+  const skillSrcDir = join(__dirname, 'src/skills');
+  const skillDestDir = join(opencodeDir, 'skills');
+
+  if (existsSync(skillSrcDir)) {
+    cpSync(skillSrcDir, skillDestDir, { recursive: true });
+    console.log('✅ Copied skill definitions');
+  }
+
+  const toolsSrcDir = join(__dirname, 'dist/tools');
+  const toolsDestDir = join(opencodeDir, 'tools/bobs-workshop');
+
+  if (existsSync(toolsSrcDir)) {
+    cpSync(toolsSrcDir, toolsDestDir, { recursive: true });
+    console.log('✅ Copied tool definitions');
+  }
+
+  const configPath = join(opencodeDir, 'opencode.jsonc');
+  const configContent = existsSync(configPath)
+    ? readFileSync(configPath, 'utf8')
+    : '{}';
+
+  let config;
+  try {
+    config = parse(configContent, { allowTrailingComma: true });
+  } catch (err) {
+    console.warn(`⚠️  Could not parse opencode.jsonc: ${err.message}`);
+    config = {};
+  }
+
+  const agentsConfig = JSON.parse(readFileSync(
+    join(__dirname, 'config/agents.json'), 'utf8'
+  ));
+
+  if (!config.agent) config.agent = {};
+  let agentsAdded = 0;
+
+  Object.entries(agentsConfig).forEach(([name, agentDef]) => {
+    if (!config.agent[name]) {
+      config.agent[name] = agentDef;
+      console.log(`✅ Added agent: ${name}`);
+      agentsAdded++;
+    } else {
+      console.log(`⏭️  Agent ${name} already exists, skipping`);
+    }
+  });
+
+  if (agentsAdded === 0) {
+    console.log('ℹ️  All agents already configured');
+  }
+
+  const newConfig = JSON.stringify(config, null, 2);
+  writeFileSync(configPath, newConfig);
+
+  console.log('✅ bobs-workshop installed successfully!');
+  console.log('');
+  console.log('Next steps:');
+  console.log('  1. Review your agents in .opencode/opencode.jsonc');
+  console.log('  2. Create your first MANUAL: manuals/MAN-260128-feature.md');
+  console.log('  3. Start using background_agent, manual_update, verify_manual tools');
+}
+
+try {
+  postinstall();
+} catch (error) {
+  console.error('❌ Installation failed:', error.message);
+  console.error(error.stack);
+  process.exit(1);
+}