oscura 0.5.0__tar.gz → 0.6.0__tar.gz

oscura-0.6.0/.github/config/README.md

@@ -0,0 +1,150 @@
+# GitHub Configuration Files
+
+This directory contains Infrastructure-as-Code (IaC) configuration files for GitHub repository settings.
+
+## Files
+
+### `main-branch-ruleset.json`
+
+Complete export of the current active ruleset configuration, including metadata (IDs, timestamps, links).
+
+**Purpose**: Documentation and backup of the live configuration.
+
+**Usage**: Reference only. Do not use for imports (contains repo-specific IDs).
+
+### `main-branch-ruleset-template.json`
+
+Clean template for creating/updating the main branch ruleset.
+
+**Purpose**: Replicable configuration for forks and new instances.
+
+**Usage**: Applied by `.github/scripts/setup-github-repo.sh` during repository setup.
+
+## Configuration Details
+
+### Main Branch Ruleset
+
+**Protection mechanisms**:
+
+- **Pull Request Rule**: Requires squash merge only (no required reviews for maintainers)
+- **Merge Queue Rule**: ALLGREEN strategy ensures all workflow checks pass before merging
+
+**Key settings**:
+
+```json
+{
+  "grouping_strategy": "ALLGREEN",      // All checks must pass
+  "merge_method": "SQUASH",              // Squash commits on merge
+  "check_response_timeout_minutes": 60,  // 1-hour timeout
+  "max_entries_to_build": 5,             // Batch up to 5 PRs
+  "min_entries_to_merge": 1              // Minimum 1 PR per batch
+}
+```
+
+**Why no required_status_checks rule?**
+
+The merge queue's ALLGREEN strategy already ensures all workflow checks pass. Adding explicit required status checks causes conflicts because:
+
+- PR workflows run on `pull_request` events
+- Merge queue creates `merge_group` events
+- Required checks defined for PR events won't run on merge_group events
+- Queue gets stuck waiting for checks that can't run
+
+**Solution**: Let ALLGREEN handle validation. It automatically requires all checks to pass without naming them explicitly.
+
+## Applying Configuration
+
+### Initial Setup
+
+```bash
+.github/scripts/setup-github-repo.sh
+```
+
+This script:
+
+1. Reads `main-branch-ruleset-template.json`
+2. Checks if ruleset exists
+3. Creates new ruleset OR updates existing one
+4. Idempotent (safe to run multiple times)
+
+### Manual Application
+
+```bash
+# Create new ruleset
+gh api -X POST repos/OWNER/REPO/rulesets \
+  --input .github/config/main-branch-ruleset-template.json
+
+# Update existing ruleset (replace ID with your ruleset ID)
+gh api -X PUT repos/OWNER/REPO/rulesets/12055878 \
+  --input .github/config/main-branch-ruleset-template.json
+```
+
+### Exporting Current Config
+
+```bash
+# List all rulesets and find ID
+gh api repos/OWNER/REPO/rulesets --jq '.[] | {id, name}'
+
+# Export specific ruleset
+gh api repos/OWNER/REPO/rulesets/ID > .github/config/main-branch-ruleset.json
+```
+
+## For Fork Maintainers
+
+When setting up a fork:
+
+1. **Option A - Use setup script** (recommended):
+
+   ```bash
+   .github/scripts/setup-github-repo.sh
+   ```
+
+2. **Option B - Manual setup**:
+
+   ```bash
+   # Set your repository
+   export REPO_FULL="your-org/your-repo"
+
+   # Create ruleset
+   gh api -X POST repos/${REPO_FULL}/rulesets \
+     --input .github/config/main-branch-ruleset-template.json
+   ```
+
+3. **Verify**:
+
+   ```bash
+   gh api repos/${REPO_FULL}/rulesets --jq '.[] | {name, enforcement}'
+   ```
+
+## Troubleshooting
+
+### Merge Queue Stuck in AWAITING_CHECKS
+
+**Symptoms**: PR enters merge queue but stays stuck, never progresses
+
+**Cause**: Ruleset has `required_status_checks` that only run on `pull_request` events, not `merge_group` events
+
+**Fix**: Remove `required_status_checks` from ruleset, rely on ALLGREEN strategy instead:
+
+```bash
+gh api -X PUT repos/OWNER/REPO/rulesets/ID \
+  --input .github/config/main-branch-ruleset-template.json
+```
+
+### Ruleset Already Exists
+
+The setup script is idempotent - it updates existing rulesets by name. Safe to run multiple times.
+
+### Permission Denied
+
+Requires admin permissions on the repository. Check:
+
+```bash
+gh auth status
+gh repo view OWNER/REPO --json viewerPermission
+```
+
+## Version History
+
+- **2026-01-24**: Removed `required_status_checks` rule after merge queue stuck incident
+- **2026-01-22**: Initial ruleset created with merge queue enabled

oscura-0.6.0/.github/config/main-branch-ruleset-template.json

@@ -0,0 +1,37 @@
+{
+  "name": "main branch protection with merge queue",
+  "target": "branch",
+  "enforcement": "active",
+  "conditions": {
+    "ref_name": {
+      "exclude": [],
+      "include": ["refs/heads/main"]
+    }
+  },
+  "rules": [
+    {
+      "type": "pull_request",
+      "parameters": {
+        "required_approving_review_count": 0,
+        "dismiss_stale_reviews_on_push": false,
+        "require_code_owner_review": false,
+        "require_last_push_approval": false,
+        "required_review_thread_resolution": false,
+        "allowed_merge_methods": ["squash"]
+      }
+    },
+    {
+      "type": "merge_queue",
+      "parameters": {
+        "merge_method": "SQUASH",
+        "max_entries_to_build": 5,
+        "min_entries_to_merge": 1,
+        "max_entries_to_merge": 5,
+        "min_entries_to_merge_wait_minutes": 0,
+        "grouping_strategy": "ALLGREEN",
+        "check_response_timeout_minutes": 60
+      }
+    }
+  ],
+  "bypass_actors": []
+}

oscura-0.6.0/.github/config/main-branch-ruleset.json

@@ -0,0 +1,53 @@
+{
+  "id": 12055878,
+  "name": "main branch protection with merge queue",
+  "target": "branch",
+  "source_type": "Repository",
+  "source": "oscura-re/oscura",
+  "enforcement": "active",
+  "conditions": {
+    "ref_name": {
+      "exclude": [],
+      "include": ["refs/heads/main"]
+    }
+  },
+  "rules": [
+    {
+      "type": "pull_request",
+      "parameters": {
+        "required_approving_review_count": 0,
+        "dismiss_stale_reviews_on_push": false,
+        "required_reviewers": [],
+        "require_code_owner_review": false,
+        "require_last_push_approval": false,
+        "required_review_thread_resolution": false,
+        "allowed_merge_methods": ["squash"]
+      }
+    },
+    {
+      "type": "merge_queue",
+      "parameters": {
+        "merge_method": "SQUASH",
+        "max_entries_to_build": 5,
+        "min_entries_to_merge": 1,
+        "max_entries_to_merge": 5,
+        "min_entries_to_merge_wait_minutes": 0,
+        "grouping_strategy": "ALLGREEN",
+        "check_response_timeout_minutes": 60
+      }
+    }
+  ],
+  "node_id": "RRS_lACqUmVwb3NpdG9yec5D805OzgC39UY",
+  "created_at": "2026-01-22T18:09:28.843Z",
+  "updated_at": "2026-01-24T16:30:10.799Z",
+  "bypass_actors": [],
+  "current_user_can_bypass": "never",
+  "_links": {
+    "self": {
+      "href": "https://api.github.com/repos/oscura-re/oscura/rulesets/12055878"
+    },
+    "html": {
+      "href": "https://github.com/oscura-re/oscura/rules/12055878"
+    }
+  }
+}

oscura-0.6.0/.gitignore

@@ -0,0 +1,313 @@
+# =============================================================================
+# Python
+# =============================================================================
+__pycache__/
+*.py[cod]
+*$py.class
+*.so
+
+# Virtual environments
+.venv/
+venv/
+.env/
+
+# Distribution / packaging
+dist/
+build/
+*.egg-info/
+*.egg
+.eggs/
+
+# =============================================================================
+# Testing
+# =============================================================================
+.pytest_cache/
+.coverage
+.coverage.*
+htmlcov/
+.tox/
+.nox/
+coverage.xml
+*.cover
+test_output/
+
+# =============================================================================
+# Benchmarking
+# =============================================================================
+# pytest-benchmark autosave directory (machine-specific, CI artifact)
+.benchmarks/
+
+# =============================================================================
+# Type checking / Linting
+# =============================================================================
+.mypy_cache/
+.ruff_cache/
+.dmypy.json
+dmypy.json
+
+# =============================================================================
+# Pre-push / CI Caching
+# =============================================================================
+# Build cache for package build optimization
+.cache/
+
+# =============================================================================
+# Spellcheck
+# =============================================================================
+# cSpell cache (dictionary cache for performance)
+.cspell/.cache/
+
+# =============================================================================
+# Package managers
+# =============================================================================
+# uv cache (if using uv package manager)
+.uv-cache/
+
+# =============================================================================
+# IDE / Editors
+# =============================================================================
+.idea/
+*.swp
+*.swo
+*~
+.project
+.pydevproject
+.settings/
+
+# VS Code - keep config but ignore user-specific
+.vscode/*
+!.vscode/settings.json
+!.vscode/extensions.json
+!.vscode/launch.json
+!.vscode/markdown.css
+!.vscode/tasks.json
+!.vscode/README.md
+
+# =============================================================================
+# Operating System
+# =============================================================================
+.DS_Store
+.DS_Store?
+._*
+.Spotlight-V100
+.Trashes
+Thumbs.db
+ehthumbs.db
+Desktop.ini
+
+# =============================================================================
+# Project-specific
+# =============================================================================
+# Temporary files
+/tmp/
+*.tmp
+*.temp
+*.bak
+
+# Logs
+*.log
+logs/
+
+# Generated outputs
+output/
+demos/output/
+
+# Coverage and work tracking files
+coverage.json
+active_work.json
+
+# =============================================================================
+# Security / Sensitive Files
+# =============================================================================
+# Private keys and certificates
+*.key
+*.pem
+
+# Credentials and secrets
+*credentials*
+.env
+.env.local
+.env.*.local
+secrets.*
+# Keep .env.example as template (not ignored)
+
+# =============================================================================
+# LaTeX Generated Files
+# =============================================================================
+# latexindent backup files
+*.bak[0-9]
+*.bak[0-9][0-9]
+
+# GHDL work files
+work-obj*.cf
+
+# =============================================================================
+# Claude Code Runtime Files
+# =============================================================================
+# Runtime-generated files (not tracked)
+.claude/summaries/*
+!.claude/summaries/.gitkeep
+
+# Runtime state files
+.claude/agent-registry.json
+.claude/*.backup*.json
+.claude/workflow-progress*.json
+.claude/settings.local.json
+
+# Hook logs and caches (generated at runtime)
+.claude/hooks/*.log
+.claude/hooks/errors.archive/
+.claude/hooks/.context_state.json
+.claude/hooks/.settings_hash
+.claude/hooks/orchestration-metrics.json
+.claude/hooks/__pycache__/
+
+# Orchestration activity log (debugging)
+.claude/orchestration.log
+.claude/orchestration.log.*
+.claude/reports/
+.coordination/
+
+# =============================================================================
+# Documentation Generated Files
+# =============================================================================
+# MkDocs generated site
+site/
+
+# Hypothesis testing data
+.hypothesis/
+
+# Changelog fragments (towncrier/scriv)
+changelog.d/
+
+# =============================================================================
+# Oscura-Specific
+# =============================================================================
+
+# -----------------------------------------------------------------------------
+# Demo Data (Generated)
+# -----------------------------------------------------------------------------
+# All demo data is synthetic and generated by scripts
+# Regenerate with: python demos/generate_all_demo_data.py
+demos/*/demo_data/*
+demos/*/demo_data/*/*
+!demos/*/demo_data/.gitkeep
+!demos/*/demo_data/*/.gitkeep
+
+# Keep demo generation scripts and configs
+!demos/generate_all_demo_data.py
+!demos/*/generate_demo_data.py
+!demos/02_custom_daq/custom_daq_continuous.yml
+
+# -----------------------------------------------------------------------------
+# Test Data
+# -----------------------------------------------------------------------------
+# Test data - exclude large files with potential legal concerns
+test_data/*.zip
+oscura_test_data/
+
+# Performance test data (generated, large files)
+tests/performance/test_data/*.npz
+
+# Include synthetic test data (small, legally safe, reproducible)
+!test_data/synthetic/
+!test_data/README.md
+
+# -----------------------------------------------------------------------------
+# Generated Binary Files (root directory only)
+# -----------------------------------------------------------------------------
+# Large binary test files generated during testing
+/*.bin
+/*.wfm
+/*.tss
+/*.pcap
+/*.npz
+/*.mf4
+
+# Temporary data files in root
+/*.m
+/*.xlsx
+/*.csv
+/*.yml
+/*.yaml
+
+# Exceptions: keep tracked config files
+!pyproject.toml
+!.pre-commit-config.yaml
+!.yamllint.yaml
+!.markdownlint.yaml
+!mkdocs.yml
+!cspell.json
+!lychee.toml
+
+# -----------------------------------------------------------------------------
+# Demo Output Directories
+# -----------------------------------------------------------------------------
+# Generated by demo scripts (can be regenerated by running demos)
+**/signal_re_*/
+**/wfm_outputs*/
+**/ultimate_outputs/
+**/ultimate_re_outputs/
+**/exploratory_outputs/
+**/udp_analysis*/
+
+# Automotive demo generated files
+demos/discovered_signals.dbc
+demos/08_automotive/discovered_signals.dbc
+demos/09_automotive/discovered_signals.dbc
+
+# -----------------------------------------------------------------------------
+# Generated Reports and Artifacts
+# -----------------------------------------------------------------------------
+# Runtime artifacts
+generated_reports/
+generated_dissectors/
+
+# Validation result files
+**/validation_results.json
+**/remediation_results.json
+validation_results/
+
+# -----------------------------------------------------------------------------
+# Temporary Documentation (Claude-generated)
+# -----------------------------------------------------------------------------
+# These should never be committed - use .claude/reports/ for permanent records
+*REPORT*.md
+*SUMMARY*.md
+*ASSESSMENT*.md
+*ANALYSIS*.md
+*AUDIT*.md
+*ACTION_ITEMS*.md
+*INSTRUCTIONS*.md
+*COMPLETE*.md
+*VALIDATION*.md
+*OPTIMIZATION*.md
+*IMPLEMENTATION*.md
+*ISSUES*.md
+*CAPABILITIES*.md
+*APPROACH*.md
+*VERIFICATION*.md
+*FIXES*.md
+*IMPROVEMENTS*.md
+
+# Exceptions: legitimate historical documentation
+!docs/audits/*COMPLETE*.md
+!docs/audits/*IMPLEMENTATION*.md
+
+# =============================================================================
+# GitHub Configuration Exports
+# =============================================================================
+# Exported configuration files (repo-specific, regenerated by export script)
+.github/config/rulesets-all.json
+.github/config/repository-settings.json
+.github/config/environments.json
+.github/config/tag-protection.json
+.github/config/labels.json
+.github/config/topics.json
+
+# Keep template files (these should be tracked)
+!.github/config/*-template.json
+!.github/config/main-branch-ruleset.json
+!.github/config/README.md
+.claude/agent-outputs/
+examples/outputs/

oscura-0.6.0/.gitmessage

@@ -0,0 +1,22 @@
+# <type>: <subject>
+#
+# <body>
+#
+# <footer>
+#
+# Type: feat|fix|docs|style|refactor|perf|test|chore
+# Subject: imperative mood, no period, <72 chars
+# Body: what and why vs. how, wrap at 72 chars
+# Footer: Breaking changes, issue references
+#
+# ---------------------------------------------------------------
+# IMPORTANT: Do not include AI tool attribution in commit messages
+# Commits should describe WHAT changed and WHY, not WHO wrote it
+# ---------------------------------------------------------------
+#
+# Examples:
+#   feat: add support for CAN FD protocol decoding
+#   fix: correct byte order handling in DBC parser
+#   docs: update API reference for signal analyzers
+#   refactor: simplify waveform processing pipeline
+#   test: add edge case coverage for packet streaming