From 1d1342fcf00c4c4342e5631ac372d086cffefb32 Mon Sep 17 00:00:00 2001 From: Rahul Tyagi Date: Sat, 13 Jun 2026 23:17:17 +0530 Subject: [PATCH] chore: add CI, issue/PR templates, contributing guide, and changelog - .github/workflows/ci.yml: bun install + typecheck + tests + shellcheck on push and PR (concurrency-cancels older runs) - .github/ISSUE_TEMPLATE/: structured bug-report and feature-request forms; config.yml disables blank issues and points discussions elsewhere - .github/pull_request_template.md: per-type checklist tying into the core/ + adapters/ layout - CONTRIBUTING.md: quick-start, project layout, recipes for adding new pets and new agent adapters - CODE_OF_CONDUCT.md: Contributor Covenant 2.1 - CHANGELOG.md: v1.0.0 entry covering the multi-agent work - README: add CI / license / bun badges - .gitignore: cover .DS_Store, editor dirs, local .campy state, bun lockfile --- .github/ISSUE_TEMPLATE/bug_report.yml | 56 ++++++++++++++++++ .github/ISSUE_TEMPLATE/config.yml | 5 ++ .github/ISSUE_TEMPLATE/feature_request.yml | 29 +++++++++ .github/pull_request_template.md | 22 +++++++ .github/workflows/ci.yml | 46 +++++++++++++++ .gitignore | 16 ++++- CHANGELOG.md | 33 +++++++++++ CODE_OF_CONDUCT.md | 41 +++++++++++++ CONTRIBUTING.md | 68 ++++++++++++++++++++++ README.md | 2 + 10 files changed, 317 insertions(+), 1 deletion(-) create mode 100644 .github/ISSUE_TEMPLATE/bug_report.yml create mode 100644 .github/ISSUE_TEMPLATE/config.yml create mode 100644 .github/ISSUE_TEMPLATE/feature_request.yml create mode 100644 .github/pull_request_template.md create mode 100644 .github/workflows/ci.yml create mode 100644 CHANGELOG.md create mode 100644 CODE_OF_CONDUCT.md create mode 100644 CONTRIBUTING.md diff --git a/.github/ISSUE_TEMPLATE/bug_report.yml b/.github/ISSUE_TEMPLATE/bug_report.yml new file mode 100644 index 0000000..ade14df --- /dev/null +++ b/.github/ISSUE_TEMPLATE/bug_report.yml @@ -0,0 +1,56 @@ +name: Bug report +description: Something in campy is broken or behaving unexpectedly +title: "bug: " +labels: ["bug"] +body: + - type: markdown + attributes: + value: | + Thanks for the report — a focused reproduction makes fixes fast. + - type: textarea + id: what-happened + attributes: + label: What happened? + description: Describe the behavior you saw and what you expected. + placeholder: "When I ran `campy attach` in zellij, ..." + validations: + required: true + - type: textarea + id: repro + attributes: + label: Steps to reproduce + placeholder: | + 1. Install with `bun add -g github:dropdevrahul/campy` + 2. Run `campy install claude-code` + 3. ... + validations: + required: true + - type: dropdown + id: agent + attributes: + label: Which agent are you using? + options: + - Claude Code + - OpenCode + - Pi + - Gemini CLI + - Codex CLI + - Cursor CLI + - Aider + - Not agent-specific + validations: + required: true + - type: input + id: env + attributes: + label: Environment + description: OS, terminal, bun version (`bun --version`) + placeholder: "macOS 14.5, Ghostty 1.0, bun 1.3.12" + validations: + required: true + - type: textarea + id: logs + attributes: + label: Relevant logs or state file contents + description: Output of `campy status`, contents of `~/.campy/state.json`, or terminal output. Use code fences. + render: shell diff --git a/.github/ISSUE_TEMPLATE/config.yml b/.github/ISSUE_TEMPLATE/config.yml new file mode 100644 index 0000000..87f3f61 --- /dev/null +++ b/.github/ISSUE_TEMPLATE/config.yml @@ -0,0 +1,5 @@ +blank_issues_enabled: false +contact_links: + - name: Question / discussion + url: https://github.com/dropdevrahul/campy/discussions + about: General questions, ideas, or "how do I…" — please post in Discussions instead of opening an issue. diff --git a/.github/ISSUE_TEMPLATE/feature_request.yml b/.github/ISSUE_TEMPLATE/feature_request.yml new file mode 100644 index 0000000..42d4a51 --- /dev/null +++ b/.github/ISSUE_TEMPLATE/feature_request.yml @@ -0,0 +1,29 @@ +name: Feature request +description: Suggest a new pet, agent, or capability +title: "feat: " +labels: ["enhancement"] +body: + - type: textarea + id: problem + attributes: + label: What problem does this solve? + description: Why is this worth adding? + validations: + required: true + - type: textarea + id: proposal + attributes: + label: Proposed approach + description: Optional. If you have an idea for how to build it. + - type: dropdown + id: kind + attributes: + label: What kind of feature? + options: + - New pet + - New agent adapter + - New CLI subcommand + - Animation / theme + - Other + validations: + required: true diff --git a/.github/pull_request_template.md b/.github/pull_request_template.md new file mode 100644 index 0000000..f3f14cb --- /dev/null +++ b/.github/pull_request_template.md @@ -0,0 +1,22 @@ +## Summary + + + +## Type + +- [ ] Bug fix +- [ ] New feature (new pet, agent, or capability) +- [ ] Refactor / internal cleanup +- [ ] Docs only + +## Checklist + +- [ ] `bun test` passes locally +- [ ] `bun run typecheck` passes locally +- [ ] If you added a new pet: registered in `core/pets/index.ts` + entries in `PET_ICONS`, `PET_GREETINGS`, `PET_PERSONALITY` +- [ ] If you added a new agent adapter: an entry in `core/detect.ts` and an installer in `cli/campy.ts` +- [ ] README / CLAUDE.md updated if behavior changed + +## Test plan + + diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml new file mode 100644 index 0000000..9a17607 --- /dev/null +++ b/.github/workflows/ci.yml @@ -0,0 +1,46 @@ +name: CI + +on: + push: + branches: [main] + pull_request: + branches: [main] + +concurrency: + group: ${{ github.workflow }}-${{ github.ref }} + cancel-in-progress: true + +jobs: + test: + name: Test & Typecheck + runs-on: ubuntu-latest + steps: + - name: Checkout + uses: actions/checkout@v4 + + - name: Install bun + uses: oven-sh/setup-bun@v2 + with: + bun-version: "1.3.12" + + - name: Install dependencies + run: bun install --frozen-lockfile || bun install + + - name: Typecheck + run: bun run typecheck + + - name: Run tests + run: bun test + + lint-shell: + name: ShellCheck adapter scripts + runs-on: ubuntu-latest + steps: + - name: Checkout + uses: actions/checkout@v4 + + - name: Run shellcheck + uses: ludeeus/action-shellcheck@2.0.0 + with: + scandir: ./adapters + severity: warning diff --git a/.gitignore b/.gitignore index 3d7e996..00f2eab 100644 --- a/.gitignore +++ b/.gitignore @@ -1,2 +1,16 @@ node_modules -.worktrees \ No newline at end of file +.worktrees + +# macOS +.DS_Store + +# Editor/IDE +.vscode/ +.idea/ +*.swp + +# Local runtime state +.campy/ + +# Bun +bun.lockb diff --git a/CHANGELOG.md b/CHANGELOG.md new file mode 100644 index 0000000..5ee5a46 --- /dev/null +++ b/CHANGELOG.md @@ -0,0 +1,33 @@ +# Changelog + +All notable changes to this project will be documented in this file. The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/), and this project loosely follows [Semantic Versioning](https://semver.org/). + +## [1.0.0] — 2026-06-13 + +First proper release. campy is now a multi-agent project rather than an OpenCode-only plugin. + +### Added + +- **Portable `core/` module** — single source of truth for all pet logic (types, animation engine, GIF engine, pets, theme, personality, happiness, events, store, actions, runtime, render, detect). +- **`campy` CLI** (`cli/campy.ts`) — subcommands: `watch`, `attach`, `statusline`, `mcp`, `event`, `feed`, `play`, `pet`, `sleep`, `wake`, `switch`, `status`, `setup`, `install`. +- **State-file bus** — short-lived hooks mutate `~/.campy/state.json` (atomic temp + rename); long-lived renderers read it. +- **MCP adapter** (`adapters/mcp/`) — dependency-free stdio JSON-RPC 2.0 server. Watches the project directory and emits `file_edited` events; exposes `campy_status`, `campy_feed`, `campy_play`, `campy_pet`, `campy_switch` tools that return inline ASCII pet cards. Unlocks Gemini CLI, Codex CLI, and Cursor CLI in one go. +- **Claude Code adapter** (`adapters/claude-code/`) — `post-tool-use`, `pre-tool-use`, `session-start`, `stop` hooks + statusline + `/campy:*` slash commands. Zero token cost for passive reactions. +- **Pi adapter** (`adapters/pi/`) — native in-process TUI widget extension. +- **Gemini adapter** (`adapters/gemini/`) — `gemini-extension.json` + `GEMINI.md` context file. +- **Native installers** — `campy install claude-code | opencode | pi | gemini | codex | cursor | aider`. Each writes the tool's own config format and is idempotent. +- **`campy setup`** — auto-detects installed agents via `core/detect.ts` and wires each natively. +- **`campy attach`** — auto-spawns a side `campy watch` pane in tmux / zellij / wezterm / kitty; graceful manual fallback otherwise. +- **Claude Code marketplace manifest** (`.claude-plugin/marketplace.json`) — installable via `/plugin marketplace add dropdevrahul/campy`. +- **Tests** — 38 unit tests across `core/` (reactions, happiness, store), MCP dispatch, and agent detection. +- **Docs** — `CLAUDE.md` architecture guide and `docs/superpowers/specs/2026-06-13-cli-agent-support-design.md` design spec. + +### Changed + +- **`.opencode/plugins/`** refactored — `lib/*.ts`, `config.ts`, and `pets/*.ts` are now thin `export *` re-export shims pointing at `core/`. Entry files (`pets.tsx`, `gif-pets.tsx`) unchanged. +- **`package.json`** — renamed to `campy`; added `bin`, `files`, and `exports` (`./core`, `./pi`, `./mcp`); repository/bugs/homepage URLs updated. +- **README** — install instructions cover the two paths that work today (GitHub install via `bun add -g github:dropdevrahul/campy`, and clone + symlink); per-agent install table added. + +### Preserved + +- **`ghost-pet/`** — legacy standalone Bash plugin for Claude Code is still in the repo for backward compatibility while the new `adapters/claude-code/` adapter rolls out. diff --git a/CODE_OF_CONDUCT.md b/CODE_OF_CONDUCT.md new file mode 100644 index 0000000..eb744d6 --- /dev/null +++ b/CODE_OF_CONDUCT.md @@ -0,0 +1,41 @@ +# Contributor Covenant Code of Conduct + +## Our pledge + +We as members, contributors, and leaders pledge to make participation in our community a harassment-free experience for everyone, regardless of age, body size, visible or invisible disability, ethnicity, sex characteristics, gender identity and expression, level of experience, education, socio-economic status, nationality, personal appearance, race, religion, or sexual identity and orientation. + +We pledge to act and interact in ways that contribute to an open, welcoming, diverse, inclusive, and healthy community. + +## Our standards + +Examples of behavior that contributes to a positive environment: + +* Demonstrating empathy and kindness toward other people +* Being respectful of differing opinions, viewpoints, and experiences +* Giving and gracefully accepting constructive feedback +* Accepting responsibility and apologizing to those affected by our mistakes +* Focusing on what is best for the overall community + +Examples of unacceptable behavior: + +* The use of sexualized language or imagery, and sexual attention or advances of any kind +* Trolling, insulting or derogatory comments, and personal or political attacks +* Public or private harassment +* Publishing others' private information without their explicit permission +* Other conduct which could reasonably be considered inappropriate in a professional setting + +## Enforcement responsibilities + +Project maintainers are responsible for clarifying and enforcing our standards of acceptable behavior and will take appropriate and fair corrective action in response to any behavior that they deem inappropriate, threatening, offensive, or harmful. + +## Scope + +This Code of Conduct applies within all community spaces, and also applies when an individual is officially representing the community in public spaces. + +## Enforcement + +Instances of abusive, harassing, or otherwise unacceptable behavior may be reported to the project maintainers responsible for enforcement by opening a private channel (see the maintainer profile on GitHub). All complaints will be reviewed and investigated promptly and fairly. + +## Attribution + +This Code of Conduct is adapted from the [Contributor Covenant](https://www.contributor-covenant.org), version 2.1, available at . diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md new file mode 100644 index 0000000..55a47d3 --- /dev/null +++ b/CONTRIBUTING.md @@ -0,0 +1,68 @@ +# Contributing to campy + +Thanks for the interest! campy is small and friendly — PRs welcome for new pets, new agent adapters, animation polish, and bug fixes. + +## Quick start + +```bash +git clone https://github.com/dropdevrahul/campy.git +cd campy +bun install +bun test # 38 tests +bun run typecheck # tsc --noEmit +``` + +Run the pet locally: + +```bash +bun cli/campy.ts watch +bun cli/campy.ts statusline +bun cli/campy.ts status +``` + +## Project layout + +See `CLAUDE.md` for the full architecture tour. The short version: + +| Directory | What lives there | +|---|---| +| `core/` | Portable pet logic (animation, store, runtime, render). No host-specific code. | +| `cli/campy.ts` | The `campy` binary. | +| `adapters/` | One subdirectory per host (claude-code, pi, mcp, gemini). | +| `.opencode/plugins/` | Thin shims re-exporting from `core/`. | +| `tests/` | `bun:test` unit tests. | +| `assets/` | GIFs + generated ASCII frame JSON. | + +## Adding a new pet + +1. Create `core/pets/.ts` exporting a `PetAnimations` object — use `core/pets/cat.ts` as the reference. +2. Register in `core/pets/index.ts` (`PET_ANIMATIONS` map). +3. Add entries to `PET_ICONS`, `PET_COLORS`, `PET_GREETINGS`, `PET_PERSONALITY` in `core/theme.ts` and `core/personality.ts`. +4. Run `bun test` and add a smoke test if behavior is non-trivial. +5. Verify in OpenCode (`npm run dev`) and the CLI (`bun cli/campy.ts switch && bun cli/campy.ts watch`). + +## Adding a new agent adapter + +1. Add the agent id to `AgentId` and a detection rule in `core/detect.ts`. +2. Add an installer in `cli/campy.ts` (use existing installers as templates — keep them idempotent). +3. Add the adapter under `adapters//` — either an MCP-style server (see `adapters/mcp/`), short-lived hooks (see `adapters/claude-code/`), or an in-process extension (see `adapters/pi/`). +4. Document the install path in `README.md` and `CLAUDE.md`. + +## Style notes + +- TypeScript strict mode. No `any` unless wrapping an external surface (e.g. host-agent types we don't own). +- Prefer adding to `core/` over duplicating logic in an adapter. +- Keep commits small and focused — `feat:`, `fix:`, `docs:`, `test:`, `chore:` prefixes (loose Conventional Commits — not enforced). +- No comments unless the *why* is non-obvious. + +## Tests + +`bun test` runs all of `tests/`. Add tests for new event reactions, store mutations, agent detection, or MCP dispatch. UI animation is verified manually — note that in your PR description. + +## Reporting bugs + +Use the bug template at . The most useful things to include: output of `campy status`, contents of `~/.campy/state.json`, and which agent + terminal you're using. + +## Code of conduct + +Be kind. See [CODE_OF_CONDUCT.md](./CODE_OF_CONDUCT.md). diff --git a/README.md b/README.md index 5dc796e..6a44fe1 100644 --- a/README.md +++ b/README.md @@ -3,7 +3,9 @@ # campy +[![CI](https://github.com/dropdevrahul/campy/actions/workflows/ci.yml/badge.svg)](https://github.com/dropdevrahul/campy/actions/workflows/ci.yml) [![License: MIT](https://img.shields.io/badge/License-MIT-green.svg)](https://opensource.org/licenses/MIT) +[![Made with bun](https://img.shields.io/badge/made%20with-bun-black.svg)](https://bun.sh) Animated terminal pets for CLI coding agents — Claude Code, OpenCode, Pi, Gemini CLI, Codex CLI, Cursor CLI, Aider.