@fink-andreas/pi-linear-tools 0.4.2 → 0.4.3

package/CHANGELOG.md

@@ -1,5 +1,21 @@
 # Changelog
 
+## v0.4.3 (2026-04-02)
+
+Sync-doc parity and tool prompt metadata polish release.
+
+### Bug Fixes
+- Fixed first-run `sync-doc` batch parity so `check` and `run` produce aligned project index planning
+- Preserved existing managed marker location when `position` is `top`
+- Resolved archived projects more reliably during project update flows
+
+### Improvements
+- Added `promptSnippet` metadata consistently across all Linear tools for better in-app tool discoverability/context
+- Added default activity limit handling for issue activity execution paths
+
+### Tests
+- Added/updated sync-doc regression coverage for first-run check/run parity and marker placement stability
+
 ## v0.4.2 (2026-03-26)
 
 Rate-limit resilience and API usage diagnostics release.

package/README.md

@@ -2,6 +2,20 @@
 
 `pi-linear-tools` is a Pi extension for the [Pi coding agent](https://github.com/badlogic/pi-mono) that lets you manage [Linear](https://linear.app/about) issues, projects, and milestones via LLM tools and CLI commands.
 
+Useful mental model:
+- `issue update` changes issue fields; `issue comment` adds discussion; `issue activity` reads the Activity timeline
+- `project update` changes project fields; `project-update` manages Updates tab entries
+- `project-update` maps to Linear project updates in the Updates tab
+- `sync-doc init` scaffolds `.linear-tools/config.json` in the folder you point at
+- `sync-doc run` and `sync-doc check` default to all configured targets in `.linear-tools/config.json`
+- `sync-doc --target X` narrows the operation to one configured target
+
+Reference conventions:
+- issues use issue key or issue ID
+- projects use project name or project ID
+- project updates use project update ID
+- milestones use milestone ID
+
 ## Install
 
 ### As a pi package (recommended)
@@ -43,10 +57,13 @@ Optional non-interactive commands:
 ## LLM-callable tools
 
 ### `linear_issue`
-Actions: `list`, `view`, `create`, `update`, `comment`, `start`, `delete`
+Actions: `list`, `view`, `activity`, `create`, `update`, `comment`, `start`, `delete`
 
 ### `linear_project`
-Actions: `list`
+Actions: `list`, `view`, `create`, `update`, `delete`, `archive`, `unarchive`
+
+### `linear_project_update`
+Actions: `list`, `view`, `create`, `update`, `archive`, `unarchive`
 
 ### `linear_milestone`
 Actions: `list`, `view`, `create`, `update`, `delete`
@@ -57,6 +74,12 @@ If installed globally via ```npm install -g @fink-andreas/pi-linear-tools```, CL
 
 ```bash
 pi-linear-tools --help
+pi-linear-tools issue --help
+pi-linear-tools project --help
+pi-linear-tools project-update --help
+pi-linear-tools sync-doc --help
+pi-linear-tools sync-doc init --cwd /path/to/subproject --project "Project name or ID"
+pi-linear-tools sync-doc explain
 pi-linear-tools config
 pi-linear-tools config --api-key lin_xxx
 pi-linear-tools config --default-team ENG
@@ -65,6 +88,8 @@ pi-linear-tools config --team ENG --project "My Project"
 
 ### Issue commands
 
+Use `update` to change the issue itself. Use `comment` to add discussion. Use `activity` to read the Activity timeline shown in Linear.
+
 ```bash
 # List issues
 pi-linear-tools issue list --project "My Project"
@@ -75,6 +100,10 @@ pi-linear-tools issue list --project "My Project" --assignee me
 pi-linear-tools issue view ENG-123
 pi-linear-tools issue view ENG-123 --no-comments
 
+# Read Activity timeline
+pi-linear-tools issue activity ENG-123 --limit 20
+pi-linear-tools issue activity https://linear.app/workspace/issue/ENG-123/example --limit 20
+
 # Create issue
 pi-linear-tools issue create --title "Fix login bug" --team ENG
 pi-linear-tools issue create --title "New feature" --team ENG --project "My Project" --priority 2 --assignee me
@@ -83,13 +112,15 @@ pi-linear-tools issue create --title "New feature" --team ENG --project "My Proj
 pi-linear-tools issue update ENG-123 --state "In Progress"
 pi-linear-tools issue update ENG-123 --title "Updated title" --assignee me
 pi-linear-tools issue update ENG-123 --milestone "Sprint 1"
+pi-linear-tools issue update ENG-123 --sub-issue-of ENG-100
 
 # Comment on issue
 pi-linear-tools issue comment ENG-123 --body "This is fixed in PR #456"
+pi-linear-tools issue comment ENG-123 --body "Blocked on API review"
 
 # Start working on issue (creates branch, sets state to In Progress)
 pi-linear-tools issue start ENG-123
-pi-linear-tools issue start ENG-123 --branch custom-branch-name
+pi-linear-tools issue start ENG-123 --from-ref main --on-branch-exists suffix
 
 # Delete issue
 pi-linear-tools issue delete ENG-123
@@ -97,10 +128,107 @@ pi-linear-tools issue delete ENG-123
 
 ### Project commands
 
+Use `project update` to change the project record itself: name, teams, dates, lead, description, priority, color, or icon.
+
 ```bash
 pi-linear-tools project list
+pi-linear-tools project view "My Project"
+pi-linear-tools project create --name "Roadmap Refresh" --teams ENG,OPS --lead me
+pi-linear-tools project update "Roadmap Refresh" --description "Updated scope" --target-date 2026-06-30
+pi-linear-tools project update "Roadmap Refresh" --lead me --teams ENG,OPS
+pi-linear-tools project delete "Roadmap Refresh"
+pi-linear-tools project archive "Roadmap Refresh"
+pi-linear-tools project unarchive 11111111-1111-4111-8111-111111111111
 ```
 
+### Project update commands
+
+This maps to the Updates tab inside a Linear project. Create an update by project name or ID, then use the returned project update ID for later view, update, archive, or unarchive actions.
+
+```bash
+pi-linear-tools project-update list --project "My Project"
+pi-linear-tools project-update view 22222222-2222-4222-8222-222222222222
+pi-linear-tools project-update create --project "My Project" --body "Weekly progress update" --health onTrack
+pi-linear-tools project-update update 22222222-2222-4222-8222-222222222222 --body "Revised update" --health atRisk
+pi-linear-tools project-update archive 22222222-2222-4222-8222-222222222222
+pi-linear-tools project-update unarchive 22222222-2222-4222-8222-222222222222
+```
+
+### Sync doc commands
+
+```bash
+pi-linear-tools sync-doc init --cwd /path/to/subproject --project "Project name or ID"
+pi-linear-tools sync-doc explain
+pi-linear-tools sync-doc list
+pi-linear-tools sync-doc run
+pi-linear-tools sync-doc check
+pi-linear-tools sync-doc run --target project-overview
+pi-linear-tools sync-doc check --target project-overview
+pi-linear-tools sync-doc run --file README.md --project "Project name or ID" --field content
+pi-linear-tools sync-doc run --file docs/provider.md --project "Project name or ID" --target-type document --document-title "Provider Doc"
+```
+
+Use one project overview target for the project body, then sync deeper docs as separate Linear documents.
+
+Use `pi-linear-tools sync-doc init --cwd /path/to/subproject --project "Project name or ID"` to scaffold a starter config.
+
+Placement rule:
+- put `.linear-tools/config.json` in the smallest folder that owns the docs you are syncing
+- the CLI resolves the nearest `.linear-tools/config.json` upward from the current directory
+- use repo root only for targets intentionally shared across multiple subprojects
+- `~/.linear-tools/config.json` is supported for personal defaults, but it should be treated as an override layer, not the main source of truth for repo-owned sync targets
+
+Recommended pattern for multiple docs:
+- one `projectField` target syncs the project overview into `project.content` or `project.description`
+- deeper docs use `targetType: "document"` so each file gets its own Linear document
+- the project overview target can set `documentIndexMarker` to maintain a managed list of links to those documents
+
+For repos with multiple sync targets, the normal workflow is:
+- define them in the repo-root `.linear-tools/config.json`
+- run `pi-linear-tools sync-doc run` to push everything
+- run `pi-linear-tools sync-doc check` in CI or before updates if you want drift visibility
+
+Example:
+
+```json
+{
+  "syncDocs": {
+    "targets": [
+      {
+        "name": "project-overview",
+        "file": "README.md",
+        "project": "Project name or ID",
+        "field": "content",
+        "marker": "project-overview",
+        "documentIndexMarker": "project-doc-links"
+      },
+      {
+        "name": "provider-foo",
+        "targetType": "document",
+        "file": "docs/provider.md",
+        "project": "Project name or ID",
+        "title": "Provider Doc",
+        "marker": "provider-foo",
+        "documentId": "optional-existing-document-id"
+      }
+    ]
+  }
+}
+```
+
+Store that config at `.linear-tools/config.json`. Sync state is written to `.linear-tools/sync-state.json`.
+If `documentId` is omitted on a document target, the first sync creates a new Linear document and stores the created ID in sync state.
+
+Managed content is wrapped in marker comments inside the target Linear field so manual content above or below the managed block is preserved:
+
+```md
+<!-- linear-tools:sync-start README -->
+...synced markdown...
+<!-- linear-tools:sync-end README -->
+```
+
+When `documentIndexMarker` is configured on the overview target, the project field also gets a second managed block containing links to the synced Linear documents.
+
 ### Team commands
 
 ```bash

package/extensions/pi-linear-tools.js

@@ -48,12 +48,25 @@ try {
 import {
   executeIssueList,
   executeIssueView,
+  executeIssueActivity,
   executeIssueCreate,
   executeIssueUpdate,
   executeIssueComment,
   executeIssueStart,
   executeIssueDelete,
   executeProjectList,
+  executeProjectView,
+  executeProjectCreate,
+  executeProjectUpdate,
+  executeProjectDelete,
+  executeProjectArchive,
+  executeProjectUnarchive,
+  executeProjectUpdateList,
+  executeProjectUpdateView,
+  executeProjectUpdateCreate,
+  executeProjectUpdateUpdate,
+  executeProjectUpdateArchive,
+  executeProjectUpdateUnarchive,
   executeTeamList,
   executeMilestoneList,
   executeMilestoneView,
@@ -478,18 +491,19 @@ async function registerLinearTools(pi) {
   pi.registerTool({
     name: 'linear_issue',
     label: 'Linear Issue',
-    description: 'Interact with Linear issues. Actions: list, view, create, update, comment, start, delete',
+    description: 'Interact with Linear issues. Actions: list, view, activity, create, update, comment, start, delete',
+    promptSnippet: 'Interact with Linear issues (list, view, activity, create, update, comment, start, delete)',
     parameters: {
       type: 'object',
       properties: {
         action: {
           type: 'string',
-          enum: ['list', 'view', 'create', 'update', 'comment', 'start', 'delete'],
+          enum: ['list', 'view', 'activity', '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)',
+          description: 'Issue key (ABC-123) or Linear issue ID (for view, activity, update, comment, start, delete)',
         },
         project: {
           type: 'string',
@@ -509,8 +523,8 @@ async function registerLinearTools(pi) {
           description: 'Optional explicit assignee ID alias for update/create debugging/compatibility.',
         },
         limit: {
-          type: 'number',
-          description: 'Maximum number of issues to list (default: 50)',
+          type: 'integer',
+          description: 'Maximum number of issues or activity entries to list',
         },
         includeComments: {
           type: 'boolean',
@@ -525,9 +539,13 @@ async function registerLinearTools(pi) {
           description: 'Issue description in markdown (for create, update)',
         },
         priority: {
-          type: 'number',
+          type: 'integer',
           description: 'Priority 0..4 (for create, update)',
         },
+        includeArchived: {
+          type: 'boolean',
+          description: 'Include archived resources when listing activity or project updates',
+        },
         state: {
           type: 'string',
           description: 'Target state name or ID (for create, update)',
@@ -618,6 +636,8 @@ async function registerLinearTools(pi) {
               return await executeIssueList(client, params);
             case 'view':
               return await executeIssueView(client, params);
+            case 'activity':
+              return await executeIssueActivity(client, params);
             case 'create':
               return await executeIssueCreate(client, params, { resolveDefaultTeam });
             case 'update':
@@ -692,15 +712,59 @@ async function registerLinearTools(pi) {
   pi.registerTool({
     name: 'linear_project',
     label: 'Linear Project',
-    description: 'Interact with Linear projects. Actions: list',
+    description: 'Interact with Linear projects. Actions: list, view, create, update, delete, archive, unarchive',
+    promptSnippet: 'Interact with Linear projects (list, view, create, update, delete, archive, unarchive)',
     parameters: {
       type: 'object',
       properties: {
         action: {
           type: 'string',
-          enum: ['list'],
+          enum: ['list', 'view', 'create', 'update', 'delete', 'archive', 'unarchive'],
           description: 'Action to perform on project(s)',
         },
+        project: {
+          type: 'string',
+          description: 'Project name or ID (for view, update, delete)',
+        },
+        name: {
+          type: 'string',
+          description: 'Project name (required for create, optional for update)',
+        },
+        teams: {
+          type: 'string',
+          description: 'Comma-separated team keys or IDs (required for create, optional for update)',
+        },
+        description: {
+          type: 'string',
+          description: 'Project description in markdown',
+        },
+        lead: {
+          type: 'string',
+          description: 'Project lead user ID, "me", or "none" when updating',
+        },
+        priority: {
+          type: 'integer',
+          description: 'Priority 0-4',
+          minimum: 0,
+          maximum: 4,
+          multipleOf: 1,
+        },
+        color: {
+          type: 'string',
+          description: 'Project color (hex)',
+        },
+        icon: {
+          type: 'string',
+          description: 'Project icon',
+        },
+        startDate: {
+          type: 'string',
+          description: 'Planned start date (YYYY-MM-DD)',
+        },
+        targetDate: {
+          type: 'string',
+          description: 'Planned target date (YYYY-MM-DD)',
+        },
       },
       required: ['action'],
       additionalProperties: false,
@@ -714,6 +778,18 @@ async function registerLinearTools(pi) {
           switch (params.action) {
             case 'list':
               return await executeProjectList(client);
+            case 'view':
+              return await executeProjectView(client, params);
+            case 'create':
+              return await executeProjectCreate(client, params);
+            case 'update':
+              return await executeProjectUpdate(client, params);
+            case 'delete':
+              return await executeProjectDelete(client, params);
+            case 'archive':
+              return await executeProjectArchive(client, params);
+            case 'unarchive':
+              return await executeProjectUnarchive(client, params);
             default:
               throw new Error(`Unknown action: ${params.action}`);
           }
@@ -739,10 +815,102 @@ async function registerLinearTools(pi) {
     },
   });
 
+  pi.registerTool({
+    name: 'linear_project_update',
+    label: 'Linear Project Update',
+    description: 'Interact with Linear project updates. Actions: list, view, create, update, archive, unarchive',
+    promptSnippet: 'Interact with Linear project updates (list, view, create, update, archive, unarchive)',
+    parameters: {
+      type: 'object',
+      properties: {
+        action: {
+          type: 'string',
+          enum: ['list', 'view', 'create', 'update', 'archive', 'unarchive'],
+          description: 'Action to perform on project update(s)',
+        },
+        project: {
+          type: 'string',
+          description: 'Project name or ID (for list, create)',
+        },
+        projectUpdate: {
+          type: 'string',
+          description: 'Project update ID (for view, update, archive, unarchive)',
+        },
+        body: {
+          type: 'string',
+          description: 'Project update body in markdown',
+        },
+        health: {
+          type: 'string',
+          description: 'Project update health: onTrack, atRisk, or offTrack',
+          enum: ['onTrack', 'atRisk', 'offTrack'],
+        },
+        isDiffHidden: {
+          type: 'boolean',
+          description: 'Whether to hide the diff on the update',
+        },
+        limit: {
+          type: 'integer',
+          description: 'Max updates to list',
+          minimum: 1,
+          multipleOf: 1,
+        },
+        includeArchived: {
+          type: 'boolean',
+          description: 'Whether archived updates should be included when listing',
+        },
+      },
+      required: ['action'],
+      additionalProperties: false,
+    },
+    renderResult: renderMarkdownResult,
+    async execute(_toolCallId, params) {
+      try {
+        const client = await createAuthenticatedClient();
+
+        return await withRequestUsageLogging(client, 'linear_project_update', params.action, async () => {
+          switch (params.action) {
+            case 'list':
+              return await executeProjectUpdateList(client, params);
+            case 'view':
+              return await executeProjectUpdateView(client, params);
+            case 'create':
+              return await executeProjectUpdateCreate(client, params);
+            case 'update':
+              return await executeProjectUpdateUpdate(client, params);
+            case 'archive':
+              return await executeProjectUpdateArchive(client, params);
+            case 'unarchive':
+              return await executeProjectUpdateUnarchive(client, params);
+            default:
+              throw new Error(`Unknown action: ${params.action}`);
+          }
+        });
+      } catch (error) {
+        const errorType = error?.type || '';
+        const errorMessage = String(error?.message || error || 'Unknown error');
+
+        if (errorType === 'Ratelimited' || errorMessage.toLowerCase().includes('rate limit')) {
+          const resetAt = error?.requestsResetAt
+            ? new Date(error.requestsResetAt).toLocaleTimeString()
+            : 'approximately 1 hour from now';
+          throw new Error(`Linear API rate limit exceeded. Resets at: ${resetAt}. Please wait before retrying.`);
+        }
+
+        if (errorMessage.includes('Linear API error:')) {
+          throw error;
+        }
+
+        throw new Error(`Linear project update operation failed: ${errorMessage}`);
+      }
+    },
+  });
+
   pi.registerTool({
     name: 'linear_team',
     label: 'Linear Team',
     description: 'Interact with Linear teams. Actions: list',
+    promptSnippet: 'Interact with Linear teams (list)',
     parameters: {
       type: 'object',
       properties: {
@@ -794,6 +962,7 @@ async function registerLinearTools(pi) {
       name: 'linear_milestone',
       label: 'Linear Milestone',
       description: 'Interact with Linear project milestones. Actions: list, view, create, update, delete',
+      promptSnippet: 'Interact with Linear milestones (list, view, create, update, delete)',
       parameters: {
         type: 'object',
         properties: {
@@ -983,8 +1152,9 @@ export default async function piLinearToolsExtension(pi) {
       const showMilestoneTool = await shouldExposeMilestoneTool();
       const toolLines = [
         'LLM-callable tools:',
-        '  linear_issue (list/view/create/update/comment/start/delete)',
-        '  linear_project (list)',
+        '  linear_issue (list/view/activity/create/update/comment/start/delete)',
+        '  linear_project (list/view/create/update/delete/archive/unarchive)',
+        '  linear_project_update (list/view/create/update/archive/unarchive)',
         '  linear_team (list)',
       ];