boomtick-cli 0.2.1__tar.gz → 0.2.2__tar.gz

boomtick_cli-0.2.2/PKG-INFO

@@ -0,0 +1,220 @@
+Metadata-Version: 2.4
+Name: boomtick-cli
+Version: 0.2.2
+Summary: BoomTick CLI — agentic dev-tools for GitHub + AI workflows
+Requires-Python: >=3.8
+Description-Content-Type: text/markdown
+Requires-Dist: requests>=2.0.0
+Requires-Dist: packaging>=21.3
+Requires-Dist: google-genai
+Requires-Dist: python-dotenv
+Requires-Dist: pydantic
+Requires-Dist: click
+Requires-Dist: PyGithub
+Requires-Dist: semgrep
+Requires-Dist: chromadb>=1.5.9
+Requires-Dist: sentence-transformers>=5.6.0
+Requires-Dist: duckduckgo-search>=6.0.0
+Requires-Dist: setuptools<81.0.0
+Requires-Dist: importlib-resources
+Requires-Dist: langchain-google-genai
+Requires-Dist: langchain-openai
+
+# dev-tools
+
+Developer tooling for the BoomTick repository. The primary entry point is
+`td-cli`, but agents should always call `boomtick-mcp` Tier 1 tools first —
+`td-cli` is the Tier 2 fallback. See `.agents/AGENTS.md` for the full
+tool hierarchy.
+
+---
+
+## 🚀 One-Step Setup
+
+```bash
+./setup-agent.sh
+```
+
+This script (symlinked to `dev-tools/setup-agent.sh`) handles system tools,
+Node.js, pnpm, Python dependencies, Playwright, remote origin configuration,
+and git hook registration.
+
+---
+
+## 🔑 Environment Variables
+
+| Variable | Required | Purpose |
+| :--- | :--- | :--- |
+| `GITHUB_TOKEN` (string) | **Required** | Auth for `gh` and `td-cli gh ...` commands (PR audits, comments, variables, status checks). Standard for GH Actions. |
+| `GH_TOKEN` (string) | Optional fallback | Legacy authentication variable, deprecated in favor of `GITHUB_TOKEN`. |
+| `GITHUB_REPOSITORY` (`owner/repo`) | Recommended | Ensures deterministic `origin` remote auto-configuration. |
+| `JULES_API_KEY` | Optional | Enables `td-cli agent ...` / `td-cli jules ...` cloud workflows. |
+| `GEMINI_API_KEY` | Optional | Enables Gemini-backed review/audit workflows. |
+
+**Secret handling guidance**
+
+- GitHub Actions / agent runners: store `GITHUB_TOKEN`, `JULES_API_KEY`, and
+  `GEMINI_API_KEY` in repository or org Secrets.
+- Dev containers / local shells: export secrets before running setup/CLI:
+
+```bash
+export GITHUB_TOKEN="<token>"
+export GITHUB_REPOSITORY="owner/repo"
+# optional
+export JULES_API_KEY="<key>"
+export GEMINI_API_KEY="<key>"
+```
+
+**Optional tuning variables**
+
+- `SKIP_GIT_HOOKS=1` — skip git hook execution (e.g. in CI).
+- `SKIP_VALIDATION=1` — skip post-setup runtime validation.
+- `NODE_MAJOR` — override Node major used for apt installation (defaults to `24`).
+
+---
+
+## 🧩 Workflow-Specific Setup
+
+After `./dev-tools/setup-agent.sh`, use the following workflow-specific setup:
+
+#### 1) Standard PR / Review Workflows
+
+- Plan a review (fetches context and audits):
+  - `td-cli agent plan-review --pr <PR_NUMBER>`
+- Submit audit results (after authoring the review in `pr-review-<PR>.md`):
+  - `td-cli gh audit-pr <PR_NUMBER> --submit --execute`
+- Pre-submit quality gate before push/merge:
+  - `td-cli gh pre-submit`
+
+#### 2) Jules Workflows
+
+- Required secret: `JULES_API_KEY`.
+- Optional context env var: `JULES_SOURCE_ID` (if your environment already
+  knows the source mapping).
+- Typical commands:
+  - `td-cli agent dispatch <BRANCH> "<TASK>"`
+  - `td-cli agent fix-ci --pr-number <PR> --execute`
+  - `td-cli agent sync`
+
+#### 3) Headless / Bot Auditing
+
+- For batch auditing open PRs:
+  - `td-cli gh audit-pr <PR_NUMBER> --fetch --audit --submit --execute`
+- Ensure `jq`, `gh`, Python deps, and pnpm deps are installed (handled by
+  setup script).
+
+---
+
+## 🗂️ Agent Context Index
+
+`.agent-context.json` (repository root) is the pre-built index that
+`boomtick-mcp` reads on every tool call. It contains `file_tree`, `cli_schema`,
+and `package_json` metadata — built by `boomtick-pkg/scripts/build-repo-context.py`.
+
+**The index is kept fresh automatically** by the git hooks registered during
+`./setup-agent.sh`:
+
+- `.githooks/post-checkout` — refreshes on branch switch
+- `.githooks/post-merge` — refreshes on pull/merge
+
+To manually refresh:
+
+```bash
+pnpm run agent:prime
+```
+
+If the index is stale, MCP tools fall back to raw filesystem calls, bypassing
+the index and increasing token usage. Always refresh before running reviews or
+dispatching Jules sessions.
+
+---
+
+## 🤖 Agent / Jules GitHub Command Pattern
+
+Always use `boomtick-mcp` Tier 1 tools first. `td-cli` is the fallback
+when MCP is unavailable — not the default. See `.agents/AGENTS.md` for the
+full tool mapping table.
+
+When `td-cli` must be called directly, read the CLI schema from
+`.agent-context.json` rather than guessing flags or running `--help`:
+
+```bash
+# Extract schema for a specific subcommand before calling it
+cat .agent-context.json | python3 -c "
+import json, sys
+schema = json.load(sys.stdin)
+print(json.dumps(schema['cli_schema']['subcommands']['gh pr-diff'], indent=2))
+"
+```
+
+Prefer repository CLI commands over raw `gh`:
+
+```bash
+# ✅ Preferred
+td-cli gh <repo-command>
+
+# ⚠️ Only if td-cli does not expose the operation
+gh <command>
+```
+
+If auth fails, do not run `gh auth login`. Instead, set an environment secret
+named `GITHUB_TOKEN`.
+
+---
+
+## ✅ Verification Commands (Post-Setup)
+
+```bash
+node --version         # should match .node-version
+pnpm --version         # should be 10.28.2
+td-cli doctor
+pnpm run check:runtime-files
+gh auth status
+```
+
+---
+
+## 🆘 Troubleshooting
+
+### GitHub CLI not authenticated
+
+```bash
+gh issue create --title "<title>" --body "<details>"
+```
+
+If auth fails, report this exact issue (do not run interactive auth):
+
+> GitHub CLI is not authenticated. Please add an environment secret named
+> `GITHUB_TOKEN` with a repo-scoped GitHub token.
+
+### `.agent-context.json` stale or missing
+
+```bash
+pnpm run agent:prime
+```
+
+Then re-read before proceeding with any agent operation.
+
+### pnpm / Node mismatch
+
+Stop and report the mismatch. Do not attempt to change runtime versions unless
+explicitly instructed to update the runtime contract.
+
+---
+
+## 🚀 Repository CLI (`td-cli`)
+
+`dev-tools/td-cli` is the Tier 2 unified entry point for local repository
+automation. All available subcommands and flags are defined in
+`dev-tools/cli-schema.json` (also embedded in `.agent-context.json` under
+`cli_schema`). That file is the single source of truth — never use `--help`
+to discover flags.
+
+Key subcommand groups:
+
+| Group | Description |
+| :--- | :--- |
+| `doctor` | Runtime consistency check |
+| `gh` | GitHub operations (PRs, issues, audits, conflicts) |
+| `repo` | Repository operations (CI logs, Playwright) |
+| `agent` / `jules` | Jules agent session management |

boomtick_cli-0.2.2/boomtick_cli.egg-info/PKG-INFO

@@ -0,0 +1,220 @@
+Metadata-Version: 2.4
+Name: boomtick-cli
+Version: 0.2.2
+Summary: BoomTick CLI — agentic dev-tools for GitHub + AI workflows
+Requires-Python: >=3.8
+Description-Content-Type: text/markdown
+Requires-Dist: requests>=2.0.0
+Requires-Dist: packaging>=21.3
+Requires-Dist: google-genai
+Requires-Dist: python-dotenv
+Requires-Dist: pydantic
+Requires-Dist: click
+Requires-Dist: PyGithub
+Requires-Dist: semgrep
+Requires-Dist: chromadb>=1.5.9
+Requires-Dist: sentence-transformers>=5.6.0
+Requires-Dist: duckduckgo-search>=6.0.0
+Requires-Dist: setuptools<81.0.0
+Requires-Dist: importlib-resources
+Requires-Dist: langchain-google-genai
+Requires-Dist: langchain-openai
+
+# dev-tools
+
+Developer tooling for the BoomTick repository. The primary entry point is
+`td-cli`, but agents should always call `boomtick-mcp` Tier 1 tools first —
+`td-cli` is the Tier 2 fallback. See `.agents/AGENTS.md` for the full
+tool hierarchy.
+
+---
+
+## 🚀 One-Step Setup
+
+```bash
+./setup-agent.sh
+```
+
+This script (symlinked to `dev-tools/setup-agent.sh`) handles system tools,
+Node.js, pnpm, Python dependencies, Playwright, remote origin configuration,
+and git hook registration.
+
+---
+
+## 🔑 Environment Variables
+
+| Variable | Required | Purpose |
+| :--- | :--- | :--- |
+| `GITHUB_TOKEN` (string) | **Required** | Auth for `gh` and `td-cli gh ...` commands (PR audits, comments, variables, status checks). Standard for GH Actions. |
+| `GH_TOKEN` (string) | Optional fallback | Legacy authentication variable, deprecated in favor of `GITHUB_TOKEN`. |
+| `GITHUB_REPOSITORY` (`owner/repo`) | Recommended | Ensures deterministic `origin` remote auto-configuration. |
+| `JULES_API_KEY` | Optional | Enables `td-cli agent ...` / `td-cli jules ...` cloud workflows. |
+| `GEMINI_API_KEY` | Optional | Enables Gemini-backed review/audit workflows. |
+
+**Secret handling guidance**
+
+- GitHub Actions / agent runners: store `GITHUB_TOKEN`, `JULES_API_KEY`, and
+  `GEMINI_API_KEY` in repository or org Secrets.
+- Dev containers / local shells: export secrets before running setup/CLI:
+
+```bash
+export GITHUB_TOKEN="<token>"
+export GITHUB_REPOSITORY="owner/repo"
+# optional
+export JULES_API_KEY="<key>"
+export GEMINI_API_KEY="<key>"
+```
+
+**Optional tuning variables**
+
+- `SKIP_GIT_HOOKS=1` — skip git hook execution (e.g. in CI).
+- `SKIP_VALIDATION=1` — skip post-setup runtime validation.
+- `NODE_MAJOR` — override Node major used for apt installation (defaults to `24`).
+
+---
+
+## 🧩 Workflow-Specific Setup
+
+After `./dev-tools/setup-agent.sh`, use the following workflow-specific setup:
+
+#### 1) Standard PR / Review Workflows
+
+- Plan a review (fetches context and audits):
+  - `td-cli agent plan-review --pr <PR_NUMBER>`
+- Submit audit results (after authoring the review in `pr-review-<PR>.md`):
+  - `td-cli gh audit-pr <PR_NUMBER> --submit --execute`
+- Pre-submit quality gate before push/merge:
+  - `td-cli gh pre-submit`
+
+#### 2) Jules Workflows
+
+- Required secret: `JULES_API_KEY`.
+- Optional context env var: `JULES_SOURCE_ID` (if your environment already
+  knows the source mapping).
+- Typical commands:
+  - `td-cli agent dispatch <BRANCH> "<TASK>"`
+  - `td-cli agent fix-ci --pr-number <PR> --execute`
+  - `td-cli agent sync`
+
+#### 3) Headless / Bot Auditing
+
+- For batch auditing open PRs:
+  - `td-cli gh audit-pr <PR_NUMBER> --fetch --audit --submit --execute`
+- Ensure `jq`, `gh`, Python deps, and pnpm deps are installed (handled by
+  setup script).
+
+---
+
+## 🗂️ Agent Context Index
+
+`.agent-context.json` (repository root) is the pre-built index that
+`boomtick-mcp` reads on every tool call. It contains `file_tree`, `cli_schema`,
+and `package_json` metadata — built by `boomtick-pkg/scripts/build-repo-context.py`.
+
+**The index is kept fresh automatically** by the git hooks registered during
+`./setup-agent.sh`:
+
+- `.githooks/post-checkout` — refreshes on branch switch
+- `.githooks/post-merge` — refreshes on pull/merge
+
+To manually refresh:
+
+```bash
+pnpm run agent:prime
+```
+
+If the index is stale, MCP tools fall back to raw filesystem calls, bypassing
+the index and increasing token usage. Always refresh before running reviews or
+dispatching Jules sessions.
+
+---
+
+## 🤖 Agent / Jules GitHub Command Pattern
+
+Always use `boomtick-mcp` Tier 1 tools first. `td-cli` is the fallback
+when MCP is unavailable — not the default. See `.agents/AGENTS.md` for the
+full tool mapping table.
+
+When `td-cli` must be called directly, read the CLI schema from
+`.agent-context.json` rather than guessing flags or running `--help`:
+
+```bash
+# Extract schema for a specific subcommand before calling it
+cat .agent-context.json | python3 -c "
+import json, sys
+schema = json.load(sys.stdin)
+print(json.dumps(schema['cli_schema']['subcommands']['gh pr-diff'], indent=2))
+"
+```
+
+Prefer repository CLI commands over raw `gh`:
+
+```bash
+# ✅ Preferred
+td-cli gh <repo-command>
+
+# ⚠️ Only if td-cli does not expose the operation
+gh <command>
+```
+
+If auth fails, do not run `gh auth login`. Instead, set an environment secret
+named `GITHUB_TOKEN`.
+
+---
+
+## ✅ Verification Commands (Post-Setup)
+
+```bash
+node --version         # should match .node-version
+pnpm --version         # should be 10.28.2
+td-cli doctor
+pnpm run check:runtime-files
+gh auth status
+```
+
+---
+
+## 🆘 Troubleshooting
+
+### GitHub CLI not authenticated
+
+```bash
+gh issue create --title "<title>" --body "<details>"
+```
+
+If auth fails, report this exact issue (do not run interactive auth):
+
+> GitHub CLI is not authenticated. Please add an environment secret named
+> `GITHUB_TOKEN` with a repo-scoped GitHub token.
+
+### `.agent-context.json` stale or missing
+
+```bash
+pnpm run agent:prime
+```
+
+Then re-read before proceeding with any agent operation.
+
+### pnpm / Node mismatch
+
+Stop and report the mismatch. Do not attempt to change runtime versions unless
+explicitly instructed to update the runtime contract.
+
+---
+
+## 🚀 Repository CLI (`td-cli`)
+
+`dev-tools/td-cli` is the Tier 2 unified entry point for local repository
+automation. All available subcommands and flags are defined in
+`dev-tools/cli-schema.json` (also embedded in `.agent-context.json` under
+`cli_schema`). That file is the single source of truth — never use `--help`
+to discover flags.
+
+Key subcommand groups:
+
+| Group | Description |
+| :--- | :--- |
+| `doctor` | Runtime consistency check |
+| `gh` | GitHub operations (PRs, issues, audits, conflicts) |
+| `repo` | Repository operations (CI logs, Playwright) |
+| `agent` / `jules` | Jules agent session management |

{boomtick_cli-0.2.1 → boomtick_cli-0.2.2}/pyproject.toml

@@ -4,8 +4,9 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "boomtick-cli"
-version = "0.2.1"
+version = "0.2.2"
 description = "BoomTick CLI — agentic dev-tools for GitHub + AI workflows"
+readme = "README.md"
 requires-python = ">=3.8"
 dependencies = [
     "requests>=2.0.0",

boomtick_cli-0.2.1/PKG-INFO

@@ -1,20 +0,0 @@
-Metadata-Version: 2.4
-Name: boomtick-cli
-Version: 0.2.1
-Summary: BoomTick CLI — agentic dev-tools for GitHub + AI workflows
-Requires-Python: >=3.8
-Requires-Dist: requests>=2.0.0
-Requires-Dist: packaging>=21.3
-Requires-Dist: google-genai
-Requires-Dist: python-dotenv
-Requires-Dist: pydantic
-Requires-Dist: click
-Requires-Dist: PyGithub
-Requires-Dist: semgrep
-Requires-Dist: chromadb>=1.5.9
-Requires-Dist: sentence-transformers>=5.6.0
-Requires-Dist: duckduckgo-search>=6.0.0
-Requires-Dist: setuptools<81.0.0
-Requires-Dist: importlib-resources
-Requires-Dist: langchain-google-genai
-Requires-Dist: langchain-openai

boomtick_cli-0.2.1/boomtick_cli.egg-info/PKG-INFO

@@ -1,20 +0,0 @@
-Metadata-Version: 2.4
-Name: boomtick-cli
-Version: 0.2.1
-Summary: BoomTick CLI — agentic dev-tools for GitHub + AI workflows
-Requires-Python: >=3.8
-Requires-Dist: requests>=2.0.0
-Requires-Dist: packaging>=21.3
-Requires-Dist: google-genai
-Requires-Dist: python-dotenv
-Requires-Dist: pydantic
-Requires-Dist: click
-Requires-Dist: PyGithub
-Requires-Dist: semgrep
-Requires-Dist: chromadb>=1.5.9
-Requires-Dist: sentence-transformers>=5.6.0
-Requires-Dist: duckduckgo-search>=6.0.0
-Requires-Dist: setuptools<81.0.0
-Requires-Dist: importlib-resources
-Requires-Dist: langchain-google-genai
-Requires-Dist: langchain-openai