@senad-d/branchme 0.1.1

package/.env.example

@@ -0,0 +1,5 @@
+# BranchMe GitHub token template.
+# Copy this file to .env only when you need pull_request support.
+# Keep committed placeholders empty; put real tokens only in your local .env file.
+GITHUB_TOKEN=
+GH_TOKEN=

package/CHANGELOG.md

@@ -0,0 +1,10 @@
+# Changelog
+
+## 0.1.0 - Unreleased
+
+- Implemented the `branchme` informational slash command with help aliases.
+- Added strict BranchMe tools: `branch_status`, `change_branch`, `create_branch`, `push_branch`, and `pull_request`.
+- Added argv-style git helpers for repository status, branch validation/creation/switching, clean-worktree preflight, upstream detection, and current-branch push/publish.
+- Added GitHub repository resolution, environment-token and local `.env` token fallback handling, REST pull request creation, response validation, and token redaction.
+- Added unit tests with mocked `pi.exec` and `fetch` for git helpers, GitHub helpers, command behavior, tool schemas, prompt metadata, and extension registration.
+- Updated public documentation for implemented behavior, security boundaries, package structure, and validation commands.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Senad Dizdarević
+
+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,347 @@
+<p align="center">
+  <img alt="BranchMe logo" src="img/icon.svg" width="128">
+</p>
+
+<p align="center">
+  <a href="https://pi.dev"><img alt="pi package" src="https://img.shields.io/badge/pi-package-6f42c1?style=flat-square" /></a>
+  <a href="https://www.npmjs.com/package/@senad-d/branchme"><img alt="npm" src="https://img.shields.io/npm/v/%40senad-d%2Fbranchme?style=flat-square" /></a>
+  <a href="LICENSE"><img alt="license" src="https://img.shields.io/badge/license-MIT-blue?style=flat-square" /></a>
+</p>
+
+<p align="center">
+  Current-repository branch and pull request tools for <a href="https://pi.dev">pi</a>.
+  <br />Inspect branch state, switch/create branches, push, and open GitHub PRs from pi prompts.
+</p>
+
+---
+
+BranchMe is a Pi extension for safe branch workflow automation. It adds an informational `/branchme` command and five agent-callable tools that inspect the current repository, switch to an existing local branch, create a branch from the current `HEAD`, push the current branch, and create a GitHub pull request.
+
+<table align="center">
+  <tr>
+    <th>BranchMe demo</th>
+  </tr>
+  <tr>
+    <td align="center">
+      <img src="img/demo.gif" alt="BranchMe demo: inspect branch status and use branch workflow tools in pi" title="BranchMe demo" width="760">
+    </td>
+  </tr>
+</table>
+
+- **Current-repository only:** Git and GitHub operations are scoped to the checkout where pi is running.
+- **Commit-safe:** BranchMe never stages files, creates commits, generates commit messages, rebases, merges, resets, or edits files directly.
+- **Strict tools:** tool schemas reject extra properties such as `force`, `stash`, `discard`, `owner`, `repo`, `path`, or `baseRef`.
+- **PR-ready:** create GitHub pull requests from existing local branches after verifying the `headBranch` matches GitHub and the base is visible, with explicit PR fields and `GITHUB_TOKEN` or `GH_TOKEN` from the process environment or a local `.env` fallback.
+
+> **Security:** pi packages run with your full system permissions. BranchMe can run local `git` commands, switch/create branches, push the current branch, and call the GitHub REST API to create pull requests. Read [`SECURITY.md`](SECURITY.md).
+
+## Table of Contents
+
+- [Quick Start](#quick-start)
+- [Installation](#installation)
+- [Repository and GitHub Setup](#repository-and-github-setup)
+- [Configuration](#configuration)
+- [Commands](#commands)
+- [Tools](#tools)
+- [Workflow and Boundaries](#workflow-and-boundaries)
+- [GitHub Actions](#github-actions)
+- [Troubleshooting](#troubleshooting)
+- [Diagnostics](#diagnostics)
+- [Update and Uninstall](#update-and-uninstall)
+- [Development](#development)
+- [Publishing](#publishing)
+- [License](#license)
+
+---
+
+## Quick Start
+
+```bash
+pi install npm:@senad-d/branchme
+cd /path/to/your/git/repo
+pi
+```
+
+Inside pi:
+
+```text
+/branchme
+/branchme help
+```
+
+Ask the agent to use BranchMe tools explicitly, for example:
+
+```text
+Use branch_status, then create a branch named feature/update-docs with create_branch.
+```
+
+A typical BranchMe flow is:
+
+1. Inspect state with `branch_status`.
+2. Switch with `change_branch` or create from current `HEAD` with `create_branch`.
+3. Make edits and commit outside BranchMe.
+4. Push the current branch with `push_branch`.
+5. After `push_branch` completes and GitHub can see the branches, create a pull request with `pull_request`.
+
+BranchMe is tool-based. The slash command is informational only and never changes branches, pushes, commits, stages, edits files, or opens pull requests.
+
+---
+
+## Installation
+
+| Scope | Command | Notes |
+| --- | --- | --- |
+| Global | `pi install npm:@senad-d/branchme` | Loads in every trusted pi project. |
+| Project-local | `pi install npm:@senad-d/branchme -l` | Writes to `.pi/settings.json` in the current project. |
+| One run | `pi -e npm:@senad-d/branchme` | Try without changing settings. |
+| Git | `pi install git:github.com/senad-d/branchme@<tag>` | Pin a tag or commit. |
+| Local checkout | `pi --no-extensions -e .` | Develop or test this repository in isolation. |
+
+Source checkout:
+
+```bash
+git clone https://github.com/senad-d/branchme.git
+cd branchme
+npm install --ignore-scripts
+npm run validate
+pi --no-extensions -e .
+```
+
+Use the checkout globally while developing:
+
+```bash
+pi install /absolute/path/to/branchme
+```
+
+---
+
+## Repository and GitHub Setup
+
+BranchMe does not bundle Git and does not create repositories. Start pi from inside the repository you want BranchMe to manage:
+
+```bash
+cd /path/to/your/git/repo
+git status
+git remote get-url origin
+pi
+```
+
+For pull requests, the repository must resolve to GitHub from local `origin` and/or `GITHUB_REPOSITORY`:
+
+```bash
+git remote set-url origin git@github.com:OWNER/REPO.git
+# or
+export GITHUB_REPOSITORY=OWNER/REPO
+```
+
+For `pull_request`, set a token in the process environment before starting pi:
+
+```bash
+export GITHUB_TOKEN=github_pat_...
+# or
+export GH_TOKEN=ghp_...
+pi
+```
+
+Or copy `.env.example` to `.env` in the repository root and fill in one token value:
+
+```bash
+cp .env.example .env
+$EDITOR .env
+pi
+```
+
+`push_branch` uses your normal Git remote credentials. BranchMe does not inject `GITHUB_TOKEN` into `git push`.
+When the current branch already has an upstream, BranchMe pushes an explicit `HEAD:<upstream-branch-ref>` refspec to the configured upstream remote instead of relying on a bare `git push`.
+Run `pull_request` only after `push_branch` has completed; `pull_request` preflights the GitHub `headBranch` and `baseBranch` before creating the PR and fails with retry guidance if a branch is not visible yet or the GitHub `headBranch` commit does not match the local branch.
+
+---
+
+## Configuration
+
+BranchMe has no project config file. It reads process environment variables for GitHub pull request creation and optional repository boundary checks, with a local `.env` token fallback when no process token is set. Token lookup checks `process.env.GITHUB_TOKEN`, then `process.env.GH_TOKEN`; if neither is set, BranchMe reads `.env` from the verified git root and checks `GITHUB_TOKEN`, then `GH_TOKEN`.
+
+| Variable | Meaning |
+| --- | --- |
+| `GITHUB_TOKEN` | Preferred token for `pull_request`; process environment first, then local `.env` fallback. |
+| `GH_TOKEN` | Fallback token for `pull_request`; process environment first, then local `.env` fallback. |
+| `GITHUB_REPOSITORY=owner/repo` | Optional CI fallback and boundary check for the current GitHub repository; process environment only. |
+
+BranchMe reads only `GITHUB_TOKEN` and `GH_TOKEN` from a small regular `.env` file; it rejects directories, symlinks, special files, and oversized files. BranchMe does not import other `.env` keys, read shell profiles, GitHub CLI credentials, or local credential stores. Token values are redacted from errors, tool content, and tool details.
+
+If local `origin` and `GITHUB_REPOSITORY` both resolve but disagree, `pull_request` fails closed.
+
+---
+
+## Commands
+
+| Command | Description |
+| --- | --- |
+| `/branchme` | Show a compact status panel or fallback message with current branch, GitHub repository resolution, token presence, and workflow notes. |
+| `/branchme help` | Show concise BranchMe workflow help and runtime requirements. |
+| `/branchme --help` | Alias for `/branchme help`. |
+| `/branchme -h` | Alias for `/branchme help`. |
+
+Commands are informational only. BranchMe actions are performed by agent-callable tools. `/branchme` uses the TUI panel in TUI mode, notifications in RPC mode, plain text only in print mode, and stays stdout-silent in JSON mode to avoid corrupting protocol output. Unsupported non-empty `/branchme` arguments return guidance to use `/branchme help` where the current mode can display it safely.
+
+---
+
+## Tools
+
+| Tool | Schema | Behavior |
+| --- | --- | --- |
+| `branch_status` | `{}` | Read-only git status: repo root, current branch or detached state, upstream, dirty state, ahead/behind counts, and GitHub repository when resolvable. |
+| `change_branch` | `{ "branchName": string }` | Validates `branchName`, requires `refs/heads/<branchName>` to exist locally, rejects dirty worktrees, and runs `git switch <branchName>`. |
+| `create_branch` | `{ "branchName": string }` | Validates `branchName`, rejects existing local branches, and runs `git switch -c <branchName>` from current `HEAD`. |
+| `push_branch` | `{}` | Pushes the current branch to its configured upstream remote with an explicit `HEAD:<upstream-branch-ref>` refspec, or publishes it with `git push --set-upstream origin <currentBranch>` when no upstream exists. |
+| `pull_request` | `{ "headBranch": string, "baseBranch": string, "title": string, "body": string, "draft": boolean }` | Preflights GitHub branch visibility and verifies the GitHub `headBranch` commit matches the local branch, then creates a pull request in the resolved current repository via `POST /repos/{owner}/{repo}/pulls`; branch refs must exist locally and cannot use `owner:branch`. |
+
+All schemas reject additional properties. `change_branch` never accepts `baseRef`, `force`, `stash`, `discard`, `create`, `owner`, `repo`, or path inputs. `pull_request` never accepts `owner`, `repo`, or owner-prefixed branch refs; BranchMe resolves the repository from local `origin` and/or matching `GITHUB_REPOSITORY`.
+
+---
+
+## Workflow and Boundaries
+
+Use BranchMe from pi prompts or automation that drives pi with explicit tool calls:
+
+```text
+Use branch_status.
+Create branch feature/docs-refresh from the current HEAD with create_branch.
+Push the current branch with push_branch.
+After push_branch completes, create a draft pull request from feature/docs-refresh to main titled "Refresh docs" with this body: "...".
+```
+
+BranchMe operates only on the repository where pi is running:
+
+- Git commands use `pi.exec("git", args, { cwd, signal, timeout })` with argv arrays; repository mutations run from the verified git root.
+- `change_branch` switches only to existing local branches and has no `force`, `stash`, `discard`, remote, or path input.
+- `create_branch` creates from the current `HEAD` only and has no `baseRef` input.
+- `push_branch` pushes only the current branch, uses no bare upstream `git push`, and has no `branchName` input.
+- `pull_request` creates PRs only for the resolved current GitHub repository, requires `headBranch` and `baseBranch` to exist locally, requires the GitHub `headBranch` commit to match the local branch, queues behind in-flight same-repository git mutation windows when possible, and rejects `owner:branch` head refs.
+- If local `origin` and `GITHUB_REPOSITORY` both resolve but disagree, `pull_request` fails closed.
+
+BranchMe intentionally does **not** stage files, create commits, force checkout, stash changes, discard changes, edit files directly, or generate commit messages.
+
+---
+
+## GitHub Actions
+
+GitHub Actions example:
+
+```yaml
+name: branchme-smoke
+on:
+  workflow_dispatch:
+
+permissions:
+  contents: write
+  pull-requests: write
+
+jobs:
+  branchme:
+    runs-on: ubuntu-latest
+    env:
+      GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+      GITHUB_REPOSITORY: ${{ github.repository }}
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+      - uses: actions/setup-node@v4
+        with:
+          node-version: 22
+      - run: npm install -g --ignore-scripts @earendil-works/pi-coding-agent
+      - run: pi --no-extensions -e npm:@senad-d/branchme --help
+```
+
+Ensure the token and Git credentials have permission for the branch and pull request operation you ask BranchMe to perform.
+
+---
+
+## Troubleshooting
+
+| Problem | Try |
+| --- | --- |
+| Not a git repository | Start pi from inside a git checkout. |
+| Detached `HEAD` | Use `change_branch` to switch to an existing local branch, or checkout a branch before `create_branch` or `push_branch`. |
+| Branch already exists | Choose a new local branch name for `create_branch`, or use `change_branch` to switch to it. |
+| Branch does not exist locally | Create a local branch first; `change_branch` does not checkout remote branches. |
+| Dirty worktree before branch switch | Commit, stash, or discard changes outside BranchMe before using `change_branch`. |
+| Push fails | Confirm the current branch is correct and your normal Git remote credentials can push. |
+| PR auth fails | Set `GITHUB_TOKEN` or `GH_TOKEN` before starting pi, or copy `.env.example` to `.env` and fill in one token. |
+| PR branch does not exist locally | Create or fetch/check out the local `headBranch` and `baseBranch` branches first; BranchMe does not use remote-only or cross-repository PR refs. |
+| PR branch is not visible or is stale on GitHub | Run `push_branch`, wait for it to complete, then retry `pull_request`; do not batch `push_branch` and `pull_request` in the same assistant tool call. |
+| Repository mismatch | Make `origin` and `GITHUB_REPOSITORY` refer to the same `owner/repo`. |
+| Need a commit | Use CommitMe or normal git commands; BranchMe never commits. |
+| Other extensions interfere | Test with `pi --no-extensions -e .`. |
+
+---
+
+## Diagnostics
+
+From a source checkout:
+
+```bash
+npm run validate
+npm run check:pack
+printf '/branchme help\n/quit\n' | pi --no-extensions -e .
+```
+
+Validation covers TypeScript typechecking, formatting checks, unit tests, package checks, checkout Pi runtime smoke, and package-content verification. The checkout smoke loads BranchMe through Pi, then uses a temporary verifier command to confirm all five BranchMe tools are visible through `pi.getAllTools()` with strict schemas and prompt metadata. Smoke-test notes are recorded in [`docs/SMOKE_TEST.md`](docs/SMOKE_TEST.md), and TUI/help captures are stored in [`docs/TUI_CAPTURE.md`](docs/TUI_CAPTURE.md).
+
+Refresh TUI captures intentionally with:
+
+```bash
+UPDATE_TUI_CAPTURE=1 node --test test/tui-capture.test.mjs
+```
+
+---
+
+## Update and Uninstall
+
+```bash
+pi update --extensions                  # update installed pi packages
+pi update npm:@senad-d/branchme        # update BranchMe only
+pi remove npm:@senad-d/branchme        # remove global install
+pi remove npm:@senad-d/branchme -l     # remove project-local install
+```
+
+---
+
+## Development
+
+```bash
+npm install
+npm run typecheck
+npm run format:check
+npm run test
+npm run check:pack
+npm run validate
+npm run smoke:pi:packed
+pi --no-extensions -e .
+```
+
+`npm run check:pack` verifies the npm package does not include local state, specs, caches, `node_modules`, real environment files, or other private development artifacts. The safe `.env.example` template is included.
+`npm run smoke:pi` is the checkout runtime smoke and verifies BranchMe command output plus real Pi tool registration metadata.
+`npm run smoke:pi:packed` is the release-gate smoke: it packs the npm artifact into a temporary directory, installs it with production dependency settings, and runs pi against the installed package.
+
+---
+
+## Publishing
+
+BranchMe publishes to npm as `@senad-d/branchme`. You need an npm account with publish access to the `@senad-d` scope.
+
+```bash
+npm login
+npm whoami
+npm run release:check # optional preflight; the publish script runs this too
+node scripts/publish-npm.mjs
+```
+
+The publish script requires a clean working tree, asks for the version number, runs `npm run release:check` (validation plus installed-package smoke), runs `npm version <version>` to update `package.json` and `package-lock.json`, creates the `v<version>` git tag, publishes with `npm publish --access public`, and then offers to push the release commit and tag.
+
+Run it only from a clean working tree after updating `CHANGELOG.md`.
+
+## License
+
+MIT

package/SECURITY.md

@@ -0,0 +1,77 @@
+# Security Policy
+
+## Trust model
+
+Pi packages and extensions run with the full local permissions of the user account that starts Pi. Review BranchMe source before installing it, pin versions in sensitive environments, and install only from trusted sources.
+
+```bash
+pi install npm:@senad-d/branchme@<version>
+pi install git:https://github.com/senad-d/branchme@<tag>
+```
+
+## Git behavior
+
+BranchMe runs local `git` commands through Pi's extension API with argv-style arguments. Repository mutations first resolve the git root and then run from that verified root.
+
+Implemented git mutations are limited to:
+
+- `change_branch`: `git switch <branchName>` after branch-name validation, local `refs/heads/<branchName>` verification, and clean-worktree preflight.
+- `create_branch`: `git switch -c <branchName>` from current `HEAD` after branch-name validation and existing-branch checks.
+- `push_branch`: `git push <upstreamRemote> HEAD:<upstreamBranchRef>` for the current branch when an upstream exists, or `git push --set-upstream origin <currentBranch>` when no upstream exists.
+
+Branch switching can update working-tree files as normal Git checkout behavior. Mutating branch operations for the same repository are serialized to avoid same-turn branch races. `pull_request` also uses the same repository queue around PR preflight and creation so it can wait behind an already-started same-repository push. BranchMe rejects dirty worktrees before `change_branch` and does not force checkout, stash, stage files, create commits, reset, rebase, merge, or edit files directly.
+
+## Network behavior
+
+BranchMe makes network requests only for `pull_request`, which calls the GitHub REST API:
+
+```text
+GET  https://api.github.com/repos/{owner}/{repo}/branches/{headBranch}
+GET  https://api.github.com/repos/{owner}/{repo}/branches/{baseBranch}
+POST https://api.github.com/repos/{owner}/{repo}/pulls
+```
+
+The branch preflight requests have no body. BranchMe uses the `headBranch` preflight response to compare GitHub's branch commit with the local branch commit before creating the PR. The PR request body contains only the explicit PR fields supplied to the tool: title, head branch, base branch, body, and draft flag.
+
+## Repository boundary
+
+BranchMe operates on the current repository only.
+
+- The GitHub repository is inferred from local `origin` and/or `GITHUB_REPOSITORY`.
+- Tool inputs never accept filesystem paths, `owner`, `repo`, or owner-prefixed `owner:branch` PR refs.
+- `change_branch` accepts only `branchName` and never creates branches, checks out remote branches, forces, stashes, or discards changes.
+- If local `origin` and `GITHUB_REPOSITORY` both resolve but disagree, PR creation fails closed.
+- PR branch inputs are validated as existing local branch-name refs; missing local branches and cross-repository `head` values are rejected before token lookup or any GitHub request.
+- PR branch inputs must also be visible on GitHub before the PR is created, and `headBranch` must match the local branch commit; unpublished or stale `headBranch` values fail with guidance to run `push_branch`, wait for it to complete, and retry `pull_request`.
+
+## Credentials
+
+`pull_request` checks `process.env.GITHUB_TOKEN`, then `process.env.GH_TOKEN`. If neither process token is set, BranchMe reads a local `.env` file from the verified git root and checks:
+
+- `GITHUB_TOKEN` (preferred)
+- `GH_TOKEN` (fallback)
+
+Only these two token keys are read from `.env`; other `.env` keys are ignored. The fallback uses async file I/O, requires `.env` to be a small regular file, and rejects directories, symlinks, special files, and oversized files. BranchMe does not read shell profiles, GitHub CLI credentials, or local credential stores. Token values are redacted from thrown errors, tool content, and tool details.
+
+## Telemetry
+
+BranchMe does not collect telemetry and does not send repository contents to any service beyond the explicit GitHub pull request fields provided to `pull_request`.
+
+## Reporting vulnerabilities
+
+Please report suspected security vulnerabilities privately by email: <senad.dizdarevic@proton.me>.
+
+For non-sensitive issues, use the repository issue tracker:
+
+<https://github.com/senad-d/branchme/issues>
+
+Do not open public issues for security-sensitive reports that include exploit details, private repository contents, secrets, or credentials.
+
+## Secure development checklist
+
+- Do not commit secrets, tokens, local `.env`, local `.pi/` state, or generated artifacts.
+- Keep tool schemas strict and reject unsupported fields.
+- Keep all git calls argv-style through `pi.exec("git", args)`.
+- Mock `pi.exec` and `fetch` in tests; do not touch real remotes.
+- Keep package contents minimal with `npm run check:pack`.
+- Use isolated smoke tests with `pi --no-extensions -e .`.

package/docs/PROJECT_DEFINITION_BRIEF.md

@@ -0,0 +1,114 @@
+# Project Definition Brief
+
+Approved on 2026-06-30.
+
+## 1. Bootstrap
+
+- Template source: `/Users/senad/Documents/Code/Moj_git/pi-tmp`
+- Target directory: `/Users/senad/Documents/Code/Moj_git/pi-branchme`
+- Copy status: copied; target only had `.git/` and `.pi/`, both preserved/excluded.
+
+## 2. Project identity
+
+- Package name: `@senad-d/branchme`
+- Display name: `BranchMe`
+- Exported extension function: `branchMeExtension`
+- Repository URL: `https://github.com/senad-d/branchme`
+- One-sentence pitch: Minimal Pi tools for changing/creating current-repo branches, publishing the current branch, and opening a GitHub pull request.
+
+## 3. Users and use cases
+
+- Primary users: Pi users and CI/GitHub Actions workflows.
+- Primary use cases:
+  - Check current git branch/repo status.
+  - Switch to an existing local branch after clean-worktree preflight.
+  - Create and checkout a new branch from current `HEAD`.
+  - Push the current branch to its configured upstream, or publish it to `origin` when no upstream exists.
+  - Create a PR in the current GitHub repo via REST API.
+- Non-goals:
+  - No commit, staging, diff, or message generation behavior.
+  - No GitHub CLI dependency.
+  - No cross-repository PR creation.
+  - No labels, reviewers, projects, or issue linking in v1.
+
+## 4. Pi integration surface
+
+| Surface | Name | Purpose | Notes |
+| --- | --- | --- | --- |
+| Command | `/branchme` | Simple TUI config/status/help panel | No git/GitHub mutations |
+| Command | `/branchme help` | Workflow notes | No actions |
+| Tool | `branch_status` | Read current repo/branch/upstream/dirty/push state | Read-only |
+| Tool | `change_branch` | Switch to an existing local branch | Required `branchName`; rejects dirty worktrees |
+| Tool | `create_branch` | Create + checkout new branch from current `HEAD` | Required `branchName`; fail if exists/invalid |
+| Tool | `push_branch` | Push current branch with explicit upstream target; publish with upstream if needed | No commits/staging |
+| Tool | `pull_request` | Preflight branch visibility/commit state and create PR via GitHub REST API | Required `headBranch`, `baseBranch`, `title`, `body`, `draft`; repo inferred from current checkout |
+| Event | `session_start/session_shutdown` | Optional status footer cleanup | No long-lived resources |
+| UI | TUI panel | Compact BranchMe workflow/config view | No persisted config assumed |
+| Resource | none | No skills/prompts/themes planned | Keep package minimal |
+
+## 5. Architecture
+
+- Planned files:
+  - `src/extension.ts`
+  - `src/constants.ts`
+  - `src/commands/branchme-command.ts`
+  - `src/tools/branchme-tools.ts`
+  - `src/git.ts`
+  - `src/github.ts`
+  - `src/types.ts`
+- Module boundaries:
+  - Extension entrypoint only registers command/tools/events.
+  - Git helper owns `pi.exec("git", args)` calls and branch/repo validation.
+  - GitHub helper owns env token lookup, branch visibility/commit preflight, and REST requests.
+  - Tools expose precise TypeBox schemas and structured details.
+- Dependencies:
+  - Pi core packages as peer deps with `"*"`.
+  - `@earendil-works/pi-tui` is a peer/dev dependency because the TUI panel imports width and key utilities.
+  - No Octokit; use Node 22 `fetch`.
+
+## 6. Config, state, and persistence
+
+- Config source: no BranchMe config file; `/branchme` displays runtime status and workflow notes. GitHub tokens may come from process environment or a small regular `.env` fallback in the verified git root.
+- Session state: none; tool results include useful `details`.
+- Files written: none by extension code, except normal git metadata changes from branch checkout/push.
+- Cleanup behavior: clear any footer/status key on `session_shutdown` if used.
+
+## 7. Security and privacy
+
+- Shell execution: only `git` via argv-style `pi.exec`, not shell strings.
+- File access/mutation: no working-tree file edits; git metadata changes only.
+- Network access: `pull_request` calls `https://api.github.com/repos/{owner}/{repo}/branches/{branch}` before `https://api.github.com/repos/{owner}/{repo}/pulls`.
+- Credentials/secrets: `GITHUB_TOKEN` / `GH_TOKEN` from process env or hardened local `.env` fallback; never log token.
+- Telemetry/retention: none.
+- User confirmations: no extra confirmation by default, to support automation; tools rely on explicit arguments.
+
+## 8. Documentation and packaging
+
+- README changes: describe implemented behavior, workflow, tools, CI env usage.
+- SECURITY changes: document git mutation, GitHub API, token behavior.
+- CHANGELOG changes: rename initial unreleased entry to BranchMe.
+- package.json changes: set package identity/URLs/keywords/peer deps.
+- npm/git distribution plan: npm package `@senad-d/branchme`, repo `senad-d/branchme`.
+
+## 9. Validation plan
+
+- Typecheck: `npm run typecheck`
+- Tests: unit and isolated integration tests for commands, tools, git/GitHub helpers, package metadata, and TUI captures.
+- Package dry-run: `npm run check:pack`
+- Formatting: `npm run format:check`
+- Full validation: `npm run validate`
+- Checkout Pi smoke test: `npm run smoke:pi` / `pi --no-extensions -e .`
+- Installed-artifact release smoke: `npm run smoke:pi:packed`
+
+## 10. Open questions and assumptions
+
+- Questions:
+  - None blocking.
+- Assumptions:
+  - `/branchme` has no persisted config in v1.
+  - `push_branch` uses `origin` when current branch has no upstream.
+  - `pull_request` infers owner/repo from current GitHub checkout or `GITHUB_REPOSITORY`, but never accepts owner/repo as tool input and requires local branch refs with `headBranch` matching GitHub.
+- Decisions:
+  - No commit functionality.
+  - Tools perform all actions; slash commands are help/config only.
+  - PR tool requires all PR fields explicitly.

package/docs/SMOKE_TEST.md

@@ -0,0 +1,41 @@
+# BranchMe Smoke Test Notes
+
+Date: 2026-06-30
+
+Validated from the repository checkout with no discovered extensions enabled.
+
+## Commands
+
+```bash
+npm run validate
+npm run smoke:pi
+npm run smoke:pi:packed
+npm run check:pack
+printf '/branchme help\n/quit\n' | pi --no-extensions -e .
+pi --no-extensions -e .
+```
+
+## Automated smoke behavior
+
+- `npm run smoke:pi` runs isolated checkout Pi processes from a temporary working directory: one with `pi --no-extensions -e <package> -e <temporary verifier>` and `/branchmeverify verify`, then one with `pi --no-extensions -e <package>` and `/branchme help`.
+- The temporary verifier is a non-LLM Pi extension command that calls `pi.getAllTools()` after BranchMe loads and confirms `branch_status`, `change_branch`, `create_branch`, `push_branch`, and `pull_request` are active runtime tools with strict schemas, prompt guidelines, descriptions, and extension source metadata.
+- The checkout smoke accepts either `/branchme help` text or the read-only BranchMe status fallback as equivalent non-mutating command output.
+- `npm run smoke:pi:packed` creates an npm tarball under a temporary directory, installs that tarball into a separate temporary package with `npm install --omit=dev`, and runs pi against the installed package instead of the source checkout.
+- `npm run smoke:pi:packed` is the release gate for packaged runtime imports and required packaged files; `npm run release:check` and `node scripts/publish-npm.mjs` run it before publish, while everyday `npm run validate` keeps the faster checkout smoke.
+- Both smoke runs disable discovered extensions, skills, prompt templates, themes, context files, persistent sessions, telemetry, startup network checks, and GitHub token environment variables.
+- Both smoke runs are credential-free, allow documented credential variable names in help text, reject credential value patterns, do not call BranchMe mutation tools, and do not contact GitHub.
+- Pi's documented `getAllTools()` metadata currently exposes parameter schemas and prompt guidelines, but not `promptSnippet`, and the ExtensionAPI does not expose a safe non-LLM tool invocation method. The checkout runtime smoke therefore gates real Pi tool registration metadata; isolated `branch_status` execution remains covered by mocked unit tests and real-git helper tests until Pi exposes a direct runtime invocation API.
+- Set `BRANCHME_SKIP_PI_SMOKE=1` to skip intentionally, or `BRANCHME_PI_BIN=/path/to/pi` to test a specific Pi binary for the checkout smoke.
+- If no Pi binary is available, the checkout smoke script prints an explicit skip message; default CI installs the Pi dev dependency, so `npm run validate` exercises the real Pi loading path.
+
+## Result
+
+- `npm run validate` passed.
+- `npm run smoke:pi` loaded BranchMe through Pi, verified all five BranchMe tools through the real `pi.getAllTools()` runtime surface, and confirmed non-mutating BranchMe command output.
+- `npm run smoke:pi:packed` packed BranchMe outside the repository, installed the artifact in a temporary production workspace, loaded the installed package through Pi, and confirmed non-mutating BranchMe command output.
+- `npm run check:pack` confirmed the package contents are limited to public docs, images, source, license, package metadata, `.env.example`, and `tsconfig.json`.
+- The isolated Pi smoke command loaded BranchMe and displayed BranchMe help or status output instead of template behavior.
+- The bare `pi --no-extensions -e .` smoke command exited cleanly in this non-interactive validation environment.
+- No template command or template tool output was observed.
+
+The piped `pi --no-extensions -e .` form was also used so the smoke test could exit without leaving an interactive TUI session open.