bpsai-pair 0.2.0__py3-none-any.whl

bpsai_pair/config.py

@@ -0,0 +1,310 @@
+"""
+Configuration management for PairCoder.
+"""
+from __future__ import annotations
+
+import os
+from pathlib import Path
+from typing import Optional, Dict, Any
+import yaml
+import json
+from dataclasses import dataclass, asdict, field
+
+
+@dataclass
+class Config:
+    """PairCoder configuration."""
+
+    # Project settings
+    project_name: str = "My Project"
+    primary_goal: str = "Build awesome software"
+    coverage_target: int = 80
+
+    # Branch settings
+    default_branch_type: str = "feature"
+    main_branch: str = "main"
+
+    # Context settings
+    context_dir: str = "context"
+
+    # Pack settings
+    default_pack_name: str = "agent_pack.tgz"
+    pack_excludes: list[str] = field(default_factory=lambda: [
+        ".git", ".venv", "__pycache__", "node_modules",
+        "dist", "build", "*.log", "*.bak"
+    ])
+
+    # CI settings
+    python_formatter: str = "ruff"
+    node_formatter: str = "prettier"
+
+    @classmethod
+    def load(cls, root: Path) -> "Config":
+        """Load configuration from .paircoder.yml or environment."""
+        config_file = root / ".paircoder.yml"
+
+        data = {}
+        if config_file.exists():
+            with open(config_file) as f:
+                yaml_data = yaml.safe_load(f) or {}
+
+                # Handle both flat and nested structures
+                if "version" in yaml_data:
+                    # New nested structure
+                    if "project" in yaml_data:
+                        project = yaml_data["project"]
+                        data["project_name"] = project.get("name", "My Project")
+                        data["primary_goal"] = project.get("primary_goal", "Build awesome software")
+                        data["coverage_target"] = project.get("coverage_target", 80)
+
+                    if "workflow" in yaml_data:
+                        workflow = yaml_data["workflow"]
+                        data["default_branch_type"] = workflow.get("default_branch_type", "feature")
+                        data["main_branch"] = workflow.get("main_branch", "main")
+                        data["context_dir"] = workflow.get("context_dir", "context")
+
+                    if "pack" in yaml_data:
+                        pack = yaml_data["pack"]
+                        data["default_pack_name"] = pack.get("default_name", "agent_pack.tgz")
+                        data["pack_excludes"] = pack.get("excludes", [])
+
+                    if "ci" in yaml_data:
+                        ci = yaml_data["ci"]
+                        data["python_formatter"] = ci.get("python_formatter", "ruff")
+                        data["node_formatter"] = ci.get("node_formatter", "prettier")
+                else:
+                    # Old flat structure (backwards compatibility)
+                    data = yaml_data
+
+        # Override with environment variables
+        env_mappings = {
+            "PAIRCODER_MAIN_BRANCH": "main_branch",
+            "PAIRCODER_CONTEXT_DIR": "context_dir",
+            "PAIRCODER_DEFAULT_BRANCH": "default_branch_type",
+            "PAIRCODER_PROJECT_NAME": "project_name",
+        }
+
+        for env_var, config_key in env_mappings.items():
+            if env_value := os.getenv(env_var):
+                data[config_key] = env_value
+
+        # Create config with collected data
+        return cls(**{k: v for k, v in data.items() if k in cls.__annotations__})
+
+    def save(self, root: Path) -> None:
+        """Save configuration to .paircoder.yml."""
+        config_file = root / ".paircoder.yml"
+
+        data = {
+            "version": "0.1.3",
+            "project": {
+                "name": self.project_name,
+                "primary_goal": self.primary_goal,
+                "coverage_target": self.coverage_target,
+            },
+            "workflow": {
+                "default_branch_type": self.default_branch_type,
+                "main_branch": self.main_branch,
+                "context_dir": self.context_dir,
+            },
+            "pack": {
+                "default_name": self.default_pack_name,
+                "excludes": self.pack_excludes,
+            },
+            "ci": {
+                "python_formatter": self.python_formatter,
+                "node_formatter": self.node_formatter,
+            }
+        }
+
+        with open(config_file, 'w') as f:
+            yaml.dump(data, f, default_flow_style=False, sort_keys=False)
+
+    def to_dict(self) -> Dict[str, Any]:
+        """Convert to dictionary."""
+        return asdict(self)
+
+    def to_json(self) -> str:
+        """Convert to JSON string."""
+        return json.dumps(self.to_dict(), indent=2)
+
+
+class ContextTemplate:
+    """Templates for context files."""
+
+    @staticmethod
+    def development_md(config: Config) -> str:
+        """Generate development.md template."""
+        return f"""# Development Log
+
+**Project:** {config.project_name}
+**Phase:** Phase 1: Initial Setup
+**Primary Goal:** {config.primary_goal}
+
+## KPIs & Non-Functional Targets
+
+- Test Coverage: ≥ {config.coverage_target}%
+- Documentation: Complete for all public APIs
+- Performance: Response time < 200ms (p95)
+
+## Phase 1 — Foundation (Weeks 1–2)
+
+**Objectives**
+- Set up project structure and CI/CD
+- Define core architecture and interfaces
+- Establish testing framework
+
+**Tasks**
+- [ ] Initialize repository with PairCoder
+- [ ] Set up CI workflows
+- [ ] Create initial project structure
+- [ ] Write architectural decision records
+
+**Testing Plan**
+- Unit tests for all business logic
+- Integration tests for external boundaries
+- End-to-end tests for critical user flows
+
+**Risks & Rollback**
+- Risk: Incomplete requirements — Mitigation: Regular stakeholder reviews
+- Rollback: Git revert with documented rollback procedures
+
+## Context Sync (AUTO-UPDATED)
+
+- **Overall goal is:** {config.primary_goal}
+- **Last action was:** Initialized project
+- **Next action will be:** Set up CI/CD pipeline
+- **Blockers:** None
+"""
+
+    @staticmethod
+    def agents_md(config: Config) -> str:
+        """Generate agents.md template."""
+        return f"""# Agents Guide — AI Pair Coding Playbook
+
+**Project:** {config.project_name}
+**Purpose:** {config.primary_goal}
+
+## Ground Rules
+
+1. **Context is King**: Always refer to `/context/development.md` for current state
+2. **Test First**: Write tests before implementation
+3. **Small Changes**: Keep PRs under 200 lines when possible
+4. **Update Loop**: Run `bpsai-pair context-sync` after every significant change
+
+## Project Structure
+
+```
+.
+├── {config.context_dir}/          # Project context and memory
+├── src/                            # Source code
+├── tests/                          # Test suites
+├── docs/                           # Documentation
+└── .paircoder.yml                  # Configuration
+```
+
+## Workflow
+
+1. Check status: `bpsai-pair status`
+2. Create feature: `bpsai-pair feature <name> --primary "<goal>" --phase "<phase>"`
+3. Make changes (with tests)
+4. Update context: `bpsai-pair context-sync --last "<what>" --next "<next>"`
+5. Create pack: `bpsai-pair pack`
+6. Share with AI agent
+
+## Testing Requirements
+
+- Minimum coverage: {config.coverage_target}%
+- All new code must have tests
+- Integration tests for external dependencies
+- Performance tests for critical paths
+
+## Code Style
+
+- Python: {config.python_formatter} for formatting and linting
+- JavaScript: {config.node_formatter} for formatting
+- Commit messages: Conventional Commits format
+- Branch names: {config.default_branch_type}/<description>
+
+## Context Loop Protocol
+
+After EVERY meaningful change:
+```bash
+bpsai-pair context-sync \\
+    --last "What was just completed" \\
+    --next "The immediate next step" \\
+    --blockers "Any impediments"
+```
+
+## Excluded from Context
+
+The following are excluded from agent packs (see `.agentpackignore`):
+{chr(10).join(f'- {exclude}' for exclude in config.pack_excludes)}
+
+## Commands Reference
+
+- `bpsai-pair init` - Initialize scaffolding
+- `bpsai-pair feature` - Create feature branch
+- `bpsai-pair pack` - Create context package
+- `bpsai-pair sync` - Update context loop
+- `bpsai-pair status` - Show current state
+- `bpsai-pair validate` - Check structure
+- `bpsai-pair ci` - Run local CI checks
+"""
+
+    @staticmethod
+    def gitignore() -> str:
+        """Generate .gitignore template."""
+        return """# PairCoder
+.paircoder.yml.local
+agent_pack*.tgz
+*.bak
+
+# Python
+__pycache__/
+*.py[cod]
+*$py.class
+*.so
+.Python
+.venv/
+venv/
+ENV/
+env/
+*.egg-info/
+dist/
+build/
+.pytest_cache/
+.mypy_cache/
+.ruff_cache/
+.coverage
+htmlcov/
+
+# Node
+node_modules/
+npm-debug.log*
+yarn-debug.log*
+yarn-error.log*
+.npm
+.yarn-integrity
+
+# IDE
+.idea/
+.vscode/
+*.swp
+*.swo
+*~
+.DS_Store
+
+# Environment
+.env
+.env.local
+.env.*.local
+
+# Logs
+*.log
+logs/
+
+# OS
+Thumbs.db
+Desktop.ini
+"""

bpsai_pair/data/cookiecutter-paircoder/cookiecutter.json

@@ -0,0 +1,12 @@
+
+{
+  "project_name": "Paircoder Project",
+  "project_slug": "{{ cookiecutter.project_name | lower | replace(' ', '-') }}",
+  "primary_goal": "<PRIMARY GOAL>",
+  "coverage_target": "80%",
+  "owner_gh_handle": "<OWNER>",
+  "architect_gh_handle": "<ARCHITECT>",
+  "build_gh_handle": "<BUILD>",
+  "qa_gh_handle": "<QA>",
+  "sre_gh_handle": "<SRE>"
+}

bpsai_pair/data/cookiecutter-paircoder/{{cookiecutter.project_slug}}/.agentpackignore

@@ -0,0 +1 @@
+# Default agent pack exclusions\n.git/\n.venv/\n__pycache__/\nnode_modules/\ndist/\nbuild/\n*.log\n*.bak\n*.tgz\n*.tar.gz\n*.zip\n

bpsai_pair/data/cookiecutter-paircoder/{{cookiecutter.project_slug}}/.editorconfig

@@ -0,0 +1,17 @@
+
+root = true
+
+[*]
+end_of_line = lf
+insert_final_newline = true
+charset = utf-8
+trim_trailing_whitespace = true
+indent_style = space
+indent_size = 2
+
+[*.py]
+indent_size = 4
+
+[*.md]
+max_line_length = off
+trim_trailing_whitespace = false

bpsai_pair/data/cookiecutter-paircoder/{{cookiecutter.project_slug}}/.github/PULL_REQUEST_TEMPLATE.md

@@ -0,0 +1,47 @@
+
+## Summary
+- What change does this PR introduce and why?
+- Link to the PRIMARY GOAL or tracked issue: <link>
+
+## Risk Level
+- [ ] Low
+- [ ] Medium
+- [ ] High (requires explicit rollback plan & ADR)
+
+## Change Type
+- [ ] Feature
+- [ ] Refactor
+- [ ] Fix
+- [ ] Docs/Chore
+
+## Scope & Impact
+- Affected modules/dirs: <list>
+- Backwards compatibility: <preserved / changed (explain)>
+- Breaking changes: <none / explain + migration>
+
+## Test Plan
+- Unit tests added/updated: <list>
+- Integration/Contract tests: <list>
+- Manual verification steps: <commands + expected results>
+
+## Context Update (MANDATORY)
+Paste the diff or summary of updates to `/context/*`:
+```
+Overall goal is: <...>
+Last action was: <...>
+Next action will be: <...>
+Blockers/Risks: <...>
+```
+
+## Rollback Plan
+- Strategy: <revert commit SHA / feature flag / backup restore>
+- Data/Schema implications: <if any>
+
+## Screenshots / Logs (optional)
+<attach>
+
+## Checklist
+- [ ] CI green (lint, type, tests, audit)
+- [ ] Coverage ≥ target or unchanged
+- [ ] ADR updated/added when design or contracts change
+- [ ] No secrets/PII introduced; `.agentpackignore` updated if needed

bpsai_pair/data/cookiecutter-paircoder/{{cookiecutter.project_slug}}/.github/workflows/ci.yml

@@ -0,0 +1,90 @@
+
+name: CI
+
+on:
+  push:
+    branches: [ main ]
+  pull_request:
+    branches: [ main ]
+
+permissions:
+  contents: read
+
+jobs:
+  node:
+    name: Node CI
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - name: Detect package.json
+        id: detect
+        run: |
+          if [ -f package.json ]; then echo "has_node=true" >> $GITHUB_OUTPUT; else echo "has_node=false" >> $GITHUB_OUTPUT; fi
+      - name: Setup Node
+        if: steps.detect.outputs.has_node == true
+        uses: actions/setup-node@v4
+        with:
+          node-version: lts/*
+          cache: npm
+      - name: Install deps
+        if: steps.detect.outputs.has_node == true
+        run: npm ci --ignore-scripts
+      - name: Format & Lint
+        if: steps.detect.outputs.has_node == true
+        run: |
+          (npm run -s fmt || npx --yes prettier -c .) || true
+          (npm run -s lint || npx --yes eslint .)
+      - name: Type Check
+        if: steps.detect.outputs.has_node == true && hashFiles(tsconfig.json) != 
+        run: (npm run -s typecheck || npx --yes tsc -p . --noEmit)
+      - name: Test
+        if: steps.detect.outputs.has_node == true
+        run: |
+          npm test --silent || npm run -s test
+      - name: Audit (non-blocking)
+        if: steps.detect.outputs.has_node == true
+        run: npm audit --audit-level=high || true
+
+  python:
+    name: Python CI
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - name: Detect Python project
+        id: detect
+        run: |
+          if [ -f requirements.txt ] || [ -f pyproject.toml ]; then echo "has_py=true" >> $GITHUB_OUTPUT; else echo "has_py=false" >> $GITHUB_OUTPUT; fi
+      - name: Setup Python
+        if: steps.detect.outputs.has_py == true
+        uses: actions/setup-python@v5
+        with:
+          python-version: 3.11
+          cache: pip
+      - name: Install deps
+        if: steps.detect.outputs.has_py == true
+        run: |
+          python -m pip install --upgrade pip
+          if [ -f requirements.txt ]; then pip install -r requirements.txt; fi
+          pip install ruff pytest mypy pip-audit
+      - name: Format & Lint
+        if: steps.detect.outputs.has_py == true
+        run: |
+          ruff format --check . || true
+          ruff check .
+      - name: Type Check
+        if: steps.detect.outputs.has_py == true
+        run: mypy . || true
+      - name: Test
+        if: steps.detect.outputs.has_py == true
+        run: pytest -q
+      - name: Audit (non-blocking)
+        if: steps.detect.outputs.has_py == true
+        run: pip-audit || true
+
+  gates:
+    name: Quality Gates
+    runs-on: ubuntu-latest
+    needs: [node, python]
+    steps:
+      - name: All language jobs completed
+        run: echo "Downstream jobs succeeded"

bpsai_pair/data/cookiecutter-paircoder/{{cookiecutter.project_slug}}/.github/workflows/project_tree.yml

@@ -0,0 +1,33 @@
+
+name: Refresh Project Tree
+
+on:
+  schedule:
+    - cron: 17 3 CODEOWNERS context CONTRIBUTING.md docs infra prompts scripts SECURITY.md services src templates tests tools CODEOWNERS context CONTRIBUTING.md docs infra prompts scripts SECURITY.md services src templates tests tools *
+  workflow_dispatch: {}
+
+permissions:
+  contents: write
+
+jobs:
+  refresh:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - name: Generate project tree
+        run: |
+          TS=$(date -u +%Y-%m-%dT%H:%M:%SZ)
+          echo "# Project Tree (snapshot)" > context/project_tree.md
+          echo "_Generated: ${TS}_" >> context/project_tree.md
+          echo >> context/project_tree.md
+          echo  >> context/project_tree.md
+      - name: Commit changes if any
+        run: |
+          git config user.name "github-actions"
+          git config user.email "actions@github.com"
+          git add context/project_tree.md || true
+          if ! git diff --cached --quiet; then
+            git commit -m "chore(context): refresh project_tree snapshot" && git push;
+          else
+            echo "No changes to commit.";
+          fi

bpsai_pair/data/cookiecutter-paircoder/{{cookiecutter.project_slug}}/.gitignore

@@ -0,0 +1,5 @@
+.venv/
+__pycache__/
+*.pyc
+agent_pack.tgz
+*.bak

bpsai_pair/data/cookiecutter-paircoder/{{cookiecutter.project_slug}}/.gitleaks.toml

@@ -0,0 +1,17 @@
+
+title = "paircoder gitleaks config"
+
+[allowlist]
+  description = "Allowed patterns"
+  files = [
+    "^context/project_tree.md$",
+    "^docs/adr/",
+  ]
+
+[allowlist.regexes]
+  description = "Common false positives"
+  regexes = [
+    "(?i)example(_|-)secret",
+    "(?i)dummy(token|key)",
+    "\b[0-9a-f]{8}-[0-9a-f]{4}-[1-5][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}\b",
+  ]

bpsai_pair/data/cookiecutter-paircoder/{{cookiecutter.project_slug}}/.pre-commit-config.yaml

@@ -0,0 +1,38 @@
+
+repos:
+  - repo: https://github.com/pre-commit/pre-commit-hooks
+    rev: v4.6.0
+    hooks:
+      - id: check-yaml
+      - id: check-json
+      - id: check-toml
+      - id: end-of-file-fixer
+      - id: trailing-whitespace
+  - repo: https://github.com/astral-sh/ruff-pre-commit
+    rev: v0.5.7
+    hooks:
+      - id: ruff
+        args: ["--fix"]
+      - id: ruff-format
+  - repo: https://github.com/igorshubovych/markdownlint-cli
+    rev: v0.42.0
+    hooks:
+      - id: markdownlint
+        args: ["--fix"]
+  - repo: https://github.com/pre-commit/mirrors-prettier
+    rev: v3.3.3
+    hooks:
+      - id: prettier
+        additional_dependencies: []
+  - repo: https://github.com/pre-commit/mirrors-eslint
+    rev: v9.9.1
+    hooks:
+      - id: eslint
+        additional_dependencies: []
+        files: \.(js|jsx|ts|tsx)$
+        args: ["--max-warnings", "0"]
+  - repo: local
+    hooks:
+      - id: gitleaks-scan
+        name: gitleaks scan
+        entry: bash -c gitleaks detect --no-banner --redact --config .gitleaks.toml

bpsai_pair/data/cookiecutter-paircoder/{{cookiecutter.project_slug}}/CODEOWNERS

@@ -0,0 +1,9 @@
+
+*       @{{cookiecutter.owner_gh_handle}}
+/context/*                 @{{cookiecutter.owner_gh_handle}} @{{cookiecutter.architect_gh_handle}}
+/scripts/*                 @{{cookiecutter.owner_gh_handle}} @{{cookiecutter.build_gh_handle}}
+/.github/*                 @{{cookiecutter.owner_gh_handle}} @{{cookiecutter.build_gh_handle}}
+/prompts/*                 @{{cookiecutter.owner_gh_handle}} @{{cookiecutter.architect_gh_handle}}
+/tests/**                  @{{cookiecutter.qa_gh_handle}} @{{cookiecutter.owner_gh_handle}}
+/infra/**                  @{{cookiecutter.sre_gh_handle}} @{{cookiecutter.owner_gh_handle}}
+/schemas/**                @{{cookiecutter.architect_gh_handle}} @{{cookiecutter.owner_gh_handle}}

bpsai_pair/data/cookiecutter-paircoder/{{cookiecutter.project_slug}}/CONTRIBUTING.md

@@ -0,0 +1,35 @@
+
+# Contributing Guide
+
+Thanks for contributing! This repo is optimized for AI pair coding and human review.
+
+## Branching & Commits
+- Branch from `main` using: `feature/<short-goal>`, `refactor/<module>`, or `fix/<ticket>`.
+- Use Conventional Commits (feat, fix, refactor, docs, test, chore, build, ci).
+
+## Local Dev & CI
+- Run local CI before pushing:
+  ```bash
+  scripts/ci_local.sh
+  ```
+- Add/adjust tests **before** behavior changes.
+- Keep diffs small and focused; open PRs early.
+
+## Context Discipline (MANDATORY)
+- `/context/*` is canonical for agent runs. Update the Context Sync block in `context/development.md` after each change:
+```
+## Context Sync (AUTO-UPDATED)
+Overall goal is: <PRIMARY GOAL>
+Last action was: <what changed and why> (commit SHA)
+Next action will be: <smallest valuable step with owner>
+Blockers/Risks: <if any>
+```
+
+## Pull Requests
+- Use the PR template (risk, test plan, rollback, context diff).
+- Public API/infra changes require an ADR under `/docs/adr/`.
+- High-risk PRs require CODEOWNERS sign-off.
+
+## Secrets & Data Safety
+- Never commit secrets; provide `.env.example`.
+- Do not include binaries/media in agent packs; maintain `.agentpackignore`.

bpsai_pair/data/cookiecutter-paircoder/{{cookiecutter.project_slug}}/SECURITY.md

@@ -0,0 +1,14 @@
+
+# Security Policy
+
+## Supported Versions
+We aim to keep `main` secure. Fixes are backported to the latest minor.
+
+## Reporting a Vulnerability
+- Email: security@<your-domain> (or open a private GitHub security advisory)
+- Include: affected versions/commit, reproduction, impact, proposed severity.
+- We acknowledge within 2 business days and update until resolution.
+
+## Handling Sensitive Data
+- No secrets in repo or agent packs.
+- Use redacted fixtures/synthetic data for tests and context.

bpsai_pair/data/cookiecutter-paircoder/{{cookiecutter.project_slug}}/context/agents.md

@@ -0,0 +1,6 @@
+# Agents Guide\n\nThis project uses a **Context Loop**. Always keep these fields current:\n\n- **Overall goal is:** Single-sentence mission\n- **Last action was:** What just completed\n- **Next action will be:** The very next step\n- **Blockers:** Known issues or decisions needed\n\n### Working Rules for Agents\n- Do not modify or examine ignored directories (see `.agentpackignore`). Assume large assets exist even if excluded.\n- Prefer minimal, reversible changes.\n- After committing code, run `bpsai-pair context-sync` to update the loop.\n- Request a new context pack when the tree or docs change significantly.\n\n### Context Pack\nRun `bpsai-pair pack --out agent_pack.tgz` and upload to your session.\n
+---
+
+## Branch Discipline
+- Use `--type feature|fix|refactor` when creating features.
+- Conventional Commits recommended.