pi-discord-bot 0.1.1

package/docs/operator-env-config.md

@@ -0,0 +1,278 @@
+# Operator env and config guide
+
+This page is for people operating `pi-discord-bot` locally, especially if they already use the normal Pi CLI / TUI on the same machine.
+
+## Mental model
+
+`pi-discord-bot` uses:
+- **Discord token** from an env file
+- **Pi shared auth/settings** from your normal Pi setup
+- **runtime workspace** outside the repo by default
+- **Discord policy** from `<workspace>/discord-policy.json`
+
+So in most cases you do **not** need to put model provider API keys in this repo-specific env file if Pi is already authenticated on the machine.
+
+---
+
+## 1. Environment file
+
+Recommended path:
+
+```bash
+~/.config/pi-discord-bot.env
+```
+
+Minimum example:
+
+```bash
+DISCORD_TOKEN=your_discord_bot_token
+```
+
+Optional:
+
+```bash
+DISCORD_GUILD_ID=123456789012345678
+```
+
+### What each variable does
+
+#### `DISCORD_TOKEN`
+Required.
+Used by the Discord bot client to log in.
+
+#### `DISCORD_GUILD_ID`
+Optional.
+If set, the default generated policy can use it for guild-scoped slash command registration / faster iteration.
+If omitted, the bot can register commands globally.
+
+---
+
+## 2. Pi auth and settings
+
+This bot intentionally follows **Pi shared auth/settings/default model flow**.
+
+That means:
+- it uses Pi’s shared auth storage
+- it uses Pi’s shared settings manager
+- it does **not** hardcode a provider/model in repo config
+
+### If you already use Pi TUI / CLI
+If you already use Pi normally on this machine, that is the expected setup.
+The Discord bot should reuse that auth/settings context.
+
+Typical user flow:
+1. open Pi TUI / CLI
+2. authenticate there
+3. run `pi-discord-bot`
+4. use `/model`, `/settings`, etc. in Discord if you want per-session changes
+
+### Important operator note
+Do not keep stale repo docs or env files that suggest this bot requires provider-specific API keys like:
+- `ANTHROPIC_API_KEY`
+- `OPENAI_API_KEY`
+
+Those may still be valid for Pi itself depending on your environment, but this bot is designed to rely on **Pi shared auth** rather than hardcoded bot-local model credentials.
+
+---
+
+## 3. Runtime workspace
+
+Default runtime dir used by this repo:
+
+```text
+$XDG_STATE_HOME/pi-discord-bot/agent
+```
+
+or, if `XDG_STATE_HOME` is unset:
+
+```text
+~/.local/state/pi-discord-bot/agent
+```
+
+Optional override via env:
+
+```bash
+PI_DISCORD_BOT_WORKDIR=/absolute/path/to/pi-discord-bot-agent
+```
+
+Important contents:
+
+```text
+./agent/
+  discord-policy.json
+  MEMORY.md
+  skills/
+  guild:.../
+  dm:.../
+```
+
+Treat this directory as **private runtime state**.
+It may contain:
+- user messages
+- assistant responses
+- local file paths
+- attachment metadata
+- tool outputs
+
+Do not commit or share it.
+
+---
+
+## 4. Discord policy file
+
+Create it with:
+
+```bash
+mkdir -p ~/.local/state/pi-discord-bot/agent
+cp discord-policy.example.json ~/.local/state/pi-discord-bot/agent/discord-policy.json
+```
+
+Or with a custom workspace:
+
+```bash
+mkdir -p "$PI_DISCORD_BOT_WORKDIR"
+cp discord-policy.example.json "$PI_DISCORD_BOT_WORKDIR/discord-policy.json"
+```
+
+Example:
+
+```json
+{
+  "allowDMs": true,
+  "guildIds": ["123456789012345678"],
+  "channelIds": ["234567890123456789"],
+  "mentionMode": "mention-only",
+  "slashCommands": {
+    "enabled": true
+  }
+}
+```
+
+### Main fields
+
+#### `allowDMs`
+Allow or deny bot usage in DMs.
+
+#### `guildIds`
+Optional guild allowlist.
+Omit to allow all guilds.
+
+#### `channelIds`
+Optional channel allowlist.
+Omit to allow all channels.
+
+#### `mentionMode`
+- `mention-only`: normal guild chat must mention the bot
+- `allow-all`: normal guild chat can be processed without mention gating
+
+Text commands starting with `/` are still accepted as commands.
+
+#### `slashCommands.enabled`
+Enable or disable slash command registration.
+
+#### `slashCommands.guildId`
+Optional guild-scoped slash command registration.
+Useful for faster development iteration.
+If omitted, global commands are used.
+
+---
+
+## 5. How this fits with Pi TUI users
+
+Most operators who use Pi already will probably do this:
+
+### Step A: authenticate in Pi first
+Use Pi in its normal interface and make sure auth works there.
+
+### Step B: configure Discord env
+Create:
+
+```bash
+~/.config/pi-discord-bot.env
+```
+
+with at least:
+
+```bash
+DISCORD_TOKEN=...
+```
+
+### Step C: configure workspace policy
+Create:
+
+```bash
+~/.local/state/pi-discord-bot/agent/discord-policy.json
+```
+
+### Step D: start bot
+
+```bash
+npx tsx src/main.ts ./agent
+```
+
+or with systemd.
+
+This is the intended operator workflow.
+The workspace should live outside the repo.
+
+---
+
+## 6. systemd setup
+
+Typical setup:
+
+```bash
+mkdir -p ~/.config/systemd/user ~/.config
+cp pi-discord-bot.service ~/.config/systemd/user/
+cp pi-discord-bot.env.example ~/.config/pi-discord-bot.env
+$EDITOR ~/.config/pi-discord-bot.env
+systemctl --user daemon-reload
+systemctl --user enable --now pi-discord-bot.service
+```
+
+Useful commands:
+
+```bash
+systemctl --user status pi-discord-bot.service
+journalctl --user -u pi-discord-bot.service -f
+systemctl --user restart pi-discord-bot.service
+```
+
+---
+
+## 7. Troubleshooting checklist
+
+### Bot starts but cannot answer model requests
+Check that Pi auth works outside the bot first.
+If Pi itself is not authenticated, the Discord bot will not have usable model access either.
+
+### Slash commands do not show immediately
+If commands are global, Discord may take time to refresh them.
+This is a Discord propagation issue, not necessarily a bot bug.
+
+### Normal guild messages are ignored
+Check:
+- `guildIds`
+- `channelIds`
+- `mentionMode`
+
+If `mentionMode` is `mention-only`, normal chat must mention the bot.
+Text commands like `/tree` are handled separately.
+
+### Admin actions fail
+Check bot permissions in Discord:
+- Manage Channels
+- Create Public Threads
+- Create Private Threads
+- Send Messages
+- Read Message History
+
+---
+
+## 8. Recommended operator practice
+
+If you maintain this repo for other Pi users:
+- keep env docs focused on `DISCORD_TOKEN`
+- document Pi shared auth instead of provider-specific API keys
+- keep `./agent` out of version control
+- treat Discord policy and systemd as the main operator knobs

package/docs/publishing-checklist.md

@@ -0,0 +1,95 @@
+# Publishing checklist
+
+Use this checklist before publishing `pi-discord-bot` as a public repo or future npm package.
+
+## 1. Publish safety review
+
+### Do not publish runtime/private state
+Make sure these are **not** included in your release commit or package contents:
+- workspace contents
+- `~/.config/pi-discord-bot.env`
+- Pi auth files
+- Discord tokens
+- logs with user conversations
+- downloaded attachments
+
+### Current repo risk summary
+The main source tree does **not** contain obvious hardcoded secrets.
+The main publishing risk is runtime data in the workspace directory, which should live outside the repo and is private operational state.
+
+## 2. Git repo checklist
+
+Before pushing to GitHub/GitLab:
+
+```bash
+git status
+```
+
+Check that these are ignored or absent:
+- workspace contents
+- `.env`
+- local auth/config files
+- generated `.tgz` package artifacts
+
+Recommended validation:
+
+```bash
+npm test
+npx tsc --noEmit
+```
+
+## 3. Repo metadata checklist
+
+Before publishing the repo publicly, confirm:
+- `README.md` is current
+- `docs/operator-env-config.md` is current
+- `LICENSE` is correct for your intended distribution
+- `package.json` metadata is updated with your real repository URLs
+
+Fields to replace before public release:
+- `repository.url`
+- `homepage`
+- `bugs.url`
+- author/publisher metadata if you want them included
+
+## 4. npm publishing checklist
+
+When publishing to npm:
+1. confirm `dist/` build output is correct
+2. confirm package metadata is correct
+3. confirm the package contents are safe
+4. run a dry pack:
+
+```bash
+npm pack --dry-run
+```
+
+5. inspect the file list carefully
+6. only then publish
+
+## 5. Recommended package-content review
+
+Run:
+
+```bash
+npm pack --dry-run
+```
+
+Verify that the package would include only things like:
+- `dist/`
+- `README.md`
+- `LICENSE`
+- maybe selected docs/examples
+
+It should **not** include:
+- workspace contents
+- tests unless you want them shipped
+- local config
+- private logs
+
+## 6. Release recommendation
+
+Recommended order:
+1. publish the Git repo
+2. publish the npm package
+3. let users install either from npm or from source, depending on their workflow

package/docs/using-skill-in-pi.md

@@ -0,0 +1,128 @@
+# Use `pi-discord-bot` from Pi with almost zero setup
+
+This guide is for people who already use **Pi CLI / TUI** and want Pi itself to guide the bot setup.
+
+The goal is:
+- install the package as a Pi package
+- load the skill
+- let the skill walk you through the rest
+
+## Recommended path: install the skill from npm
+
+Once the package is published, install it into Pi with:
+
+```bash
+pi install npm:pi-discord-bot
+```
+
+Then start Pi:
+
+```bash
+pi
+```
+
+Then run:
+
+```text
+/skill:pi-discord-bot
+```
+
+Or directly:
+
+```text
+/skill:pi-discord-bot help me set up and run the Discord bot
+```
+
+That is the preferred low-friction workflow.
+
+---
+
+## Install the skill from source instead
+
+If you have the repo checked out locally, you can install it into Pi from the local path:
+
+```bash
+pi install /absolute/path/to/pi-discord-bot
+```
+
+Then:
+
+```bash
+pi
+```
+
+And in Pi:
+
+```text
+/skill:pi-discord-bot
+```
+
+This is the best option if you are developing the repo locally.
+
+---
+
+## No install path if you are already inside the repo
+
+If you are already in the repo, Pi can discover the project skill automatically:
+
+```bash
+cd ~/pi-discord-bot
+pi
+```
+
+Then either ask naturally:
+
+```text
+Help me configure this bot.
+```
+
+or force the skill explicitly:
+
+```text
+/skill:pi-discord-bot
+```
+
+---
+
+## What to ask Pi
+
+After the skill is loaded, ask Pi things like:
+- "Set up this bot with the simplest workflow."
+- "Help me configure `~/.config/pi-discord-bot.env`."
+- "Help me create the workspace `discord-policy.json`."
+- "Set this up with the included systemd user service."
+- "The bot is not responding in Discord; debug it."
+
+The skill is meant to drive the setup flow for you, instead of making you manually piece the repo together.
+
+---
+
+## Best practice
+
+If you want the cleanest user flow, do this:
+
+### npm package flow
+```bash
+pi install npm:pi-discord-bot
+pi
+```
+
+Then in Pi:
+
+```text
+/skill:pi-discord-bot help me set up the bot
+```
+
+### source flow
+```bash
+pi install /absolute/path/to/pi-discord-bot
+pi
+```
+
+Then in Pi:
+
+```text
+/skill:pi-discord-bot help me set up the bot
+```
+
+That way the user mainly interacts with **Pi + the skill**, not a long manual checklist.

package/package.json

@@ -0,0 +1,66 @@
+{
+  "name": "pi-discord-bot",
+  "version": "0.1.1",
+  "description": "A small Discord harness built around Pi primitives.",
+  "license": "MIT",
+  "type": "module",
+  "keywords": [
+    "pi",
+    "pi-package",
+    "discord",
+    "bot",
+    "agent",
+    "discord.js"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/shuyhere/pi-discord-bot.git"
+  },
+  "homepage": "https://github.com/shuyhere/pi-discord-bot#readme",
+  "bugs": {
+    "url": "https://github.com/shuyhere/pi-discord-bot/issues"
+  },
+  "engines": {
+    "node": ">=22"
+  },
+  "files": [
+    "dist",
+    "skills",
+    "README.md",
+    "LICENSE",
+    "docs",
+    "discord-policy.example.json",
+    "pi-discord-bot.env.example",
+    "pi-discord-bot.service"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "bin": {
+    "pi-discord-bot": "dist/main.js"
+  },
+  "pi": {
+    "skills": [
+      "./skills"
+    ]
+  },
+  "scripts": {
+    "dev": "tsx watch src/main.ts",
+    "build": "tsc -p tsconfig.json",
+    "start": "node dist/main.js",
+    "test": "node --import tsx --test src/**/*.test.ts",
+    "prepublishOnly": "npm run build && npm test"
+  },
+  "dependencies": {
+    "@mariozechner/pi-agent-core": "^0.64.0",
+    "@mariozechner/pi-ai": "^0.64.0",
+    "@mariozechner/pi-coding-agent": "^0.64.0",
+    "@sinclair/typebox": "^0.34.41",
+    "discord.js": "^14.19.3"
+  },
+  "devDependencies": {
+    "@types/node": "^24.3.0",
+    "tsx": "^4.19.2",
+    "typescript": "^5.7.3"
+  }
+}

package/pi-discord-bot.env.example

@@ -0,0 +1,12 @@
+# Required
+DISCORD_TOKEN=replace_me
+
+# Optional: useful for guild-scoped slash command iteration
+# DISCORD_GUILD_ID=123456789012345678
+
+# Optional: external runtime workspace directory.
+# Default if unset:
+#   $XDG_STATE_HOME/pi-discord-bot/agent
+# or:
+#   ~/.local/state/pi-discord-bot/agent
+# PI_DISCORD_BOT_WORKDIR=/absolute/path/to/pi-discord-bot-agent

package/pi-discord-bot.service

@@ -0,0 +1,16 @@
+[Unit]
+Description=Pi Discord Bot
+After=network-online.target
+Wants=network-online.target
+
+[Service]
+Type=simple
+WorkingDirectory=%h/pi-discord-bot
+EnvironmentFile=%h/.config/pi-discord-bot.env
+ExecStart=/usr/bin/env npx tsx src/main.ts
+Restart=always
+RestartSec=5
+TimeoutStopSec=20
+
+[Install]
+WantedBy=default.target