pi-soccer-widget

Pi extension that shows a compact soccer widget above the prompt editor for your favorite club and World Cup follow.

What this is

pi-soccer-widget is a Pi Coding Agent package. It registers /soccer:* commands, stores lightweight local config under ~/.pi/agent/, and renders one widget line focused on recent results, the next opponent, and optional standings. Club mode prioritizes your favorite team and can fall back to watchlist or discovery teams during thin off-season data. World Cup mode adds followed-country menus and matchday-oriented refresh.

Features

• Favorite club first, with watchlist and discovery fallback
• Candidate search before adding teams to reduce typos
• /soccer:setup guided API key and favorite-team setup
• /soccer:worldcup menu plus first-run followed-country setup
• 6-hour sync cache with optional /soccer:sync
• One compact widget at a time
• Configurable league search scope via PI_SOCCER_LEAGUES

Install

This is a Pi package. Install with pi install, not plain npm install:

pi install npm:pi-soccer-widget
# or
pi install git:github.com/eiei114/pi-soccer-widget

By default pi install writes to ~/.pi/agent/settings.json. Add -l to install into the current project (.pi/settings.json).

Requirements:

• Pi Coding Agent CLI
• Node.js >= 20
• A free token from football-data.org

If Pi is not installed yet:

npm install -g --ignore-scripts @earendil-works/pi-coding-agent
# or
curl -fsSL https://pi.dev/install.sh | sh

Quick start

1. Install the package with pi install npm:pi-soccer-widget.
2. Start or reload Pi (/reload in an existing session).
3. Run /soccer:setup to store your football-data.org API key and pick a favorite team.
4. Confirm setup with /soccer:status (shows source only, never the key value).

Optional environment fallback:

FOOTBALL_DATA_API_TOKEN=your_api_token

Usage summary

Canonical commands (11 total):

/soccer:setup
/soccer:login
/soccer:status
/soccer:logout
/soccer:sync
/soccer:search <name>
/soccer:add [name]
/soccer:favorite [name]
/soccer:list
/soccer:remove [name]
/soccer:worldcup

Omit the team name on /soccer:add, /soccer:favorite, or /soccer:remove to open a Pi UI picker. Pass a team name for fuzzy match; numeric IDs and cached search indexes are not supported.

For World Cup menus, widget behavior, environment variables, and local file layout, see docs/usage.md. For sample widget output, see docs/examples.md.

Package contents

Published npm tarball includes:

• extensions/index.ts and compiled dist/extensions/*
• README.md, CHANGELOG.md, LICENSE
• OPERATIONS.md (maintainer operations guide)

Runtime state is written locally under ~/.pi/agent/ (config, auth, cache, snapshots). See docs/usage.md.

Development

npm install
npm test          # build + node:test suite
npm run check     # test + pack dry-run
npm run release:check

Load a checkout directly:

pi -e ./extensions/index.ts

Or place the extension under ~/.pi/agent/extensions/ or .pi/extensions/ and run /reload.

Release

Releases use GitHub Actions:

• Auto Release (auto-release.yml) tags v* when package.json version changes on main.
• Publish to npm (publish.yml) runs npm run check, then publishes with npm Trusted Publishing (OIDC).

Before merging a release bump, run:

npm run release:check

Maintainer checklist and tarball expectations: docs/release.md.

Security

API keys are entered through Pi extension UI (/soccer:login), stored locally at ~/.pi/agent/pi-soccer-widget-auth.json, and never sent to the model. FOOTBALL_DATA_API_TOKEN overrides the saved file when set. Report security issues privately; see SECURITY.md.

Links

• npm: https://www.npmjs.com/package/pi-soccer-widget
• Issues: https://github.com/eiei114/pi-soccer-widget/issues
• Usage details: docs/usage.md
• Examples: docs/examples.md
• Release checklist: docs/release.md
• Maintainer operations: OPERATIONS.md

License

MIT. See LICENSE.