@ship-cli/opencode 0.0.4 → 0.0.5

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ship-cli/opencode",
-  "version": "0.0.4",
+  "version": "0.0.5",
   "type": "module",
   "description": "OpenCode plugin for Ship - Linear task management integration",
   "license": "MIT",

package/src/plugin.ts

@@ -14,28 +14,92 @@ import { tool as createTool } from "@opencode-ai/plugin";
 
 type OpencodeClient = PluginInput["client"];
 
-const SHIP_GUIDANCE = `## Ship CLI Guidance
+const SHIP_GUIDANCE = `## Ship Tool Guidance
+
+**IMPORTANT: Always use the \`ship\` tool, NEVER run \`ship\` or \`pnpm ship\` via bash/terminal.**
+
+The \`ship\` tool is available for Linear task management. Use it instead of CLI commands.
+
+### Available Actions (via ship tool)
+- \`ready\` - Tasks you can work on (no blockers)
+- \`blocked\` - Tasks waiting on dependencies  
+- \`list\` - All tasks (with optional filters)
+- \`show\` - Task details (requires taskId)
+- \`start\` - Begin working on task (requires taskId)
+- \`done\` - Mark task complete (requires taskId)
+- \`create\` - Create new task (requires title)
+- \`update\` - Update task (requires taskId + fields to update)
+- \`block\` - Add blocking relationship (requires blocker + blocked)
+- \`unblock\` - Remove blocking relationship (requires blocker + blocked)
+- \`relate\` - Link tasks as related (requires taskId + relatedTaskId)
+- \`prime\` - Get AI context
+- \`status\` - Check configuration
 
-Ship integrates Linear issue tracking with your development workflow. Use it to:
-- View and manage tasks assigned to you
-- Track task dependencies (blockers)
-- Start/complete work on tasks
-- Create new tasks
+### Best Practices
+1. Use \`ship\` tool with action \`ready\` to see available work
+2. Use \`ship\` tool with action \`start\` before beginning work
+3. Use \`ship\` tool with action \`done\` when completing tasks
+4. Use \`ship\` tool with action \`block\` for dependency relationships
 
-### Quick Commands
-- \`ship ready\` - Tasks you can work on (no blockers)
-- \`ship blocked\` - Tasks waiting on dependencies
-- \`ship list\` - All tasks
-- \`ship show <ID>\` - Task details
-- \`ship start <ID>\` - Begin working on task
-- \`ship done <ID>\` - Mark task complete
-- \`ship create "title"\` - Create new task
+### Linear Task Relationships
 
-### Best Practices
-1. Check \`ship ready\` to see what can be worked on
-2. Use \`ship start\` before beginning work
-3. Use \`ship done\` when completing tasks
-4. Check blockers before starting dependent tasks`;
+Linear has native relationship types. **Always use these instead of writing dependencies in text:**
+
+**Blocking (for dependencies):**
+- Use ship tool: action=\`block\`, blocker=\`BRI-100\`, blocked=\`BRI-101\`
+- Use ship tool: action=\`unblock\` to remove relationships
+- Use ship tool: action=\`blocked\` to see waiting tasks
+
+**Related (for cross-references):**
+- Use ship tool: action=\`relate\`, taskId=\`BRI-100\`, relatedTaskId=\`BRI-101\`
+- Use this when tasks are conceptually related but not blocking each other
+
+**Mentioning Tasks in Descriptions (Clickable Pills):**
+To create clickable task pills in descriptions, use full markdown links:
+\`[BRI-123](https://linear.app/WORKSPACE/issue/BRI-123/slug)\`
+
+Get the full URL from ship tool (action=\`show\`, taskId=\`BRI-123\`) and use it in markdown link format.
+Plain text \`BRI-123\` will NOT create clickable pills.
+
+### Task Description Template
+
+\`\`\`markdown
+## Context
+Brief explanation of why this task exists and where it fits.
+
+## Problem Statement
+What specific problem does this task solve? Current vs desired behavior.
+
+## Implementation Notes
+- Key files: \`path/to/file.ts\`
+- Patterns: Reference existing implementations
+- Technical constraints
+
+## Acceptance Criteria
+- [ ] Specific, testable requirement 1
+- [ ] Specific, testable requirement 2
+- [ ] Tests pass
+
+## Out of Scope
+- What NOT to include
+
+## Dependencies
+- Blocked by: [BRI-XXX](url) (brief reason)
+- Blocks: [BRI-YYY](url) (brief reason)
+\`\`\`
+
+**Important:** 
+1. Set blocking relationships via ship tool action=\`block\` (appears in Linear sidebar)
+2. ALSO document in description using markdown links for context
+3. Get task URLs from ship tool action=\`show\`
+
+### Task Quality Checklist
+- Title is actionable and specific (not "Fix bug" but "Fix null pointer in UserService.getById")
+- Context explains WHY, not just WHAT
+- Acceptance criteria are testable
+- **Dependencies set via \`ship block\`** AND documented with markdown links
+- Links use full URL format: \`[BRI-123](https://linear.app/...)\`
+- Priority reflects business impact (urgent/high/medium/low)`;
 
 /**
  * Get the current model/agent context for a session by querying messages.
@@ -66,46 +130,45 @@ async function getSessionContext(
   return undefined;
 }
 
+/**
+ * Get the ship command based on NODE_ENV.
+ * 
+ * - NODE_ENV=development: Use "pnpm ship" (for developing the CLI in this repo)
+ * - Otherwise: Use "ship" (globally installed CLI)
+ */
+function getShipCommand(): string[] {
+  if (process.env.NODE_ENV === "development") {
+    return ["pnpm", "ship"];
+  }
+  return ["ship"];
+}
+
 /**
  * Inject ship context into a session.
  *
- * Runs `ship prime` and injects the output along with CLI guidance.
- * Silently skips if ship is not installed or not initialized.
+ * Injects static guidance for using the ship tool. Does NOT fetch live data
+ * from Linear - the AI should use the ship tool to get task data.
+ * This ensures instant response on first message.
  */
 async function injectShipContext(
   client: OpencodeClient,
-  $: PluginInput["$"],
   sessionID: string,
   context?: { model?: { providerID: string; modelID: string }; agent?: string }
 ): Promise<void> {
   try {
-    // Use quiet() to prevent any output from bleeding into TUI
-    const primeOutput = await $`ship prime`.quiet().text();
-
-    if (!primeOutput || primeOutput.trim() === "") {
-      return;
-    }
-
-    // Wrap the plain markdown output with XML tags (like beads plugin does)
-    const shipContext = `<ship-context>
-${primeOutput.trim()}
-</ship-context>
-
-${SHIP_GUIDANCE}`;
-
-    // Inject content via noReply + synthetic
-    // Must pass model and agent to prevent mode/model switching
+    // Inject only the static guidance - no API calls
+    // The AI will use the ship tool to fetch live data when needed
     await client.session.prompt({
       path: { id: sessionID },
       body: {
         noReply: true,
         model: context?.model,
         agent: context?.agent,
-        parts: [{ type: "text", text: shipContext, synthetic: true }],
+        parts: [{ type: "text", text: SHIP_GUIDANCE, synthetic: true }],
       },
     });
   } catch {
-    // Silent skip if ship prime fails (not installed or not initialized)
+    // Silent skip on error
   }
 }
 
@@ -117,8 +180,9 @@ async function runShip(
   args: string[]
 ): Promise<{ success: boolean; output: string }> {
   try {
+    const cmd = getShipCommand();
     // Use quiet() to prevent output from bleeding into TUI
-    const result = await $`ship ${args}`.quiet().nothrow();
+    const result = await $`${cmd} ${args}`.quiet().nothrow();
     const stdout = await new Response(result.stdout).text();
     const stderr = await new Response(result.stderr).text();
 
@@ -141,9 +205,10 @@ async function runShip(
  */
 async function isShipConfigured($: PluginInput["$"]): Promise<boolean> {
   try {
+    const cmd = getShipCommand();
     // Try running ship prime - it will fail if not configured
     // Use quiet() to suppress stdout/stderr from bleeding into TUI
-    const result = await $`ship prime`.quiet().nothrow();
+    const result = await $`${cmd} prime`.quiet().nothrow();
     return result.exitCode === 0;
   } catch {
     return false;
@@ -234,30 +299,36 @@ Run 'ship init' in the terminal first if not configured.`,
           "start",
           "done",
           "create",
+          "update",
           "block",
           "unblock",
+          "relate",
           "prime",
           "status",
         ])
         .describe(
-          "Action to perform: ready (unblocked tasks), list (all tasks), blocked (blocked tasks), show (task details), start (begin task), done (complete task), create (new task), block/unblock (dependencies), prime (AI context), status (current config)"
+          "Action to perform: ready (unblocked tasks), list (all tasks), blocked (blocked tasks), show (task details), start (begin task), done (complete task), create (new task), update (modify task), block/unblock (dependencies), relate (link related tasks), prime (AI context), status (current config)"
         ),
       taskId: createTool.schema
         .string()
         .optional()
-        .describe("Task identifier (e.g., BRI-123) - required for show, start, done"),
+        .describe("Task identifier (e.g., BRI-123) - required for show, start, done, update"),
       title: createTool.schema
         .string()
         .optional()
-        .describe("Task title - required for create"),
+        .describe("Task title - required for create, optional for update"),
       description: createTool.schema
         .string()
         .optional()
-        .describe("Task description - optional for create"),
+        .describe("Task description - optional for create/update"),
       priority: createTool.schema
         .enum(["urgent", "high", "medium", "low", "none"])
         .optional()
-        .describe("Task priority - optional for create"),
+        .describe("Task priority - optional for create/update"),
+      status: createTool.schema
+        .enum(["backlog", "todo", "in_progress", "in_review", "done", "cancelled"])
+        .optional()
+        .describe("Task status - optional for update"),
       blocker: createTool.schema
         .string()
         .optional()
@@ -266,6 +337,10 @@ Run 'ship init' in the terminal first if not configured.`,
         .string()
         .optional()
         .describe("Blocked task ID - required for block/unblock"),
+      relatedTaskId: createTool.schema
+        .string()
+        .optional()
+        .describe("Related task ID - required for relate (use with taskId)"),
       filter: createTool.schema
         .object({
           status: createTool.schema
@@ -360,7 +435,7 @@ After that, you can use this tool to manage tasks.`;
           if (!args.taskId) {
             return "Error: taskId is required for show action";
           }
-          const result = await runShip($, ["show", args.taskId, "--json"]);
+          const result = await runShip($, ["show", "--json", args.taskId]);
           if (!result.success) {
             return `Failed to get task: ${result.output}`;
           }
@@ -398,22 +473,51 @@ After that, you can use this tool to manage tasks.`;
           if (!args.title) {
             return "Error: title is required for create action";
           }
-          const createArgs = ["create", args.title, "--json"];
+          const createArgs = ["create", "--json"];
           if (args.description) createArgs.push("--description", args.description);
           if (args.priority) createArgs.push("--priority", args.priority);
+          createArgs.push(args.title);
 
           const result = await runShip($, createArgs);
           if (!result.success) {
             return `Failed to create task: ${result.output}`;
           }
           try {
-            const task = JSON.parse(result.output);
+            const response = JSON.parse(result.output);
+            const task = response.task;
             return `Created task ${task.identifier}: ${task.title}\nURL: ${task.url}`;
           } catch {
             return result.output;
           }
         }
 
+        case "update": {
+          if (!args.taskId) {
+            return "Error: taskId is required for update action";
+          }
+          if (!args.title && !args.description && !args.priority && !args.status) {
+            return "Error: at least one of title, description, priority, or status is required for update";
+          }
+          const updateArgs = ["update", "--json"];
+          if (args.title) updateArgs.push("--title", args.title);
+          if (args.description) updateArgs.push("--description", args.description);
+          if (args.priority) updateArgs.push("--priority", args.priority);
+          if (args.status) updateArgs.push("--status", args.status);
+          updateArgs.push(args.taskId);
+
+          const result = await runShip($, updateArgs);
+          if (!result.success) {
+            return `Failed to update task: ${result.output}`;
+          }
+          try {
+            const response = JSON.parse(result.output);
+            const task = response.task;
+            return `Updated task ${task.identifier}: ${task.title}\nURL: ${task.url}`;
+          } catch {
+            return result.output;
+          }
+        }
+
         case "block": {
           if (!args.blocker || !args.blocked) {
             return "Error: both blocker and blocked task IDs are required";
@@ -436,6 +540,17 @@ After that, you can use this tool to manage tasks.`;
           return `Removed ${args.blocker} as blocker of ${args.blocked}`;
         }
 
+        case "relate": {
+          if (!args.taskId || !args.relatedTaskId) {
+            return "Error: both taskId and relatedTaskId are required for relate action";
+          }
+          const result = await runShip($, ["relate", args.taskId, args.relatedTaskId]);
+          if (!result.success) {
+            return `Failed to relate tasks: ${result.output}`;
+          }
+          return `Linked ${args.taskId} ↔ ${args.relatedTaskId} as related`;
+        }
+
         case "prime": {
           const result = await runShip($, ["prime"]);
           if (!result.success) {
@@ -454,6 +569,24 @@ After that, you can use this tool to manage tasks.`;
 /**
  * Ship OpenCode Plugin
  */
+// Pre-define commands (loaded at plugin init, not lazily in config hook)
+const SHIP_COMMANDS = {
+  ready: {
+    description: "Find ready-to-work tasks with no blockers",
+    template: `Use the \`ship\` tool with action \`ready\` to find tasks that are ready to work on (no blocking dependencies).
+
+Present the results in a clear format showing:
+- Task ID (e.g., BRI-123)
+- Title  
+- Priority
+- URL
+
+If there are ready tasks, ask the user which one they'd like to work on. If they choose one, use the \`ship\` tool with action \`start\` to begin work on it.
+
+If there are no ready tasks, suggest checking blocked tasks (action \`blocked\`) or creating a new task (action \`create\`).`,
+  },
+};
+
 export const ShipPlugin: Plugin = async ({ client, $ }) => {
   const injectedSessions = new Set<string>();
 
@@ -495,7 +628,7 @@ export const ShipPlugin: Plugin = async ({ client, $ }) => {
       injectedSessions.add(sessionID);
 
       // Use output.message which has the resolved model/agent values
-      await injectShipContext(client, $, sessionID, {
+      await injectShipContext(client, sessionID, {
         model: output.message.model,
         agent: output.message.agent,
       });
@@ -505,10 +638,15 @@ export const ShipPlugin: Plugin = async ({ client, $ }) => {
       if (event.type === "session.compacted") {
         const sessionID = event.properties.sessionID;
         const context = await getSessionContext(client, sessionID);
-        await injectShipContext(client, $, sessionID, context);
+        await injectShipContext(client, sessionID, context);
       }
     },
 
+    config: async (config) => {
+      // Register commands (using pre-defined SHIP_COMMANDS for reliability)
+      config.command = { ...config.command, ...SHIP_COMMANDS };
+    },
+
     // Register the ship tool
     tool: {
       ship: shipTool,