@fink-andreas/pi-linear-tools 0.1.0

package/CHANGELOG.md

@@ -0,0 +1,16 @@
+# Changelog
+
+## v0.1.0 (planned)
+
+Initial public release of `@fink-andreas/pi-linear-tools`.
+
+### Included
+- Linear issue/project/team/milestone tools for pi
+- Extension commands for configuration/help
+- Local CLI for settings and tool operations
+- Project/team/milestone and assignee handling improvements covered by test suite
+
+### Notes
+- npm package: `@fink-andreas/pi-linear-tools`
+- Planned git tag: `v0.1.0`
+- GitHub release notes source: `RELEASE_NOTES_v0.1.0.md`

package/FUNCTIONALITY.md

@@ -0,0 +1,57 @@
+# pi-linear-tools Functionality
+
+## Scope
+
+`pi-linear-tools` provides Linear SDK functionality as a pi extension package.
+
+Included:
+- extension configuration command (`/linear-tools-config`)
+- issue/project/milestone tools powered by `@linear/sdk`
+- issue start flow with optional git branch creation/switch
+- settings persistence for API key/default team/project team mapping
+
+Excluded:
+- daemon runtime
+- polling loop
+- systemd service installation/control
+- tmux/process session management
+- RPC process lifecycle management
+
+## Core modules
+
+- `src/linear-client.js`: Linear SDK client factory
+- `src/linear.js`: issue/project/milestone operations and formatting helpers
+- `src/settings.js`: settings defaults/validation/load/save
+- `src/logger.js`: structured logging
+- `extensions/pi-linear-tools.js`: command and tool registration
+- `src/cli.js`: optional local CLI for settings operations
+
+## Tool behavior notes
+
+- `LINEAR_API_KEY` is resolved from env first, then settings
+- project references may be project name or project ID
+- issue references may be identifier (`ABC-123`) or Linear issue ID
+- default team resolution order for issue creation:
+  1. explicit `team` parameter
+  2. project-level configured team
+  3. global `defaultTeam`
+- `linear_issue` `start` action:
+  - uses Linear branch name if available
+  - can create/switch git branch via `pi.exec("git", ...)`
+
+## Settings schema
+
+```json
+{
+  "schemaVersion": 1,
+  "linearApiKey": null,
+  "defaultTeam": null,
+  "projects": {
+    "<linear-project-id>": {
+      "scope": {
+        "team": "ENG"
+      }
+    }
+  }
+}
+```

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Andreas Fink
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/POST_RELEASE_CHECKLIST.md

@@ -0,0 +1,30 @@
+# Post-release verification checklist
+
+## Registry and install checks
+
+```bash
+npm view @fink-andreas/pi-linear-tools version
+npm install -g @fink-andreas/pi-linear-tools
+pi-linear-tools --help
+```
+
+## pi package route smoke test
+
+```bash
+pi install git:github.com/fink-andreas/pi-linear-tools
+# then enable extension resource and run
+/linear-tools-help
+```
+
+## Basic command smoke test
+
+```bash
+pi-linear-tools project list
+pi-linear-tools team list
+```
+
+## Closeout
+
+- Capture any regressions as follow-up Linear issues
+- Post release summary to INN-234
+- Mark milestone complete

package/README.md

@@ -0,0 +1,157 @@
+# pi-linear-tools
+
+`pi-linear-tools` is a **Pi extension package** for the [Pi coding agent](https://github.com/badlogic/pi-mono), with Linear SDK-powered tools for issues, projects, and milestones.
+
+## Install
+
+### As a pi package (recommended)
+```bash
+pi install git:github.com/fink-andreas/pi-linear-tools
+pi config
+```
+Enable the `pi-linear-tools` extension resource.
+
+### As an npm package
+```bash
+npm install -g @fink-andreas/pi-linear-tools
+```
+
+## Initial configuration
+
+After installation, run `/linear-tools-config` in pi.
+
+When used **without parameters**, it starts the interactive setup flow and guides you through:
+- authentication (API key)
+- workspace selection
+- default team selection
+
+```text
+/linear-tools-config
+```
+
+Optional non-interactive commands:
+```text
+/linear-tools-config --api-key lin_xxx
+/linear-tools-config --default-team ENG
+/linear-tools-config --team ENG --project "My Project"
+```
+
+## Extension commands
+
+- `/linear-tools-config`
+- `/linear-tools-help`
+
+## LLM-callable tools
+
+### `linear_issue`
+Actions: `list`, `view`, `create`, `update`, `comment`, `start`, `delete`
+
+### `linear_project`
+Actions: `list`
+
+### `linear_milestone`
+Actions: `list`, `view`, `create`, `update`, `delete`
+
+## CLI usage
+
+If installed globally via npm, you can run:
+
+```bash
+npm install -g @fink-andreas/pi-linear-tools
+pi-linear-tools --help
+pi-linear-tools config
+pi-linear-tools config --api-key lin_xxx
+pi-linear-tools config --default-team ENG
+pi-linear-tools config --team ENG --project "My Project"
+```
+
+If `pi-linear-tools` is not found, run it from the repo:
+
+```bash
+node bin/pi-linear-tools.js --help
+```
+
+### Issue commands
+
+```bash
+# List issues
+pi-linear-tools issue list --project "My Project"
+pi-linear-tools issue list --project "My Project" --states "In Progress,Backlog"
+pi-linear-tools issue list --project "My Project" --assignee me
+
+# View issue details
+pi-linear-tools issue view ENG-123
+pi-linear-tools issue view ENG-123 --no-comments
+
+# 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
+
+# Update issue
+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"
+
+# Comment on issue
+pi-linear-tools issue comment ENG-123 --body "This is fixed in PR #456"
+
+# 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
+
+# Delete issue
+pi-linear-tools issue delete ENG-123
+```
+
+### Project commands
+
+```bash
+pi-linear-tools project list
+```
+
+### Team commands
+
+```bash
+pi-linear-tools team list
+```
+
+### Milestone commands
+
+```bash
+# List milestones
+pi-linear-tools milestone list --project "My Project"
+
+# View milestone details
+pi-linear-tools milestone view <milestone-id>
+
+# Create milestone
+pi-linear-tools milestone create --project "My Project" --name "v1.0 Release"
+pi-linear-tools milestone create --project "My Project" --name "Sprint 1" --target-date 2024-12-31 --status planned
+
+# Update milestone
+pi-linear-tools milestone update <milestone-id> --status inProgress
+
+# Delete milestone
+pi-linear-tools milestone delete <milestone-id>
+```
+
+## Configuration storage
+
+Settings path:
+
+`~/.pi/agent/extensions/pi-linear-tools/settings.json`
+
+Environment fallback:
+- `LINEAR_API_KEY` (takes precedence over settings)
+
+## Development
+
+```bash
+npm install
+npm test
+npm run release:check
+node index.js --help
+```
+
+Release checklist: see `RELEASE.md`.
+Post-release verification checklist: see `POST_RELEASE_CHECKLIST.md`.

package/RELEASE.md

@@ -0,0 +1,50 @@
+# Release Runbook
+
+## npm publish (`v0.1.0`)
+
+1. Ensure clean working tree
+   ```bash
+   git status
+   ```
+2. Run pre-publish checks
+   ```bash
+   npm run release:check
+   ```
+3. Verify npm authentication
+   ```bash
+   npm whoami
+   ```
+4. Publish package
+   ```bash
+   npm publish --access public
+   ```
+5. Verify published version
+   ```bash
+   npm view @fink-andreas/pi-linear-tools version
+   ```
+
+## Post-publish quick validation
+
+```bash
+npm install -g @fink-andreas/pi-linear-tools
+pi-linear-tools --help
+```
+
+## GitHub release
+
+```bash
+git tag v0.1.0
+git push origin v0.1.0
+```
+
+Create release notes from `RELEASE_NOTES_v0.1.0.md`:
+
+```bash
+gh release create v0.1.0 --title "v0.1.0" --notes-file RELEASE_NOTES_v0.1.0.md
+```
+
+Verify release:
+
+```bash
+gh release view v0.1.0
+```

package/bin/pi-linear-tools.js

@@ -0,0 +1,8 @@
+#!/usr/bin/env node
+
+import { runCli } from '../src/cli.js';
+
+runCli().catch((error) => {
+  console.error('pi-linear-tools CLI error:', error?.message || error);
+  process.exit(1);
+});