opentide 0.1.0__tar.gz

opentide-0.1.0/.agents/skills/cli-e2e-testing/SKILL.md

@@ -0,0 +1,126 @@
+# CLI E2E Testing
+
+Typer-native end-to-end tests for the `opentide` CLI using `CliRunner` (in-process) plus a small subprocess smoke layer.
+
+## When to use
+
+- Adding or changing CLI commands, flags, or JSON output shape
+- Extending the simulated Tide workspace (`tide_corpus`)
+- Deploy dry-run payload verification (unit + E2E)
+- Schema forward-evolution scaffolds (`future/rule_1_1`)
+
+## Terminology
+
+Use **threat**, **objective**, and **rule** in fixture names and test labels. Do **not** use legacy prefixes MDR, DOM, or TVM.
+
+| Object   | Schema id        | Filename pattern                    |
+|----------|------------------|-------------------------------------|
+| threat   | `threat::1.0`    | `threat-{id}-{slug}.yaml`           |
+| objective| `objective::1.0` | `objective-{id}-{slug}.yaml`        |
+| rule     | `rule::1.0`      | `rule-{id}-{platform}-{slug}.yaml`  |
+
+Baseline is current `*::1.0` only — no tide_1 legacy slices.
+
+## Layout
+
+```
+tests/
+  fixtures/tide_corpus/
+    manifest.toml          # slice lifecycle (current active, future reserved)
+    current/               # canonical E2E workspace
+    future/rule_1_1/       # reserved until rule::1.1 lands
+  test_cli/
+    conftest.py            # cli_runner, tide_corpus_repo, invoke_cli, parse_cli_json
+    e2e/                   # @pytest.mark.cli_e2e (and cli_smoke for subprocess)
+  test_deployment/
+    test_deploy_payloads.py  # per-platform API payload golden tests
+```
+
+## Running tests
+
+```bash
+# E2E only (development)
+uv run pytest tests/test_cli/e2e/ -m "cli_e2e or cli_smoke" --no-cov
+
+# Unit tests (excludes E2E markers — matches CI matrix)
+uv run pytest tests/ -m "not cli_e2e and not cli_smoke"
+
+# Local CI parity (unit then E2E)
+scripts/ci-local.sh --full
+
+# Update syrupy snapshots
+uv run pytest tests/test_cli/e2e/ --snapshot-update
+uv run pytest tests/test_deployment/test_deploy_payloads.py --snapshot-update
+```
+
+## CI
+
+- **Unit matrix** (Python 3.10–3.14): `-m "not cli_e2e and not cli_smoke"`
+- **`cli-e2e` job** (Python 3.14 only, `needs: [test]`): `-m "cli_e2e or cli_smoke"`
+- **`cli-windows-smoke` job**: `test_console_script_smoke.py -m cli_smoke` — the only coverage of `spawn` platforms
+
+E2E does not contribute to coverage metrics.
+
+### `cli_smoke` must stay out-of-process
+
+`cli_e2e` uses `CliRunner`, which calls `app` inside the pytest process and never runs
+the installed console script. `cli_smoke` covers that gap and therefore carries
+`@pytest.mark.script_launch_mode("subprocess")` — `pytest-console-scripts` defaults to
+`inprocess`, which only loads the entry point as a function and cannot catch import-time
+failures (for example multiprocessing `spawn` re-importing the entry point).
+
+Smoke tests also take `tide_corpus_repo` so the console script indexes a real corpus.
+Running them against the default empty workspace makes them pass vacuously, because
+object parsing never engages.
+
+## Shared fixtures
+
+| Fixture              | Purpose                                              |
+|----------------------|------------------------------------------------------|
+| `cli_runner`         | `typer.testing.CliRunner()`                          |
+| `tide_corpus_repo`   | Copy of `current/` slice into `tmp_path` with env    |
+| `invoke_cli`         | Helper: `--repo`, `--json` defaults                  |
+| `parse_cli_json`     | Extract top-level JSON from stdout (after indexer)   |
+| `corpus_rule_uuids`  | Deterministic rule UUIDs per platform              |
+| `mock_query_validators` | No-op validators for validate query E2E          |
+
+## tide_corpus extension
+
+1. Add YAML under `tests/fixtures/tide_corpus/current/Objects/…`
+2. Use deterministic UUIDs (`00000000-0000-4000-8xxx-…`)
+3. Include platform `configurations.*` blocks for deploy payload tests
+4. Register new forward slices in `manifest.toml` (`status = "reserved"` → `"active"`)
+
+## Deploy payload testing
+
+**Unit** (`test_deploy_payloads.py`): load corpus rule → `preview_rule_deployment()` → syrupy snapshot of `api_request`.
+
+**E2E** (`test_deploy_e2e.py`):
+
+```
+opentide --json --repo <corpus> deploy --dry-run --platform <platform> --plan FULL --wide --skip-promotion
+```
+
+Assert `ok`, `dry_run`, `plan[platform]`, and `payloads[platform][]` with `uuid` + `api_request`.
+
+Mock only the network boundary (`DeployTide.mdr` deployer); do not mock payload compilation.
+
+## Mocking policy
+
+| Mock                         | Do not mock                    |
+|------------------------------|--------------------------------|
+| HTTP / cloud SDK clients     | Index loading, deploy plan     |
+| Query validators (E2E only)  | JSON emission, exit codes      |
+| `modified_mdr_files` (mutate)| Payload preview compile path   |
+
+## Schema bump checklist
+
+1. Bump Pydantic models / `SchemaVersionChain`
+2. Add objects under `future/<slice>/`
+3. Flip `manifest.toml` slice `status` to `active`
+4. Regenerate syrupy snapshots
+5. Remove `xfail` from `test_schema_compat_e2e.py` when slice is live
+
+## JSON parsing note
+
+The indexer prints progress to stdout before JSON. Use `parse_cli_json()` (first top-level `{` + `JSONDecoder.raw_decode`) — do not assume stdout is JSON-only.

opentide-0.1.0/.agents/skills/codeql/SKILL.md

@@ -0,0 +1,46 @@
+# CodeQL — OpenTide
+
+Static analysis for Python and GitHub Actions workflows. One workflow, no duplicate scans.
+
+## When to use
+
+- Adding or changing security-sensitive Python or workflow code
+- Investigating CodeQL alerts on a PR
+- Running analysis locally before a large security-related change
+
+## CI workflow
+
+[`.github/workflows/codeql.yml`](../../../.github/workflows/codeql.yml):
+
+- **Languages:** `python` and `actions` in one matrix job (categories `/language:python` and `/language:actions`)
+- **Why both in the workflow:** PR code-scanning comparison requires the same `(codeql.yml) /language:python` category registered on `development`; Code Quality dynamic scans alone leave PR checks in a NEUTRAL "configuration not found" state
+- **Triggers:** push to `main`/`development`, all PRs, weekly schedule
+- **Queries:** `security-extended`
+- **Python deps:** `uv sync --group dev` before analyze
+
+Code Quality may also run a dynamic Python scan on push; if duplicate alerts appear, disable Python in Code Quality settings and rely on this workflow.
+
+## Local analysis
+
+```bash
+scripts/codeql-local.sh              # create DB + analyze Python (~40–60s cold)
+scripts/codeql-local.sh --install    # brew install CodeQL CLI only
+```
+
+Mirrors the Python path in CI. Not suitable for pre-commit or pre-push hooks.
+
+Output: `codeql-results.sarif` at repo root.
+
+## When to run locally vs CI
+
+| Situation | Run |
+|-----------|-----|
+| Normal feature work | CI only |
+| Workflow or auth changes | `scripts/codeql-local.sh` before push |
+| Fixing a CodeQL alert | Local repro, then push fix |
+| Pre-commit / pre-push | **Do not** — too slow |
+
+## Related
+
+- `AGENTS.md` — CI overview
+- [`github-actions-templates`](../github-actions-templates/SKILL.md) — workflow authoring

opentide-0.1.0/.agents/skills/docs-maintenance/SKILL.md

@@ -0,0 +1,100 @@
+---
+name: opentide-docs-maintenance
+description: >-
+  Maintain OpenTide documentation in docs/ — Fumadocs structure, frontmatter,
+  meta.json navigation, and keeping CLI/MCP/SDK pages in sync with code.
+---
+
+# OpenTide documentation maintenance
+
+Use this skill when adding features, changing CLI/MCP/SDK surface area, or authoring pages under `docs/`.
+
+## Doc structure (four tabs)
+
+| Tab | Path | Update when |
+|-----|------|-------------|
+| Usage | `docs/usage/` | Setup flows, workflows, concepts, migration |
+| CLI | `docs/cli/` | Typer commands, flags, behaviour |
+| MCP | `docs/mcp/` | Tools, resources, config templates |
+| SDK | `docs/sdk/` | Public Python API, registry, models |
+
+Internal maintainer docs: `docs/internal/` (excluded from public site root).
+
+Authoring conventions: [`docs/README.md`](../../docs/README.md).
+
+## Page template
+
+Every new page:
+
+```markdown
+---
+title: Human title
+description: One sentence for cards and search
+---
+
+# Human title
+
+First paragraph explains purpose in plain language.
+```
+
+Optional Fumadocs fields: `icon`, `full`.
+
+## Navigation
+
+Add the page slug to the folder's `meta.json` `pages` array. Root tabs use `"root": true`.
+
+```json
+{
+  "pages": ["index", "---Section---", "new-page"]
+}
+```
+
+## Code change checklist
+
+When modifying source, update docs in the **same PR**:
+
+| Source file | Doc target |
+|-------------|------------|
+| `src/opentide/cli/__init__.py` | `docs/cli/*.md` |
+| `src/opentide/cli/setup_app.py` | `docs/cli/setup.md`, `docs/usage/repository-setup.md` |
+| `src/opentide/mcp_server/server.py` | `docs/mcp/tools.md`, `docs/mcp/resources.md` |
+| `src/opentide/mcp_server/tools.py` | `docs/mcp/tools.md` |
+| `src/opentide/core/registry.py` | `docs/sdk/registry.md` |
+| `src/opentide/__init__.py` | `docs/sdk/index.md` |
+| `src/opentide/cli/enums.py` (platforms) | `docs/usage/concepts/platforms.md` |
+| `src/opentide/data/setup/skills/` | `docs/usage/workflows/agentic-setup.md` |
+
+## Verify CLI accuracy
+
+Extract live help when documenting flags:
+
+```bash
+uv run opentide --help
+uv run opentide <command> --help
+```
+
+Do not document flags that do not exist (e.g. legacy `--scope` on `document` — use subcommands).
+
+## Validation
+
+```bash
+scripts/validate-docs.sh
+```
+
+Fixes: missing frontmatter, broken internal links, orphan pages not listed in meta.json.
+
+## Platform capability rule
+
+Seven platforms deploy; five validate queries. CrowdStrike and HarfangLab: **`supported: false`** for query validation — document this consistently in Usage, CLI, MCP, and SDK pages.
+
+## Cross-linking
+
+- Usage → CLI/MCP/SDK for "technical reference"
+- CLI/MCP/SDK → Usage for "getting started"
+- Relative paths only; no hardcoded `github.com/.../blob/` for in-repo pages
+
+## Fumadocs site repo
+
+**Build and deploy:** [OpenTideHQ/website](https://github.com/OpenTideHQ/website). This repo ships content under `docs/` only.
+
+Notes: [`docs/fumadocs/`](../../docs/fumadocs/).

opentide-0.1.0/.agents/skills/github-actions-templates/SKILL.md

@@ -0,0 +1,328 @@
+---
+name: github-actions-templates
+description: Create production-ready GitHub Actions workflows for automated testing, building, and deploying applications. Use when setting up CI/CD with GitHub Actions, automating development workflows, or creating reusable workflow templates.
+---
+
+# GitHub Actions Templates
+
+Production-ready GitHub Actions workflow patterns for testing, building, and deploying applications.
+
+## Purpose
+
+Create efficient, secure GitHub Actions workflows for continuous integration and deployment across various tech stacks.
+
+## When to Use
+
+- Automate testing and deployment
+- Build Docker images and push to registries
+- Deploy to Kubernetes clusters
+- Run security scans
+- Implement matrix builds for multiple environments
+
+## Common Workflow Patterns
+
+### Pattern 1: Test Workflow
+
+```yaml
+name: Test
+
+on:
+  push:
+    branches: [main, develop]
+  pull_request:
+    branches: [main]
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+
+    strategy:
+      matrix:
+        node-version: [18.x, 20.x]
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Use Node.js ${{ matrix.node-version }}
+        uses: actions/setup-node@v4
+        with:
+          node-version: ${{ matrix.node-version }}
+          cache: "npm"
+
+      - name: Install dependencies
+        run: npm ci
+
+      - name: Run linter
+        run: npm run lint
+
+      - name: Run tests
+        run: npm test
+
+      - name: Upload coverage
+        uses: codecov/codecov-action@v4
+        with:
+          files: ./coverage/lcov.info
+```
+
+**Reference:** See `assets/test-workflow.yml`
+
+### Pattern 2: Build and Push Docker Image
+
+```yaml
+name: Build and Push
+
+on:
+  push:
+    branches: [main]
+    tags: ["v*"]
+
+env:
+  REGISTRY: ghcr.io
+  IMAGE_NAME: ${{ github.repository }}
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+      packages: write
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Log in to Container Registry
+        uses: docker/login-action@v3
+        with:
+          registry: ${{ env.REGISTRY }}
+          username: ${{ github.actor }}
+          password: ${{ secrets.GITHUB_TOKEN }}
+
+      - name: Extract metadata
+        id: meta
+        uses: docker/metadata-action@v5
+        with:
+          images: ${{ env.REGISTRY }}/${{ env.IMAGE_NAME }}
+          tags: |
+            type=ref,event=branch
+            type=ref,event=pr
+            type=semver,pattern={{version}}
+            type=semver,pattern={{major}}.{{minor}}
+
+      - name: Build and push
+        uses: docker/build-push-action@v5
+        with:
+          context: .
+          push: true
+          tags: ${{ steps.meta.outputs.tags }}
+          labels: ${{ steps.meta.outputs.labels }}
+          cache-from: type=gha
+          cache-to: type=gha,mode=max
+```
+
+**Reference:** See `assets/deploy-workflow.yml`
+
+### Pattern 3: Deploy to Kubernetes
+
+```yaml
+name: Deploy to Kubernetes
+
+on:
+  push:
+    branches: [main]
+
+jobs:
+  deploy:
+    runs-on: ubuntu-latest
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Configure AWS credentials
+        uses: aws-actions/configure-aws-credentials@v4
+        with:
+          aws-access-key-id: ${{ secrets.AWS_ACCESS_KEY_ID }}
+          aws-secret-access-key: ${{ secrets.AWS_SECRET_ACCESS_KEY }}
+          aws-region: us-west-2
+
+      - name: Update kubeconfig
+        run: |
+          aws eks update-kubeconfig --name production-cluster --region us-west-2
+
+      - name: Deploy to Kubernetes
+        run: |
+          kubectl apply -f k8s/
+          kubectl rollout status deployment/my-app -n production
+          kubectl get services -n production
+
+      - name: Verify deployment
+        run: |
+          kubectl get pods -n production
+          kubectl describe deployment my-app -n production
+```
+
+### Pattern 4: Matrix Build
+
+```yaml
+name: Matrix Build
+
+on: [push, pull_request]
+
+jobs:
+  build:
+    runs-on: ${{ matrix.os }}
+
+    strategy:
+      matrix:
+        os: [ubuntu-latest, macos-latest, windows-latest]
+        python-version: ["3.9", "3.10", "3.11", "3.12"]
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+
+      - name: Install dependencies
+        run: |
+          python -m pip install --upgrade pip
+          pip install -r requirements.txt
+
+      - name: Run tests
+        run: pytest
+```
+
+**Reference:** See `assets/matrix-build.yml`
+
+## Workflow Best Practices
+
+1. **Use specific action versions** (@v4, not @latest)
+2. **Cache dependencies** to speed up builds
+3. **Use secrets** for sensitive data
+4. **Implement status checks** on PRs
+5. **Use matrix builds** for multi-version testing
+6. **Set appropriate permissions**
+7. **Use reusable workflows** for common patterns
+8. **Implement approval gates** for production
+9. **Add notification steps** for failures
+10. **Use self-hosted runners** for sensitive workloads
+
+## Reusable Workflows
+
+```yaml
+# .github/workflows/reusable-test.yml
+name: Reusable Test Workflow
+
+on:
+  workflow_call:
+    inputs:
+      node-version:
+        required: true
+        type: string
+    secrets:
+      NPM_TOKEN:
+        required: true
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-node@v4
+        with:
+          node-version: ${{ inputs.node-version }}
+      - run: npm ci
+      - run: npm test
+```
+
+**Use reusable workflow:**
+
+```yaml
+jobs:
+  call-test:
+    uses: ./.github/workflows/reusable-test.yml
+    with:
+      node-version: "20.x"
+    secrets:
+      NPM_TOKEN: ${{ secrets.NPM_TOKEN }}
+```
+
+## Security Scanning
+
+```yaml
+name: Security Scan
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+
+jobs:
+  security:
+    runs-on: ubuntu-latest
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Run Trivy vulnerability scanner
+        uses: aquasecurity/trivy-action@0.28.0
+        with:
+          scan-type: "fs"
+          scan-ref: "."
+          format: "sarif"
+          output: "trivy-results.sarif"
+
+      - name: Upload Trivy results to GitHub Security
+        uses: github/codeql-action/upload-sarif@v3
+        with:
+          sarif_file: "trivy-results.sarif"
+
+      - name: Run Snyk Security Scan
+        uses: snyk/actions/node@0.4.0
+        env:
+          SNYK_TOKEN: ${{ secrets.SNYK_TOKEN }}
+```
+
+## Deployment with Approvals
+
+```yaml
+name: Deploy to Production
+
+on:
+  push:
+    tags: ["v*"]
+
+jobs:
+  deploy:
+    runs-on: ubuntu-latest
+    environment:
+      name: production
+      url: https://app.example.com
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Deploy application
+        run: |
+          echo "Deploying to production..."
+          # Deployment commands here
+
+      - name: Notify Slack
+        if: success()
+        uses: slackapi/slack-github-action@v1
+        with:
+          webhook-url: ${{ secrets.SLACK_WEBHOOK }}
+          payload: |
+            {
+              "text": "Deployment to production completed successfully!"
+            }
+```
+
+
+## Related Skills
+
+- `gitlab-ci-patterns` - For GitLab CI workflows
+- `deployment-pipeline-design` - For pipeline architecture
+- `secrets-management` - For secrets handling