@fink-andreas/pi-linear-tools 0.1.0

package/extensions/pi-linear-tools.js

@@ -0,0 +1,582 @@
+import { loadSettings, saveSettings } from '../src/settings.js';
+import { createLinearClient } from '../src/linear-client.js';
+import { debug } from '../src/logger.js';
+import {
+  resolveProjectRef,
+  fetchTeams,
+  fetchWorkspaces,
+} from '../src/linear.js';
+import {
+  executeIssueList,
+  executeIssueView,
+  executeIssueCreate,
+  executeIssueUpdate,
+  executeIssueComment,
+  executeIssueStart,
+  executeIssueDelete,
+  executeProjectList,
+  executeTeamList,
+  executeMilestoneList,
+  executeMilestoneView,
+  executeMilestoneCreate,
+  executeMilestoneUpdate,
+  executeMilestoneDelete,
+} from '../src/handlers.js';
+
+function parseArgs(argsString) {
+  if (!argsString || !argsString.trim()) return [];
+  const tokens = argsString.match(/"[^"]*"|'[^']*'|\S+/g) || [];
+  return tokens.map((t) => {
+    if ((t.startsWith('"') && t.endsWith('"')) || (t.startsWith("'") && t.endsWith("'"))) {
+      return t.slice(1, -1);
+    }
+    return t;
+  });
+}
+
+function readFlag(args, flag) {
+  const idx = args.indexOf(flag);
+  if (idx >= 0 && idx + 1 < args.length) return args[idx + 1];
+  return undefined;
+}
+
+let cachedApiKey = null;
+
+async function getLinearApiKey() {
+  const envKey = process.env.LINEAR_API_KEY;
+  if (envKey && envKey.trim()) {
+    return envKey.trim();
+  }
+
+  if (cachedApiKey) {
+    return cachedApiKey;
+  }
+
+  try {
+    const settings = await loadSettings();
+    if (settings.linearApiKey && settings.linearApiKey.trim()) {
+      cachedApiKey = settings.linearApiKey.trim();
+      return cachedApiKey;
+    }
+  } catch {
+    // ignore, error below
+  }
+
+  throw new Error('LINEAR_API_KEY not set. Use /linear-tools-config --api-key <key> or set environment variable.');
+}
+
+async function resolveDefaultTeam(projectId) {
+  const settings = await loadSettings();
+
+  if (projectId && settings.projects?.[projectId]?.scope?.team) {
+    return settings.projects[projectId].scope.team;
+  }
+
+  return settings.defaultTeam || null;
+}
+
+async function runGit(pi, args) {
+  if (typeof pi.exec !== 'function') {
+    throw new Error('pi.exec is unavailable in this runtime; cannot run git operations');
+  }
+
+  const result = await pi.exec('git', args);
+  if (result?.code !== 0) {
+    const stderr = String(result?.stderr || '').trim();
+    throw new Error(`git ${args.join(' ')} failed${stderr ? `: ${stderr}` : ''}`);
+  }
+  return result;
+}
+
+async function gitBranchExists(pi, branchName) {
+  if (typeof pi.exec !== 'function') return false;
+  const result = await pi.exec('git', ['rev-parse', '--verify', branchName]);
+  return result?.code === 0;
+}
+
+async function startGitBranchForIssue(pi, branchName, fromRef = 'HEAD', onBranchExists = 'switch') {
+  const exists = await gitBranchExists(pi, branchName);
+
+  if (!exists) {
+    await runGit(pi, ['checkout', '-b', branchName, fromRef || 'HEAD']);
+    return { action: 'created', branchName };
+  }
+
+  if (onBranchExists === 'suffix') {
+    let suffix = 1;
+    let nextName = `${branchName}-${suffix}`;
+
+    // eslint-disable-next-line no-await-in-loop
+    while (await gitBranchExists(pi, nextName)) {
+      suffix += 1;
+      nextName = `${branchName}-${suffix}`;
+    }
+
+    await runGit(pi, ['checkout', '-b', nextName, fromRef || 'HEAD']);
+    return { action: 'created-suffix', branchName: nextName };
+  }
+
+  await runGit(pi, ['checkout', branchName]);
+  return { action: 'switched', branchName };
+}
+
+async function runInteractiveConfigFlow(ctx) {
+  const settings = await loadSettings();
+  const envKey = process.env.LINEAR_API_KEY?.trim();
+
+  let apiKey = envKey || settings.linearApiKey?.trim() || null;
+
+  if (!apiKey) {
+    const authMethod = await ctx.ui.select('Select authentication method', ['OAuth', 'API Key']);
+
+    if (!authMethod) {
+      ctx.ui.notify('Configuration cancelled', 'warning');
+      return;
+    }
+
+    if (authMethod === 'OAuth') {
+      ctx.ui.notify('OAuth setup is not implemented yet. Aborting.', 'warning');
+      return;
+    }
+
+    const promptedKey = await ctx.ui.input('Enter Linear API key', 'lin_xxx');
+    const normalized = String(promptedKey || '').trim();
+    if (!normalized) {
+      ctx.ui.notify('No API key provided. Aborting.', 'warning');
+      return;
+    }
+
+    apiKey = normalized;
+    settings.linearApiKey = normalized;
+    cachedApiKey = normalized;
+  }
+
+  const client = createLinearClient(apiKey);
+  const workspaces = await fetchWorkspaces(client);
+
+  if (workspaces.length === 0) {
+    throw new Error('No workspaces available for this Linear account');
+  }
+
+  const workspaceOptions = workspaces.map((w) => `${w.name} (${w.id})`);
+  const selectedWorkspaceLabel = await ctx.ui.select('Select workspace', workspaceOptions);
+  if (!selectedWorkspaceLabel) {
+    ctx.ui.notify('Configuration cancelled', 'warning');
+    return;
+  }
+
+  const selectedWorkspace = workspaces[workspaceOptions.indexOf(selectedWorkspaceLabel)];
+  settings.defaultWorkspace = {
+    id: selectedWorkspace.id,
+    name: selectedWorkspace.name,
+  };
+
+  const teams = await fetchTeams(client);
+  if (teams.length === 0) {
+    throw new Error('No teams found in selected workspace');
+  }
+
+  const teamOptions = teams.map((t) => `${t.key} - ${t.name} (${t.id})`);
+  const selectedTeamLabel = await ctx.ui.select('Select default team', teamOptions);
+  if (!selectedTeamLabel) {
+    ctx.ui.notify('Configuration cancelled', 'warning');
+    return;
+  }
+
+  const selectedTeam = teams[teamOptions.indexOf(selectedTeamLabel)];
+  settings.defaultTeam = selectedTeam.key;
+
+  await saveSettings(settings);
+  ctx.ui.notify(`Configuration saved: workspace ${selectedWorkspace.name}, team ${selectedTeam.key}`, 'info');
+}
+
+function registerLinearTools(pi) {
+  if (typeof pi.registerTool !== 'function') return;
+
+  pi.registerTool({
+    name: 'linear_issue',
+    label: 'Linear Issue',
+    description: 'Interact with Linear issues. Actions: list, view, create, update, comment, start, delete',
+    parameters: {
+      type: 'object',
+      properties: {
+        action: {
+          type: 'string',
+          enum: ['list', 'view', 'create', 'update', 'comment', 'start', 'delete'],
+          description: 'Action to perform on issue(s)',
+        },
+        issue: {
+          type: 'string',
+          description: 'Issue key (ABC-123) or Linear issue ID (for view, update, comment, start, delete)',
+        },
+        project: {
+          type: 'string',
+          description: 'Project name or ID for listing/creating issues (default: current repo directory name)',
+        },
+        states: {
+          type: 'array',
+          items: { type: 'string' },
+          description: 'Filter by state names for listing',
+        },
+        assignee: {
+          type: 'string',
+          description: 'For list: "me" or "all". For create/update: "me" or assignee ID.',
+        },
+        assigneeId: {
+          type: 'string',
+          description: 'Optional explicit assignee ID alias for update/create debugging/compatibility.',
+        },
+        limit: {
+          type: 'number',
+          description: 'Maximum number of issues to list (default: 50)',
+        },
+        includeComments: {
+          type: 'boolean',
+          description: 'Include comments when viewing issue (default: true)',
+        },
+        title: {
+          type: 'string',
+          description: 'Issue title (required for create, optional for update)',
+        },
+        description: {
+          type: 'string',
+          description: 'Issue description in markdown (for create, update)',
+        },
+        priority: {
+          type: 'number',
+          description: 'Priority 0..4 (for create, update)',
+        },
+        state: {
+          type: 'string',
+          description: 'Target state name or ID (for create, update)',
+        },
+        milestone: {
+          type: 'string',
+          description: 'For update: milestone name/ID, or "none" to clear milestone assignment.',
+        },
+        projectMilestoneId: {
+          type: 'string',
+          description: 'Optional explicit milestone ID alias for update.',
+        },
+        subIssueOf: {
+          type: 'string',
+          description: 'For update: set this issue as sub-issue of the given issue key/ID, or "none" to clear parent.',
+        },
+        parentOf: {
+          type: 'array',
+          items: { type: 'string' },
+          description: 'For update: set listed issues as children of this issue.',
+        },
+        blockedBy: {
+          type: 'array',
+          items: { type: 'string' },
+          description: 'For update: add "blocked by" dependencies (issues that block this issue).',
+        },
+        blocking: {
+          type: 'array',
+          items: { type: 'string' },
+          description: 'For update: add "blocking" dependencies (issues this issue blocks).',
+        },
+        relatedTo: {
+          type: 'array',
+          items: { type: 'string' },
+          description: 'For update: add related issue links.',
+        },
+        duplicateOf: {
+          type: 'string',
+          description: 'For update: mark this issue as duplicate of the given issue key/ID.',
+        },
+        team: {
+          type: 'string',
+          description: 'Team key (e.g. ENG) or name (optional if default team configured)',
+        },
+        parentId: {
+          type: 'string',
+          description: 'Parent issue ID for sub-issues (for create)',
+        },
+        body: {
+          type: 'string',
+          description: 'Comment body in markdown (for comment)',
+        },
+        parentCommentId: {
+          type: 'string',
+          description: 'Parent comment ID for reply (for comment)',
+        },
+        branch: {
+          type: 'string',
+          description: 'Custom branch name override (for start)',
+        },
+        fromRef: {
+          type: 'string',
+          description: 'Git ref to branch from (default: HEAD, for start)',
+        },
+        onBranchExists: {
+          type: 'string',
+          enum: ['switch', 'suffix'],
+          description: 'When branch exists: switch to it or create suffixed branch (for start)',
+        },
+      },
+      required: ['action'],
+      additionalProperties: false,
+    },
+    async execute(_toolCallId, params) {
+      const apiKey = await getLinearApiKey();
+      const client = createLinearClient(apiKey);
+
+      switch (params.action) {
+        case 'list':
+          return executeIssueList(client, params);
+        case 'view':
+          return executeIssueView(client, params);
+        case 'create':
+          return executeIssueCreate(client, params, { resolveDefaultTeam });
+        case 'update':
+          return executeIssueUpdate(client, params);
+        case 'comment':
+          return executeIssueComment(client, params);
+        case 'start':
+          return executeIssueStart(client, params, {
+            gitExecutor: async (branchName, fromRef, onBranchExists) => {
+              return startGitBranchForIssue(pi, branchName, fromRef, onBranchExists);
+            },
+          });
+        case 'delete':
+          return executeIssueDelete(client, params);
+        default:
+          throw new Error(`Unknown action: ${params.action}`);
+      }
+    },
+  });
+
+  pi.registerTool({
+    name: 'linear_project',
+    label: 'Linear Project',
+    description: 'Interact with Linear projects. Actions: list',
+    parameters: {
+      type: 'object',
+      properties: {
+        action: {
+          type: 'string',
+          enum: ['list'],
+          description: 'Action to perform on project(s)',
+        },
+      },
+      required: ['action'],
+      additionalProperties: false,
+    },
+    async execute(_toolCallId, params) {
+      const apiKey = await getLinearApiKey();
+      const client = createLinearClient(apiKey);
+
+      switch (params.action) {
+        case 'list':
+          return executeProjectList(client);
+        default:
+          throw new Error(`Unknown action: ${params.action}`);
+      }
+    },
+  });
+
+  pi.registerTool({
+    name: 'linear_team',
+    label: 'Linear Team',
+    description: 'Interact with Linear teams. Actions: list',
+    parameters: {
+      type: 'object',
+      properties: {
+        action: {
+          type: 'string',
+          enum: ['list'],
+          description: 'Action to perform on team(s)',
+        },
+      },
+      required: ['action'],
+      additionalProperties: false,
+    },
+    async execute(_toolCallId, params) {
+      const apiKey = await getLinearApiKey();
+      const client = createLinearClient(apiKey);
+
+      switch (params.action) {
+        case 'list':
+          return executeTeamList(client);
+        default:
+          throw new Error(`Unknown action: ${params.action}`);
+      }
+    },
+  });
+
+  pi.registerTool({
+    name: 'linear_milestone',
+    label: 'Linear Milestone',
+    description: 'Interact with Linear project milestones. Actions: list, view, create, update, delete',
+    parameters: {
+      type: 'object',
+      properties: {
+        action: {
+          type: 'string',
+          enum: ['list', 'view', 'create', 'update', 'delete'],
+          description: 'Action to perform on milestone(s)',
+        },
+        milestone: {
+          type: 'string',
+          description: 'Milestone ID (for view, update, delete)',
+        },
+        project: {
+          type: 'string',
+          description: 'Project name or ID (for list, create)',
+        },
+        name: {
+          type: 'string',
+          description: 'Milestone name (required for create, optional for update)',
+        },
+        description: {
+          type: 'string',
+          description: 'Milestone description in markdown',
+        },
+        targetDate: {
+          type: 'string',
+          description: 'Target completion date (ISO 8601 date)',
+        },
+        status: {
+          type: 'string',
+          enum: ['backlogged', 'planned', 'inProgress', 'paused', 'completed', 'done', 'cancelled'],
+          description: 'Milestone status',
+        },
+      },
+      required: ['action'],
+      additionalProperties: false,
+    },
+    async execute(_toolCallId, params) {
+      const apiKey = await getLinearApiKey();
+      const client = createLinearClient(apiKey);
+
+      switch (params.action) {
+        case 'list':
+          return executeMilestoneList(client, params);
+        case 'view':
+          return executeMilestoneView(client, params);
+        case 'create':
+          return executeMilestoneCreate(client, params);
+        case 'update':
+          return executeMilestoneUpdate(client, params);
+        case 'delete':
+          return executeMilestoneDelete(client, params);
+        default:
+          throw new Error(`Unknown action: ${params.action}`);
+      }
+    },
+  });
+}
+
+export default function piLinearToolsExtension(pi) {
+  registerLinearTools(pi);
+
+  pi.registerCommand('linear-tools-config', {
+    description: 'Configure pi-linear-tools settings (API key and default team mappings)',
+    handler: async (argsText, ctx) => {
+      const args = parseArgs(argsText);
+      const apiKey = readFlag(args, '--api-key');
+      const defaultTeam = readFlag(args, '--default-team');
+      const projectTeam = readFlag(args, '--team');
+      const projectName = readFlag(args, '--project');
+
+      if (apiKey) {
+        const settings = await loadSettings();
+        settings.linearApiKey = apiKey;
+        await saveSettings(settings);
+        cachedApiKey = null;
+        if (ctx?.hasUI) {
+          ctx.ui.notify('LINEAR_API_KEY saved to settings', 'info');
+        }
+        return;
+      }
+
+      if (defaultTeam) {
+        const settings = await loadSettings();
+        settings.defaultTeam = defaultTeam;
+        await saveSettings(settings);
+        if (ctx?.hasUI) {
+          ctx.ui.notify(`Default team set to: ${defaultTeam}`, 'info');
+        }
+        return;
+      }
+
+      if (projectTeam && projectName) {
+        const settings = await loadSettings();
+
+        let projectId = projectName;
+        try {
+          const resolvedKey = await getLinearApiKey();
+          const client = createLinearClient(resolvedKey);
+          const resolved = await resolveProjectRef(client, projectName);
+          projectId = resolved.id;
+        } catch {
+          // keep provided value as project ID/name key
+        }
+
+        if (!settings.projects[projectId]) {
+          settings.projects[projectId] = {
+            scope: {
+              team: null,
+            },
+          };
+        }
+
+        if (!settings.projects[projectId].scope) {
+          settings.projects[projectId].scope = { team: null };
+        }
+
+        settings.projects[projectId].scope.team = projectTeam;
+        await saveSettings(settings);
+
+        if (ctx?.hasUI) {
+          ctx.ui.notify(`Team for project "${projectName}" set to: ${projectTeam}`, 'info');
+        }
+        return;
+      }
+
+      if (!apiKey && !defaultTeam && !projectTeam && !projectName && ctx?.hasUI && ctx?.ui) {
+        await runInteractiveConfigFlow(ctx);
+        return;
+      }
+
+      const settings = await loadSettings();
+      const hasKey = !!(settings.linearApiKey || process.env.LINEAR_API_KEY);
+      const keySource = process.env.LINEAR_API_KEY ? 'environment' : (settings.linearApiKey ? 'settings' : 'not set');
+
+      pi.sendMessage({
+        customType: 'pi-linear-tools',
+        content: `Configuration:\n  LINEAR_API_KEY: ${hasKey ? 'configured' : 'not set'} (source: ${keySource})\n  Default workspace: ${settings.defaultWorkspace?.name || 'not set'}\n  Default team: ${settings.defaultTeam || 'not set'}\n  Project team mappings: ${Object.keys(settings.projects || {}).length}\n\nCommands:\n  /linear-tools-config --api-key lin_xxx\n  /linear-tools-config --default-team ENG\n  /linear-tools-config --team ENG --project MyProject\n\nNote: environment LINEAR_API_KEY takes precedence over settings file.`,
+        display: true,
+      });
+    },
+  });
+
+  pi.registerCommand('linear-tools-help', {
+    description: 'Show pi-linear-tools commands and tools',
+    handler: async (_args, ctx) => {
+      if (ctx?.hasUI) {
+        ctx.ui.notify('pi-linear-tools extension commands available', 'info');
+      }
+
+      pi.sendMessage({
+        customType: 'pi-linear-tools',
+        content: [
+          'Commands:',
+          '  /linear-tools-config --api-key <key>',
+          '  /linear-tools-config --default-team <team-key>',
+          '  /linear-tools-config --team <team-key> --project <project-name-or-id>',
+          '  /linear-tools-help',
+          '',
+          'LLM-callable tools:',
+          '  linear_issue (list/view/create/update/comment/start/delete)',
+          '  linear_project (list)',
+          '  linear_team (list)',
+          '  linear_milestone (list/view/create/update/delete)',
+        ].join('\n'),
+        display: true,
+      });
+    },
+  });
+}

package/index.js

@@ -0,0 +1,8 @@
+#!/usr/bin/env node
+
+import { runCli } from './src/cli.js';
+
+runCli().catch((error) => {
+  console.error('pi-linear-tools error:', error?.message || error);
+  process.exit(1);
+});

package/package.json

@@ -0,0 +1,49 @@
+{
+  "name": "@fink-andreas/pi-linear-tools",
+  "version": "0.1.0",
+  "description": "Pi extension with Linear SDK tools and configuration commands",
+  "type": "module",
+  "engines": {
+    "node": ">=18.0.0"
+  },
+  "main": "index.js",
+  "bin": {
+    "pi-linear-tools": "bin/pi-linear-tools.js"
+  },
+  "files": [
+    "bin/",
+    "src/",
+    "extensions/",
+    "index.js",
+    "README.md",
+    "CHANGELOG.md",
+    "RELEASE.md",
+    "POST_RELEASE_CHECKLIST.md",
+    "FUNCTIONALITY.md",
+    "settings.json.example"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "start": "node index.js",
+    "test": "node tests/test-package-manifest.js && node tests/test-extension-registration.js && node tests/test-settings.js && node tests/test-assignee-update.js && node tests/test-full-assignee-flow.js",
+    "release:check": "npm test && npm pack --dry-run"
+  },
+  "keywords": [
+    "linear",
+    "pi",
+    "pi-package",
+    "tools",
+    "sdk"
+  ],
+  "pi": {
+    "extensions": [
+      "./extensions"
+    ]
+  },
+  "license": "MIT",
+  "dependencies": {
+    "@linear/sdk": "^75.0.0"
+  }
+}

package/settings.json.example

@@ -0,0 +1,12 @@
+{
+  "schemaVersion": 1,
+  "linearApiKey": "lin_xxx",
+  "defaultTeam": "ENG",
+  "projects": {
+    "97ec7cae-e252-493d-94d3-6910aa28cacf": {
+      "scope": {
+        "team": "ENG"
+      }
+    }
+  }
+}