overlord-cli 4.1.0 → 4.3.0

package/bin/_cli/setup.mjs

@@ -24,6 +24,8 @@ const PACKAGE_PLUGIN_DIR = path.resolve(__dirname, '..', '..', 'plugins', 'overl
 const REPO_PLUGIN_DIR = path.resolve(__dirname, '..', '..', '..', '..', 'plugins', 'overlord');
 const PACKAGE_CLAUDE_PLUGIN_DIR = path.resolve(__dirname, '..', '..', 'plugins', 'claude');
 const REPO_CLAUDE_PLUGIN_DIR = path.resolve(__dirname, '..', '..', '..', '..', 'plugins', 'claude');
+const PACKAGE_CURSOR_PLUGIN_DIR = path.resolve(__dirname, '..', '..', 'plugins', 'cursor');
+const REPO_CURSOR_PLUGIN_DIR = path.resolve(__dirname, '..', '..', '..', '..', 'plugins', 'cursor');
 const CODEX_TARGET_PLUGIN_DIR = path.join(os.homedir(), '.codex', 'plugins', 'overlord');
 const CODEX_TARGET_PLUGIN_MANIFEST = path.join(
   CODEX_TARGET_PLUGIN_DIR,
@@ -479,9 +481,7 @@ function currentContentHashForAgent(agent) {
     return claudeContentHash();
   }
   if (agent === 'cursor') {
-    return contentHash(
-      [CURSOR_RULES_CONTENT, ...slashCommandFiles('cursor').map(file => file.content)].join('\n')
-    );
+    return contentHashForDirectory(cursorSourcePluginDir());
   }
   if (agent === 'gemini') {
     return contentHash(slashCommandFiles('gemini').map(file => file.content).join('\n'));
@@ -508,6 +508,14 @@ function claudeSourcePluginDir() {
   );
 }
 
+function cursorSourcePluginDir() {
+  if (fs.existsSync(PACKAGE_CURSOR_PLUGIN_DIR)) return PACKAGE_CURSOR_PLUGIN_DIR;
+  if (fs.existsSync(REPO_CURSOR_PLUGIN_DIR)) return REPO_CURSOR_PLUGIN_DIR;
+  throw new Error(
+    `Cursor plugin bundle not found. Checked ${PACKAGE_CURSOR_PLUGIN_DIR} and ${REPO_CURSOR_PLUGIN_DIR}.`
+  );
+}
+
 function listFilesRecursive(dir) {
   if (!fs.existsSync(dir)) return [];
   return fs.readdirSync(dir, { withFileTypes: true }).flatMap(entry => {
@@ -731,6 +739,8 @@ function openCodePaths() {
 function cursorPaths() {
   const base = path.join(os.homedir(), '.cursor');
   return {
+    pluginDir: path.join(base, 'plugins', 'local', 'overlord'),
+    pluginManifest: path.join(base, 'plugins', 'local', 'overlord', '.cursor-plugin', 'plugin.json'),
     rulesFile: path.join(base, 'rules', 'overlord-local.mdc'),
     settingsFile: path.join(base, 'settings.json')
   };
@@ -870,10 +880,21 @@ function installCodex() {
 
 function installCursor() {
   const paths = cursorPaths();
-  writeTextFile(paths.rulesFile, CURSOR_RULES_CONTENT);
-  console.log(`  ✓ Installed rules: ${paths.rulesFile}`);
-
-  const slashResult = installSlashCommands('cursor');
+  const sourceDir = cursorSourcePluginDir();
+  fs.mkdirSync(path.dirname(paths.pluginDir), { recursive: true });
+  fs.rmSync(paths.pluginDir, { recursive: true, force: true });
+  fs.cpSync(sourceDir, paths.pluginDir, { recursive: true });
+  console.log(`  ✓ Installed plugin: ${paths.pluginDir}`);
+
+  if (fs.existsSync(paths.rulesFile)) {
+    fs.rmSync(paths.rulesFile, { force: true });
+    console.log(`  ✓ Removed legacy rules file: ${paths.rulesFile}`);
+  }
+  const removedLegacySlash = uninstallSlashCommands('cursor');
+  if (removedLegacySlash.removedFiles.length > 0) {
+    console.log('  ✓ Removed legacy slash commands:');
+    for (const filePath of removedLegacySlash.removedFiles) console.log(`      ${filePath}`);
+  }
 
   const existingSettings = readJsonFile(paths.settingsFile);
   const permissions =
@@ -898,10 +919,10 @@ function installCursor() {
 
   const manifest = readManifest();
   manifest.cursor = {
-    version: BUNDLE_VERSION,
+    version: pluginVersion(paths.pluginManifest) ?? '0.0.0',
     contentHash: currentContentHashForAgent('cursor'),
     installedAt: new Date().toISOString(),
-    files: [paths.rulesFile, paths.settingsFile, ...slashResult.managedFiles]
+    files: [...listFilesRecursive(paths.pluginDir), paths.settingsFile]
   };
   writeManifest(manifest);
 
@@ -958,8 +979,10 @@ function doctorAgent(agent) {
     agent === 'claude'
       ? pluginVersion(path.join(claudeSourcePluginDir(), '.claude-plugin', 'plugin.json'))
       : agent === 'codex'
-      ? pluginVersion(path.join(codexSourcePluginDir(), '.codex-plugin', 'plugin.json'))
-      : BUNDLE_VERSION;
+        ? pluginVersion(path.join(codexSourcePluginDir(), '.codex-plugin', 'plugin.json'))
+        : agent === 'cursor'
+          ? pluginVersion(path.join(cursorSourcePluginDir(), '.cursor-plugin', 'plugin.json'))
+          : BUNDLE_VERSION;
   const currentHash = currentContentHashForAgent(agent);
 
   if (entry.version !== currentVersion || entry.contentHash !== currentHash) {
@@ -1382,7 +1405,7 @@ export async function runSetupCommand(args) {
   ovld setup           Interactive setup (select agents and configure permissions)
   ovld setup claude    Prepare the Overlord Claude plugin and migrate v3.25 connector files
   ovld setup codex     Install Overlord Codex plugin bundle
-  ovld setup cursor    Install Overlord rules, slash commands, and permissions for Cursor
+  ovld setup cursor    Install Overlord Cursor local plugin and permissions
   ovld setup gemini    Install Overlord slash commands and policy rules for Gemini CLI
   ovld setup opencode  Install Overlord connector for OpenCode
   ovld setup all       Prepare all supported agents

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "overlord-cli",
-  "version": "4.1.0",
+  "version": "4.3.0",
   "description": "Overlord CLI — launch AI agents on tickets from anywhere",
   "type": "module",
   "bin": {

package/plugins/cursor/.cursor-plugin/plugin.json

@@ -0,0 +1,14 @@
+{
+  "name": "overlord",
+  "version": "0.1.0",
+  "description": "Local Overlord workflow plugin for Cursor terminal agents.",
+  "author": {
+    "name": "Cooperativ",
+    "url": "https://github.com/cooperativ"
+  },
+  "homepage": "https://github.com/cooperativ/overlord",
+  "repository": "https://github.com/cooperativ/overlord",
+  "license": "UNLICENSED",
+  "skills": "./skills/",
+  "mcpServers": "./mcp.json"
+}

package/plugins/cursor/commands/connect.md

@@ -0,0 +1 @@
+Run `ovld protocol connect --ticket-id <ticketId>` using the text after `/connect`.

package/plugins/cursor/commands/load.md

@@ -0,0 +1 @@
+Run `ovld protocol load-context --ticket-id <ticketId>` using the text after `/load`.

package/plugins/cursor/commands/spawn.md

@@ -0,0 +1 @@
+Run `ovld protocol spawn --agent cursor --objective "<objective>"` using text after `/spawn` unless raw flags were provided.

package/plugins/cursor/mcp.json

@@ -0,0 +1,8 @@
+{
+  "mcpServers": {
+    "overlord": {
+      "command": "node",
+      "args": ["./scripts/overlord-mcp.mjs"]
+    }
+  }
+}

package/plugins/cursor/rules/overlord-local.mdc

@@ -0,0 +1,8 @@
+---
+description: Overlord local workflow protocol for Cursor.
+alwaysApply: true
+---
+
+# Overlord Local Workflow
+
+Attach first, update during work, ask when blocked, and deliver last using `ovld protocol` commands.

package/plugins/cursor/scripts/overlord-mcp.mjs

@@ -0,0 +1,150 @@
+#!/usr/bin/env node
+
+import { execFile } from 'node:child_process';
+import { promisify } from 'node:util';
+
+const execFileAsync = promisify(execFile);
+const OVLD_BIN = process.env.OVLD_BIN?.trim() || 'ovld';
+const PROTOCOL_VERSION = '2025-06-18';
+let buffer = Buffer.alloc(0);
+
+function send(message) {
+  const json = JSON.stringify(message);
+  const body = Buffer.from(json, 'utf8');
+  const header = Buffer.from(`Content-Length: ${body.length}\r\n\r\n`, 'utf8');
+  process.stdout.write(Buffer.concat([header, body]));
+}
+
+function parseMessages(chunk) {
+  buffer = Buffer.concat([buffer, chunk]);
+  const messages = [];
+  while (true) {
+    const headerEnd = buffer.indexOf('\r\n\r\n');
+    if (headerEnd === -1) break;
+    const headerText = buffer.subarray(0, headerEnd).toString('utf8');
+    const lengthMatch = headerText.match(/Content-Length:\s*(\d+)/i);
+    if (!lengthMatch) throw new Error('Missing Content-Length header');
+    const contentLength = Number(lengthMatch[1]);
+    const totalLength = headerEnd + 4 + contentLength;
+    if (buffer.length < totalLength) break;
+    const body = buffer.subarray(headerEnd + 4, totalLength).toString('utf8');
+    buffer = buffer.subarray(totalLength);
+    messages.push(JSON.parse(body));
+  }
+  return messages;
+}
+
+async function runProtocol(subcommand, args = {}) {
+  const flags = Object.entries(args).flatMap(([key, value]) => {
+    if (value === undefined || value === null) return [];
+    if (typeof value === 'boolean') return value ? [`--${key}`] : [];
+    if (Array.isArray(value)) return [`--${key}`, JSON.stringify(value)];
+    if (typeof value === 'object') return [`--${key}-json`, JSON.stringify(value)];
+    return [`--${key}`, String(value)];
+  });
+
+  try {
+    const { stdout } = await execFileAsync(OVLD_BIN, ['protocol', subcommand, ...flags], {
+      env: {
+        ...process.env,
+        AGENT_IDENTIFIER: process.env.AGENT_IDENTIFIER ?? 'cursor-overlord-plugin'
+      },
+      maxBuffer: 20 * 1024 * 1024
+    });
+    const data = stdout.trim() ? JSON.parse(stdout) : {};
+    return { content: [{ type: 'text', text: JSON.stringify(data, null, 2) }], structuredContent: data };
+  } catch (error) {
+    const message = error instanceof Error ? error.message : String(error);
+    return { content: [{ type: 'text', text: message }], isError: true };
+  }
+}
+
+process.stdin.on('data', async chunk => {
+  for (const message of parseMessages(chunk)) {
+    if (!message || typeof message !== 'object' || !('id' in message)) continue;
+    if (message.method === 'initialize') {
+      send({
+        jsonrpc: '2.0',
+        id: message.id,
+        result: {
+          protocolVersion: PROTOCOL_VERSION,
+          capabilities: { tools: { listChanged: false } },
+          serverInfo: { name: 'overlord-cursor', version: '0.1.0' }
+        }
+      });
+      continue;
+    }
+    if (message.method === 'tools/list') {
+      send({
+        jsonrpc: '2.0',
+        id: message.id,
+        result: {
+          tools: [
+            {
+              name: 'attach_ticket',
+              description: 'Attach to an Overlord ticket.',
+              inputSchema: { type: 'object', properties: { ticket_id: { type: 'string' } }, required: ['ticket_id'] }
+            },
+            {
+              name: 'post_update',
+              description: 'Post a progress update.',
+              inputSchema: {
+                type: 'object',
+                properties: { session_key: { type: 'string' }, ticket_id: { type: 'string' }, summary: { type: 'string' } },
+                required: ['session_key', 'ticket_id', 'summary']
+              }
+            },
+            {
+              name: 'deliver_ticket',
+              description: 'Deliver completed work.',
+              inputSchema: {
+                type: 'object',
+                properties: { session_key: { type: 'string' }, ticket_id: { type: 'string' }, summary: { type: 'string' } },
+                required: ['session_key', 'ticket_id', 'summary']
+              }
+            }
+          ]
+        }
+      });
+      continue;
+    }
+    if (message.method === 'tools/call') {
+      const toolName = message.params?.name;
+      const args = message.params?.arguments ?? {};
+      if (toolName === 'attach_ticket') {
+        send({ jsonrpc: '2.0', id: message.id, result: await runProtocol('attach', { 'ticket-id': args.ticket_id }) });
+      } else if (toolName === 'post_update') {
+        send({
+          jsonrpc: '2.0',
+          id: message.id,
+          result: await runProtocol('update', {
+            'session-key': args.session_key,
+            'ticket-id': args.ticket_id,
+            summary: args.summary,
+            phase: 'execute'
+          })
+        });
+      } else if (toolName === 'deliver_ticket') {
+        send({
+          jsonrpc: '2.0',
+          id: message.id,
+          result: await runProtocol('deliver', {
+            'session-key': args.session_key,
+            'ticket-id': args.ticket_id,
+            summary: args.summary
+          })
+        });
+      } else {
+        send({ jsonrpc: '2.0', id: message.id, error: { code: -32602, message: `Unknown tool: ${toolName}` } });
+      }
+      continue;
+    }
+    if (message.method === 'ping') {
+      send({ jsonrpc: '2.0', id: message.id, result: {} });
+      continue;
+    }
+    send({ jsonrpc: '2.0', id: message.id, error: { code: -32601, message: `Method not found: ${message.method}` } });
+  }
+});
+
+process.stdin.resume();

package/plugins/cursor/skills/overlord-ticket-workflow/SKILL.md

@@ -0,0 +1,8 @@
+---
+name: overlord-ticket-workflow
+description: Durable local workflow for Overlord tickets from Cursor.
+---
+
+# Overlord Ticket Workflow
+
+Attach first with `ovld protocol attach --ticket-id <ticket-id>`, keep the `sessionKey`, post updates during implementation, and deliver last with change rationales.