@fink-andreas/pi-linear-tools 0.1.0 → 0.2.1

package/extensions/pi-linear-tools.js

@@ -1,11 +1,113 @@
 import { loadSettings, saveSettings } from '../src/settings.js';
 import { createLinearClient } from '../src/linear-client.js';
-import { debug } from '../src/logger.js';
+import { setQuietMode } from '../src/logger.js';
 import {
   resolveProjectRef,
   fetchTeams,
   fetchWorkspaces,
 } from '../src/linear.js';
+import fs from 'node:fs';
+import path from 'node:path';
+import { pathToFileURL } from 'node:url';
+
+function isPiCodingAgentRoot(dir) {
+  const pkgPath = path.join(dir, 'package.json');
+  if (!fs.existsSync(pkgPath)) return false;
+  try {
+    const pkg = JSON.parse(fs.readFileSync(pkgPath, 'utf8'));
+    return pkg?.name === '@mariozechner/pi-coding-agent';
+  } catch {
+    return false;
+  }
+}
+
+function findPiCodingAgentRoot() {
+  const entry = process.argv?.[1];
+  if (!entry) return null;
+
+  // Method 1: walk up from argv1 (works when argv1 is .../pi-coding-agent/dist/cli.js)
+  {
+    let dir = path.dirname(entry);
+    for (let i = 0; i < 20; i += 1) {
+      if (isPiCodingAgentRoot(dir)) {
+        return dir;
+      }
+      const parent = path.dirname(dir);
+      if (parent === dir) break;
+      dir = parent;
+    }
+  }
+
+  // Method 2: npm global layout guess (works when argv1 is .../<prefix>/bin/pi)
+  // <prefix>/bin/pi  ->  <prefix>/lib/node_modules/@mariozechner/pi-coding-agent
+  {
+    const binDir = path.dirname(entry);
+    const prefix = path.resolve(binDir, '..');
+    const candidate = path.join(prefix, 'lib', 'node_modules', '@mariozechner', 'pi-coding-agent');
+    if (isPiCodingAgentRoot(candidate)) {
+      return candidate;
+    }
+  }
+
+  // Method 3: common global node_modules locations
+  for (const candidate of [
+    '/usr/local/lib/node_modules/@mariozechner/pi-coding-agent',
+    '/usr/lib/node_modules/@mariozechner/pi-coding-agent',
+  ]) {
+    if (isPiCodingAgentRoot(candidate)) {
+      return candidate;
+    }
+  }
+
+  return null;
+}
+
+async function importFromPiRoot(relativePathFromPiRoot) {
+  const piRoot = findPiCodingAgentRoot();
+
+  if (!piRoot) throw new Error('Unable to locate @mariozechner/pi-coding-agent installation');
+
+  const absPath = path.join(piRoot, relativePathFromPiRoot);
+  return import(pathToFileURL(absPath).href);
+}
+
+async function importPiCodingAgent() {
+  try {
+    return await import('@mariozechner/pi-coding-agent');
+  } catch {
+    return importFromPiRoot('dist/index.js');
+  }
+}
+
+async function importPiTui() {
+  try {
+    return await import('@mariozechner/pi-tui');
+  } catch {
+    // pi-tui is a dependency of pi-coding-agent and may be nested under it
+    return importFromPiRoot('node_modules/@mariozechner/pi-tui/dist/index.js');
+  }
+}
+
+// Optional imports for markdown rendering (provided by pi runtime)
+let Markdown = null;
+let Text = null;
+let getMarkdownTheme = null;
+
+try {
+  const piTui = await importPiTui();
+  Markdown = piTui?.Markdown || null;
+  Text = piTui?.Text || null;
+} catch {
+  // ignore
+}
+
+try {
+  const piCodingAgent = await importPiCodingAgent();
+  getMarkdownTheme = piCodingAgent?.getMarkdownTheme || null;
+} catch {
+  // ignore
+}
+
 import {
   executeIssueList,
   executeIssueView,
@@ -22,6 +124,7 @@ import {
   executeMilestoneUpdate,
   executeMilestoneDelete,
 } from '../src/handlers.js';
+import { authenticate, getAccessToken, logout } from '../src/auth/index.js';
 
 function parseArgs(argsString) {
   if (!argsString || !argsString.trim()) return [];
@@ -42,27 +145,57 @@ function readFlag(args, flag) {
 
 let cachedApiKey = null;
 
-async function getLinearApiKey() {
+async function getLinearAuth() {
   const envKey = process.env.LINEAR_API_KEY;
   if (envKey && envKey.trim()) {
-    return envKey.trim();
+    return { apiKey: envKey.trim() };
+  }
+
+  const settings = await loadSettings();
+  const authMethod = settings.authMethod || 'api-key';
+
+  if (authMethod === 'oauth') {
+    const accessToken = await getAccessToken();
+    if (accessToken) {
+      return { accessToken };
+    }
   }
 
   if (cachedApiKey) {
-    return cachedApiKey;
+    return { apiKey: cachedApiKey };
   }
 
-  try {
-    const settings = await loadSettings();
-    if (settings.linearApiKey && settings.linearApiKey.trim()) {
-      cachedApiKey = settings.linearApiKey.trim();
-      return cachedApiKey;
-    }
-  } catch {
-    // ignore, error below
+  const apiKey = settings.apiKey || settings.linearApiKey;
+  if (apiKey && apiKey.trim()) {
+    cachedApiKey = apiKey.trim();
+    return { apiKey: cachedApiKey };
+  }
+
+  const fallbackAccessToken = await getAccessToken();
+  if (fallbackAccessToken) {
+    return { accessToken: fallbackAccessToken };
   }
 
-  throw new Error('LINEAR_API_KEY not set. Use /linear-tools-config --api-key <key> or set environment variable.');
+  throw new Error(
+    'No Linear authentication configured. Use /linear-tools-config --api-key <key> or run `pi-linear-tools auth login` in CLI.'
+  );
+}
+
+async function createAuthenticatedClient() {
+  return createLinearClient(await getLinearAuth());
+}
+
+function withMilestoneScopeHint(error) {
+  const message = String(error?.message || error || 'Unknown error');
+
+  if (/invalid scope/i.test(message) && /write/i.test(message)) {
+    return new Error(
+      `${message}\nHint: Milestone create/update/delete require Linear write scope. ` +
+      `Use API key auth for milestone management: /linear-tools-config --api-key <key>`
+    );
+  }
+
+  return error;
 }
 
 async function resolveDefaultTeam(projectId) {
@@ -120,38 +253,166 @@ async function startGitBranchForIssue(pi, branchName, fromRef = 'HEAD', onBranch
   return { action: 'switched', branchName };
 }
 
-async function runInteractiveConfigFlow(ctx) {
+async function runInteractiveConfigFlow(ctx, pi) {
   const settings = await loadSettings();
+  const previousAuthMethod = settings.authMethod || 'api-key';
   const envKey = process.env.LINEAR_API_KEY?.trim();
 
-  let apiKey = envKey || settings.linearApiKey?.trim() || null;
+  let client;
+  let apiKey = settings.apiKey?.trim() || settings.linearApiKey?.trim() || null;
+  let accessToken = null;
 
-  if (!apiKey) {
-    const authMethod = await ctx.ui.select('Select authentication method', ['OAuth', 'API Key']);
+  setQuietMode(true);
+  try {
+    accessToken = await getAccessToken();
+  } finally {
+    setQuietMode(false);
+  }
 
-    if (!authMethod) {
+  const hasWorkingAuth = !!(envKey || apiKey || accessToken);
+
+  if (hasWorkingAuth) {
+    const source = envKey ? 'environment API key' : (accessToken ? 'OAuth token' : 'stored API key');
+    const logoutSelection = await ctx.ui.select(
+      `Existing authentication detected (${source}). Logout and re-authenticate?`,
+      ['No', 'Yes']
+    );
+
+    if (!logoutSelection) {
       ctx.ui.notify('Configuration cancelled', 'warning');
       return;
     }
 
-    if (authMethod === 'OAuth') {
-      ctx.ui.notify('OAuth setup is not implemented yet. Aborting.', 'warning');
-      return;
+    if (logoutSelection === 'Yes') {
+      setQuietMode(true);
+      try {
+        await logout();
+      } finally {
+        setQuietMode(false);
+      }
+
+      settings.apiKey = null;
+      if (Object.prototype.hasOwnProperty.call(settings, 'linearApiKey')) {
+        delete settings.linearApiKey;
+      }
+      cachedApiKey = null;
+      accessToken = null;
+      apiKey = null;
+
+      await saveSettings(settings);
+      ctx.ui.notify('Stored authentication cleared.', 'info');
+
+      if (envKey) {
+        ctx.ui.notify('LINEAR_API_KEY is still set in environment and cannot be removed by this command.', 'warning');
+      }
+    } else {
+      if (envKey) {
+        client = createLinearClient(envKey);
+      } else if (accessToken) {
+        settings.authMethod = 'oauth';
+        client = createLinearClient({ accessToken });
+      } else if (apiKey) {
+        settings.authMethod = 'api-key';
+        cachedApiKey = apiKey;
+        client = createLinearClient(apiKey);
+      }
     }
+  }
+
+  if (!client) {
+    const selectedAuthMethod = await ctx.ui.select('Select authentication method', ['API Key (recommended for full functionlaity)', 'OAuth']);
 
-    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');
+    if (!selectedAuthMethod) {
+      ctx.ui.notify('Configuration cancelled', 'warning');
       return;
     }
 
-    apiKey = normalized;
-    settings.linearApiKey = normalized;
-    cachedApiKey = normalized;
+    if (selectedAuthMethod === 'OAuth') {
+      settings.authMethod = 'oauth';
+      cachedApiKey = null;
+
+      setQuietMode(true);
+      try {
+        accessToken = await getAccessToken();
+
+        if (!accessToken) {
+          ctx.ui.notify('Starting OAuth login...', 'info');
+          try {
+            await authenticate({
+              onAuthorizationUrl: async (authUrl) => {
+                pi.sendMessage({
+                  customType: 'pi-linear-tools',
+                  content: [
+                    '### Linear OAuth login',
+                    '',
+                    `[Open authorization URL](${authUrl})`,
+                    '',
+                    'If browser did not open automatically, copy and open this URL:',
+                    `\`${authUrl}\``,
+                    '',
+                    'After authorizing, paste the callback URL in the next prompt.',
+                  ].join('\n'),
+                  display: true,
+                });
+                ctx.ui.notify('Complete OAuth in browser, then paste callback URL in the prompt.', 'info');
+              },
+              manualCodeInput: async () => {
+                const entered = await ctx.ui.input(
+                  'Paste callback URL from browser (or type "cancel")',
+                  'http://localhost:34711/callback?code=...&state=...'
+                );
+                const normalized = String(entered || '').trim();
+                if (!normalized || normalized.toLowerCase() === 'cancel') {
+                  return null;
+                }
+                return normalized;
+              },
+            });
+          } catch (error) {
+            if (String(error?.message || '').includes('cancelled by user')) {
+              ctx.ui.notify('OAuth authentication cancelled.', 'warning');
+              return;
+            }
+            throw error;
+          }
+          accessToken = await getAccessToken();
+        }
+
+        if (!accessToken) {
+          throw new Error('OAuth authentication failed: no access token available after login');
+        }
+
+        client = createLinearClient({ accessToken });
+      } finally {
+        setQuietMode(false);
+      }
+    } else {
+      setQuietMode(true);
+      try {
+        await logout();
+      } finally {
+        setQuietMode(false);
+      }
+
+      if (!envKey && !apiKey) {
+        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;
+      }
+
+      const selectedApiKey = envKey || apiKey;
+      settings.apiKey = selectedApiKey;
+      settings.authMethod = 'api-key';
+      cachedApiKey = selectedApiKey;
+      client = createLinearClient(selectedApiKey);
+    }
   }
 
-  const client = createLinearClient(apiKey);
   const workspaces = await fetchWorkspaces(client);
 
   if (workspaces.length === 0) {
@@ -188,9 +449,59 @@ async function runInteractiveConfigFlow(ctx) {
 
   await saveSettings(settings);
   ctx.ui.notify(`Configuration saved: workspace ${selectedWorkspace.name}, team ${selectedTeam.key}`, 'info');
+
+  if (previousAuthMethod !== settings.authMethod) {
+    ctx.ui.notify(
+      'Authentication method changed. Please restart pi to refresh and make the correct tools available.',
+      'warning'
+    );
+  }
 }
 
-function registerLinearTools(pi) {
+async function shouldExposeMilestoneTool() {
+  const settings = await loadSettings();
+  const authMethod = settings.authMethod || 'api-key';
+  const apiKeyFromSettings = (settings.apiKey || settings.linearApiKey || '').trim();
+  const apiKeyFromEnv = (process.env.LINEAR_API_KEY || '').trim();
+  const hasApiKey = !!(apiKeyFromEnv || apiKeyFromSettings);
+
+  return authMethod === 'api-key' || hasApiKey;
+}
+
+/**
+ * Render tool result as markdown
+ */
+function renderMarkdownResult(result, _options, _theme) {
+  const text = result.content?.[0]?.text || '';
+
+  // Fall back to plain text if markdown packages not available
+  if (!Markdown || !getMarkdownTheme) {
+    const lines = text.split('\n');
+    return {
+      render: (width) => lines.map((line) => (width && line.length > width ? line.slice(0, width) : line)),
+      invalidate: () => {},
+    };
+  }
+
+  // Return Markdown component directly - the TUI will call its render() method
+  try {
+    const mdTheme = getMarkdownTheme();
+    return new Markdown(text, 0, 0, mdTheme, _theme ? { color: (t) => _theme.fg('toolOutput', t) } : undefined);
+  } catch (error) {
+    // If markdown rendering fails for any reason, show a visible error so we can diagnose.
+    const msg = `[pi-linear-tools] Markdown render failed: ${String(error?.message || error)}`;
+    if (Text) {
+      return new Text((_theme ? _theme.fg('error', msg) : msg) + `\n\n` + text, 0, 0);
+    }
+    const lines = (msg + '\n\n' + text).split('\n');
+    return {
+      render: (width) => lines.map((line) => (width && line.length > width ? line.slice(0, width) : line)),
+      invalidate: () => {},
+    };
+  }
+}
+
+async function registerLinearTools(pi) {
   if (typeof pi.registerTool !== 'function') return;
 
   pi.registerTool({
@@ -302,10 +613,6 @@ function registerLinearTools(pi) {
           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)',
@@ -319,9 +626,9 @@ function registerLinearTools(pi) {
       required: ['action'],
       additionalProperties: false,
     },
+    renderResult: renderMarkdownResult,
     async execute(_toolCallId, params) {
-      const apiKey = await getLinearApiKey();
-      const client = createLinearClient(apiKey);
+      const client = await createAuthenticatedClient();
 
       switch (params.action) {
         case 'list':
@@ -364,9 +671,9 @@ function registerLinearTools(pi) {
       required: ['action'],
       additionalProperties: false,
     },
+    renderResult: renderMarkdownResult,
     async execute(_toolCallId, params) {
-      const apiKey = await getLinearApiKey();
-      const client = createLinearClient(apiKey);
+      const client = await createAuthenticatedClient();
 
       switch (params.action) {
         case 'list':
@@ -393,9 +700,9 @@ function registerLinearTools(pi) {
       required: ['action'],
       additionalProperties: false,
     },
+    renderResult: renderMarkdownResult,
     async execute(_toolCallId, params) {
-      const apiKey = await getLinearApiKey();
-      const client = createLinearClient(apiKey);
+      const client = await createAuthenticatedClient();
 
       switch (params.action) {
         case 'list':
@@ -406,72 +713,71 @@ function registerLinearTools(pi) {
     },
   });
 
-  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',
-        },
+  if (await shouldExposeMilestoneTool()) {
+    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)',
+          },
+        },
+        required: ['action'],
+        additionalProperties: false,
       },
-      required: ['action'],
-      additionalProperties: false,
-    },
-    async execute(_toolCallId, params) {
-      const apiKey = await getLinearApiKey();
-      const client = createLinearClient(apiKey);
+      renderResult: renderMarkdownResult,
+      async execute(_toolCallId, params) {
+        const client = await createAuthenticatedClient();
 
-      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}`);
-      }
-    },
-  });
+        try {
+          switch (params.action) {
+            case 'list':
+              return await executeMilestoneList(client, params);
+            case 'view':
+              return await executeMilestoneView(client, params);
+            case 'create':
+              return await executeMilestoneCreate(client, params);
+            case 'update':
+              return await executeMilestoneUpdate(client, params);
+            case 'delete':
+              return await executeMilestoneDelete(client, params);
+            default:
+              throw new Error(`Unknown action: ${params.action}`);
+          }
+        } catch (error) {
+          throw withMilestoneScopeHint(error);
+        }
+      },
+    });
+  }
 }
 
-export default function piLinearToolsExtension(pi) {
-  registerLinearTools(pi);
-
+export default async function piLinearToolsExtension(pi) {
   pi.registerCommand('linear-tools-config', {
     description: 'Configure pi-linear-tools settings (API key and default team mappings)',
     handler: async (argsText, ctx) => {
@@ -483,11 +789,19 @@ export default function piLinearToolsExtension(pi) {
 
       if (apiKey) {
         const settings = await loadSettings();
-        settings.linearApiKey = apiKey;
+        const previousAuthMethod = settings.authMethod || 'api-key';
+        settings.apiKey = apiKey;
+        settings.authMethod = 'api-key';
         await saveSettings(settings);
         cachedApiKey = null;
         if (ctx?.hasUI) {
           ctx.ui.notify('LINEAR_API_KEY saved to settings', 'info');
+          if (previousAuthMethod !== settings.authMethod) {
+            ctx.ui.notify(
+              'Authentication method changed. Please restart pi to refresh and make the correct tools available.',
+              'warning'
+            );
+          }
         }
         return;
       }
@@ -507,8 +821,7 @@ export default function piLinearToolsExtension(pi) {
 
         let projectId = projectName;
         try {
-          const resolvedKey = await getLinearApiKey();
-          const client = createLinearClient(resolvedKey);
+          const client = await createAuthenticatedClient();
           const resolved = await resolveProjectRef(client, projectName);
           projectId = resolved.id;
         } catch {
@@ -537,13 +850,13 @@ export default function piLinearToolsExtension(pi) {
       }
 
       if (!apiKey && !defaultTeam && !projectTeam && !projectName && ctx?.hasUI && ctx?.ui) {
-        await runInteractiveConfigFlow(ctx);
+        await runInteractiveConfigFlow(ctx, pi);
         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');
+      const hasKey = !!(settings.apiKey || settings.linearApiKey || process.env.LINEAR_API_KEY);
+      const keySource = process.env.LINEAR_API_KEY ? 'environment' : (settings.apiKey || settings.linearApiKey ? 'settings' : 'not set');
 
       pi.sendMessage({
         customType: 'pi-linear-tools',
@@ -553,6 +866,16 @@ export default function piLinearToolsExtension(pi) {
     },
   });
 
+  pi.registerCommand('linear-tools-reload', {
+    description: 'Reload extension runtime (extensions, skills, prompts, themes)',
+    handler: async (_args, ctx) => {
+      if (ctx?.hasUI) {
+        ctx.ui.notify('Reloading runtime...', 'info');
+      }
+      await ctx.reload();
+    },
+  });
+
   pi.registerCommand('linear-tools-help', {
     description: 'Show pi-linear-tools commands and tools',
     handler: async (_args, ctx) => {
@@ -560,6 +883,20 @@ export default function piLinearToolsExtension(pi) {
         ctx.ui.notify('pi-linear-tools extension commands available', 'info');
       }
 
+      const showMilestoneTool = await shouldExposeMilestoneTool();
+      const toolLines = [
+        'LLM-callable tools:',
+        '  linear_issue (list/view/create/update/comment/start/delete)',
+        '  linear_project (list)',
+        '  linear_team (list)',
+      ];
+
+      if (showMilestoneTool) {
+        toolLines.push('  linear_milestone (list/view/create/update/delete)');
+      } else {
+        toolLines.push('  linear_milestone hidden: requires API key auth');
+      }
+
       pi.sendMessage({
         customType: 'pi-linear-tools',
         content: [
@@ -568,15 +905,14 @@ export default function piLinearToolsExtension(pi) {
           '  /linear-tools-config --default-team <team-key>',
           '  /linear-tools-config --team <team-key> --project <project-name-or-id>',
           '  /linear-tools-help',
+          '  /linear-tools-reload',
           '',
-          '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)',
+          ...toolLines,
         ].join('\n'),
         display: true,
       });
     },
   });
+
+  await registerLinearTools(pi);
 }