pi-spotify-widget 0.1.0

package/CHANGELOG.md

@@ -0,0 +1,19 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+This project follows semantic versioning.
+
+## [0.1.0] - 2026-06-03
+
+### Added
+
+- Now Playing widget in Pi prompt editor (track, artist, playing/paused, progress seek bar).
+- OAuth 2.0 + PKCE login via `/spotify:login` with localhost callback on port 8888.
+- Interactive Client ID setup (Dashboard opens in browser; optional `PI_SPOTIFY_CLIENT_ID` env override).
+- Secret-safe `/spotify:status`, `/spotify:logout`, and `/spotify:refresh`.
+- Playback controls (`/spotify:prev`, `/spotify:next`, `/spotify:pause`, `/spotify:play`) and `/spotify:play-uri`.
+- `/spotify:share` for X compose (intent URL; optional API credentials via env).
+- `spotify-playback` Agent Skill for playback and share workflows.
+- Token refresh lifecycle and adaptive polling with stale snapshot fallback.
+- CI workflow and npm Trusted Publishing setup.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 YOUR_NAME
+
+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/README.md

@@ -0,0 +1,160 @@
+# pi-spotify-widget
+
+[![CI](https://github.com/eiei114/pi-spotify-widget/actions/workflows/ci.yml/badge.svg)](https://github.com/eiei114/pi-spotify-widget/actions/workflows/ci.yml)
+[![Publish](https://github.com/eiei114/pi-spotify-widget/actions/workflows/publish.yml/badge.svg)](https://github.com/eiei114/pi-spotify-widget/actions/workflows/publish.yml)
+[![npm version](https://img.shields.io/npm/v/pi-spotify-widget.svg)](https://www.npmjs.com/package/pi-spotify-widget)
+[![npm downloads](https://img.shields.io/npm/dm/pi-spotify-widget.svg)](https://www.npmjs.com/package/pi-spotify-widget)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
+[![Pi package](https://img.shields.io/badge/pi-package-purple.svg)](https://pi.dev/packages)
+[![Trusted Publishing](https://img.shields.io/badge/npm-Trusted%20Publishing-blue.svg)](docs/release.md)
+
+> Show Spotify playback status in Pi's prompt editor widget.
+
+## What this is
+
+TypeScript-first Pi package that displays **Now Playing** (track, artist, playing/paused) in the prompt editor widget. Auth uses **OAuth 2.0 + PKCE** against Spotify Web API — not a static API key.
+
+## Features
+
+- **Now Playing widget** — track, artist, playback state, compact progress seek bar
+- **OAuth login** — `/spotify:login` opens Dashboard + browser, stores tokens locally
+- **Secret-safe status** — `/spotify:status` without exposing token values
+- **Playback controls** — `/spotify:prev`, `/spotify:next`, `/spotify:pause`, `/spotify:play`
+- **Share to X** — `/spotify:share` opens compose with Now Playing text (soccer-widget style)
+- **Manual refresh** — `/spotify:refresh`
+- **Token refresh** — access token lifecycle before API calls
+
+## Install
+
+```bash
+pi install npm:pi-spotify-widget
+```
+
+Or install from GitHub:
+
+```bash
+pi install git:github.com/eiei114/pi-spotify-widget
+```
+
+## Spotify Developer setup (required)
+
+Each user creates their own Spotify app (v1 **BYO Client ID** policy). Client Secret is not needed for PKCE.
+
+### Option A — Interactive setup (recommended)
+
+1. Install the package (see [Install](#install)) and start Pi.
+2. Run `/spotify:login` — the [Spotify Developer Dashboard](https://developer.spotify.com/dashboard) opens automatically.
+3. Create an app and add redirect URI: `http://127.0.0.1:8888/callback`
+4. Paste your **Client ID** into the Pi prompt when asked.
+5. Complete browser OAuth authorization.
+
+The Client ID is saved locally at `~/.pi/agent/pi-spotify-widget-config.json` (not sent to the model). OAuth tokens are stored separately at `~/.pi/agent/pi-spotify-widget-auth.json`.
+
+### Option B — Environment variable
+
+Set `PI_SPOTIFY_CLIENT_ID` before starting Pi to skip the Client ID prompt:
+
+```powershell
+# PowerShell
+$env:PI_SPOTIFY_CLIENT_ID="your_client_id_here"
+```
+
+```bash
+# bash
+export PI_SPOTIFY_CLIENT_ID="your_client_id_here"
+```
+
+Bundled Client ID and Extended Quota are planned for a future release. v1 does not ship a shared maintainer app.
+
+## Quick start
+
+```bash
+pi install npm:pi-spotify-widget
+```
+
+Try locally from a git checkout:
+
+```bash
+pi -e .
+```
+
+Then run:
+
+```txt
+/spotify:login
+/spotify:status
+/spotify:refresh
+```
+
+## Commands
+
+| Command | Description |
+|---|---|
+| `/spotify:login` | Open Dashboard, enter Client ID (if needed), OAuth PKCE login |
+| `/spotify:status` | Secret-safe auth status (no token values) |
+| `/spotify:logout` | Remove stored tokens |
+| `/spotify:refresh` | Force Now Playing snapshot fetch |
+| `/spotify:prev` | Skip to previous track |
+| `/spotify:next` | Skip to next track |
+| `/spotify:pause` | Pause playback |
+| `/spotify:play` | Resume playback |
+| `/spotify:help` | Playback command list for AI/user |
+| `/spotify:share` | Open X compose with Now Playing (optional prefix text) |
+| `/spotify:play-uri` | Play a Spotify track URL or URI |
+
+## Package contents
+
+| Path | Purpose |
+|---|---|
+| `extensions/` | Pi TypeScript extension entrypoints |
+| `lib/` | Spotify auth, API client, widget render |
+| `docs/` | Release and setup docs |
+
+## Development
+
+```bash
+npm install
+npm run ci
+```
+
+## Release
+
+This package is set up for npm Trusted Publishing, so no `NPM_TOKEN` is required.
+
+```bash
+npm version patch
+git push --follow-tags
+```
+
+See [`docs/release.md`](docs/release.md) for setup details.
+
+## Template checklist
+
+After creating a repository from this template, follow [`docs/template-checklist.md`](docs/template-checklist.md).
+
+More docs:
+
+- [`docs/typescript.md`](docs/typescript.md)
+- [`docs/examples.md`](docs/examples.md)
+- [`docs/github-template.md`](docs/github-template.md)
+- [`docs/repository-settings.md`](docs/repository-settings.md)
+
+## Security
+
+Pi packages can execute code with your local permissions. This package:
+
+- sends network requests to Spotify Web API
+- stores OAuth tokens under `~/.pi/agent/` (local only)
+- opens your system browser for login
+
+Review extensions before installing third-party packages. For vulnerability reporting, see [`SECURITY.md`](SECURITY.md).
+
+## Links
+
+- npm: https://www.npmjs.com/package/pi-spotify-widget
+- GitHub: https://github.com/eiei114/pi-spotify-widget
+- Issues: https://github.com/eiei114/pi-spotify-widget/issues
+
+## License
+
+MIT

package/docs/examples.md

@@ -0,0 +1,49 @@
+# Examples
+
+This template ships one minimal example for each Pi package resource type.
+
+## Extension
+
+`extensions/hello.ts` registers:
+
+- `/template-hello`
+- a small session status indicator
+
+Try it with:
+
+```bash
+pi -e .
+```
+
+Then run:
+
+```txt
+/template-hello YourName
+```
+
+## Agent Skill
+
+`skills/example-skill/SKILL.md` demonstrates a minimal Agent Skill.
+
+Replace it with your real workflow instructions.
+
+## Prompt template
+
+`prompts/example.md` demonstrates a tiny prompt template with one variable.
+
+## Theme
+
+`themes/example-theme.json` is a placeholder theme. Replace it or remove `themes/` if your package does not ship themes.
+
+## Typed custom tool
+
+`extensions/index.ts` registers:
+
+- `/template-info`
+- `template_greet` custom tool
+
+The tool demonstrates:
+
+- TypeBox object parameters
+- a string enum schema via `StringEnum`
+- shared logic imported from `lib/greeting.ts`

package/docs/github-template.md

@@ -0,0 +1,43 @@
+# GitHub Template Repository
+
+Enable template mode on the source repository:
+
+```txt
+GitHub repo → Settings → General → Template repository
+```
+
+Create a public repository from the template:
+
+```bash
+gh repo create OWNER/new-pi-extension \
+  --public \
+  --template OWNER/pi-extension-template \
+  --clone
+```
+
+Create a private repository from the template:
+
+```bash
+gh repo create OWNER/new-pi-extension \
+  --private \
+  --template OWNER/pi-extension-template \
+  --clone
+```
+
+Include all branches if needed:
+
+```bash
+gh repo create OWNER/new-pi-extension \
+  --public \
+  --template OWNER/pi-extension-template \
+  --include-all-branches \
+  --clone
+```
+
+After creation:
+
+```bash
+cd new-pi-extension
+npm install
+npm run ci
+```

package/docs/release.md

@@ -0,0 +1,38 @@
+# Release
+
+This package uses npm Trusted Publishing with GitHub Actions OIDC.
+
+Do not add `NPM_TOKEN` or long-lived npm tokens to GitHub Secrets.
+
+## One-time npm setup
+
+On npmjs.com, configure Trusted Publishing for this package:
+
+- Publisher: GitHub Actions
+- Repository: this GitHub repository
+- Workflow filename: `publish.yml`
+
+## Publish
+
+```bash
+npm version patch
+git push --follow-tags
+```
+
+The `v*` tag triggers `.github/workflows/publish.yml`, which runs CI and publishes to npm.
+
+## GitHub Actions requirements
+
+- `permissions: id-token: write`
+- GitHub-hosted runner
+- No `NPM_TOKEN`
+- `npm publish` from the configured workflow file
+
+## First release checklist
+
+- [ ] `package.json` name is final
+- [ ] `repository.url` points to the real GitHub repository
+- [ ] npm Trusted Publisher is configured
+- [ ] `npm run ci` passes
+- [ ] `npm pack --dry-run` contains only intended files
+- [ ] `CHANGELOG.md` has the release date

package/docs/repository-settings.md

@@ -0,0 +1,41 @@
+# Repository Settings
+
+Use this file after creating a real repository from the template.
+
+## GitHub About
+
+Suggested fields:
+
+- Description: one-line pitch for the Pi package
+- Website: npm package URL or project docs URL
+- Topics:
+  - `pi`
+  - `pi-package`
+  - `agent-skill`
+  - `typescript`
+
+## Template mode
+
+If this repository itself should be reusable as a template:
+
+```txt
+Settings → General → Template repository
+```
+
+## Branch protection
+
+Recommended for public packages:
+
+- Require pull request before merging
+- Require status checks to pass
+- Require `CI` workflow
+- Block force pushes on the default branch
+
+## npm package page
+
+After first publish:
+
+- Confirm README renders correctly
+- Confirm package provenance appears
+- Confirm package contents are intentional
+- Add npm URL to GitHub About and README

package/docs/template-checklist.md

@@ -0,0 +1,85 @@
+# Template Setup Checklist
+
+このテンプレートから新しい Pi 拡張OSSを作った後に埋めること。
+
+## Repository
+
+- [ ] GitHub repository name を決める
+- [ ] GitHub About 欄を書く
+- [ ] GitHub topics を設定する
+  - [ ] `pi`
+  - [ ] `pi-package`
+  - [ ] `agent-skill`
+  - [ ] `typescript`
+- [ ] GitHub Settingsで `Template repository` をONにする
+- [ ] Repository URL を `package.json` に反映する
+- [ ] README の `OWNER/REPO` を実リポジトリに置き換える
+
+## Package metadata
+
+- [ ] `package.json` の `name` を変更する
+- [ ] `description` を書く
+- [ ] `author` を入れる
+- [ ] `repository.url` を埋める
+- [ ] `bugs.url` を埋める
+- [ ] `homepage` を埋める
+- [ ] `keywords` を見直す
+- [ ] `LICENSE` の年・名前を更新する
+
+## README placeholders
+
+- [ ] `PACKAGE_DISPLAY_NAME` を置き換える
+- [ ] `PACKAGE_NAME` を置き換える
+- [ ] `OWNER/REPO` を置き換える
+- [ ] one-line pitch を書く
+- [ ] feature list を書く
+- [ ] quick start command を実コマンドにする
+- [ ] npm URL を確認する
+- [ ] GitHub URL を確認する
+
+## Pi package manifest
+
+- [ ] `pi.extensions` に公開する拡張だけを残す
+- [ ] `pi.skills` に公開する skill だけを残す
+- [ ] 不要なら `prompts/` を消す
+- [ ] 不要なら `themes/` を消す
+- [ ] サンプル名を実名に変える
+
+## TypeScript
+
+- [ ] `extensions/index.ts` を実装に合わせて更新する
+- [ ] `extensions/hello.ts` が不要なら削除する
+- [ ] 共通ロジックを `lib/` に切り出す
+- [ ] `strict: true` を維持する
+- [ ] custom tool parameters は TypeBox schema で定義する
+- [ ] string choices は `StringEnum` helper を使う
+- [ ] runtime dependency は `dependencies`、Pi提供packageは `peerDependencies` に置く
+- [ ] `package.json.files` に公開対象だけを入れる
+
+## GitHub Template repo
+
+- [ ] `gh repo create --template OWNER/pi-extension-template` で作成できることを確認する
+- [ ] public/privateどちらの作成例もdocsに載せる
+
+## CI / Release
+
+- [ ] `npm run ci` が通る
+- [ ] `npm pack --dry-run` が通る
+- [ ] npm Trusted Publishing を設定する
+- [ ] `NPM_TOKEN` を使っていないことを確認する
+- [ ] tag publish が動くことを初回リリースで確認する
+
+## npm page
+
+- [ ] npm package URL を README に追加する
+- [ ] npm description が適切に表示されるか確認する
+- [ ] provenance が付いているか確認する
+- [ ] 不要なファイルが package に含まれていないか確認する
+
+## Before first release
+
+- [ ] サンプルコードを実機 Pi でロードする
+- [ ] `pi install git:github.com/OWNER/REPO` を試す
+- [ ] `pi -e .` を試す
+- [ ] README のコマンドがコピペで動くか確認する
+- [ ] CHANGELOG に `0.1.0` を書く

package/docs/typescript.md

@@ -0,0 +1,75 @@
+# TypeScript Guide
+
+This is a TypeScript-first Pi package template.
+
+## Layout
+
+```txt
+extensions/*.ts      Pi extension entrypoints
+lib/*.ts             Shared TypeScript helpers
+skills/*/SKILL.md    Agent Skills
+prompts/*.md         Prompt templates
+themes/*.json        Themes
+tests/*.test.mjs     Smoke tests
+tests/*.test.ts      Optional TypeScript tests if you add a TS test runner
+```
+
+Pi loads TypeScript extensions directly, so no build step is required for normal use.
+
+## Strict mode
+
+`tsconfig.json` keeps `strict: true`. Prefer fixing types over loosening compiler options.
+
+## Extension entrypoints
+
+Two entrypoint styles are shown:
+
+- `extensions/hello.ts`: single-file extension
+- `extensions/index.ts`: index-style extension that imports shared code from `lib/`
+
+For larger packages, keep entrypoints thin and put reusable logic in `lib/`.
+
+## TypeBox schemas
+
+Use TypeBox schemas for custom tool parameters.
+
+```ts
+import { Type } from "typebox";
+
+const parameters = Type.Object({
+  name: Type.String({ description: "Name to greet" }),
+});
+```
+
+## String enums
+
+For string choices, use the local `StringEnum` helper from `lib/schema.ts`.
+
+```ts
+import { StringEnum } from "../lib/schema.ts";
+
+const mode = StringEnum(["short", "friendly"], {
+  description: "Greeting style",
+});
+```
+
+This emits a JSON Schema `enum`, which is friendlier to model providers than a union of string literals.
+
+## Runtime dependencies vs peer dependencies
+
+Pi bundles core packages for extension authors. Keep Pi-provided packages as `peerDependencies` and also install them as `devDependencies` for local typechecking.
+
+Use `peerDependencies` for:
+
+- `@earendil-works/pi-coding-agent`
+- `@earendil-works/pi-ai`
+- `@earendil-works/pi-tui`
+- `typebox`
+
+Use `dependencies` for runtime packages your extension imports that Pi does not provide.
+
+Use `devDependencies` for local-only tools such as TypeScript, test runners, and linters.
+
+## Package contents
+
+Control npm package contents with `package.json` `files`. Prefer this over `.npmignore` so the published package stays explicit.