groundcrew 0.1.0__tar.gz

groundcrew-0.1.0/.aider.conf.yml

@@ -0,0 +1,18 @@
+# aider configuration for groundcrew
+# https://aider.chat/docs/config/aider_conf.html
+
+read:
+  - ARCHITECTURE.md
+  - CLAUDE.md
+  - src/groundcrew/__init__.py
+
+lint: true
+lint-cmd: "ruff check {files} && ruff format --check {files}"
+
+auto-test: false
+test-cmd: "pytest tests/ -x -q"
+
+model: claude-sonnet-4-5
+
+attribute-author: false
+attribute-co-author: true

groundcrew-0.1.0/.claude/commands/domain.md

@@ -0,0 +1,11 @@
+Domain-specific slash commands for groundcrew.
+
+Replace this file with commands that match the tool's core operations.
+See agentdelta's .claude/commands/ for reference examples:
+  - diff.md    — runs the primary comparison operation
+  - inspect.md — inspects a single artifact
+  - record.md  — generates recording boilerplate
+  - add-adapter.md — scaffolds a new framework adapter
+
+Naming convention: /project:<verb> where verb describes what it does,
+not what it is. "diff" not "agentdelta", "record" not "trace".

groundcrew-0.1.0/.claude/commands/pr-prep.md

@@ -0,0 +1,18 @@
+Run the full pre-PR checklist and report what's ready and what needs fixing.
+
+Steps:
+1. Run lint: `make lint` (ruff check + ruff format --check)
+2. Run type check: `make typecheck` (mypy)
+3. Run tests: `make test` (pytest with coverage)
+4. Check CHANGELOG.md has an entry under [Unreleased] for this change
+5. Check that no debug print() statements or TODO comments were left in modified files
+
+Report in this format:
+  ✅ Lint — clean
+  ✅ Types — clean
+  ✅ Tests — 43 passed, 87% coverage
+  ⚠️  CHANGELOG — no [Unreleased] entry found
+  ✅ No debug artifacts
+
+If anything fails, show the exact error and the file:line to fix.
+Do not mark the PR ready until all 5 checks pass.

groundcrew-0.1.0/.claude/commands/release.md

@@ -0,0 +1,21 @@
+Prepare a release: bump version, finalize CHANGELOG, and show the git tag command.
+
+Usage: /project:release <version>  (e.g. /project:release 0.2.0)
+
+Steps:
+1. Verify all checks pass: lint, typecheck, tests (run make all)
+2. In CHANGELOG.md:
+   - Rename [Unreleased] to [<version>] - <today's date in YYYY-MM-DD>
+   - Add a new empty [Unreleased] section at the top
+   - Update the comparison links at the bottom
+3. In pyproject.toml: set version = "<version>"
+4. Show the git commands needed (do NOT run them):
+   ```
+   git add CHANGELOG.md pyproject.toml
+   git commit -m "chore: release v<version>"
+   git tag v<version>
+   git push origin main --tags
+   ```
+5. Note: the GitHub Actions release.yml will auto-publish to PyPI on tag push.
+
+Do NOT push or tag without explicit user confirmation.

groundcrew-0.1.0/.claude/commands/test.md

@@ -0,0 +1,14 @@
+Run the full test suite with coverage and report results.
+
+Steps:
+1. Run: `make test`
+   (equivalent to: `pytest tests/ --cov=<name> --cov-report=term-missing`)
+2. Report:
+   - Total tests, passed, failed, skipped
+   - Coverage percentage — flag if below 85%
+   - Any failing tests: show the test name, error message, and the relevant source line
+3. If any tests fail, diagnose the root cause before suggesting a fix:
+   - Is it a logic error in the implementation?
+   - Is it a test that needs updating due to an intentional behavior change?
+   - Is it a missing edge case?
+4. Do NOT suggest disabling or skipping tests to make the suite pass.

groundcrew-0.1.0/.coderabbit.yaml

@@ -0,0 +1,17 @@
+language: en
+early_access: false
+reviews:
+  profile: chill
+  request_changes_workflow: false
+  high_level_summary: true
+  poem: false
+  review_status: true
+  collapse_walkthrough: false
+  auto_review:
+    enabled: true
+    drafts: false
+  path_filters:
+    - "!assets/**"
+    - "!*.md"
+chat:
+  auto_reply: true

groundcrew-0.1.0/.continue/config.json

@@ -0,0 +1,29 @@
+{
+  "name": "groundcrew",
+  "version": "0.1.0",
+  "schema": "v1",
+  "context": [
+    {"provider": "file", "params": {"nRetrieve": 20, "nFinal": 5}},
+    {"provider": "code"}
+  ],
+  "docs": [
+    {
+      "title": "groundcrew Architecture",
+      "startUrl": "file://./ARCHITECTURE.md",
+      "faviconUrl": ""
+    }
+  ],
+  "customCommands": [
+    {
+      "name": "explain",
+      "prompt": "Explain how this part of groundcrew works: {input}. Use the module map in AGENTS.md as context.",
+      "description": "Explain a part of the codebase"
+    }
+  ],
+  "rules": [
+    "This is groundcrew — Deterministic state oracle and semantic action codec for computer-use agents.",
+    "Library code must not use print() — use rich.console.Console.",
+    "All public API must have type annotations and docstrings.",
+    "Tests use pytest. CLI tests use click.testing.CliRunner."
+  ]
+}

groundcrew-0.1.0/.cursor/rules/project.mdc

@@ -0,0 +1,32 @@
+---
+description: groundcrew coding rules and architecture context
+globs: ["src/**/*.py", "tests/**/*.py"]
+alwaysApply: true
+---
+
+# groundcrew — Cursor Rules
+
+## What this project does
+Deterministic state oracle and semantic action codec for computer-use agents
+
+## Module map
+```
+src/groundcrew/
+├── # TODO: fill in after implementation
+```
+
+## Invariants — never break these
+- TODO: list invariants
+
+## Code style
+- Python 3.10+, fully type-annotated, mypy strict mode
+- Ruff lint rules: E W F I UP B S N SIM RUF PT
+- No print() in library code — use rich.console.Console
+- All public functions and classes must have docstrings
+- Tests: pytest, CliRunner for CLI tests
+
+## When adding a new feature
+1. Implement in the appropriate module
+2. Export from __init__.py, add to __all__ alphabetically
+3. Add tests in tests/test_<module>.py
+4. Update CHANGELOG.md under [Unreleased]

groundcrew-0.1.0/.editorconfig

@@ -0,0 +1,24 @@
+root = true
+
+[*]
+indent_style = space
+indent_size = 4
+end_of_line = lf
+charset = utf-8
+trim_trailing_whitespace = true
+insert_final_newline = true
+
+[*.yml]
+indent_size = 2
+
+[*.yaml]
+indent_size = 2
+
+[*.toml]
+indent_size = 4
+
+[*.md]
+trim_trailing_whitespace = false
+
+[Makefile]
+indent_style = tab

groundcrew-0.1.0/.github/CODEOWNERS

@@ -0,0 +1 @@
+* @sandeep-alluru

groundcrew-0.1.0/.github/FUNDING.yml

@@ -0,0 +1 @@
+github: sandeep-alluru

groundcrew-0.1.0/.github/ISSUE_TEMPLATE/bug_report.yml

@@ -0,0 +1,42 @@
+name: Bug Report
+description: Something is broken
+labels: ["bug"]
+body:
+  - type: input
+    id: version
+    attributes:
+      label: groundcrew version
+      placeholder: "0.1.0"
+    validations:
+      required: true
+
+  - type: input
+    id: python
+    attributes:
+      label: Python version
+      placeholder: "3.11.5"
+    validations:
+      required: true
+
+  - type: textarea
+    id: command
+    attributes:
+      label: Command / code that triggered the bug
+      render: bash
+    validations:
+      required: true
+
+  - type: textarea
+    id: expected
+    attributes:
+      label: Expected behavior
+    validations:
+      required: true
+
+  - type: textarea
+    id: actual
+    attributes:
+      label: Actual behavior (include full traceback)
+      render: text
+    validations:
+      required: true

groundcrew-0.1.0/.github/ISSUE_TEMPLATE/feature_request.yml

@@ -0,0 +1,28 @@
+name: Feature Request
+description: Propose a new feature
+labels: ["enhancement"]
+body:
+  - type: textarea
+    id: problem
+    attributes:
+      label: Problem
+    validations:
+      required: true
+
+  - type: textarea
+    id: solution
+    attributes:
+      label: Proposed solution
+    validations:
+      required: true
+
+  - type: dropdown
+    id: contribution
+    attributes:
+      label: Are you willing to implement this?
+      options:
+        - "Yes — I'll open a PR"
+        - "Maybe — if someone helps"
+        - "No — just requesting"
+    validations:
+      required: true

groundcrew-0.1.0/.github/PULL_REQUEST_TEMPLATE.md

@@ -0,0 +1,31 @@
+## What changed
+
+<!-- One paragraph summary -->
+
+## Why
+
+Closes #
+
+## Type of change
+
+- [ ] `fix:` Bug fix
+- [ ] `feat:` New feature
+- [ ] `refactor:` No behavior change
+- [ ] `docs:` Documentation only
+- [ ] `test:` Tests only
+- [ ] `chore:` Deps, CI, tooling
+- [ ] `perf:` Performance
+
+## Testing done
+
+- [ ] `make test` passes
+- [ ] `make lint` passes
+- [ ] `make typecheck` passes
+- [ ] New tests added
+
+## Checklist
+
+- [ ] `CHANGELOG.md` updated under `[Unreleased]`
+- [ ] Public API changes have docstrings
+- [ ] No secrets committed
+- [ ] README updated if CLI/behavior changed

groundcrew-0.1.0/.github/copilot-instructions.md

@@ -0,0 +1,34 @@
+# GitHub Copilot Instructions — groundcrew
+
+groundcrew: Deterministic state oracle and semantic action codec for computer-use agents
+
+## Module map
+
+```
+src/groundcrew/
+├── # TODO: fill in after implementation
+```
+
+## Key invariants
+
+- TODO: document invariants
+
+## Code style
+
+- Python 3.10+, type-annotated, mypy strict mode
+- Ruff lint rules: E W F I UP B S N SIM RUF PT; ignore S101 (assert in tests), N806
+- No `print()` in library code — use `rich.console.Console`
+- All public classes and functions must have docstrings
+- Tests use `pytest`; CLI tests use `click.testing.CliRunner`
+
+## Adding a new output format
+
+1. Add `to_<format>(result) -> str` in `report.py`
+2. Add format name to `--format` choices in `cli.py`
+3. Add tests
+
+## Adding a new adapter / integration
+
+1. Create `src/groundcrew/instrument_<framework>.py`
+2. Export from `__init__.py`, add to `__all__` alphabetically
+3. Add tests

groundcrew-0.1.0/.github/dependabot.yml

@@ -0,0 +1,15 @@
+version: 2
+updates:
+  - package-ecosystem: pip
+    directory: /
+    schedule:
+      interval: weekly
+    open-pull-requests-limit: 5
+    labels: [dependencies]
+
+  - package-ecosystem: github-actions
+    directory: /
+    schedule:
+      interval: weekly
+    open-pull-requests-limit: 5
+    labels: [dependencies, ci]

groundcrew-0.1.0/.github/labels.yml

@@ -0,0 +1,98 @@
+# Bug reports
+- name: bug
+  color: "d73a4a"
+  description: "Something isn't working"
+
+- name: fix
+  color: "d73a4a"
+  description: "A bug fix"
+
+# Features
+- name: enhancement
+  color: "a2eeef"
+  description: "New feature or request"
+
+- name: feature
+  color: "a2eeef"
+  description: "New feature"
+
+- name: feat
+  color: "a2eeef"
+  description: "New feature (conventional commit)"
+
+# Documentation
+- name: documentation
+  color: "0075ca"
+  description: "Improvements or additions to documentation"
+
+- name: docs
+  color: "0075ca"
+  description: "Documentation update"
+
+# Maintenance
+- name: chore
+  color: "e4e669"
+  description: "Build process, dependencies, or tooling"
+
+- name: dependencies
+  color: "0366d6"
+  description: "Pull requests that update a dependency"
+
+- name: ci
+  color: "e4e669"
+  description: "CI/CD changes"
+
+- name: refactor
+  color: "fef2c0"
+  description: "Code refactoring without behavior change"
+
+# Tests
+- name: test
+  color: "bfd4f2"
+  description: "Adding missing tests or correcting existing tests"
+
+# Version bumps
+- name: major
+  color: "ee0701"
+  description: "Breaking change — bumps major version"
+
+- name: minor
+  color: "fbca04"
+  description: "Non-breaking new feature — bumps minor version"
+
+- name: patch
+  color: "0075ca"
+  description: "Backwards compatible bug fix — bumps patch version"
+
+# Meta
+- name: good first issue
+  color: "7057ff"
+  description: "Good for newcomers"
+
+- name: help wanted
+  color: "008672"
+  description: "Extra attention is needed"
+
+- name: security
+  color: "ee0701"
+  description: "Security vulnerability"
+
+- name: pinned
+  color: "e11d48"
+  description: "Pinned issue — do not close"
+
+- name: duplicate
+  color: "cfd3d7"
+  description: "This issue or pull request already exists"
+
+- name: invalid
+  color: "e4e4e7"
+  description: "This doesn't seem right"
+
+- name: wontfix
+  color: "e4e4e7"
+  description: "This will not be worked on"
+
+- name: question
+  color: "d876e3"
+  description: "Further information is requested"

groundcrew-0.1.0/.github/release-drafter.yml

@@ -0,0 +1,58 @@
+name-template: "v$RESOLVED_VERSION"
+tag-template: "v$RESOLVED_VERSION"
+categories:
+  - title: "🚀 New Features"
+    labels:
+      - "feature"
+      - "enhancement"
+      - "feat"
+  - title: "🐛 Bug Fixes"
+    labels:
+      - "fix"
+      - "bugfix"
+      - "bug"
+  - title: "🧰 Maintenance"
+    labels:
+      - "chore"
+      - "dependencies"
+      - "ci"
+      - "refactor"
+  - title: "📖 Documentation"
+    labels:
+      - "documentation"
+      - "docs"
+  - title: "🧪 Tests"
+    labels:
+      - "test"
+      - "tests"
+change-template: "- $TITLE @$AUTHOR (#$NUMBER)"
+change-prefix: ""
+no-changes-template: "No changes."
+version-resolver:
+  major:
+    labels:
+      - "major"
+      - "breaking"
+  minor:
+    labels:
+      - "minor"
+      - "feature"
+      - "enhancement"
+      - "feat"
+  patch:
+    labels:
+      - "patch"
+      - "fix"
+      - "bugfix"
+      - "documentation"
+      - "chore"
+      - "dependencies"
+      - "ci"
+      - "refactor"
+  default: patch
+template: |
+  ## What's Changed
+
+  $CHANGES
+
+  **Full Changelog**: https://github.com/sandeep-alluru/groundcrew/compare/$PREVIOUS_TAG...v$RESOLVED_VERSION

groundcrew-0.1.0/.github/workflows/ci.yml

@@ -0,0 +1,81 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+
+jobs:
+  test:
+    name: Test (${{ matrix.os }} / Python ${{ matrix.python-version }})
+    runs-on: ${{ matrix.os }}
+    strategy:
+      fail-fast: false
+      matrix:
+        os: [ubuntu-latest, macos-latest]
+        python-version: ["3.10", "3.11", "3.12"]
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Set up Python ${{ matrix.python-version }}
+        uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+
+      - name: Cache pip
+        uses: actions/cache@v4
+        with:
+          path: ~/.cache/pip
+          key: ${{ runner.os }}-pip-${{ matrix.python-version }}-${{ hashFiles('pyproject.toml') }}
+          restore-keys: ${{ runner.os }}-pip-${{ matrix.python-version }}-
+
+      - name: Install dependencies
+        run: pip install -e ".[dev]"
+
+      - name: Lint
+        run: ruff check src/ tests/
+
+      - name: Format check
+        run: ruff format --check src/ tests/
+
+      - name: Type check
+        run: mypy src/groundcrew/ --ignore-missing-imports
+
+      - name: Test
+        run: pytest tests/ -v --tb=short
+
+      - name: Upload coverage
+        if: matrix.python-version == '3.11' && matrix.os == 'ubuntu-latest'
+        uses: codecov/codecov-action@v5
+        with:
+          files: coverage.xml
+          fail_ci_if_error: false
+
+  receipt-audit:
+    name: Receipt Audit
+    runs-on: ubuntu-latest
+    if: github.event_name == 'pull_request'
+    needs: test
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.11"
+      - name: Cache pip
+        uses: actions/cache@v4
+        with:
+          path: ~/.cache/pip
+          key: ${{ runner.os }}-pip-3.11-${{ hashFiles('pyproject.toml') }}
+      - name: Install groundcrew
+        run: pip install -e .
+      - name: Audit receipt store (if DB exists)
+        run: |
+          if [ -f .groundcrew/receipts.db ]; then
+            groundcrew log
+            groundcrew status
+          else
+            echo "No receipt store — skipping audit."
+          fi
+        continue-on-error: true

groundcrew-0.1.0/.github/workflows/codeql.yml

@@ -0,0 +1,32 @@
+name: CodeQL Security Scan
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+  schedule:
+    - cron: "0 18 * * 5"  # every Friday at 18:00 UTC
+
+jobs:
+  analyze:
+    name: Analyze (Python)
+    runs-on: ubuntu-latest
+    permissions:
+      actions: read
+      contents: read
+      security-events: write
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Initialize CodeQL
+        uses: github/codeql-action/init@v3
+        with:
+          languages: python
+          queries: security-extended
+
+      - name: Perform CodeQL Analysis
+        uses: github/codeql-action/analyze@v3
+        with:
+          category: "/language:python"

groundcrew-0.1.0/.github/workflows/docs.yml

@@ -0,0 +1,53 @@
+name: Docs
+
+on:
+  push:
+    branches: [main]
+    paths:
+      - "docs/**"
+      - "mkdocs.yml"
+      - "src/**"
+      - "ARCHITECTURE.md"
+      - "CHANGELOG.md"
+      - "CONTRIBUTING.md"
+  workflow_dispatch:
+
+permissions:
+  contents: read
+  pages: write
+  id-token: write
+
+concurrency:
+  group: pages
+  cancel-in-progress: true
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.11"
+          cache: pip
+
+      - name: Install docs dependencies
+        run: pip install -e ".[docs]"
+
+      - name: Build docs
+        run: mkdocs build --strict
+
+      - uses: actions/upload-pages-artifact@v3
+        with:
+          path: site/
+
+  deploy:
+    needs: build
+    runs-on: ubuntu-latest
+    environment:
+      name: github-pages
+      url: ${{ steps.deployment.outputs.page_url }}
+    steps:
+      - uses: actions/deploy-pages@v4
+        id: deployment