@alasano/pi-linear 0.3.0 → 0.4.0

package/README.md

@@ -34,27 +34,34 @@ pi install npm:@alasano/pi-linear
 
 ## Authentication
 
-The extension auto-detects the `LINEAR_API_KEY` environment variable if set globally. No setup needed in that case.
+The extension can use either stored workspaces or the `LINEAR_API_KEY` environment variable. Stored workspaces are preferred by default so multi-account switching keeps working even if `LINEAR_API_KEY` is set globally.
 
-For multi-workspace support or if you don't have the env var, use the `/linear-auth` command:
+Use the `/linear-auth` command to manage workspaces and choose the auth preference:
 
-| Command                      | Description                                              |
-| ---------------------------- | -------------------------------------------------------- |
-| `/linear-auth add <name>`    | Add a workspace with an API key (prompts for key)        |
-| `/linear-auth remove <name>` | Remove a workspace (shows selector if name omitted)      |
-| `/linear-auth switch <name>` | Switch active workspace (shows selector if name omitted) |
-| `/linear-auth status`        | Show current auth source and configured workspaces       |
-| `/linear-auth`               | Same as status                                           |
+| Command                              | Description                                                          |
+| ------------------------------------ | -------------------------------------------------------------------- |
+| `/linear-auth add <name>`            | Add a workspace with an API key (prompts for key)                    |
+| `/linear-auth remove <name>`         | Remove a workspace (shows selector if name omitted)                  |
+| `/linear-auth switch <name>`         | Switch active workspace and prefer stored workspaces                 |
+| `/linear-auth prefer workspace\|env` | Choose whether stored workspaces or `LINEAR_API_KEY` are tried first |
+| `/linear-auth status`                | Show auth preference, active source, and configured workspaces       |
+| `/linear-auth`                       | Same as status                                                       |
 
 When you add your first workspace, it becomes active automatically. Adding a second workspace prompts you to switch. After a `/reload` with two or more workspaces configured, the agent gets a `linear_switch_workspace` tool and can switch between them when asked.
 
-Auth resolution order:
+Default auth resolution order (`/linear-auth prefer workspace`):
 
 1. Active stored workspace (if any workspaces are configured)
-2. `LINEAR_API_KEY` environment variable (fallback when no workspaces configured)
+2. `LINEAR_API_KEY` environment variable (fallback when no workspace is active)
 3. Interactive prompt (asks you to set up a key)
 
-Credentials are stored at `~/.pi/agent/state/extensions/linear/credentials.json`.
+Environment auth resolution order (`/linear-auth prefer env`):
+
+1. `LINEAR_API_KEY` environment variable
+2. Active stored workspace (fallback when `LINEAR_API_KEY` is not set)
+3. Interactive prompt (asks you to set up a key)
+
+Credentials and auth preference are stored at `~/.pi/agent/extensions/linear/credentials.json`.
 
 ## Tool settings
 

package/extensions/client.ts

@@ -9,13 +9,20 @@ import { ISSUE_SELECTION } from './selections';
 const LINEAR_GRAPHQL_ENDPOINT = 'https://api.linear.app/graphql';
 const IDENTIFIER_PATTERN = /^([A-Z][A-Z0-9]*)-(\d+)$/i;
 
+export type AuthPreference = 'workspace' | 'env';
+
 export type WorkspaceCredentials = {
   activeWorkspace: string | null;
+  authPreference: AuthPreference;
   workspaces: Record<string, { apiKey: string }>;
 };
 
+function normalizeAuthPreference(value: unknown): AuthPreference {
+  return value === 'env' ? 'env' : 'workspace';
+}
+
 function emptyCredentials(): WorkspaceCredentials {
-  return { activeWorkspace: null, workspaces: {} };
+  return { activeWorkspace: null, authPreference: 'workspace', workspaces: {} };
 }
 
 export function getCredentialFilePath() {
@@ -38,6 +45,7 @@ export async function readCredentials(): Promise<WorkspaceCredentials> {
     }
     const activeWorkspace =
       typeof parsed.activeWorkspace === 'string' ? parsed.activeWorkspace : null;
+    const authPreference = normalizeAuthPreference(parsed.authPreference);
     const workspaces: Record<string, { apiKey: string }> = {};
     for (const [name, entry] of Object.entries(parsed.workspaces)) {
       if (
@@ -49,7 +57,7 @@ export async function readCredentials(): Promise<WorkspaceCredentials> {
         workspaces[name] = { apiKey: (entry as { apiKey: string }).apiKey };
       }
     }
-    return { activeWorkspace, workspaces };
+    return { activeWorkspace, authPreference, workspaces };
   } catch {
     return emptyCredentials();
   }
@@ -96,6 +104,14 @@ export async function switchWorkspace(name: string): Promise<WorkspaceCredential
     throw new Error(`Workspace "${name}" does not exist.`);
   }
   creds.activeWorkspace = name;
+  creds.authPreference = 'workspace';
+  await writeCredentials(creds);
+  return creds;
+}
+
+export async function setAuthPreference(preference: AuthPreference): Promise<WorkspaceCredentials> {
+  const creds = await readCredentials();
+  creds.authPreference = preference;
   await writeCredentials(creds);
   return creds;
 }
@@ -114,10 +130,15 @@ export async function resolveApiKey(
 ): Promise<{ apiKey?: string; source: 'env' | 'workspace' | 'none' }> {
   const creds = await readCredentials();
   const workspaceKey = getActiveApiKey(creds);
-  if (workspaceKey) return { apiKey: workspaceKey, source: 'workspace' };
-
   const envApiKey = asString(process.env.LINEAR_API_KEY);
-  if (envApiKey) return { apiKey: envApiKey, source: 'env' };
+
+  if (creds.authPreference === 'env') {
+    if (envApiKey) return { apiKey: envApiKey, source: 'env' };
+    if (workspaceKey) return { apiKey: workspaceKey, source: 'workspace' };
+  } else {
+    if (workspaceKey) return { apiKey: workspaceKey, source: 'workspace' };
+    if (envApiKey) return { apiKey: envApiKey, source: 'env' };
+  }
 
   const promptIfMissing = options?.promptIfMissing ?? true;
   if (promptIfMissing && ctx.hasUI) {

package/extensions/index.ts

@@ -4,6 +4,7 @@ import {
   addWorkspace,
   removeWorkspace,
   switchWorkspace,
+  setAuthPreference,
   listWorkspaceNames,
   getActiveWorkspaceName,
   resolveApiKey,
@@ -27,7 +28,8 @@ import { registerLinearSettings } from './settings';
 
 export default async function linearExtension(pi: ExtensionAPI) {
   pi.registerCommand('linear-auth', {
-    description: 'Manage Linear workspace auth (usage: /linear-auth [add|remove|switch|status])',
+    description:
+      'Manage Linear workspace auth (usage: /linear-auth [add|remove|switch|prefer|status])',
     handler: async (args, ctx) => {
       const parts = args.trim().split(/\s+/);
       const subcommand = parts[0]?.toLowerCase() || '';
@@ -145,7 +147,37 @@ export default async function linearExtension(pi: ExtensionAPI) {
           }
 
           await switchWorkspace(workspaceName);
-          ctx.ui.notify(`Active workspace: ${workspaceName}`, 'info');
+          ctx.ui.notify(`Active workspace: ${workspaceName}\nAuth preference: workspace`, 'info');
+          return;
+        }
+
+        case 'prefer': {
+          const preference = name.toLowerCase();
+          if (preference !== 'workspace' && preference !== 'env') {
+            ctx.ui.notify('Usage: /linear-auth prefer [workspace|env]', 'warning');
+            return;
+          }
+
+          const updated = await setAuthPreference(preference);
+          const envIsSet = Boolean(asString(process.env.LINEAR_API_KEY));
+          const active = getActiveWorkspaceName(updated);
+          const lines = [`Auth preference: ${preference}`];
+
+          if (preference === 'env') {
+            if (envIsSet) {
+              lines.push('LINEAR_API_KEY will be used before stored workspaces.');
+            } else if (active) {
+              lines.push('LINEAR_API_KEY is not set; falling back to the active workspace.');
+            } else {
+              lines.push('LINEAR_API_KEY is not set and no active workspace is configured.');
+            }
+          } else if (active) {
+            lines.push(`Workspace "${active}" will be used before LINEAR_API_KEY.`);
+          } else {
+            lines.push('No active workspace configured; falling back to LINEAR_API_KEY if set.');
+          }
+
+          ctx.ui.notify(lines.join('\n'), preference === 'env' && !envIsSet ? 'warning' : 'info');
           return;
         }
 
@@ -157,6 +189,7 @@ export default async function linearExtension(pi: ExtensionAPI) {
           });
           const names = listWorkspaceNames(creds);
           const active = getActiveWorkspaceName(creds);
+          const envIsSet = Boolean(asString(process.env.LINEAR_API_KEY));
 
           let sourceLabel: string;
           if (source === 'workspace') {
@@ -167,7 +200,7 @@ export default async function linearExtension(pi: ExtensionAPI) {
             sourceLabel = 'none';
           }
 
-          const lines = [`Auth source: ${sourceLabel}`];
+          const lines = [`Auth preference: ${creds.authPreference}`, `Auth source: ${sourceLabel}`];
           if (names.length > 0) {
             lines.push(
               `Workspaces: ${names.map((n) => (n === active ? `${n} (active)` : n)).join(', ')}`,
@@ -176,12 +209,34 @@ export default async function linearExtension(pi: ExtensionAPI) {
             lines.push('No workspaces configured');
           }
 
+          if (creds.authPreference === 'workspace' && envIsSet) {
+            if (source === 'workspace') {
+              lines.push(
+                'LINEAR_API_KEY is set but not active. Run /linear-auth prefer env to use it.',
+              );
+            } else if (source === 'env') {
+              lines.push(
+                'No active workspace is configured, so LINEAR_API_KEY is being used as fallback.',
+              );
+            }
+          } else if (creds.authPreference === 'env' && names.length > 0) {
+            if (source === 'env') {
+              lines.push(
+                'Stored workspaces are available but not active. Run /linear-auth prefer workspace or /linear-auth switch <name> to use one.',
+              );
+            } else if (source === 'workspace') {
+              lines.push(
+                'LINEAR_API_KEY is not set, so the active workspace is being used as fallback.',
+              );
+            }
+          }
+
           ctx.ui.notify(lines.join('\n'), source === 'none' ? 'warning' : 'info');
           return;
         }
 
         default: {
-          ctx.ui.notify('Usage: /linear-auth [add|remove|switch|status]', 'warning');
+          ctx.ui.notify('Usage: /linear-auth [add|remove|switch|prefer|status]', 'warning');
         }
       }
     },

package/extensions/tools/documents.ts

@@ -23,6 +23,36 @@ import {
   renderLinearUpdateDocumentCall,
 } from '../renderers/documents';
 
+const DOCUMENT_RELATED_CONTEXT_FIELDS = [
+  'cycleId',
+  'initiativeId',
+  'issueId',
+  'projectId',
+  'releaseId',
+  'resourceFolderId',
+] as const;
+
+type DocumentRelatedContextField = (typeof DOCUMENT_RELATED_CONTEXT_FIELDS)[number];
+
+function hasDocumentRelatedContext(
+  params: Partial<Record<DocumentRelatedContextField, unknown>>,
+  rawInput: JsonObject,
+): boolean {
+  return DOCUMENT_RELATED_CONTEXT_FIELDS.some((field) =>
+    Boolean(asString(params[field]) || asString(rawInput[field])),
+  );
+}
+
+function documentInputBase(rawInput: JsonObject, omitTeamId: boolean): JsonObject {
+  if (!omitTeamId) return rawInput;
+
+  // Linear rejects document inputs with multiple parent/context IDs (for example
+  // issueId + teamId). Treat teamId/teamKey as the document context only when no
+  // more specific relation is provided; issue/project/etc. imply their context.
+  const { teamId: _teamId, ...inputWithoutTeamId } = rawInput;
+  return inputWithoutTeamId;
+}
+
 export function documentTools() {
   return [
     defineTool({
@@ -124,7 +154,7 @@ export function documentTools() {
       name: 'linear_create_document',
       label: 'Linear Create Document',
       description:
-        'Create a document. Supports top-level DocumentCreateInput fields and raw input.',
+        'Create a document. Supports top-level DocumentCreateInput fields and raw input. Use issueId/projectId/etc. for related documents; teamId/teamKey are only for team-scoped documents.',
       parameters: Type.Object({
         color: Type.Optional(Type.String()),
         content: Type.Optional(Type.String()),
@@ -147,9 +177,10 @@ export function documentTools() {
       async execute(_toolCallId, params, signal, _onUpdate, ctx) {
         return withLinearAuth(ctx, signal, async (apiKey) => {
           const rawInput = asObject(params.input) || {};
-          const rawInputTeamId = asString(rawInput.teamId);
+          const hasRelatedContext = hasDocumentRelatedContext(params, rawInput);
+          const rawInputTeamId = hasRelatedContext ? undefined : asString(rawInput.teamId);
           const teamId =
-            params.teamId || params.teamKey || rawInputTeamId
+            !hasRelatedContext && (params.teamId || params.teamKey || rawInputTeamId)
               ? await resolveTeamId(
                   apiKey,
                   {
@@ -161,7 +192,7 @@ export function documentTools() {
               : undefined;
 
           const input = {
-            ...rawInput,
+            ...documentInputBase(rawInput, hasRelatedContext),
             ...compactObject({
               color: params.color,
               content: params.content,
@@ -218,7 +249,7 @@ export function documentTools() {
       name: 'linear_update_document',
       label: 'Linear Update Document',
       description:
-        'Update a document by id. Supports top-level DocumentUpdateInput fields and raw input.',
+        'Update a document by id. Supports top-level DocumentUpdateInput fields and raw input. Use issueId/projectId/etc. for related documents; teamId/teamKey are only for team-scoped documents.',
       parameters: Type.Object({
         documentId: Type.String(),
         color: Type.Optional(Type.String()),
@@ -243,9 +274,10 @@ export function documentTools() {
       async execute(_toolCallId, params, signal, _onUpdate, ctx) {
         return withLinearAuth(ctx, signal, async (apiKey) => {
           const rawInput = asObject(params.input) || {};
-          const rawInputTeamId = asString(rawInput.teamId);
+          const hasRelatedContext = hasDocumentRelatedContext(params, rawInput);
+          const rawInputTeamId = hasRelatedContext ? undefined : asString(rawInput.teamId);
           const teamId =
-            params.teamId || params.teamKey || rawInputTeamId
+            !hasRelatedContext && (params.teamId || params.teamKey || rawInputTeamId)
               ? await resolveTeamId(
                   apiKey,
                   {
@@ -257,7 +289,7 @@ export function documentTools() {
               : undefined;
 
           const input = {
-            ...rawInput,
+            ...documentInputBase(rawInput, hasRelatedContext),
             ...compactObject({
               color: params.color,
               content: params.content,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@alasano/pi-linear",
-  "version": "0.3.0",
+  "version": "0.4.0",
   "description": "Linear integration for pi with 55+ tools, multi-workspace auth, and per-tool settings",
   "keywords": [
     "pi-package"
@@ -13,6 +13,7 @@
   },
   "type": "module",
   "scripts": {
+    "test": "vitest run",
     "typecheck": "tsc --noEmit"
   },
   "pi": {