pi-producthunt 0.1.1

package/CHANGELOG.md

@@ -0,0 +1,21 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+This project follows semantic versioning.
+
+## [0.1.1] - 2026-06-01
+
+### Changed
+
+- Publish workflow now supports npm publishing on merged package version bumps in addition to tags, releases, and manual dispatch.
+- Publish workflow now installs a current npm CLI so npm Trusted Publishing OIDC is supported.
+- CI and publish workflow commands no longer include literal trailing `\\n` text.
+
+## [0.1.0] - YYYY-MM-DD
+
+### Added
+
+- Initial Pi package template.
+- Example extension, Agent Skill, prompt, and theme.
+- CI and npm Trusted Publishing workflow.

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,171 @@
+# Pi Product Hunt
+
+[![CI](https://github.com/eiei114/pi-producthunt/actions/workflows/ci.yml/badge.svg)](https://github.com/eiei114/pi-producthunt/actions/workflows/ci.yml)
+[![Publish](https://github.com/eiei114/pi-producthunt/actions/workflows/publish.yml/badge.svg)](https://github.com/eiei114/pi-producthunt/actions/workflows/publish.yml)
+[![npm version](https://img.shields.io/npm/v/pi-producthunt.svg)](https://www.npmjs.com/package/pi-producthunt)
+[![npm downloads](https://img.shields.io/npm/dm/pi-producthunt.svg)](https://www.npmjs.com/package/pi-producthunt)
+[![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)
+
+> Product Hunt research and digest workflows inside Pi.
+
+Pi Product Hunt is a read-only Pi extension package for Product Hunt market research. It calls the Product Hunt GraphQL API directly, adds interactive `/producthunt:*` commands for humans, and exposes structured tools for agents to gather launches, post details, comments, and digest-ready research notes.
+
+## Features
+
+- Daily Product Hunt launch scans.
+- Product/post search for competitor and trend research.
+- Post detail and comment collection for user-reaction analysis.
+- Digest-ready Markdown with sections for signals, reactions, and watchlists.
+- Persistent login that stores your Product Hunt token in the Pi agent directory.
+- Agent tools with typed parameters for autonomous Product Hunt research.
+
+## Install
+
+```bash
+pi install npm:pi-producthunt
+```
+
+Or install from GitHub:
+
+```bash
+pi install git:github.com/eiei114/pi-producthunt
+```
+
+Try without installing permanently:
+
+```bash
+pi -e npm:pi-producthunt
+```
+
+For local development from a checkout:
+
+```bash
+pi -e .
+```
+
+## Authentication
+
+Use the interactive login command:
+
+```txt
+/producthunt:login
+```
+
+This stores your token in:
+
+```txt
+~/.pi/agent/pi-producthunt-auth.json
+```
+
+You can remove the stored token with:
+
+```txt
+/producthunt:logout
+```
+
+You can also provide a token through the environment. Environment auth takes priority over the stored login token:
+
+```bash
+export PRODUCTHUNT_ACCESS_TOKEN=...
+```
+
+## Commands
+
+Commands are human-facing and require no fixed inline arguments. If input is needed, Pi asks interactively.
+
+```txt
+/producthunt:status
+/producthunt:login
+/producthunt:logout
+/producthunt:today
+/producthunt:search
+/producthunt:post
+/producthunt:comments
+/producthunt:digest
+/producthunt:research
+```
+
+Example flows:
+
+```txt
+/producthunt:today      # today's launch list
+/producthunt:search     # asks for a search query
+/producthunt:post       # asks for slug, ID, or URL
+/producthunt:comments   # asks for slug, ID, or URL
+/producthunt:digest     # asks for today / yesterday / custom date
+/producthunt:research   # asks for a research topic
+```
+
+## Agent tools
+
+Agents can call these typed tools directly:
+
+```txt
+producthunt_status
+producthunt_get_posts
+producthunt_search_posts
+producthunt_get_post
+producthunt_get_post_comments
+producthunt_research_topic
+producthunt_digest
+```
+
+Examples:
+
+```txt
+producthunt_search_posts({ query: "AI coding agent", limit: 10 })
+producthunt_get_post({ ref: "example-product-slug" })
+producthunt_get_post_comments({ ref: "example-product-slug", limit: 10 })
+producthunt_digest({ date: "2026-06-01", limit: 10 })
+```
+
+## Package contents
+
+| Path | Purpose |
+|---|---|
+| `extensions/` | Pi extension entrypoint and command/tool registration |
+| `lib/` | Product Hunt API client, auth store, formatters, schemas, helpers |
+| `docs/` | Release and package setup docs |
+| `tests/` | Node test suite |
+
+## Development
+
+```bash
+npm install
+npm run ci
+```
+
+`npm run ci` runs:
+
+- TypeScript typecheck
+- Node tests
+- `npm pack --dry-run`
+
+## Release
+
+This package supports npm Trusted Publishing, but you can also publish manually when needed:
+
+```bash
+npm publish --access public --otp <OTP>
+```
+
+Do not store long-lived npm tokens in this repo.
+
+## Security
+
+Pi packages execute with your local permissions. Review source before installing third-party packages.
+
+Product Hunt tokens are never committed by this package. `/producthunt:login` stores the token locally in `~/.pi/agent/pi-producthunt-auth.json`; `/producthunt:logout` deletes that stored file. `PRODUCTHUNT_ACCESS_TOKEN` is never modified by logout.
+
+For vulnerability reporting, see [`SECURITY.md`](SECURITY.md).
+
+## Links
+
+- npm: https://www.npmjs.com/package/pi-producthunt
+- GitHub: https://github.com/eiei114/pi-producthunt
+- Issues: https://github.com/eiei114/pi-producthunt/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,61 @@
+# GitHub Template Repository
+
+## Recommended development flow
+
+After generating a repo from this template, use this default order:
+
+```txt
+Vault notes -> PRD -> Issues -> implement -> ci/check -> release -> save learnings
+```
+
+In practice:
+
+1. Create Vault notes under `4_Project/<ProjectName>/`.
+2. Add `CONTEXT.md`, `README.md`, `ROADMAP.md`, `Docs/`, `Issues/`, and `Progress/`.
+3. Write the PRD in `Docs/`.
+4. Split approved issue files into `Issues/`.
+5. Implement in the OSS repo created from this template.
+6. Run CI and package checks before release.
+7. Save release notes and follow-up decisions back to the Vault project.
+
+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
+```\n

package/docs/release.md

@@ -0,0 +1,45 @@
+# 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
+```
+
+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.
+
+The `v*.*.*` tag also triggers `.github/workflows/publish.yml`, which runs CI and publishes to npm when tags are pushed manually.
+Publishing also runs when a GitHub Release is published, and can be run manually from GitHub Actions with `workflow_dispatch`.
+
+The workflow skips `name@version` if that exact package version already exists on npm.
+
+## GitHub Actions requirements
+
+- `permissions: id-token: write`
+- `permissions: actions: write` on auto-release so it can dispatch `publish.yml`
+- GitHub-hosted runner
+- Node.js 24, so the release job uses a current npm CLI for Trusted Publishing
+- 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\n

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,98 @@
+# Template Setup Checklist
+
+このテンプレートから新しい Pi 拡張OSSを作った後に埋めること。
+
+## Recommended flow
+
+- [ ] Vault project notes を `4_Project/<ProjectName>/` に作る
+- [ ] `CONTEXT.md` / `README.md` / `ROADMAP.md` / `Docs/` / `Issues/` / `Progress/` を揃える
+- [ ] PRD を `4_Project/<ProjectName>/Docs/` に置く
+- [ ] approved issue を `4_Project/<ProjectName>/Issues/` に切る
+- [ ] OSS repo 側で実装する
+- [ ] `npm run ci` / `npm test` / `npm pack --dry-run` を通す
+- [ ] release 後に Vault へ learnings / release notes を戻す
+
+## 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 Trusted Publisher の workflow filename が `publish.yml` になっている
+- [ ] `NPM_TOKEN` を使っていないことを確認する
+- [ ] `auto-release.yml` が `main` の version bump から tag/release を作ることを確認する
+- [ ] `publish.yml` が `workflow_dispatch` と `release.published` に対応していることを確認する
+- [ ] 初回リリースで npm provenance が付いているか確認する
+
+## 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` を書く\n

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.