octocode-cli 1.2.8 → 1.2.9

package/skills/octocode-research/package.json

@@ -1,25 +1,22 @@
 {
-  "name": "octocode-skill",
+  "name": "octocode-research",
   "version": "2.2.0",
-  "type": "module",
   "description": "Code research server using octocode tools - HTTP API on port 1987",
-  "author": "Guy Bary <bgauryy@octocodeai.com>",
-  "homepage": "https://octocode.ai",
-  "repository": "bgauryy/octocode-mcp.git",
-  "bugs": "https://github.com/bgauryy/octocode-mcp/issues",
-  "license": "MIT",
   "keywords": [
     "agent-skill",
     "code-research",
     "http-server",
-    "octocode",
-    "mcp"
+    "mcp",
+    "octocode"
   ],
+  "author": "Guy Bary <bgauryy@octocodeai.com>",
+  "homepage": "https://octocode.ai",
+  "repository": "bgauryy/octocode-mcp.git",
+  "bugs": "https://github.com/bgauryy/octocode-mcp/issues",
+  "license": "MIT",
+  "type": "module",
   "main": "scripts/server.js",
   "types": "scripts/server.d.ts",
-  "bin": {
-    "octocode-research": "./scripts/server.js"
-  },
   "exports": {
     ".": {
       "types": "./scripts/server.d.ts",
@@ -30,38 +27,32 @@
       "import": "./scripts/server.js"
     }
   },
+  "bin": "./scripts/server-init.js",
   "files": [
     "scripts",
     "src",
-    "ecosystem.config.cjs",
     "SKILL.md",
     "tsconfig.json"
   ],
+  "engines": {
+    "node": ">=20.0.0"
+  },
   "scripts": {
     "build": "tsdown",
-    "start": "node scripts/server.js",
-    "server-init": "node scripts/server-init.js",
-    "pm2:start": "pm2 start ecosystem.config.cjs",
-    "pm2:stop": "pm2 stop ecosystem.config.cjs",
-    "pm2:restart": "pm2 restart ecosystem.config.cjs",
-    "pm2:reload": "pm2 reload ecosystem.config.cjs",
-    "pm2:delete": "pm2 delete ecosystem.config.cjs",
-    "pm2:logs": "pm2 logs octocode-research",
-    "pm2:monit": "pm2 monit",
+    "copy:claude": "rm -rf ~/.claude/skills/octocode-research && mkdir -p ~/.claude/skills && cp -r . ~/.claude/skills/octocode-research",
     "dev": "tsx watch src/server.ts",
-    "test": "vitest run",
-    "test:watch": "vitest",
     "lint": "eslint src",
     "lint:fix": "eslint src --fix",
-    "copy:claude": "rm -rf ~/.claude/skills/octocode-research && mkdir -p ~/.claude/skills && cp -r . ~/.claude/skills/octocode-research"
+    "start": "node scripts/server-init.js",
+    "test": "vitest run",
+    "test:watch": "vitest"
   },
   "dependencies": {
     "express": "^4.21.2",
     "js-yaml": "^4.1.1",
     "octocode-mcp": "workspace:^",
     "octocode-shared": "workspace:^",
-    "zod": "^3.25.0",
-    "zod-to-json-schema": "^3.25.1"
+    "zod": "^3.25.0"
   },
   "devDependencies": {
     "@eslint/js": "^9.27.0",
@@ -75,10 +66,7 @@
     "tsdown": "^0.18.3",
     "tsx": "^4.21.0",
     "typescript": "^5.9.3",
-    "typescript-eslint": "^8.32.0",
+    "typescript-eslint": "^8.52.0",
     "vitest": "^4.0.16"
-  },
-  "engines": {
-    "node": ">=20.0.0"
   }
 }

package/skills/octocode-research/references/PARALLEL_AGENT_PROTOCOL.md

@@ -2,6 +2,25 @@
 
 **CRITICAL: When spawning parallel agents, follow this EXACT protocol.**
 
+## When to Use Parallel Agents
+
+| Condition | Action |
+|-----------|--------|
+| Single domain | Sequential OK |
+| Multiple domains / repos / subsystems | **MUST use parallel Task agents** |
+
+**Domain = separate repos, services, languages, or unrelated subsystems.** Same repo across files = single domain (sequential).
+
+| Separate Domains (→ Parallel) | Same Domain (→ Sequential) |
+|------|------|
+| Different repos (react vs vue) | Same repo, different files |
+| Different services (auth vs payments) | Same service, different modules |
+| Different runtimes (JS frontend vs Python backend) | Same language, different packages |
+
+**Agent selection**: Deep exploration → `Explore`/`opus`. Quick lookup → `Explore`/`haiku`.
+
+---
+
 ## Spawn Phase
 
 **Step 1**: Generate session ID and prepare output directory

package/skills/octocode-research/references/SESSION_MANAGEMENT.md

@@ -0,0 +1,38 @@
+# Session & Checkpoint Management
+
+## When to Checkpoint
+
+Checkpoint when context becomes heavy or research is extensive. This prevents context window exhaustion and enables resumption.
+
+| State Transition | Trigger |
+|---|---|
+| RESEARCH → CHECKPOINT | Context heavy or research extensive |
+| CHECKPOINT → RESEARCH | After saving, continue compressed |
+| OUTPUT → PLAN/RESEARCH | User says "continue researching" |
+
+## Checkpoint Protocol
+
+Save to `.octocode/research/{session-id}/checkpoint-{N}.md`.
+
+**Save**: goal, key findings (file:line), open questions, next steps.
+**Discard**: full tool JSON, intermediate results, verbose hints.
+
+### Session Directory Structure
+
+```
+.octocode/research/{session-id}/
+├── session.json    # {id, state, mainResearchGoal}
+├── checkpoint-*.md
+├── domain-*.md     # Parallel agent outputs
+└── research.md     # Final output
+```
+
+### Resumption
+
+If `session.json` exists with state ≠ DONE → Ask "Resume from last checkpoint?"
+
+When resuming:
+1. Read `session.json` for context
+2. Read latest `checkpoint-*.md` for findings so far
+3. Continue from where the checkpoint left off
+4. Update task status in `TodoWrite`

package/skills/octocode-research/scripts/server-init.js

@@ -1,2 +1,2 @@
 #!/usr/bin/env node
-import{join as e}from"path";import{closeSync as t,constants as n,existsSync as r,mkdirSync as i,openSync as a,readFileSync as o,statSync as s,unlinkSync as c,writeSync as l}from"fs";import{homedir as u}from"os";import{spawn as d}from"child_process";const f=`http://localhost:${parseInt(process.env.OCTOCODE_PORT||`1987`,10)}/health`,p=e(u(),`.octocode`),m=e(p,`server-init.lock`),h=parseInt(process.env.OCTOCODE_LOCK_TIMEOUT||`60000`,10),g=parseInt(process.env.OCTOCODE_INIT_TIMEOUT||`30000`,10),_=parseInt(process.env.OCTOCODE_POLL_INTERVAL||`500`,10);function v(){r(p)||i(p,{recursive:!0})}function y(e){if(!r(e))return!0;try{let t=o(e,`utf-8`);if(t&&t.trim().length>0){let e=JSON.parse(t);if(Date.now()-e.timestamp>h)return!0;try{return process.kill(e.pid,0),!1}catch{return!0}}}catch{}try{let t=s(e);return Date.now()-t.mtimeMs>h}catch{return!0}}function b(e){try{r(e)&&c(e)}catch{}}async function x(){v();for(let e=0;e<3;e++)try{let e=a(m,n.O_CREAT|n.O_EXCL|n.O_WRONLY),r={pid:process.pid,timestamp:Date.now()};return l(e,JSON.stringify(r)),t(e),!0}catch(e){let t=e;if(t.code===`EEXIST`){if(y(m)){b(m),await new Promise(e=>setTimeout(e,50));continue}return!1}else return console.error(`[server-init] Lock error: ${t.message}`),!1}return!1}function S(){try{r(m)&&JSON.parse(o(m,`utf-8`)).pid===process.pid&&c(m)}catch{}}async function C(){try{let e=await fetch(f,{signal:AbortSignal.timeout(5e3)});return e.ok?await e.json():null}catch(e){return e instanceof Error&&!e.message.includes(`ECONNREFUSED`)&&console.error(`[server-init] Health check error: ${e.message}`),null}}function w(){return new Promise((t,n)=>{let r=new URL(`.`,import.meta.url).pathname,i=d(`node`,[e(r,`server.js`)],{detached:!0,stdio:`ignore`,cwd:r});i.on(`error`,e=>{console.error(`[server-init] Failed to start server: ${e.message}`),n(e)}),setTimeout(()=>{i.unref(),console.log(`[server-init] Started server process (pid: ${i.pid})`),t()},100)})}async function T(){let e=Date.now(),t=_;for(;Date.now()-e<g;){let e=await C();if(e?.status===`ok`)return!0;e?.status===`initializing`&&console.log(`[server-init] Server initializing...`),await new Promise(e=>setTimeout(e,t)),t=Math.min(t*1.5,2e3)}return!1}async function E(){let e=await C();e?.status===`ok`&&(console.log(`ok`),process.exit(0)),e?.status===`initializing`&&(console.log(`[server-init] Server is initializing, waiting...`),await T()?(console.log(`ok`),process.exit(0)):(console.error(`[server-init] ERROR: Server stuck in initializing state`),process.exit(1))),await x()||(console.log(`[server-init] Another process is starting server, waiting...`),await T()?(console.log(`ok`),process.exit(0)):(console.error(`[server-init] ERROR: Timeout waiting for server`),process.exit(1)));try{let e=await C();e?.status===`ok`&&(console.log(`ok`),S(),process.exit(0)),e?.status===`initializing`&&(console.log(`[server-init] Server is initializing, waiting...`),await T()?(console.log(`ok`),S(),process.exit(0)):(console.error(`[server-init] ERROR: Server stuck in initializing state`),S(),process.exit(1))),console.log(`[server-init] Server not running, starting...`);try{await w()}catch{console.error(`[server-init] ERROR: Failed to spawn server process`),S(),process.exit(1)}await T()?(console.log(`ok`),S(),process.exit(0)):(console.error(`[server-init] ERROR: Server failed to start within timeout`),S(),process.exit(1))}catch(e){console.error(`[server-init] ERROR:`,e instanceof Error?e.message:e),S(),process.exit(1)}}process.on(`SIGINT`,()=>{S(),process.exit(130)}),process.on(`SIGTERM`,()=>{S(),process.exit(143)}),E();export{};
+import{join as e}from"path";import{spawn as t}from"child_process";const n=parseInt(process.env.OCTOCODE_RESEARCH_PORT||process.env.OCTOCODE_PORT||`1987`,10),r=`http://${process.env.OCTOCODE_RESEARCH_HOST||`localhost`}:${n}/health`,i=parseInt(process.env.OCTOCODE_INIT_TIMEOUT||`30000`,10),a=parseInt(process.env.OCTOCODE_POLL_INTERVAL||`500`,10);async function o(){try{let e=await fetch(r,{signal:AbortSignal.timeout(5e3)});return e.ok?await e.json():null}catch(e){return e instanceof Error&&!e.message.includes(`ECONNREFUSED`)&&console.error(`[server-init] Health check error: ${e.message}`),null}}function s(){return new Promise((n,r)=>{let i=new URL(`.`,import.meta.url).pathname,a=t(`node`,[e(i,`server.js`)],{stdio:`ignore`,cwd:i,detached:!0});a.on(`error`,e=>{console.error(`[server-init] Failed to start server: ${e.message}`),r(e)}),a.unref(),setTimeout(()=>{console.log(`[server-init] Spawned detached server process (pid: ${a.pid})`),n()},100)})}async function c(){let e=Date.now(),t=a;for(;Date.now()-e<i;){let e=await o();if(e?.status===`ok`)return!0;e?.status===`initializing`&&console.log(`[server-init] Server initializing...`),await new Promise(e=>setTimeout(e,t)),t=Math.min(t*1.5,2e3)}return!1}async function l(){let e=await o();e?.status===`ok`&&(console.log(`ok`),process.exit(0)),e?.status===`initializing`&&(console.log(`[server-init] Server is initializing, waiting...`),await c()?(console.log(`ok`),process.exit(0)):(console.error(`[server-init] ERROR: Server stuck in initializing state`),process.exit(1))),console.log(`[server-init] Server not running, starting detached daemon...`);try{await s()}catch{console.error(`[server-init] ERROR: Failed to spawn server process`),process.exit(1)}await c()||(console.error(`[server-init] ERROR: Server failed to start within timeout`),process.exit(1)),console.log(`ok`),process.exit(0)}l();export{};

package/skills/octocode-research/scripts/server.d.ts

@@ -2,7 +2,8 @@
 import { Express } from "express";
 
 //#region src/server.d.ts
+declare const PID_FILE: string;
 declare function createServer(): Promise<Express>;
 declare function startServer(): Promise<void>;
 //#endregion
-export { createServer, startServer };
+export { PID_FILE, createServer, startServer };