Skip to content

Commit d7fba06

Browse files
benvinegarbenvinegar
authored
Package pi plugin for npm and add release workflow (#8)
1 parent 264e2c1 commit d7fba06

5 files changed

Lines changed: 191 additions & 19 deletions

File tree

‎.github/workflows/release-pi.yml‎

Lines changed: 73 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,73 @@
1+
name: Release pi package
2+
3+
on:
4+
push:
5+
tags:
6+
- 'pi-v*'
7+
workflow_dispatch:
8+
inputs:
9+
publish:
10+
description: Publish to npm (unchecked = dry run only)
11+
type: boolean
12+
required: false
13+
default: false
14+
15+
permissions:
16+
contents: read
17+
id-token: write
18+
19+
concurrency:
20+
group: release-pi
21+
cancel-in-progress: false
22+
23+
jobs:
24+
release:
25+
runs-on: ubuntu-latest
26+
27+
steps:
28+
- uses: actions/checkout@v4
29+
30+
- uses: actions/setup-node@v4
31+
with:
32+
node-version: 22
33+
registry-url: https://registry.npmjs.org
34+
35+
- name: Read package metadata
36+
id: pkg
37+
run: |
38+
echo "name=$(node -p \"require('./pi/package.json').name\")" >> "$GITHUB_OUTPUT"
39+
echo "version=$(node -p \"require('./pi/package.json').version\")" >> "$GITHUB_OUTPUT"
40+
41+
- name: Validate release tag matches package version
42+
if: github.event_name == 'push'
43+
run: |
44+
expected="pi-v${{ steps.pkg.outputs.version }}"
45+
if [ "${GITHUB_REF_NAME}" != "$expected" ]; then
46+
echo "::error title=Tag/version mismatch::Expected tag $expected for version ${{ steps.pkg.outputs.version }}, got ${GITHUB_REF_NAME}."
47+
exit 1
48+
fi
49+
50+
- name: Ensure npm version is not already published
51+
if: github.event_name == 'push' || (github.event_name == 'workflow_dispatch' && inputs.publish)
52+
run: |
53+
if npm view "${{ steps.pkg.outputs.name }}@${{ steps.pkg.outputs.version }}" version >/dev/null 2>&1; then
54+
echo "::error title=Version already published::${{ steps.pkg.outputs.name }}@${{ steps.pkg.outputs.version }} already exists on npm."
55+
exit 1
56+
fi
57+
58+
- name: Validate package contents
59+
working-directory: pi
60+
run: npm pack --dry-run
61+
62+
- name: Publish to npm
63+
if: github.event_name == 'push' || (github.event_name == 'workflow_dispatch' && inputs.publish)
64+
working-directory: pi
65+
run: npm publish --access public --provenance
66+
env:
67+
NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}
68+
69+
- name: Dry-run summary
70+
if: github.event_name == 'workflow_dispatch' && !inputs.publish
71+
run: |
72+
echo "Dry run complete for ${{ steps.pkg.outputs.name }}@${{ steps.pkg.outputs.version }}."
73+
echo "Re-run this workflow with publish=true to publish."

‎README.md‎

Lines changed: 16 additions & 10 deletions
Original file line numberDiff line numberDiff line change
@@ -10,31 +10,37 @@ Paste a screenshot in your browser, your agent gets the URL instantly.
1010

1111
## Available plugins
1212

13-
| Agent | Directory | Status |
14-
|---|---|---|
15-
| [pi](https://github.com/mariozechner/pi) | [`pi/`](pi/) | ✅ |
16-
| [OpenCode](https://github.com/anomalyco/opencode) | [`opencode/`](opencode/) | ✅ |
13+
| Agent | Directory | npm package | Install |
14+
|---|---|---|---|
15+
| [pi](https://github.com/mariozechner/pi) | [`pi/`](pi/) | `@modem-dev/glance-pi` | `pi install npm:@modem-dev/glance-pi` |
16+
| [OpenCode](https://github.com/anomalyco/opencode) | [`opencode/`](opencode/) | — | See [`opencode/README.md`](opencode/README.md) |
1717

1818
## How it works
1919

2020
Each plugin creates a live session on glance.sh, gives you a URL to open, and waits for you to paste an image. The image URL is returned to the agent over SSE — no manual copy-paste needed.
2121

22-
```
22+
```text
2323
agent ──POST /api/session──▶ { id, url }
2424
agent ──GET /api/session/<id>/events──▶ SSE (waiting…)
2525
user ──opens /s/<id>, pastes image──▶ agent receives URL
2626
```
2727

2828
Sessions are anonymous and ephemeral (10-minute TTL). Images expire after 30 minutes.
2929

30-
## Adding a new plugin
30+
## Packaging policy
31+
32+
New plugins should be published as installable packages (npm where possible) with a one-command install path in their README.
3133

32-
Create a directory for your agent (e.g. `cursor/`, `cline/`) with:
34+
Each plugin directory should include:
3335

34-
1. The integration code
35-
2. A `README.md` with install instructions
36+
1. Integration code
37+
2. `README.md` with install / verify / update / remove steps
38+
3. `package.json` (if the target agent supports package-based install)
39+
4. Release automation (GitHub Actions workflow + documented version/tag convention)
40+
41+
## Adding a new plugin
3642

37-
Open a PR.
43+
Create a directory for your agent (e.g. `cursor/`, `cline/`) with the files above and open a PR.
3844

3945
## License
4046

‎pi/README.md‎

Lines changed: 61 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -13,21 +13,75 @@ Maintains a **persistent background session** on glance.sh. Paste an image anyti
1313

1414
## Install
1515

16-
Symlink or copy `glance.ts` into your pi extensions directory:
16+
Recommended (npm package):
1717

1818
```bash
19-
# symlink (recommended — stays up to date with git pulls)
20-
ln -s "$(pwd)/glance.ts" ~/.pi/extensions/glance.ts
19+
pi install npm:@modem-dev/glance-pi
20+
```
21+
22+
If you are working from a local checkout instead:
23+
24+
```bash
25+
# from this directory (agent-plugins/pi)
26+
pi install .
2127

22-
# or copy
23-
cp glance.ts ~/.pi/extensions/glance.ts
28+
# from the main repo root
29+
pi install ./agent-plugins/pi
2430
```
2531

26-
Restart pi. The background session starts automatically.
32+
Then restart pi or run `/reload`.
2733

28-
## How it works
34+
## Verify
35+
36+
Run:
37+
38+
```text
39+
/glance
40+
```
41+
42+
You should see a session URL like `https://glance.sh/s/<id>`.
43+
44+
## Update / remove
45+
46+
```bash
47+
pi update
48+
pi remove npm:@modem-dev/glance-pi
49+
```
50+
51+
For a local path install, remove that path from your pi settings (or run `pi remove` with the same path you installed).
2952

53+
## Publishing (maintainers)
54+
55+
Releases are automated via GitHub Actions.
56+
57+
Prerequisite: configure `NPM_TOKEN` in the `glance-agent-plugins` repository with publish access to `@modem-dev/glance-pi`.
58+
59+
1. Bump `version` in `pi/package.json`.
60+
2. Commit and push to `main`.
61+
3. Create and push a matching tag:
62+
63+
```bash
64+
git tag pi-v0.1.0
65+
git push origin pi-v0.1.0
66+
```
67+
68+
The `Release pi package` workflow validates the tag/version match and publishes with npm provenance.
69+
You can also run the workflow manually in dry-run mode from Actions.
70+
71+
## Manual install (legacy)
72+
73+
If you prefer manual file management, symlink or copy `glance.ts` into your pi extensions directory:
74+
75+
```bash
76+
mkdir -p ~/.pi/agent/extensions
77+
ln -s "$(pwd)/glance.ts" ~/.pi/agent/extensions/glance.ts
78+
# or:
79+
cp glance.ts ~/.pi/agent/extensions/glance.ts
3080
```
81+
82+
## How it works
83+
84+
```text
3185
pi starts
3286
└─▶ create session on glance.sh
3387
└─▶ connect SSE (background, auto-reconnect)

‎pi/glance.ts‎

Lines changed: 4 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -10,8 +10,10 @@
1010
* - `glance` tool — the LLM can call it to request a screenshot;
1111
* it surfaces the existing session URL and waits for a paste.
1212
*
13-
* Install: symlink or copy this file into your pi extensions directory,
14-
* e.g. ~/.pi/extensions/glance.ts
13+
* Install:
14+
* - Recommended: `pi install npm:@modem-dev/glance-pi`
15+
* - Local checkout: `pi install /path/to/glance-agent-plugins/pi`
16+
* - Manual fallback: symlink/copy into ~/.pi/agent/extensions/glance.ts
1517
*/
1618

1719
import { Type } from "@mariozechner/pi-ai";

‎pi/package.json‎

Lines changed: 37 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,37 @@
1+
{
2+
"name": "@modem-dev/glance-pi",
3+
"version": "0.1.0",
4+
"description": "glance.sh extension package for pi",
5+
"license": "MIT",
6+
"repository": {
7+
"type": "git",
8+
"url": "git+https://github.com/modem-dev/glance-agent-plugins.git",
9+
"directory": "pi"
10+
},
11+
"homepage": "https://github.com/modem-dev/glance-agent-plugins/tree/main/pi",
12+
"bugs": {
13+
"url": "https://github.com/modem-dev/glance-agent-plugins/issues"
14+
},
15+
"keywords": [
16+
"pi-package",
17+
"pi-extension",
18+
"pi",
19+
"glance",
20+
"screenshot",
21+
"agent"
22+
],
23+
"files": [
24+
"glance.ts",
25+
"README.md"
26+
],
27+
"pi": {
28+
"extensions": [
29+
"./glance.ts"
30+
]
31+
},
32+
"peerDependencies": {
33+
"@mariozechner/pi-ai": "*",
34+
"@mariozechner/pi-coding-agent": "*",
35+
"@mariozechner/pi-tui": "*"
36+
}
37+
}

0 commit comments

Comments
 (0)