# Development Scripts

This directory contains development and maintenance scripts for ComfyUI-Doctor.

## Full Test Automation

### run_full_tests_windows.ps1

Runs the required end-to-end validation sequence in one command on Windows:

1. supply-chain dependency and workflow risk checks
2. `detect-secrets`
3. all `pre-commit` hooks
4. host-like package/startup validation
5. backend unit tests
6. frontend E2E

The script always uses the project-local `.venv` interpreter for Python tooling and tests (Windows track).

**Usage**:
```powershell
powershell -File scripts/run_full_tests_windows.ps1

# Optional: skip dependency bootstrap
powershell -File scripts/run_full_tests_windows.ps1 -SkipBootstrap

# Optional: skip E2E stage
powershell -File scripts/run_full_tests_windows.ps1 -SkipE2E
```

### run_full_tests_linux.sh

Linux/WSL equivalent of the full-test automation flow with OS-aware venv selection:

- WSL: `.venv-wsl`
- native Linux: `.venv`

**Usage**:
```bash
bash scripts/run_full_tests_linux.sh

# Optional: skip dependency bootstrap
bash scripts/run_full_tests_linux.sh --skip-bootstrap

# Optional: skip E2E stage
bash scripts/run_full_tests_linux.sh --skip-e2e
```

### pre_push_checks.sh

Repository-managed pre-push gate entrypoint. It runs the same mandatory full test flow and exits non-zero on any failure, which blocks `git push` when hook is enabled.

**Usage**:
```bash
bash scripts/pre_push_checks.sh
```

Enable the hook once:
```bash
git config core.hooksPath .githooks
```

---

## Focused Security / Contract / E2E Regression Gate

### focused_gate.py

Runs the focused security, contract, and E2E regression gate locally. This is a targeted lane, not a replacement for the full local gate above.

**Usage**:
```bash
# Full gate (Python + E2E tests)
python scripts/focused_gate.py

# Fast mode (Python tests only, < 2 minutes)
python scripts/focused_gate.py --fast

# E2E tests only
python scripts/focused_gate.py --e2e
```

**What it checks**:
- Plugin security (allowlist, trust states, DoS limits)
- Metadata contract (schema validation)
- Dependency policy (requires/provides)
- Outbound payload safety (sanitization)
- E2E regression (UI stability)

**Exit codes**:
- `0` = All passed
- `1` = Python tests failed
- `2` = E2E tests failed
- `3` = Both failed

### focused_gate.sh

Bash alternative to `focused_gate.py` for Unix environments.

**Usage**:
```bash
# Full gate
./scripts/focused_gate.sh

# Fast mode (Python only)
./scripts/focused_gate.sh --fast

# E2E only
./scripts/focused_gate.sh --e2e
```

### Deprecated Compatibility Wrappers

The old `scripts/phase2_gate.py` and `scripts/phase2_gate.sh` entrypoints remain as thin wrappers for existing local automation. New commands and documentation should use the focused-gate names above.

---

## Outbound Safety Checker

### check_outbound_safety.py

Static analysis tool to prevent bypass of outbound sanitization funnel.

**Usage**:
```bash
# Run all checks
python scripts/check_outbound_safety.py
```

**What it detects**:
- Raw context fields in outbound payloads
- Missing `sanitize_outbound_payload()` calls
- Dangerous fallback patterns (`sanitized_X or X`)
- `json.dumps()` on sensitive data

**Exit codes**:
- `0` = All checks passed
- `1` = Violations detected
- `2` = Script error

---

## Plugin Migration Tooling

### plugin_manifest.py

Generates plugin manifest JSON files with computed SHA256 hashes.

**Usage**:
```bash
# Dry-run (print to stdout, no writes)
python scripts/plugin_manifest.py pipeline/plugins/community/example.py

# Write manifest
python scripts/plugin_manifest.py pipeline/plugins/community/example.py --write

# Batch process
python scripts/plugin_manifest.py pipeline/plugins/community/*.py --write
```

### plugin_allowlist.py

Scans plugins and generates allowlist config snippet.

**Usage**:
```bash
# Scan and suggest allowlist
python scripts/plugin_allowlist.py

# Include trust report
python scripts/plugin_allowlist.py --report
```

### plugin_validator.py

Validates plugin manifests and configuration.

**Usage**:
```bash
# Validate all plugins
python scripts/plugin_validator.py

# Validate specific plugin
python scripts/plugin_validator.py community.example

# Check allowlist consistency
python scripts/plugin_validator.py --check-config
```

### plugin_hmac_sign.py (Optional)

Generates HMAC-SHA256 signatures for plugins.

**Usage**:
```bash
# Interactive mode
python scripts/plugin_hmac_sign.py pipeline/plugins/community/example.py

# Environment variable mode
DOCTOR_PLUGIN_HMAC_KEY="secret" python scripts/plugin_hmac_sign.py example.py
```

---

## Other Scripts

### security_audit.py

Generates a sanitized quarterly security-audit report template. This supports the scheduled/manual audit workflow and does not run external scanners by itself.

**Usage**:
```bash
python scripts/security_audit.py --date 2026-05-31 --quarter Q2
python scripts/security_audit.py --output security-audit-template.md --force
```

### run-playwright.mjs

Wrapper for running Playwright E2E tests with proper environment setup.

**Usage**:
```bash
npm test  # Calls this script automatically
npm run test:integration
npm run test:stress
```

### preflight-js.mjs

Pre-flight checks for JavaScript/E2E tests.

---

## CI Integration

These scripts mirror the GitHub Actions workflows:

- `focused_gate.py` ↔ `.github/workflows/focused-regression-gate.yml`
- `check_outbound_safety.py` ↔ `.github/workflows/outbound-safety.yml`
- `security_audit.py` ↔ `.github/workflows/security-audit.yml`

Run scripts locally before pushing to catch issues early.