@subsimplicity/pi-extension-linear 0.0.1

package/README.md

@@ -0,0 +1,109 @@
+# linear
+
+`@subsimplicity/pi-extension-linear` is a [pi](https://pi.dev) extension that gives agents focused Linear issue tools while they work in a coding session.
+
+The extension is intentionally a local Linear toolbelt first: it uses Linear's GraphQL API with a personal API key or OAuth access token, avoids polling, and only injects issue context automatically when a prompt mentions Linear issue identifiers such as `ENG-123`.
+
+## Supported surface
+
+This package is a focused Pi extension for Linear issue workflows. It is not a standalone MCP server or a full Linear API wrapper.
+
+### Issue read/search
+
+- Fetch an issue by UUID or identifier, e.g. `ENG-123`.
+- Include issue description, URL, priority, estimate, due date, timestamps, workflow state, team, project, labels, creator, assignee, delegate, and recent comments.
+- Search recently updated issues with filters for:
+  - text query against identifier/title/description/searchable content
+  - team UUID, key, or exact name
+  - workflow state name or state type
+  - label names
+  - priority
+  - assignee UUID or email
+  - project name
+  - archived issue inclusion
+- List issues assigned to and recently created by the authenticated user.
+
+### Team/workflow discovery
+
+- List Linear teams with UUIDs, keys, and names.
+- List workflow states for a team by team UUID, key, or exact name.
+
+### Issue writes
+
+- Create issues with team, title, and optional markdown description, assignee, due date, label IDs, priority, project, and state.
+- Update issues by UUID or identifier. Supported fields are title, description, assignee, due date, replacement label IDs, priority, project, and state.
+- Add markdown comments to issues.
+
+### Pi integration
+
+- Show a `linear:` status indicator in pi.
+- Inject concise Linear context automatically when a prompt mentions issue keys such as `ENG-123`.
+- Add `#...` autocomplete for recently updated Linear issues.
+
+## Requirements
+
+Set one of these environment variables before starting pi:
+
+```bash
+export LINEAR_API_KEY=lin_api_...
+# or, for OAuth bearer-token auth:
+export LINEAR_ACCESS_TOKEN=...
+```
+
+Personal API keys are easiest for local use. OAuth/app-actor and webhook-based Linear Agents are intentionally out of scope for this first package.
+
+## Install / use locally
+
+From this package directory:
+
+```bash
+bun install
+pi -e ./src/index.ts
+```
+
+To install from a local checkout so pi loads it automatically:
+
+```bash
+pi install ./path/to/linear
+```
+
+Use a project-local install when you want pi to record it in that project's `.pi/settings.json`:
+
+```bash
+pi install -l ./path/to/linear
+```
+
+## Tools
+
+| Tool                   | Purpose                                                                 |
+| ---------------------- | ----------------------------------------------------------------------- |
+| `linear_setup`         | Check Linear credentials and return the authenticated user.             |
+| `linear_get_issue`     | Fetch an issue by UUID or identifier, e.g. `ENG-123`.                   |
+| `linear_search_issues` | Search issues with focused filters and recently-updated ordering.       |
+| `linear_my_work`       | List issues assigned to and recently created by the authenticated user. |
+| `linear_list_teams`    | List Linear teams with keys and UUIDs.                                  |
+| `linear_list_states`   | List workflow states for a team.                                        |
+| `linear_create_issue`  | Create a Linear issue.                                                  |
+| `linear_update_issue`  | Update a Linear issue.                                                  |
+| `linear_comment_issue` | Add a markdown comment to a Linear issue.                               |
+
+## Commands
+
+- `/linear-setup` — check credentials and show the authenticated Linear user.
+- `/linear-issue ENG-123` — fetch an issue and add it to the transcript.
+- `/linear-search text` — search recently updated issues by text.
+- `/linear-my-work` — show issues assigned to and recently created by you.
+- `/linear-teams` — list team keys and UUIDs.
+- `/linear-states TEAM_KEY` — list workflow states for a team.
+
+## Autocomplete
+
+Type `#` followed by part of an issue key/title to autocomplete recently updated issues. Completing `#ENG` inserts `ENG-123`.
+
+## Development
+
+```bash
+bun install
+bun run typecheck
+bun run lint
+```

package/package.json

@@ -0,0 +1,49 @@
+{
+  "name": "@subsimplicity/pi-extension-linear",
+  "version": "0.0.1",
+  "description": "Pi extension for working with Linear issues from coding sessions",
+  "module": "src/index.ts",
+  "exports": "./src/index.ts",
+  "type": "module",
+  "keywords": [
+    "linear",
+    "pi-package",
+    "project-management",
+    "issues"
+  ],
+  "files": [
+    "src",
+    "README.md",
+    "package.json"
+  ],
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://registry.npmjs.org/"
+  },
+  "repository": {
+    "directory": "linear",
+    "type": "git",
+    "url": "https://github.com/subsimplicity/pi-extensions-public/blob/main/linear/README.md"
+  },
+  "scripts": {
+    "format": "prettier --write .",
+    "lint": "eslint --fix .",
+    "typecheck": "tsc"
+  },
+  "pi": {
+    "extensions": [
+      "./src/index.ts"
+    ]
+  },
+  "devDependencies": {
+    "@subsimplicity/eslint-config-subsimplicity": "latest",
+    "@types/bun": "^1.3.14",
+    "eslint": "^10.4.0",
+    "prettier": "^3.8.3",
+    "typescript": "^6.0.3"
+  },
+  "peerDependencies": {
+    "@earendil-works/pi-coding-agent": "*",
+    "@earendil-works/pi-tui": "*"
+  }
+}

package/src/autocomplete.ts

@@ -0,0 +1,140 @@
+import type {
+  AutocompleteItem,
+  AutocompleteProvider,
+  AutocompleteSuggestions,
+} from "@earendil-works/pi-tui";
+import { LinearClient, hasLinearCredentials } from "./client.ts";
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+import type { LinearIssueSummary } from "./types.ts";
+import { fuzzyFilter } from "@earendil-works/pi-tui";
+
+const MAX_PRELOADED_ISSUES = 100;
+const MAX_SUGGESTIONS = 20;
+
+function isAbortError(error: unknown): boolean {
+  return error instanceof Error && error.name === "AbortError";
+}
+
+function extractLinearToken(textBeforeCursor: string): string | undefined {
+  const match = /(?:^|[ \t])#([A-Za-z0-9-]*)$/.exec(textBeforeCursor);
+  return match?.[1];
+}
+
+function issueToItem(issue: LinearIssueSummary): AutocompleteItem {
+  return {
+    description: `${issue.state?.name ?? "no state"} · ${issue.title}`,
+    label: issue.identifier,
+    value: issue.identifier,
+  };
+}
+
+function filterIssues(
+  issues: LinearIssueSummary[],
+  query: string,
+): AutocompleteItem[] {
+  if (!query.trim()) {
+    return issues.slice(0, MAX_SUGGESTIONS).map(issueToItem);
+  }
+
+  const upper = query.toUpperCase();
+  const identifierMatches = issues
+    .filter((issue) => issue.identifier.startsWith(upper))
+    .slice(0, MAX_SUGGESTIONS)
+    .map(issueToItem);
+  if (identifierMatches.length > 0) return identifierMatches;
+
+  return fuzzyFilter(
+    issues,
+    query,
+    (issue) => `${issue.identifier} ${issue.title}`,
+  )
+    .slice(0, MAX_SUGGESTIONS)
+    .map(issueToItem);
+}
+
+function createLinearAutocompleteProvider(
+  current: AutocompleteProvider,
+  getIssues: (signal: AbortSignal) => Promise<LinearIssueSummary[] | undefined>,
+): AutocompleteProvider {
+  return {
+    applyCompletion(lines, cursorLine, cursorCol, item, prefix) {
+      return current.applyCompletion(
+        lines,
+        cursorLine,
+        cursorCol,
+        item,
+        prefix,
+      );
+    },
+
+    async getSuggestions(
+      lines,
+      cursorLine,
+      cursorCol,
+      options,
+    ): Promise<AutocompleteSuggestions | null> {
+      const currentLine = lines[cursorLine] ?? "";
+      const token = extractLinearToken(currentLine.slice(0, cursorCol));
+      if (token === undefined) {
+        return current.getSuggestions(lines, cursorLine, cursorCol, options);
+      }
+
+      const issues = await getIssues(options.signal);
+      if (options.signal.aborted || !issues?.length) {
+        return current.getSuggestions(lines, cursorLine, cursorCol, options);
+      }
+
+      const items = filterIssues(issues, token);
+      if (items.length === 0) {
+        return current.getSuggestions(lines, cursorLine, cursorCol, options);
+      }
+
+      return { items, prefix: `#${token}` };
+    },
+
+    shouldTriggerFileCompletion(lines, cursorLine, cursorCol) {
+      return (
+        current.shouldTriggerFileCompletion?.(lines, cursorLine, cursorCol) ??
+        true
+      );
+    },
+  };
+}
+
+export function registerLinearAutocomplete(pi: ExtensionAPI): void {
+  const client = new LinearClient();
+
+  pi.on("session_start", (_event, ctx) => {
+    if (!hasLinearCredentials()) return;
+
+    let issuesPromise: Promise<LinearIssueSummary[] | undefined> | undefined;
+    let loadErrorShown = false;
+
+    const getIssues = async (
+      signal: AbortSignal,
+    ): Promise<LinearIssueSummary[] | undefined> => {
+      issuesPromise ??= client
+        .searchIssues({ limit: MAX_PRELOADED_ISSUES }, signal)
+        .catch((error: unknown) => {
+          issuesPromise = undefined;
+          if (signal.aborted || isAbortError(error)) return undefined;
+
+          if (!loadErrorShown) {
+            loadErrorShown = true;
+            const message =
+              error instanceof Error ? error.message : String(error);
+            ctx.ui.notify(
+              `linear: failed to preload issue autocomplete: ${message}`,
+              "warning",
+            );
+          }
+          return undefined;
+        });
+      return issuesPromise;
+    };
+
+    ctx.ui.addAutocompleteProvider((current) =>
+      createLinearAutocompleteProvider(current, getIssues),
+    );
+  });
+}