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

boomtick_cli-0.4.0/MANIFEST.in

@@ -0,0 +1,3 @@
+recursive-include dev_tools/dist *
+recursive-include dev_tools/resources *
+include dev_tools/cli-schema.json

boomtick_cli-0.4.0/PKG-INFO

@@ -0,0 +1,226 @@
+Metadata-Version: 2.4
+Name: boomtick-cli
+Version: 0.4.0
+Summary: BoomTick CLI — agentic dev-tools for GitHub + AI workflows
+Author: Ariel Anders
+Project-URL: Homepage, https://github.com/arii/boomtick
+Project-URL: Repository, https://github.com/arii/boomtick
+Classifier: Programming Language :: Python :: 3
+Classifier: Operating System :: OS Independent
+Requires-Python: >=3.8
+Description-Content-Type: text/markdown
+Requires-Dist: requests>=2.0.0
+Requires-Dist: packaging>=21.3
+Requires-Dist: python-dotenv
+Requires-Dist: pydantic
+Requires-Dist: click
+Requires-Dist: PyGithub
+Requires-Dist: semgrep
+Requires-Dist: duckduckgo-search>=6.0.0
+Requires-Dist: setuptools<81.0.0
+Requires-Dist: importlib-resources
+Provides-Extra: ai
+Requires-Dist: google-genai; extra == "ai"
+Requires-Dist: chromadb>=1.5.9; extra == "ai"
+Requires-Dist: sentence-transformers>=5.6.0; extra == "ai"
+Requires-Dist: langchain-google-genai; extra == "ai"
+Requires-Dist: langchain-openai; extra == "ai"
+
+# 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 setup script is now located at the repository root (not symlinked) and 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 `./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 `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.4.0}/README.md

@@ -13,7 +13,7 @@ tool hierarchy.
 ./setup-agent.sh
 ```
 
-This script (symlinked to `dev-tools/setup-agent.sh`) handles system tools,
+This setup script is now located at the repository root (not symlinked) and handles system tools,
 Node.js, pnpm, Python dependencies, Playwright, remote origin configuration,
 and git hook registration.
 
@@ -53,7 +53,7 @@ export GEMINI_API_KEY="<key>"
 
 ## 🧩 Workflow-Specific Setup
 
-After `./dev-tools/setup-agent.sh`, use the following workflow-specific setup:
+After `./setup-agent.sh`, use the following workflow-specific setup:
 
 #### 1) Standard PR / Review Workflows
 
@@ -87,7 +87,7 @@ After `./dev-tools/setup-agent.sh`, use the following workflow-specific setup:
 
 `.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`.
+and `package_json` metadata — built by `scripts/build-repo-context.py`.
 
 **The index is kept fresh automatically** by the git hooks registered during
 `./setup-agent.sh`:

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

@@ -0,0 +1,226 @@
+Metadata-Version: 2.4
+Name: boomtick-cli
+Version: 0.4.0
+Summary: BoomTick CLI — agentic dev-tools for GitHub + AI workflows
+Author: Ariel Anders
+Project-URL: Homepage, https://github.com/arii/boomtick
+Project-URL: Repository, https://github.com/arii/boomtick
+Classifier: Programming Language :: Python :: 3
+Classifier: Operating System :: OS Independent
+Requires-Python: >=3.8
+Description-Content-Type: text/markdown
+Requires-Dist: requests>=2.0.0
+Requires-Dist: packaging>=21.3
+Requires-Dist: python-dotenv
+Requires-Dist: pydantic
+Requires-Dist: click
+Requires-Dist: PyGithub
+Requires-Dist: semgrep
+Requires-Dist: duckduckgo-search>=6.0.0
+Requires-Dist: setuptools<81.0.0
+Requires-Dist: importlib-resources
+Provides-Extra: ai
+Requires-Dist: google-genai; extra == "ai"
+Requires-Dist: chromadb>=1.5.9; extra == "ai"
+Requires-Dist: sentence-transformers>=5.6.0; extra == "ai"
+Requires-Dist: langchain-google-genai; extra == "ai"
+Requires-Dist: langchain-openai; extra == "ai"
+
+# 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 setup script is now located at the repository root (not symlinked) and 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 `./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 `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.4.0}/boomtick_cli.egg-info/SOURCES.txt

@@ -1,3 +1,4 @@
+MANIFEST.in
 README.md
 pyproject.toml
 boomtick_cli.egg-info/PKG-INFO
@@ -28,6 +29,7 @@ dev_tools/verify_versions.py
 dev_tools/version_utils.py
 dev_tools/dist/config.js
 dev_tools/dist/index.js
+dev_tools/dist/evals/run-evals.js
 dev_tools/dist/lib/error_utils.js
 dev_tools/dist/lib/git.js
 dev_tools/dist/lib/result.js
@@ -94,8 +96,10 @@ dev_tools/resources/prompt_constants.json
 dev_tools/resources/review_template.md
 dev_tools/resources/ux-audit.config.json
 dev_tools/resources/visual_guidelines.json
+dev_tools/resources/__pycache__/__init__.cpython-312.pyc
 dev_tools/services/__init__.py
 dev_tools/services/ai_service.py
+dev_tools/services/context_builder.py
 dev_tools/services/dependency_graph.py
 dev_tools/services/github.py
 dev_tools/services/jules.py
@@ -104,12 +108,20 @@ dev_tools/services/vector_store.py
 dev_tools/services/vision_service.py
 dev_tools/utils/__init__.py
 dev_tools/utils/git.py
+dev_tools/workflows/__init__.py
+dev_tools/workflows/context.py
+dev_tools/workflows/graph.py
+dev_tools/workflows/node.py
+dev_tools/workflows/nodes.py
+dev_tools/workflows/runner.py
 tests/test_config.py
 tests/test_dependency_graph.py
 tests/test_fail_fast.py
 tests/test_github_diff_parser.py
 tests/test_github_no_gh.py
 tests/test_github_parser.py
+tests/test_install_workflows.py
+tests/test_issue_validation_local.py
 tests/test_jules_batch_send.py
 tests/test_labels.py
 tests/test_latency_mitigation.py
@@ -121,4 +133,5 @@ tests/test_pr_overlap.py
 tests/test_review_template_validation.py
 tests/test_schema_utils.py
 tests/test_verify_ci_metrics.py
-tests/test_workflow_audit.py
+tests/test_workflow_audit.py
+tests/test_workflow_orchestration.py

{boomtick_cli-0.2.1 → boomtick_cli-0.4.0}/boomtick_cli.egg-info/requires.txt

@@ -1,15 +1,17 @@
 requests>=2.0.0
 packaging>=21.3
-google-genai
 python-dotenv
 pydantic
 click
 PyGithub
 semgrep
-chromadb>=1.5.9
-sentence-transformers>=5.6.0
 duckduckgo-search>=6.0.0
 setuptools<81.0.0
 importlib-resources
+
+[ai]
+google-genai
+chromadb>=1.5.9
+sentence-transformers>=5.6.0
 langchain-google-genai
 langchain-openai

{boomtick_cli-0.2.1 → boomtick_cli-0.4.0}/dev_tools/cli.py

@@ -467,15 +467,37 @@ def issue_comment(ctx, issue_number, file, body):
 @click.option("--all-open", is_flag=True)
 @click.option("--post-comments", is_flag=True)
 @click.option("--dry-run/--execute", default=True)
+@click.option("--file", default=None, help="Path to local issue draft to validate")
 @click.pass_context
-def validate_issue(ctx, issue_number, all_open, post_comments, dry_run):
+def validate_issue(ctx, issue_number, all_open, post_comments, dry_run, file=None):
     orch = ctx.obj["ORCHESTRATOR"]
-    res = orch.validate_issue(
-        issue_number=issue_number, all_open=all_open, post_comments=post_comments, dry_run=dry_run
-    )
+
+    if file:
+        content = orch._read_safe_file(file)
+        # For local files, we use title 'Draft: Local' to satisfy frontmatter check
+        res_content = orch.validate_content("Draft: Local", content)
+        res = {
+            "status": "success" if not res_content["findings"] else "error",
+            "issues": [
+                {
+                    "number": 0,
+                    "title": file,
+                    "findings": res_content["findings"],
+                    "warnings": res_content["warnings"],
+                }
+            ],
+            "total_findings": len(res_content["findings"]),
+        }
+    else:
+        res = orch.validate_issue(
+            issue_number=issue_number, all_open=all_open, post_comments=post_comments, dry_run=dry_run
+        )
+
     if not ctx.obj["JSON"]:
         for issue in res["issues"]:
-            click.echo(f"{'✅' if not issue['findings'] else '❌'} #{issue['number']}: {issue['title'][:60]}")
+            issue_ref = f"#{issue['number']}" if issue["number"] else f"File: {issue['title']}"
+            title_display = f": {issue['title'][:60]}" if issue["number"] else ""
+            click.echo(f"{'✅' if not issue['findings'] else '❌'} {issue_ref}{title_display}")
             for f in issue["findings"]:
                 click.echo(f"   ❌ {f}")
             for w in issue["warnings"]:
@@ -486,6 +508,22 @@ def validate_issue(ctx, issue_number, all_open, post_comments, dry_run):
         out(ctx, "✅ Issue validation complete.", data=res)
 
 
+@gh.command()
+@click.pass_context
+def scaffold_issue(ctx):
+    """Output a markdown skeleton containing the required headers."""
+    sections = PROJECT_CONFIG.spec_sections
+
+    output = "# Issue Title\n\n"
+    for section in sections:
+        output += f"# {section}\n\n[Provide content for {section}]\n\n"
+
+    if ctx.obj.get("JSON"):
+        out(ctx, "Issue scaffold generated.", data={"template": output})
+    else:
+        click.echo(output)
+
+
 @gh.command()
 @click.option("--title", required=True)
 @click.option("--body", required=True)
@@ -1403,6 +1441,22 @@ def plan_workflow_audit(ctx, workflow):
         _handle_unexpected_error(ctx, "agent plan-workflow-audit", e)
 
 
+@agent_group.command(name="install-workflows")
+@click.option("--dry-run/--execute", default=True)
+@click.pass_context
+def install_workflows(ctx, dry_run):
+    """Install and configure Jules/AI automation workflows for submodule or standalone use."""
+    orch = ctx.obj["ORCHESTRATOR"]
+    try:
+        res = orch.install_workflows(dry_run=dry_run)
+        if res["status"] == "success":
+            out(ctx, "✅ Workflows installed successfully.", data=res)
+        else:
+            out(ctx, "⚠️ Workflows partially installed or encountered errors.", data=res)
+    except Exception as e:
+        _handle_unexpected_error(ctx, "agent install-workflows", e)
+
+
 @agent_group.command(name="run-feedback-check")
 @limit_option(help_text="Limit the number of active sessions to check")
 @click.pass_context
@@ -1506,6 +1560,7 @@ for group in [jules_group]:
     group.add_command(send)
     group.add_command(plan_review)
     group.add_command(plan_aggregation)
+    group.add_command(install_workflows)
 
 for group in [agent_group, jules_group]:
     group.add_command(get_session, name="session")