pi-spotify-widget 0.1.0 → 0.1.8
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/CHANGELOG.md +69 -19
- package/README.md +35 -12
- package/docs/examples.md +22 -23
- package/docs/release.md +26 -5
- package/package.json +63 -62
- package/docs/github-template.md +0 -43
- package/docs/repository-settings.md +0 -41
- package/docs/template-checklist.md +0 -85
- package/docs/typescript.md +0 -75
package/CHANGELOG.md
CHANGED
|
@@ -1,19 +1,69 @@
|
|
|
1
|
-
# Changelog
|
|
2
|
-
|
|
3
|
-
|
|
4
|
-
|
|
5
|
-
|
|
6
|
-
|
|
7
|
-
|
|
8
|
-
|
|
9
|
-
|
|
10
|
-
|
|
11
|
-
|
|
12
|
-
|
|
13
|
-
-
|
|
14
|
-
|
|
15
|
-
|
|
16
|
-
|
|
17
|
-
|
|
18
|
-
|
|
19
|
-
-
|
|
1
|
+
# Changelog
|
|
2
|
+
|
|
3
|
+
## Unreleased
|
|
4
|
+
|
|
5
|
+
### Changed
|
|
6
|
+
|
|
7
|
+
- Bump package version to `0.1.8` for the next patch release.
|
|
8
|
+
|
|
9
|
+
## [0.1.7] - 2026-07-04
|
|
10
|
+
|
|
11
|
+
### Fixed
|
|
12
|
+
|
|
13
|
+
- Move the npm publish workflow to Node 24, print runtime versions for diagnosis, and publish with `--provenance --access public` so npm Trusted Publishing has a fully compatible environment.
|
|
14
|
+
|
|
15
|
+
## [0.1.6] - 2026-07-04
|
|
16
|
+
|
|
17
|
+
### Fixed
|
|
18
|
+
|
|
19
|
+
- Trigger a fresh release after npm Trusted Publishing was reconfigured so the hardened publish workflow can publish the package successfully.
|
|
20
|
+
|
|
21
|
+
## [0.1.5] - 2026-07-04
|
|
22
|
+
|
|
23
|
+
### Fixed
|
|
24
|
+
|
|
25
|
+
- Harden npm publish workflow: support release-trigger fallback, skip already-published versions, publish with explicit public access, and print a direct Trusted Publishing hint on npm 404 failures.
|
|
26
|
+
- Clarify release docs and contributor release steps around `npm version patch --no-git-tag-version` and Trusted Publishing troubleshooting.
|
|
27
|
+
|
|
28
|
+
## [0.1.4] - 2026-07-04
|
|
29
|
+
|
|
30
|
+
### Changed
|
|
31
|
+
|
|
32
|
+
- Add Buy Me a Coffee sponsor button to README and native GitHub funding link via `.github/FUNDING.yml`.
|
|
33
|
+
|
|
34
|
+
All notable changes to this project will be documented in this file.
|
|
35
|
+
|
|
36
|
+
This project follows semantic versioning.
|
|
37
|
+
|
|
38
|
+
## [0.1.3] - 2026-06-27
|
|
39
|
+
|
|
40
|
+
### Changed
|
|
41
|
+
|
|
42
|
+
- README aligned with the current Pi OSS template baseline: expanded install paths (project-local, version pin, `pi -e npm:`), accurate package contents (`skills/`), and explicit `npm run ci` / `npm pack --dry-run` guidance in Development and Release.
|
|
43
|
+
|
|
44
|
+
## [0.1.2] - 2026-06-06
|
|
45
|
+
|
|
46
|
+
### Fixed
|
|
47
|
+
|
|
48
|
+
- Auto-release workflow was added in 0.1.1 but version never changed in that commit, preventing npm publish. This release bumps the version so auto-release triggers and publishes to npm.
|
|
49
|
+
|
|
50
|
+
## [0.1.1] - 2026-06-05
|
|
51
|
+
|
|
52
|
+
### Changed
|
|
53
|
+
|
|
54
|
+
- Removed template-maintenance docs (`github-template.md`, `repository-settings.md`, `typescript.md`) from the published package.
|
|
55
|
+
- Updated README doc links to match remaining docs.
|
|
56
|
+
|
|
57
|
+
## [0.1.0] - 2026-06-03
|
|
58
|
+
|
|
59
|
+
### Added
|
|
60
|
+
|
|
61
|
+
- Now Playing widget in Pi prompt editor (track, artist, playing/paused, progress seek bar).
|
|
62
|
+
- OAuth 2.0 + PKCE login via `/spotify:login` with localhost callback on port 8888.
|
|
63
|
+
- Interactive Client ID setup (Dashboard opens in browser; optional `PI_SPOTIFY_CLIENT_ID` env override).
|
|
64
|
+
- Secret-safe `/spotify:status`, `/spotify:logout`, and `/spotify:refresh`.
|
|
65
|
+
- Playback controls (`/spotify:prev`, `/spotify:next`, `/spotify:pause`, `/spotify:play`) and `/spotify:play-uri`.
|
|
66
|
+
- `/spotify:share` for X compose (intent URL; optional API credentials via env).
|
|
67
|
+
- `spotify-playback` Agent Skill for playback and share workflows.
|
|
68
|
+
- Token refresh lifecycle and adaptive polling with stale snapshot fallback.
|
|
69
|
+
- CI workflow and npm Trusted Publishing setup.
|
package/README.md
CHANGED
|
@@ -7,6 +7,7 @@
|
|
|
7
7
|
[](LICENSE)
|
|
8
8
|
[](https://pi.dev/packages)
|
|
9
9
|
[](docs/release.md)
|
|
10
|
+
<a href="https://buymeacoffee.com/ekawano114m"><img src="https://cdn.buymeacoffee.com/buttons/v2/default-yellow.png" alt="Buy Me A Coffee" width="217" height="60"></a>
|
|
10
11
|
|
|
11
12
|
> Show Spotify playback status in Pi's prompt editor widget.
|
|
12
13
|
|
|
@@ -26,16 +27,36 @@ TypeScript-first Pi package that displays **Now Playing** (track, artist, playin
|
|
|
26
27
|
|
|
27
28
|
## Install
|
|
28
29
|
|
|
30
|
+
Install the published npm package with Pi:
|
|
31
|
+
|
|
29
32
|
```bash
|
|
30
33
|
pi install npm:pi-spotify-widget
|
|
31
34
|
```
|
|
32
35
|
|
|
36
|
+
Pin a specific version when you want reproducible installs:
|
|
37
|
+
|
|
38
|
+
```bash
|
|
39
|
+
pi install npm:pi-spotify-widget@0.1.3
|
|
40
|
+
```
|
|
41
|
+
|
|
42
|
+
Install into the current project instead of your user Pi settings:
|
|
43
|
+
|
|
44
|
+
```bash
|
|
45
|
+
pi install npm:pi-spotify-widget -l
|
|
46
|
+
```
|
|
47
|
+
|
|
33
48
|
Or install from GitHub:
|
|
34
49
|
|
|
35
50
|
```bash
|
|
36
51
|
pi install git:github.com/eiei114/pi-spotify-widget
|
|
37
52
|
```
|
|
38
53
|
|
|
54
|
+
Try it without permanently installing:
|
|
55
|
+
|
|
56
|
+
```bash
|
|
57
|
+
pi -e npm:pi-spotify-widget
|
|
58
|
+
```
|
|
59
|
+
|
|
39
60
|
## Spotify Developer setup (required)
|
|
40
61
|
|
|
41
62
|
Each user creates their own Spotify app (v1 **BYO Client ID** policy). Client Secret is not needed for PKCE.
|
|
@@ -106,38 +127,40 @@ Then run:
|
|
|
106
127
|
|
|
107
128
|
| Path | Purpose |
|
|
108
129
|
|---|---|
|
|
109
|
-
| `extensions/` | Pi TypeScript extension entrypoints |
|
|
130
|
+
| `extensions/` | Pi TypeScript extension entrypoints (`index.ts`) |
|
|
110
131
|
| `lib/` | Spotify auth, API client, widget render |
|
|
111
|
-
| `
|
|
132
|
+
| `skills/` | `spotify-playback` Agent Skill |
|
|
133
|
+
| `docs/` | Release and examples |
|
|
112
134
|
|
|
113
135
|
## Development
|
|
114
136
|
|
|
115
137
|
```bash
|
|
116
138
|
npm install
|
|
117
139
|
npm run ci
|
|
140
|
+
npm run pack:check # equivalent to: npm pack --dry-run
|
|
118
141
|
```
|
|
119
142
|
|
|
143
|
+
`npm run ci` runs typecheck, tests, and the pack check. Run `npm pack --dry-run` directly when you only want to verify tarball contents.
|
|
144
|
+
|
|
120
145
|
## Release
|
|
121
146
|
|
|
147
|
+
Before tagging, confirm `npm run ci` and `npm pack --dry-run` pass locally.
|
|
148
|
+
|
|
122
149
|
This package is set up for npm Trusted Publishing, so no `NPM_TOKEN` is required.
|
|
123
150
|
|
|
124
151
|
```bash
|
|
125
|
-
npm version patch
|
|
126
|
-
git push
|
|
152
|
+
npm version patch --no-git-tag-version
|
|
153
|
+
git push
|
|
127
154
|
```
|
|
128
155
|
|
|
129
|
-
|
|
130
|
-
|
|
131
|
-
## Template checklist
|
|
156
|
+
On `main`, `.github/workflows/auto-release.yml` checks `package.json` version. If `v<version>` does not exist yet, it creates the tag, creates the GitHub Release, then explicitly dispatches `.github/workflows/publish.yml` for that tag.
|
|
132
157
|
|
|
133
|
-
|
|
158
|
+
See [`docs/release.md`](docs/release.md) for setup details.
|
|
134
159
|
|
|
135
|
-
|
|
160
|
+
## Docs
|
|
136
161
|
|
|
137
|
-
- [`docs/typescript.md`](docs/typescript.md)
|
|
138
162
|
- [`docs/examples.md`](docs/examples.md)
|
|
139
|
-
- [`docs/
|
|
140
|
-
- [`docs/repository-settings.md`](docs/repository-settings.md)
|
|
163
|
+
- [`docs/release.md`](docs/release.md)
|
|
141
164
|
|
|
142
165
|
## Security
|
|
143
166
|
|
package/docs/examples.md
CHANGED
|
@@ -1,15 +1,17 @@
|
|
|
1
1
|
# Examples
|
|
2
2
|
|
|
3
|
-
|
|
3
|
+
Pi Spotify Widget shows Now Playing in the prompt editor widget and exposes playback commands.
|
|
4
4
|
|
|
5
5
|
## Extension
|
|
6
6
|
|
|
7
|
-
`extensions/
|
|
7
|
+
`extensions/index.ts` registers:
|
|
8
8
|
|
|
9
|
-
- `/
|
|
10
|
-
-
|
|
9
|
+
- `/spotify:login`, `/spotify:status`, `/spotify:logout`
|
|
10
|
+
- `/spotify:refresh`, `/spotify:prev`, `/spotify:next`, `/spotify:pause`, `/spotify:play`
|
|
11
|
+
- `/spotify:help`, `/spotify:share`, `/spotify:play-uri`
|
|
12
|
+
- a prompt-editor widget with track, artist, and playback state
|
|
11
13
|
|
|
12
|
-
Try it
|
|
14
|
+
Try it locally:
|
|
13
15
|
|
|
14
16
|
```bash
|
|
15
17
|
pi -e .
|
|
@@ -18,32 +20,29 @@ pi -e .
|
|
|
18
20
|
Then run:
|
|
19
21
|
|
|
20
22
|
```txt
|
|
21
|
-
/
|
|
23
|
+
/spotify:login
|
|
24
|
+
/spotify:status
|
|
25
|
+
/spotify:refresh
|
|
26
|
+
/spotify:next
|
|
27
|
+
/spotify:share
|
|
22
28
|
```
|
|
23
29
|
|
|
24
30
|
## Agent Skill
|
|
25
31
|
|
|
26
|
-
`skills/
|
|
27
|
-
|
|
28
|
-
Replace it with your real workflow instructions.
|
|
32
|
+
`skills/spotify-playback/SKILL.md` maps natural-language playback and share intents to the commands above.
|
|
29
33
|
|
|
30
|
-
|
|
34
|
+
Replace or extend it when you add new playback workflows.
|
|
31
35
|
|
|
32
|
-
|
|
36
|
+
## OAuth setup
|
|
33
37
|
|
|
34
|
-
|
|
38
|
+
Each user supplies a Spotify Developer app Client ID (PKCE; no Client Secret required).
|
|
35
39
|
|
|
36
|
-
|
|
40
|
+
Redirect URI: `http://127.0.0.1:8888/callback`
|
|
37
41
|
|
|
38
|
-
|
|
39
|
-
|
|
40
|
-
`extensions/index.ts` registers:
|
|
42
|
+
Optional environment variable before starting Pi:
|
|
41
43
|
|
|
42
|
-
|
|
43
|
-
|
|
44
|
-
|
|
45
|
-
The tool demonstrates:
|
|
44
|
+
```bash
|
|
45
|
+
export PI_SPOTIFY_CLIENT_ID="your_client_id_here"
|
|
46
|
+
```
|
|
46
47
|
|
|
47
|
-
|
|
48
|
-
- a string enum schema via `StringEnum`
|
|
49
|
-
- shared logic imported from `lib/greeting.ts`
|
|
48
|
+
Tokens are stored locally under `~/.pi/agent/` and are not exposed in `/spotify:status` output.
|
package/docs/release.md
CHANGED
|
@@ -15,18 +15,39 @@ On npmjs.com, configure Trusted Publishing for this package:
|
|
|
15
15
|
## Publish
|
|
16
16
|
|
|
17
17
|
```bash
|
|
18
|
-
npm version patch
|
|
19
|
-
git push
|
|
18
|
+
npm version patch --no-git-tag-version
|
|
19
|
+
git push
|
|
20
20
|
```
|
|
21
21
|
|
|
22
|
-
|
|
22
|
+
On `main`, `.github/workflows/auto-release.yml` checks `package.json` version. If `v<version>` does not exist yet, it creates the tag, creates the GitHub Release, then explicitly dispatches `.github/workflows/publish.yml` for that tag.
|
|
23
|
+
|
|
24
|
+
`publish.yml` also listens for `release.published` and manual `v*.*.*` tag pushes, but the explicit dispatch from `auto-release.yml` remains the primary path because `GITHUB_TOKEN` tag pushes do not reliably fan out into a second workflow on their own.
|
|
25
|
+
|
|
26
|
+
## Workflow guardrail
|
|
27
|
+
|
|
28
|
+
Tags or releases created by `GITHUB_TOKEN` do not reliably fan out into another workflow through normal `push.tags` or `release.published` triggers. This repository keeps publishing reliable by having `auto-release.yml` explicitly dispatch `publish.yml` after creating the tag/release.
|
|
23
29
|
|
|
24
30
|
## GitHub Actions requirements
|
|
25
31
|
|
|
26
32
|
- `permissions: id-token: write`
|
|
33
|
+
- `permissions: actions: write` on auto-release so it can dispatch `publish.yml`
|
|
34
|
+
- `auto-release.yml` calls `gh workflow run publish.yml --ref "$TAG" -f ref="$TAG"`
|
|
35
|
+
- publish runner uses Node `24` so npm Trusted Publishing has a compatible Node/npm pair
|
|
27
36
|
- GitHub-hosted runner
|
|
28
37
|
- No `NPM_TOKEN`
|
|
29
|
-
- `npm publish` from the configured workflow file
|
|
38
|
+
- `npm publish --provenance --access public` from the configured workflow file
|
|
39
|
+
|
|
40
|
+
## Troubleshooting
|
|
41
|
+
|
|
42
|
+
If `publish.yml` fails at `npm publish` with `E404` / `404 Not Found`, the most likely cause is npm Trusted Publishing configuration, not the GitHub workflow logic.
|
|
43
|
+
|
|
44
|
+
Check npm package settings for:
|
|
45
|
+
|
|
46
|
+
- package: `pi-spotify-widget`
|
|
47
|
+
- repository: `eiei114/pi-spotify-widget`
|
|
48
|
+
- workflow filename: `publish.yml`
|
|
49
|
+
|
|
50
|
+
The workflow now prints that hint directly when npm returns 404.
|
|
30
51
|
|
|
31
52
|
## First release checklist
|
|
32
53
|
|
|
@@ -35,4 +56,4 @@ The `v*` tag triggers `.github/workflows/publish.yml`, which runs CI and publish
|
|
|
35
56
|
- [ ] npm Trusted Publisher is configured
|
|
36
57
|
- [ ] `npm run ci` passes
|
|
37
58
|
- [ ] `npm pack --dry-run` contains only intended files
|
|
38
|
-
- [ ] `CHANGELOG.md` has the release date
|
|
59
|
+
- [ ] `CHANGELOG.md` has the release date
|
package/package.json
CHANGED
|
@@ -1,62 +1,63 @@
|
|
|
1
|
-
{
|
|
2
|
-
"name": "pi-spotify-widget",
|
|
3
|
-
"version": "0.1.
|
|
4
|
-
"description": "Lightweight Spotify Now Playing widget for Pi Coding Agent.",
|
|
5
|
-
"type": "module",
|
|
6
|
-
"license": "MIT",
|
|
7
|
-
"author": "eiei114",
|
|
8
|
-
"keywords": [
|
|
9
|
-
"pi-package",
|
|
10
|
-
"pi",
|
|
11
|
-
"agent-skill",
|
|
12
|
-
"typescript"
|
|
13
|
-
],
|
|
14
|
-
"repository": {
|
|
15
|
-
"type": "git",
|
|
16
|
-
"url": "git+https://github.com/eiei114/pi-spotify-widget.git"
|
|
17
|
-
},
|
|
18
|
-
"bugs": {
|
|
19
|
-
"url": "https://github.com/eiei114/pi-spotify-widget/issues"
|
|
20
|
-
},
|
|
21
|
-
"homepage": "https://github.com/eiei114/pi-spotify-widget#readme",
|
|
22
|
-
"files": [
|
|
23
|
-
"extensions/",
|
|
24
|
-
"lib/",
|
|
25
|
-
"docs/",
|
|
26
|
-
"README.md",
|
|
27
|
-
"LICENSE",
|
|
28
|
-
"CHANGELOG.md",
|
|
29
|
-
"skills/"
|
|
30
|
-
],
|
|
31
|
-
"scripts": {
|
|
32
|
-
"typecheck": "tsc --noEmit",
|
|
33
|
-
"test": "node --test tests/*.test.mjs",
|
|
34
|
-
"ci": "npm run typecheck && npm test && npm run pack:check",
|
|
35
|
-
"pack:check": "npm pack --dry-run"
|
|
36
|
-
|
|
37
|
-
|
|
38
|
-
|
|
39
|
-
|
|
40
|
-
|
|
41
|
-
|
|
42
|
-
|
|
43
|
-
|
|
44
|
-
|
|
45
|
-
|
|
46
|
-
|
|
47
|
-
|
|
48
|
-
|
|
49
|
-
|
|
50
|
-
"@earendil-works/pi-
|
|
51
|
-
"@earendil-works/pi-
|
|
52
|
-
"
|
|
53
|
-
|
|
54
|
-
|
|
55
|
-
|
|
56
|
-
"@earendil-works/pi-
|
|
57
|
-
"@earendil-works/pi-
|
|
58
|
-
"
|
|
59
|
-
"
|
|
60
|
-
"
|
|
61
|
-
|
|
62
|
-
}
|
|
1
|
+
{
|
|
2
|
+
"name": "pi-spotify-widget",
|
|
3
|
+
"version": "0.1.8",
|
|
4
|
+
"description": "Lightweight Spotify Now Playing widget for Pi Coding Agent.",
|
|
5
|
+
"type": "module",
|
|
6
|
+
"license": "MIT",
|
|
7
|
+
"author": "eiei114",
|
|
8
|
+
"keywords": [
|
|
9
|
+
"pi-package",
|
|
10
|
+
"pi",
|
|
11
|
+
"agent-skill",
|
|
12
|
+
"typescript"
|
|
13
|
+
],
|
|
14
|
+
"repository": {
|
|
15
|
+
"type": "git",
|
|
16
|
+
"url": "git+https://github.com/eiei114/pi-spotify-widget.git"
|
|
17
|
+
},
|
|
18
|
+
"bugs": {
|
|
19
|
+
"url": "https://github.com/eiei114/pi-spotify-widget/issues"
|
|
20
|
+
},
|
|
21
|
+
"homepage": "https://github.com/eiei114/pi-spotify-widget#readme",
|
|
22
|
+
"files": [
|
|
23
|
+
"extensions/",
|
|
24
|
+
"lib/",
|
|
25
|
+
"docs/",
|
|
26
|
+
"README.md",
|
|
27
|
+
"LICENSE",
|
|
28
|
+
"CHANGELOG.md",
|
|
29
|
+
"skills/"
|
|
30
|
+
],
|
|
31
|
+
"scripts": {
|
|
32
|
+
"typecheck": "tsc --noEmit",
|
|
33
|
+
"test": "node --test tests/*.test.mjs",
|
|
34
|
+
"ci": "npm run typecheck && npm test && npm run pack:check",
|
|
35
|
+
"pack:check": "npm pack --dry-run",
|
|
36
|
+
"version:check": "node scripts/check-version-bump.mjs"
|
|
37
|
+
},
|
|
38
|
+
"pi": {
|
|
39
|
+
"extensions": [
|
|
40
|
+
"./extensions"
|
|
41
|
+
],
|
|
42
|
+
"skills": [
|
|
43
|
+
"./skills/spotify-playback"
|
|
44
|
+
]
|
|
45
|
+
},
|
|
46
|
+
"publishConfig": {
|
|
47
|
+
"access": "public"
|
|
48
|
+
},
|
|
49
|
+
"peerDependencies": {
|
|
50
|
+
"@earendil-works/pi-ai": "*",
|
|
51
|
+
"@earendil-works/pi-coding-agent": "*",
|
|
52
|
+
"@earendil-works/pi-tui": "*",
|
|
53
|
+
"typebox": "*"
|
|
54
|
+
},
|
|
55
|
+
"devDependencies": {
|
|
56
|
+
"@earendil-works/pi-ai": "^0.80.6",
|
|
57
|
+
"@earendil-works/pi-coding-agent": "^0.80.6",
|
|
58
|
+
"@earendil-works/pi-tui": "latest",
|
|
59
|
+
"typebox": "latest",
|
|
60
|
+
"@types/node": "^25.9.1",
|
|
61
|
+
"typescript": "^6.0.3"
|
|
62
|
+
}
|
|
63
|
+
}
|
package/docs/github-template.md
DELETED
|
@@ -1,43 +0,0 @@
|
|
|
1
|
-
# GitHub Template Repository
|
|
2
|
-
|
|
3
|
-
Enable template mode on the source repository:
|
|
4
|
-
|
|
5
|
-
```txt
|
|
6
|
-
GitHub repo → Settings → General → Template repository
|
|
7
|
-
```
|
|
8
|
-
|
|
9
|
-
Create a public repository from the template:
|
|
10
|
-
|
|
11
|
-
```bash
|
|
12
|
-
gh repo create OWNER/new-pi-extension \
|
|
13
|
-
--public \
|
|
14
|
-
--template OWNER/pi-extension-template \
|
|
15
|
-
--clone
|
|
16
|
-
```
|
|
17
|
-
|
|
18
|
-
Create a private repository from the template:
|
|
19
|
-
|
|
20
|
-
```bash
|
|
21
|
-
gh repo create OWNER/new-pi-extension \
|
|
22
|
-
--private \
|
|
23
|
-
--template OWNER/pi-extension-template \
|
|
24
|
-
--clone
|
|
25
|
-
```
|
|
26
|
-
|
|
27
|
-
Include all branches if needed:
|
|
28
|
-
|
|
29
|
-
```bash
|
|
30
|
-
gh repo create OWNER/new-pi-extension \
|
|
31
|
-
--public \
|
|
32
|
-
--template OWNER/pi-extension-template \
|
|
33
|
-
--include-all-branches \
|
|
34
|
-
--clone
|
|
35
|
-
```
|
|
36
|
-
|
|
37
|
-
After creation:
|
|
38
|
-
|
|
39
|
-
```bash
|
|
40
|
-
cd new-pi-extension
|
|
41
|
-
npm install
|
|
42
|
-
npm run ci
|
|
43
|
-
```
|
|
@@ -1,41 +0,0 @@
|
|
|
1
|
-
# Repository Settings
|
|
2
|
-
|
|
3
|
-
Use this file after creating a real repository from the template.
|
|
4
|
-
|
|
5
|
-
## GitHub About
|
|
6
|
-
|
|
7
|
-
Suggested fields:
|
|
8
|
-
|
|
9
|
-
- Description: one-line pitch for the Pi package
|
|
10
|
-
- Website: npm package URL or project docs URL
|
|
11
|
-
- Topics:
|
|
12
|
-
- `pi`
|
|
13
|
-
- `pi-package`
|
|
14
|
-
- `agent-skill`
|
|
15
|
-
- `typescript`
|
|
16
|
-
|
|
17
|
-
## Template mode
|
|
18
|
-
|
|
19
|
-
If this repository itself should be reusable as a template:
|
|
20
|
-
|
|
21
|
-
```txt
|
|
22
|
-
Settings → General → Template repository
|
|
23
|
-
```
|
|
24
|
-
|
|
25
|
-
## Branch protection
|
|
26
|
-
|
|
27
|
-
Recommended for public packages:
|
|
28
|
-
|
|
29
|
-
- Require pull request before merging
|
|
30
|
-
- Require status checks to pass
|
|
31
|
-
- Require `CI` workflow
|
|
32
|
-
- Block force pushes on the default branch
|
|
33
|
-
|
|
34
|
-
## npm package page
|
|
35
|
-
|
|
36
|
-
After first publish:
|
|
37
|
-
|
|
38
|
-
- Confirm README renders correctly
|
|
39
|
-
- Confirm package provenance appears
|
|
40
|
-
- Confirm package contents are intentional
|
|
41
|
-
- Add npm URL to GitHub About and README
|
|
@@ -1,85 +0,0 @@
|
|
|
1
|
-
# Template Setup Checklist
|
|
2
|
-
|
|
3
|
-
このテンプレートから新しい Pi 拡張OSSを作った後に埋めること。
|
|
4
|
-
|
|
5
|
-
## Repository
|
|
6
|
-
|
|
7
|
-
- [ ] GitHub repository name を決める
|
|
8
|
-
- [ ] GitHub About 欄を書く
|
|
9
|
-
- [ ] GitHub topics を設定する
|
|
10
|
-
- [ ] `pi`
|
|
11
|
-
- [ ] `pi-package`
|
|
12
|
-
- [ ] `agent-skill`
|
|
13
|
-
- [ ] `typescript`
|
|
14
|
-
- [ ] GitHub Settingsで `Template repository` をONにする
|
|
15
|
-
- [ ] Repository URL を `package.json` に反映する
|
|
16
|
-
- [ ] README の `OWNER/REPO` を実リポジトリに置き換える
|
|
17
|
-
|
|
18
|
-
## Package metadata
|
|
19
|
-
|
|
20
|
-
- [ ] `package.json` の `name` を変更する
|
|
21
|
-
- [ ] `description` を書く
|
|
22
|
-
- [ ] `author` を入れる
|
|
23
|
-
- [ ] `repository.url` を埋める
|
|
24
|
-
- [ ] `bugs.url` を埋める
|
|
25
|
-
- [ ] `homepage` を埋める
|
|
26
|
-
- [ ] `keywords` を見直す
|
|
27
|
-
- [ ] `LICENSE` の年・名前を更新する
|
|
28
|
-
|
|
29
|
-
## README placeholders
|
|
30
|
-
|
|
31
|
-
- [ ] `PACKAGE_DISPLAY_NAME` を置き換える
|
|
32
|
-
- [ ] `PACKAGE_NAME` を置き換える
|
|
33
|
-
- [ ] `OWNER/REPO` を置き換える
|
|
34
|
-
- [ ] one-line pitch を書く
|
|
35
|
-
- [ ] feature list を書く
|
|
36
|
-
- [ ] quick start command を実コマンドにする
|
|
37
|
-
- [ ] npm URL を確認する
|
|
38
|
-
- [ ] GitHub URL を確認する
|
|
39
|
-
|
|
40
|
-
## Pi package manifest
|
|
41
|
-
|
|
42
|
-
- [ ] `pi.extensions` に公開する拡張だけを残す
|
|
43
|
-
- [ ] `pi.skills` に公開する skill だけを残す
|
|
44
|
-
- [ ] 不要なら `prompts/` を消す
|
|
45
|
-
- [ ] 不要なら `themes/` を消す
|
|
46
|
-
- [ ] サンプル名を実名に変える
|
|
47
|
-
|
|
48
|
-
## TypeScript
|
|
49
|
-
|
|
50
|
-
- [ ] `extensions/index.ts` を実装に合わせて更新する
|
|
51
|
-
- [ ] `extensions/hello.ts` が不要なら削除する
|
|
52
|
-
- [ ] 共通ロジックを `lib/` に切り出す
|
|
53
|
-
- [ ] `strict: true` を維持する
|
|
54
|
-
- [ ] custom tool parameters は TypeBox schema で定義する
|
|
55
|
-
- [ ] string choices は `StringEnum` helper を使う
|
|
56
|
-
- [ ] runtime dependency は `dependencies`、Pi提供packageは `peerDependencies` に置く
|
|
57
|
-
- [ ] `package.json.files` に公開対象だけを入れる
|
|
58
|
-
|
|
59
|
-
## GitHub Template repo
|
|
60
|
-
|
|
61
|
-
- [ ] `gh repo create --template OWNER/pi-extension-template` で作成できることを確認する
|
|
62
|
-
- [ ] public/privateどちらの作成例もdocsに載せる
|
|
63
|
-
|
|
64
|
-
## CI / Release
|
|
65
|
-
|
|
66
|
-
- [ ] `npm run ci` が通る
|
|
67
|
-
- [ ] `npm pack --dry-run` が通る
|
|
68
|
-
- [ ] npm Trusted Publishing を設定する
|
|
69
|
-
- [ ] `NPM_TOKEN` を使っていないことを確認する
|
|
70
|
-
- [ ] tag publish が動くことを初回リリースで確認する
|
|
71
|
-
|
|
72
|
-
## npm page
|
|
73
|
-
|
|
74
|
-
- [ ] npm package URL を README に追加する
|
|
75
|
-
- [ ] npm description が適切に表示されるか確認する
|
|
76
|
-
- [ ] provenance が付いているか確認する
|
|
77
|
-
- [ ] 不要なファイルが package に含まれていないか確認する
|
|
78
|
-
|
|
79
|
-
## Before first release
|
|
80
|
-
|
|
81
|
-
- [ ] サンプルコードを実機 Pi でロードする
|
|
82
|
-
- [ ] `pi install git:github.com/OWNER/REPO` を試す
|
|
83
|
-
- [ ] `pi -e .` を試す
|
|
84
|
-
- [ ] README のコマンドがコピペで動くか確認する
|
|
85
|
-
- [ ] CHANGELOG に `0.1.0` を書く
|
package/docs/typescript.md
DELETED
|
@@ -1,75 +0,0 @@
|
|
|
1
|
-
# TypeScript Guide
|
|
2
|
-
|
|
3
|
-
This is a TypeScript-first Pi package template.
|
|
4
|
-
|
|
5
|
-
## Layout
|
|
6
|
-
|
|
7
|
-
```txt
|
|
8
|
-
extensions/*.ts Pi extension entrypoints
|
|
9
|
-
lib/*.ts Shared TypeScript helpers
|
|
10
|
-
skills/*/SKILL.md Agent Skills
|
|
11
|
-
prompts/*.md Prompt templates
|
|
12
|
-
themes/*.json Themes
|
|
13
|
-
tests/*.test.mjs Smoke tests
|
|
14
|
-
tests/*.test.ts Optional TypeScript tests if you add a TS test runner
|
|
15
|
-
```
|
|
16
|
-
|
|
17
|
-
Pi loads TypeScript extensions directly, so no build step is required for normal use.
|
|
18
|
-
|
|
19
|
-
## Strict mode
|
|
20
|
-
|
|
21
|
-
`tsconfig.json` keeps `strict: true`. Prefer fixing types over loosening compiler options.
|
|
22
|
-
|
|
23
|
-
## Extension entrypoints
|
|
24
|
-
|
|
25
|
-
Two entrypoint styles are shown:
|
|
26
|
-
|
|
27
|
-
- `extensions/hello.ts`: single-file extension
|
|
28
|
-
- `extensions/index.ts`: index-style extension that imports shared code from `lib/`
|
|
29
|
-
|
|
30
|
-
For larger packages, keep entrypoints thin and put reusable logic in `lib/`.
|
|
31
|
-
|
|
32
|
-
## TypeBox schemas
|
|
33
|
-
|
|
34
|
-
Use TypeBox schemas for custom tool parameters.
|
|
35
|
-
|
|
36
|
-
```ts
|
|
37
|
-
import { Type } from "typebox";
|
|
38
|
-
|
|
39
|
-
const parameters = Type.Object({
|
|
40
|
-
name: Type.String({ description: "Name to greet" }),
|
|
41
|
-
});
|
|
42
|
-
```
|
|
43
|
-
|
|
44
|
-
## String enums
|
|
45
|
-
|
|
46
|
-
For string choices, use the local `StringEnum` helper from `lib/schema.ts`.
|
|
47
|
-
|
|
48
|
-
```ts
|
|
49
|
-
import { StringEnum } from "../lib/schema.ts";
|
|
50
|
-
|
|
51
|
-
const mode = StringEnum(["short", "friendly"], {
|
|
52
|
-
description: "Greeting style",
|
|
53
|
-
});
|
|
54
|
-
```
|
|
55
|
-
|
|
56
|
-
This emits a JSON Schema `enum`, which is friendlier to model providers than a union of string literals.
|
|
57
|
-
|
|
58
|
-
## Runtime dependencies vs peer dependencies
|
|
59
|
-
|
|
60
|
-
Pi bundles core packages for extension authors. Keep Pi-provided packages as `peerDependencies` and also install them as `devDependencies` for local typechecking.
|
|
61
|
-
|
|
62
|
-
Use `peerDependencies` for:
|
|
63
|
-
|
|
64
|
-
- `@earendil-works/pi-coding-agent`
|
|
65
|
-
- `@earendil-works/pi-ai`
|
|
66
|
-
- `@earendil-works/pi-tui`
|
|
67
|
-
- `typebox`
|
|
68
|
-
|
|
69
|
-
Use `dependencies` for runtime packages your extension imports that Pi does not provide.
|
|
70
|
-
|
|
71
|
-
Use `devDependencies` for local-only tools such as TypeScript, test runners, and linters.
|
|
72
|
-
|
|
73
|
-
## Package contents
|
|
74
|
-
|
|
75
|
-
Control npm package contents with `package.json` `files`. Prefer this over `.npmignore` so the published package stays explicit.
|