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

package/src/cli.js

@@ -1,6 +1,13 @@
 import { loadSettings, saveSettings } from './settings.js';
 import { createLinearClient } from './linear-client.js';
 import { resolveProjectRef } from './linear.js';
+import {
+  authenticate,
+  logout,
+  getAuthStatus,
+  isAuthenticated,
+  getAccessToken,
+} from './auth/index.js';
 import {
   executeIssueList,
   executeIssueView,
@@ -60,31 +67,61 @@ function parseBoolean(value) {
   return undefined;
 }
 
-// ===== API KEY RESOLUTION =====
+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: pi-linear-tools config --api-key <key>`
+    );
+  }
+
+  return error;
+}
+
+// ===== AUTH RESOLUTION =====
 
 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. Run: pi-linear-tools config --api-key <key>');
+  throw new Error(
+    'No Linear authentication configured. Run: pi-linear-tools auth login or pi-linear-tools config --api-key <key>'
+  );
+}
+
+async function createAuthenticatedClient() {
+  return createLinearClient(await getLinearAuth());
 }
 
 async function resolveDefaultTeam(projectId) {
@@ -106,15 +143,23 @@ Usage:
   pi-linear-tools <command> [options]
 
 Commands:
-  help                          Show this help message
-  config                        Show current configuration
-  config --api-key <key>        Set Linear API key
-  config --default-team <key>   Set default team
   issue <action> [options]      Manage issues
   project <action> [options]    Manage projects
   team <action> [options]       Manage teams
   milestone <action> [options]  Manage milestones
 
+Other commands:
+  help                          Show this help message
+  auth <action>                 Manage authentication (OAuth 2.0)
+  config                        Show current configuration
+  config --api-key <key>        Set Linear API key (legacy)
+  config --default-team <key>   Set default team
+
+Auth Actions:
+  login    Authenticate with Linear via OAuth 2.0
+  logout   Clear stored authentication tokens
+  status   Show current authentication status
+
 Issue Actions:
   list [--project X] [--states X,Y] [--assignee me|all] [--limit N]
   view <issue> [--no-comments]
@@ -122,7 +167,7 @@ Issue Actions:
   update <issue> [--title X] [--description X] [--state X] [--priority 0-4]
          [--assignee me|ID] [--milestone X] [--sub-issue-of X]
   comment <issue> --body X
-  start <issue> [--branch X] [--from-ref X] [--on-branch-exists switch|suffix]
+  start <issue> [--from-ref X] [--on-branch-exists switch|suffix]
   delete <issue>
 
 Project Actions:
@@ -147,6 +192,8 @@ Common Flags:
   --limit       Max results (default: 50)
 
 Examples:
+  pi-linear-tools auth login
+  pi-linear-tools auth status
   pi-linear-tools issue list --project MyProject --states "In Progress,Backlog"
   pi-linear-tools issue view ENG-123
   pi-linear-tools issue create --title "Fix bug" --team ENG --priority 2
@@ -154,6 +201,12 @@ Examples:
   pi-linear-tools issue start ENG-123
   pi-linear-tools milestone list --project MyProject
   pi-linear-tools config --api-key lin_xxx
+
+Authentication:
+  API key is the recommended authentication method (supports milestones).
+  Run 'pi-linear-tools config --api-key <key>' to authenticate.
+  For CI/headless environments, set the LINEAR_API_KEY environment variable.
+  OAuth 2.0 is also available via 'pi-linear-tools auth login'.
 `);
 }
 
@@ -207,7 +260,6 @@ Comment Options:
 
 Start Options:
   <issue>          Issue key or ID
-  --branch X       Custom branch name (default: issue's branch name)
   --from-ref X     Git ref to branch from (default: HEAD)
   --on-branch-exists X  "switch" or "suffix" (default: switch)
 
@@ -276,6 +328,132 @@ Delete Options:
 `);
 }
 
+function printAuthHelp() {
+  console.log(`pi-linear-tools auth - Manage Linear authentication
+
+Usage:
+  pi-linear-tools auth <action>
+
+Actions:
+  login    Authenticate with Linear via OAuth 2.0
+  logout   Clear stored authentication tokens
+  status   Show current authentication status
+
+Login:
+  Starts the OAuth 2.0 authentication flow:
+  1. Opens your browser to Linear's authorization page
+  2. You authorize the application
+  3. Tokens are stored securely in your OS keychain
+  4. Automatic token refresh keeps you authenticated
+
+Logout:
+  Clears stored OAuth tokens from your keychain.
+  You'll need to authenticate again to access Linear.
+
+Status:
+  Shows your current authentication status:
+  - Whether you're authenticated
+  - Token expiry time
+  - Granted OAuth scopes
+
+Examples:
+  pi-linear-tools auth login
+  pi-linear-tools auth status
+  pi-linear-tools auth logout
+
+Environment Variables (for CI/headless environments):
+  LINEAR_ACCESS_TOKEN     OAuth access token
+  LINEAR_REFRESH_TOKEN    OAuth refresh token
+  LINEAR_EXPIRES_AT       Token expiry timestamp (milliseconds)
+`);
+}
+
+// ===== AUTH HANDLERS =====
+
+async function handleAuthLogin(args) {
+  const port = readFlag(args, '--port');
+
+  try {
+    const tokens = await authenticate({
+      port: port ? parseInt(port, 10) : undefined,
+    });
+
+    const settings = await loadSettings();
+    settings.authMethod = 'oauth';
+    await saveSettings(settings);
+
+    console.log('\n✓ Authentication successful!');
+    console.log(`✓ Token expires at: ${new Date(tokens.expiresAt).toLocaleString()}`);
+    console.log(`✓ Granted scopes: ${tokens.scope.join(', ')}`);
+    console.log('\nYou can now use pi-linear-tools commands.');
+  } catch (error) {
+    console.error('\n✗ Authentication failed:', error.message);
+    process.exitCode = 1;
+  }
+}
+
+async function handleAuthLogout() {
+  try {
+    await logout();
+    console.log('\n✓ Logged out successfully');
+    console.log('\nYou will need to authenticate again to access Linear.');
+  } catch (error) {
+    console.error('\n✗ Logout failed:', error.message);
+    process.exitCode = 1;
+  }
+}
+
+async function handleAuthStatus() {
+  try {
+    const status = await getAuthStatus();
+
+    if (!status) {
+      console.log('\nAuthentication status: Not authenticated');
+      console.log('\nTo authenticate, run: pi-linear-tools auth login');
+      console.log('\nFor CI/headless environments, set these environment variables:');
+      console.log('  LINEAR_ACCESS_TOKEN');
+      console.log('  LINEAR_REFRESH_TOKEN');
+      console.log('  LINEAR_EXPIRES_AT');
+      return;
+    }
+
+    const isAuth = await isAuthenticated();
+
+    console.log('\nAuthentication status:', isAuth ? 'Authenticated' : 'Token expired');
+    console.log(`Token expires at: ${new Date(status.expiresAt).toLocaleString()}`);
+
+    if (status.expiresIn > 0) {
+      const minutes = Math.floor(status.expiresIn / 60000);
+      console.log(`Time until expiry: ${minutes} minute${minutes !== 1 ? 's' : ''}`);
+    }
+
+    console.log(`Granted scopes: ${status.scopes.join(', ')}`);
+  } catch (error) {
+    console.error('\n✗ Failed to get authentication status:', error.message);
+    process.exitCode = 1;
+  }
+}
+
+async function handleAuth(args) {
+  const [action] = args;
+
+  if (!action || action === '--help' || action === '-h') {
+    printAuthHelp();
+    return;
+  }
+
+  switch (action) {
+    case 'login':
+      return handleAuthLogin(args);
+    case 'logout':
+      return handleAuthLogout();
+    case 'status':
+      return handleAuthStatus();
+    default:
+      throw new Error(`Unknown auth action: ${action}`);
+  }
+}
+
 // ===== CONFIG HANDLER =====
 
 async function tryResolveProjectId(projectRef, explicitApiKey = null) {
@@ -303,7 +481,8 @@ async function handleConfig(args) {
 
   if (apiKey) {
     const settings = await loadSettings();
-    settings.linearApiKey = apiKey;
+    settings.apiKey = apiKey;
+    settings.authMethod = 'api-key';
     await saveSettings(settings);
     cachedApiKey = null;
     console.log('LINEAR_API_KEY saved to settings');
@@ -324,7 +503,7 @@ async function handleConfig(args) {
     }
 
     const settings = await loadSettings();
-    const projectId = await tryResolveProjectId(projectName, settings.linearApiKey);
+    const projectId = await tryResolveProjectId(projectName, settings.apiKey || settings.linearApiKey);
 
     if (!settings.projects[projectId]) {
       settings.projects[projectId] = { scope: { team: null } };
@@ -341,8 +520,8 @@ async function handleConfig(args) {
   }
 
   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');
 
   console.log(`Configuration:
   LINEAR_API_KEY: ${hasKey ? 'configured' : 'not set'} (source: ${keySource})
@@ -358,8 +537,7 @@ Commands:
 // ===== ISSUE HANDLERS =====
 
 async function handleIssueList(args) {
-  const apiKey = await getLinearApiKey();
-  const client = createLinearClient(apiKey);
+  const client = await createAuthenticatedClient();
 
   const params = {
     project: readFlag(args, '--project'),
@@ -373,8 +551,7 @@ async function handleIssueList(args) {
 }
 
 async function handleIssueView(args) {
-  const apiKey = await getLinearApiKey();
-  const client = createLinearClient(apiKey);
+  const client = await createAuthenticatedClient();
 
   const positional = args.filter((a) => !a.startsWith('-'));
   if (positional.length === 0) {
@@ -391,8 +568,7 @@ async function handleIssueView(args) {
 }
 
 async function handleIssueCreate(args) {
-  const apiKey = await getLinearApiKey();
-  const client = createLinearClient(apiKey);
+  const client = await createAuthenticatedClient();
 
   const params = {
     title: readFlag(args, '--title'),
@@ -414,8 +590,7 @@ async function handleIssueCreate(args) {
 }
 
 async function handleIssueUpdate(args) {
-  const apiKey = await getLinearApiKey();
-  const client = createLinearClient(apiKey);
+  const client = await createAuthenticatedClient();
 
   const positional = args.filter((a) => !a.startsWith('-'));
   if (positional.length === 0) {
@@ -438,8 +613,7 @@ async function handleIssueUpdate(args) {
 }
 
 async function handleIssueComment(args) {
-  const apiKey = await getLinearApiKey();
-  const client = createLinearClient(apiKey);
+  const client = await createAuthenticatedClient();
 
   const positional = args.filter((a) => !a.startsWith('-'));
   if (positional.length === 0) {
@@ -460,8 +634,7 @@ async function handleIssueComment(args) {
 }
 
 async function handleIssueStart(args) {
-  const apiKey = await getLinearApiKey();
-  const client = createLinearClient(apiKey);
+  const client = await createAuthenticatedClient();
 
   const positional = args.filter((a) => !a.startsWith('-'));
   if (positional.length === 0) {
@@ -470,7 +643,6 @@ async function handleIssueStart(args) {
 
   const params = {
     issue: positional[0],
-    branch: readFlag(args, '--branch'),
     fromRef: readFlag(args, '--from-ref'),
     onBranchExists: readFlag(args, '--on-branch-exists'),
   };
@@ -480,8 +652,7 @@ async function handleIssueStart(args) {
 }
 
 async function handleIssueDelete(args) {
-  const apiKey = await getLinearApiKey();
-  const client = createLinearClient(apiKey);
+  const client = await createAuthenticatedClient();
 
   const positional = args.filter((a) => !a.startsWith('-'));
   if (positional.length === 0) {
@@ -527,8 +698,7 @@ async function handleIssue(args) {
 // ===== PROJECT HANDLERS =====
 
 async function handleProjectList() {
-  const apiKey = await getLinearApiKey();
-  const client = createLinearClient(apiKey);
+  const client = await createAuthenticatedClient();
 
   const result = await executeProjectList(client);
   console.log(result.content[0].text);
@@ -553,8 +723,7 @@ async function handleProject(args) {
 // ===== TEAM HANDLERS =====
 
 async function handleTeamList() {
-  const apiKey = await getLinearApiKey();
-  const client = createLinearClient(apiKey);
+  const client = await createAuthenticatedClient();
 
   const result = await executeTeamList(client);
   console.log(result.content[0].text);
@@ -579,8 +748,7 @@ async function handleTeam(args) {
 // ===== MILESTONE HANDLERS =====
 
 async function handleMilestoneList(args) {
-  const apiKey = await getLinearApiKey();
-  const client = createLinearClient(apiKey);
+  const client = await createAuthenticatedClient();
 
   const params = {
     project: readFlag(args, '--project'),
@@ -591,8 +759,7 @@ async function handleMilestoneList(args) {
 }
 
 async function handleMilestoneView(args) {
-  const apiKey = await getLinearApiKey();
-  const client = createLinearClient(apiKey);
+  const client = await createAuthenticatedClient();
 
   const positional = args.filter((a) => !a.startsWith('-'));
   if (positional.length === 0) {
@@ -608,8 +775,7 @@ async function handleMilestoneView(args) {
 }
 
 async function handleMilestoneCreate(args) {
-  const apiKey = await getLinearApiKey();
-  const client = createLinearClient(apiKey);
+  const client = await createAuthenticatedClient();
 
   const params = {
     project: readFlag(args, '--project'),
@@ -628,8 +794,7 @@ async function handleMilestoneCreate(args) {
 }
 
 async function handleMilestoneUpdate(args) {
-  const apiKey = await getLinearApiKey();
-  const client = createLinearClient(apiKey);
+  const client = await createAuthenticatedClient();
 
   const positional = args.filter((a) => !a.startsWith('-'));
   if (positional.length === 0) {
@@ -649,8 +814,7 @@ async function handleMilestoneUpdate(args) {
 }
 
 async function handleMilestoneDelete(args) {
-  const apiKey = await getLinearApiKey();
-  const client = createLinearClient(apiKey);
+  const client = await createAuthenticatedClient();
 
   const positional = args.filter((a) => !a.startsWith('-'));
   if (positional.length === 0) {
@@ -673,19 +837,23 @@ async function handleMilestone(args) {
     return;
   }
 
-  switch (action) {
-    case 'list':
-      return handleMilestoneList(rest);
-    case 'view':
-      return handleMilestoneView(rest);
-    case 'create':
-      return handleMilestoneCreate(rest);
-    case 'update':
-      return handleMilestoneUpdate(rest);
-    case 'delete':
-      return handleMilestoneDelete(rest);
-    default:
-      throw new Error(`Unknown milestone action: ${action}`);
+  try {
+    switch (action) {
+      case 'list':
+        return await handleMilestoneList(rest);
+      case 'view':
+        return await handleMilestoneView(rest);
+      case 'create':
+        return await handleMilestoneCreate(rest);
+      case 'update':
+        return await handleMilestoneUpdate(rest);
+      case 'delete':
+        return await handleMilestoneDelete(rest);
+      default:
+        throw new Error(`Unknown milestone action: ${action}`);
+    }
+  } catch (error) {
+    throw withMilestoneScopeHint(error);
   }
 }
 
@@ -699,6 +867,11 @@ export async function runCli(argv = process.argv.slice(2)) {
     return;
   }
 
+  if (command === 'auth') {
+    await handleAuth(rest);
+    return;
+  }
+
   if (command === 'config') {
     await handleConfig(rest);
     return;

package/src/handlers.js

@@ -447,28 +447,31 @@ export async function executeIssueStart(client, params, options = {}) {
   const issue = ensureNonEmpty(params.issue, 'issue');
   const prepared = await prepareIssueStart(client, issue);
 
-  const desiredBranch = params.branch || prepared.branchName;
-  if (!desiredBranch) {
+  // Always use Linear's suggested branchName - it cannot be changed via API
+  // and using a custom branch would break Linear's branch-to-issue linking
+  const branchName = prepared.branchName;
+  if (!branchName) {
     throw new Error(
-      `No branch name resolved for issue ${prepared.issue.identifier}. Provide the 'branch' parameter explicitly.`
+      `No branch name available for issue ${prepared.issue.identifier}. The issue may not have a team assigned.`
     );
   }
 
   let gitResult;
   if (gitExecutor) {
     // Use provided git executor (e.g., pi.exec)
-    gitResult = await gitExecutor(desiredBranch, params.fromRef || 'HEAD', params.onBranchExists || 'switch');
+    gitResult = await gitExecutor(branchName, params.fromRef || 'HEAD', params.onBranchExists || 'switch');
   } else {
     // Use built-in child_process git operations
-    gitResult = await startGitBranch(desiredBranch, params.fromRef || 'HEAD', params.onBranchExists || 'switch');
+    gitResult = await startGitBranch(branchName, params.fromRef || 'HEAD', params.onBranchExists || 'switch');
   }
 
   const updatedIssue = await setIssueState(client, prepared.issue.id, prepared.startedState.id);
 
+  const identifier = updatedIssue.identifier || prepared.issue.identifier;
   const compactTitle = String(updatedIssue.title || prepared.issue?.title || '').trim().toLowerCase();
   const summary = compactTitle
-    ? `Started issue ${updatedIssue.identifier} (${compactTitle})`
-    : `Started issue ${updatedIssue.identifier}`;
+    ? `Started issue ${identifier} (${compactTitle})`
+    : `Started issue ${identifier}`;
 
   return toTextResult(summary, {
     issueId: updatedIssue.id,
@@ -589,7 +592,7 @@ export async function executeMilestoneList(client, params) {
       ? ` → ${milestone.targetDate.split('T')[0]}`
       : '';
 
-    lines.push(`- ${statusEmoji} **${milestone.name}** _[${milestone.status}]_ (${progressLabel})${dateLabel}`);
+    lines.push(`- ${statusEmoji} **${milestone.name}** _[${milestone.status}]_ (${progressLabel})${dateLabel} \`${milestone.id}\``);
     if (milestone.description) {
       lines.push(`  ${milestone.description.split('\n')[0].slice(0, 100)}${milestone.description.length > 100 ? '...' : ''}`);
     }
@@ -731,11 +734,11 @@ export async function executeMilestoneCreate(client, params) {
 export async function executeMilestoneUpdate(client, params) {
   const milestoneId = ensureNonEmpty(params.milestone, 'milestone');
 
+  // Note: status is not included as it's a computed/read-only field in Linear's API
   const result = await updateProjectMilestone(client, milestoneId, {
     name: params.name,
     description: params.description,
     targetDate: params.targetDate,
-    status: params.status,
   });
 
   const friendlyChanges = result.changed;
@@ -771,10 +774,15 @@ export async function executeMilestoneDelete(client, params) {
   const milestoneId = ensureNonEmpty(params.milestone, 'milestone');
   const result = await deleteProjectMilestone(client, milestoneId);
 
+  const label = result.name
+    ? `**${result.name}** (\`${milestoneId}\`)`
+    : `\`${milestoneId}\``;
+
   return toTextResult(
-    `Deleted milestone \`${milestoneId}\``,
+    `Deleted milestone ${label}`,
     {
       milestoneId: result.milestoneId,
+      name: result.name,
       success: result.success,
     }
   );

package/src/linear-client.js

@@ -2,29 +2,59 @@
  * Linear SDK client factory
  *
  * Creates a configured LinearClient instance for interacting with Linear API.
+ * Supports both API key and OAuth token authentication.
  */
 
 import { LinearClient } from '@linear/sdk';
+import { debug, warn, error as logError } from './logger.js';
 
 /** @type {Function|null} Test-only client factory override */
 let _testClientFactory = null;
 
 /**
  * Create a Linear SDK client
- * @param {string} apiKey - Linear API key
+ *
+ * Supports two authentication methods:
+ * 1. API Key: Pass as string or { apiKey: '...' }
+ * 2. OAuth Token: Pass as { accessToken: '...' }
+ *
+ * @param {string|object} auth - Authentication credential
+ * @param {string} [auth.apiKey] - Linear API key (for API key auth)
+ * @param {string} [auth.accessToken] - OAuth access token (for OAuth auth)
  * @returns {LinearClient} Configured Linear client
  */
-export function createLinearClient(apiKey) {
+export function createLinearClient(auth) {
   // Allow test override
   if (_testClientFactory) {
-    return _testClientFactory(apiKey);
+    return _testClientFactory(auth);
   }
 
-  if (!apiKey || typeof apiKey !== 'string') {
-    throw new Error('Linear API key is required');
+  let clientConfig;
+
+  // Handle different input formats
+  if (typeof auth === 'string') {
+    // Legacy: API key passed as string
+    clientConfig = { apiKey: auth };
+  } else if (typeof auth === 'object' && auth !== null) {
+    // Object format: { apiKey: '...' } or { accessToken: '...' }
+    if (auth.accessToken) {
+      clientConfig = { apiKey: auth.accessToken };
+      debug('Creating Linear client with OAuth access token');
+    } else if (auth.apiKey) {
+      clientConfig = { apiKey: auth.apiKey };
+      debug('Creating Linear client with API key');
+    } else {
+      throw new Error(
+        'Auth object must contain either apiKey or accessToken'
+      );
+    }
+  } else {
+    throw new Error(
+      'Invalid auth parameter: must be a string (API key) or an object with apiKey or accessToken'
+    );
   }
 
-  return new LinearClient({ apiKey });
+  return new LinearClient(clientConfig);
 }
 
 /**