bigpowers 2.34.1 → 2.35.0

package/validate-contracts/REFERENCE.md

@@ -0,0 +1,183 @@
+# Validate Contracts — Reference
+
+## Integration
+
+- **Pre-deploy gate:** The `deploy` skill runs `validate-contracts` before smoke-test.
+- **CI pipeline:** JSON Lines output is CI-friendly; pipe to `jq` for assertions.
+- **Pre-migration:** Run `validate-contracts --shape` before consuming migration output.
+
+
+---
+
+## Configuration
+
+| Variable | Default | Description |
+|----------|---------|-------------|
+| `CONTRACTS_DIR` | `specs/contracts/` | Directory containing contract YAML files |
+| `VALIDATE_ALL` | `false` | If true, run all contracts in the directory |
+| `STRICT_MODE` | `false` | Treat warnings as failures |
+| `OUTPUT_FORMAT` | `text` | `text` or `json` |
+
+
+---
+
+## Verification
+
+→ verify: `test -f validate-contracts/SKILL.md && grep -q 'name: validate-contracts' validate-contracts/SKILL.md && echo OK`
+→ verify: `grep -qi 'specs/contracts\|JSON Schema\|key.set\|data.shape' validate-contracts/SKILL.md && echo OK`
+→ verify: `grep -ci 'divergence\|missing key\|type mismatch\|diff\|conforms\|column' validate-contracts/SKILL.md | awk '{if($1>=3) print "OK"; else print "FAIL"}'`
+→ verify: `grep -ci 'JSON Lines\|machine.parse\|CI\|deploy.*gate\|pre.deploy' validate-contracts/SKILL.md | awk '{if($1>=2) print "OK"; else print "FAIL"}'`
+→ verify: `grep -q 'validate-contracts' SKILL-INDEX.md && echo OK`
+
+---
+
+## Reference block 1
+
+```yaml
+# specs/contracts/users.schema.yaml
+endpoint: /api/users
+method: GET
+schema:
+  type: object
+  required: [id, name, email]
+  properties:
+    id: { type: number }
+    name: { type: string }
+    email: { type: string, format: email }
+```
+
+---
+
+## Reference block 2
+
+```yaml
+# specs/contracts/migration-output.yaml
+file: data/users-export.json
+format: json
+fields:
+  - name: user_id
+    type: number
+    required: true
+  - name: full_name
+    type: string
+    required: true
+  - name: created_at
+    type: string
+    format: date-time
+    required: false
+```
+
+---
+
+## Example 1
+
+```
+specs/contracts/
+├── users.schema.yaml        # API response schema
+├── i18n-keys.yaml           # Key-set comparison
+├── migration-output.yaml    # Data shape contract
+└── README.md                # Local conventions
+```
+
+---
+
+## Example 2
+
+```yaml
+# specs/contracts/users.schema.yaml
+endpoint: /api/users
+method: GET
+schema:
+  type: object
+  required: [id, name, email]
+  properties:
+    id: { type: number }
+    name: { type: string }
+    email: { type: string, format: email }
+```
+
+---
+
+## Example 3
+
+```yaml
+# specs/contracts/i18n-keys.yaml
+sources:
+  reference: src/frontend/locales/en.json
+  target: src/backend/messages/en.json
+mode: subset      # all target keys must exist in reference
+```
+
+---
+
+## Example 4
+
+```bash
+validate-contracts --key-set specs/contracts/i18n-keys.yaml
+# → missing: 2 keys in reference not found in target: ['settings.privacy', 'help.faq']
+# → added: 1 key in target not in reference: ['deprecated.field']
+# → exit 1 (divergence)
+```
+
+---
+
+## Example 5
+
+```yaml
+# specs/contracts/migration-output.yaml
+file: data/users-export.json
+format: json
+fields:
+  - name: user_id
+    type: number
+    required: true
+  - name: full_name
+    type: string
+    required: true
+  - name: created_at
+    type: string
+    format: date-time
+    required: false
+```
+
+---
+
+## Example 6
+
+```bash
+validate-contracts --shape specs/contracts/migration-output.yaml
+# → PASS: 3/3 fields validated, 5000 rows OK
+# → WARN: field 'full_name' has 12 null values (0.24%)
+# → FAIL: field 'user_id' has 3 rows with type string (expected number)
+```
+
+---
+
+## Integration
+
+- **Pre-deploy gate:** The `deploy` skill runs `validate-contracts` before smoke-test.
+- **CI pipeline:** JSON Lines output is CI-friendly; pipe to `jq` for assertions.
+- **Pre-migration:** Run `validate-contracts --shape` before consuming migration output.
+
+
+---
+
+## Configuration
+
+| Variable | Default | Description |
+|----------|---------|-------------|
+| `CONTRACTS_DIR` | `specs/contracts/` | Directory containing contract YAML files |
+| `VALIDATE_ALL` | `false` | If true, run all contracts in the directory |
+| `STRICT_MODE` | `false` | Treat warnings as failures |
+| `OUTPUT_FORMAT` | `text` | `text` or `json` |
+
+
+---
+
+## Verification
+
+→ verify: `test -f validate-contracts/SKILL.md && grep -q 'name: validate-contracts' validate-contracts/SKILL.md && echo OK`
+→ verify: `grep -qi 'specs/contracts\|JSON Schema\|key.set\|data.shape' validate-contracts/SKILL.md && echo OK`
+→ verify: `grep -ci 'divergence\|missing key\|type mismatch\|diff\|conforms\|column' validate-contracts/SKILL.md | awk '{if($1>=3) print "OK"; else print "FAIL"}'`
+→ verify: `grep -ci 'JSON Lines\|machine.parse\|CI\|deploy.*gate\|pre.deploy' validate-contracts/SKILL.md | awk '{if($1>=2) print "OK"; else print "FAIL"}'`
+→ verify: `grep -q 'validate-contracts' SKILL-INDEX.md && echo OK`

package/validate-contracts/SKILL.md

@@ -28,30 +28,13 @@ Three modes of validation:
 
 All contract files live in `specs/contracts/` and use YAML:
 
-```
-specs/contracts/
-├── users.schema.yaml        # API response schema
-├── i18n-keys.yaml           # Key-set comparison
-├── migration-output.yaml    # Data shape contract
-└── README.md                # Local conventions
-```
+See [REFERENCE.md](REFERENCE.md) for examples.
 
 ### 1. API Response Contracts (`--schema`)
 
 Define expected API response shapes and validate live endpoints against them:
 
-```yaml
-# specs/contracts/users.schema.yaml
-endpoint: /api/users
-method: GET
-schema:
-  type: object
-  required: [id, name, email]
-  properties:
-    id: { type: number }
-    name: { type: string }
-    email: { type: string, format: email }
-```
+See [REFERENCE.md](REFERENCE.md) for examples.
 
 Usage:
 
@@ -65,52 +48,21 @@ validate-contracts --schema specs/contracts/users.schema.yaml --url https://api.
 
 Assert that two data sources share a consistent set of keys:
 
-```yaml
-# specs/contracts/i18n-keys.yaml
-sources:
-  reference: src/frontend/locales/en.json
-  target: src/backend/messages/en.json
-mode: subset      # all target keys must exist in reference
-```
+See [REFERENCE.md](REFERENCE.md) for examples.
 
 Usage:
 
-```bash
-validate-contracts --key-set specs/contracts/i18n-keys.yaml
-# → missing: 2 keys in reference not found in target: ['settings.privacy', 'help.faq']
-# → added: 1 key in target not in reference: ['deprecated.field']
-# → exit 1 (divergence)
-```
+See [REFERENCE.md](REFERENCE.md) for examples.
 
 ### 3. Data Shape Contracts (`--shape`)
 
 Validate that a data file matches expected column types and constraints:
 
-```yaml
-# specs/contracts/migration-output.yaml
-file: data/users-export.json
-format: json
-fields:
-  - name: user_id
-    type: number
-    required: true
-  - name: full_name
-    type: string
-    required: true
-  - name: created_at
-    type: string
-    format: date-time
-    required: false
-```
+See [REFERENCE.md](REFERENCE.md) for examples.
 
 Usage:
 
-```bash
-validate-contracts --shape specs/contracts/migration-output.yaml
-# → PASS: 3/3 fields validated, 5000 rows OK
-# → WARN: field 'full_name' has 12 null values (0.24%)
-# → FAIL: field 'user_id' has 3 rows with type string (expected number)
-```
+See [REFERENCE.md](REFERENCE.md) for examples.
 
 ## Process
 
@@ -157,26 +109,3 @@ FAILED: 1 contract has divergence
 bash scripts/validate-contracts.sh <contract-file>
 # → All pass → ready to deploy
 ```
-
-## Integration
-
-- **Pre-deploy gate:** The `deploy` skill runs `validate-contracts` before smoke-test.
-- **CI pipeline:** JSON Lines output is CI-friendly; pipe to `jq` for assertions.
-- **Pre-migration:** Run `validate-contracts --shape` before consuming migration output.
-
-## Configuration
-
-| Variable | Default | Description |
-|----------|---------|-------------|
-| `CONTRACTS_DIR` | `specs/contracts/` | Directory containing contract YAML files |
-| `VALIDATE_ALL` | `false` | If true, run all contracts in the directory |
-| `STRICT_MODE` | `false` | Treat warnings as failures |
-| `OUTPUT_FORMAT` | `text` | `text` or `json` |
-
-## Verification
-
-→ verify: `test -f validate-contracts/SKILL.md && grep -q 'name: validate-contracts' validate-contracts/SKILL.md && echo OK`
-→ verify: `grep -qi 'specs/contracts\|JSON Schema\|key.set\|data.shape' validate-contracts/SKILL.md && echo OK`
-→ verify: `grep -ci 'divergence\|missing key\|type mismatch\|diff\|conforms\|column' validate-contracts/SKILL.md | awk '{if($1>=3) print "OK"; else print "FAIL"}'`
-→ verify: `grep -ci 'JSON Lines\|machine.parse\|CI\|deploy.*gate\|pre.deploy' validate-contracts/SKILL.md | awk '{if($1>=2) print "OK"; else print "FAIL"}'`
-→ verify: `grep -q 'validate-contracts' SKILL-INDEX.md && echo OK`

package/wire-ci/REFERENCE.md

@@ -0,0 +1,257 @@
+# Wire Ci — Reference
+
+## Examples
+
+### Create CI for a Rust project
+
+```bash
+# Detect from Cargo.toml, generate workflows
+wire-ci
+
+# Validate generated workflows
+wire-ci --validate
+
+# Run locally with act
+wire-ci --dry-run
+```
+
+### Create CI for a Node project with semantic-release
+
+```bash
+wire-ci
+wire-ci --validate
+# Expect warning: "npm publish step found but no NPM_TOKEN in secrets"
+# Fix: add NPM_TOKEN to repo secrets
+```
+
+### Validate existing workflows (no generation)
+
+```bash
+wire-ci --validate --check-only
+```
+
+
+---
+
+## Options
+
+| Flag | Description |
+|------|-------------|
+| `--validate` | Check YAML syntax, permissions, secrets, common pitfalls |
+| `--dry-run` | Run workflows locally via `act` or dispatch via `gh` |
+| `--check-only` | Only validate, do not generate new files |
+| `--type <type>` | Force project type (skip auto-detection) |
+| `--force` | Overwrite existing workflow files |
+| `--no-release` | Skip release workflow generation even if semantic-release detected |
+
+
+---
+
+## Integration with build-epic
+
+When `wire-ci` is used as part of `build-epic`:
+
+1. **During develop-tdd**: If the task modifies `.github/workflows/`, run `wire-ci --validate` as a CI dry-run sub-step
+2. **During release-branch**: After push, run `gh run list --limit 1 --branch main --json status,conclusion` to verify CI passes
+
+---
+
+## Reference block 1
+
+```yaml
+name: CI
+on: [push, pull_request]
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions-rust/toolchain@v1
+        with:
+          toolchain: stable
+          components: clippy, rustfmt
+      - run: cargo fmt --all -- --check
+      - run: cargo clippy -- -D warnings
+      - run: cargo test
+      - run: cargo build --release
+```
+
+---
+
+## Reference block 2
+
+```yaml
+name: CI
+on: [push, pull_request]
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-node@v4
+        with:
+          node-version: 20
+          cache: npm
+      - run: npm ci
+      - run: npm test
+      - run: npm run lint 2>/dev/null || true
+      - run: npm run typecheck 2>/dev/null || true
+      - run: npm run build 2>/dev/null || true
+```
+
+---
+
+## Reference block 3
+
+```yaml
+name: CI
+on: [push, pull_request]
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+          cache: pip
+      - run: pip install -e ".[dev]" || pip install -e .
+      - run: pip install pytest ruff mypy
+      - run: ruff check .
+      - run: mypy . 2>/dev/null || true
+      - run: pytest
+```
+
+---
+
+## Reference block 4
+
+```yaml
+name: CI
+on: [push, pull_request]
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-go@v5
+        with:
+          go-version: stable
+          cache: true
+      - run: go vet ./...
+      - run: go test ./...
+      - run: go build ./...
+```
+
+---
+
+## Reference block 5
+
+```yaml
+name: CI
+on: [push, pull_request]
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - run: cmake -B build
+      - run: cmake --build build
+      - run: ctest --test-dir build
+```
+
+---
+
+## Reference block 6
+
+```yaml
+name: Release
+on:
+  push:
+    branches: [main]
+jobs:
+  release:
+    runs-on: ubuntu-latest
+    permissions:
+      contents: write
+      issues: write
+      pull-requests: write
+      id-token: write
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+      - uses: actions/setup-node@v4
+        with:
+          node-version: 20
+          cache: npm
+      - run: npm ci
+      - run: npm run build 2>/dev/null || true
+      - run: npx semantic-release
+        env:
+          GITHUB_TOKEN: \${{ secrets.GITHUB_TOKEN }}
+          NPM_TOKEN: \${{ secrets.NPM_TOKEN }}
+```
+
+---
+
+## Reference block 7
+
+```bash
+# Validate YAML syntax
+for f in .github/workflows/*.yaml; do
+  python3 -c "import yaml; yaml.safe_load(open('$f'))" || echo "FAIL: $f has YAML syntax errors"
+done
+
+# Check permissions block presence
+for f in .github/workflows/*.yaml; do
+  if grep -q "permissions:" "$f"; then
+    echo "OK: $f has permissions block"
+  else
+    echo "WARNING: $f missing permissions block — add one for security"
+  fi
+done
+
+# Check for npm publish without NPM_TOKEN
+for f in .github/workflows/*.yaml; do
+  if grep -q "npm publish\|npx semantic-release" "$f"; then
+    if ! grep -q "NPM_TOKEN" "$f"; then
+      echo "WARNING: $f has npm publish/semantic-release but no NPM_TOKEN secret"
+    fi
+  fi
+done
+
+# Check for hardcoded Node versions
+for f in .github/workflows/*.yaml; do
+  if grep -q "node-version: [0-9]" "$f" && grep -qv "node-version-file\|\.nvmrc" "$f"; then
+    echo "NOTE: $f has hardcoded Node version — consider using .nvmrc instead"
+  fi
+done
+
+# Check for common secrets reference errors
+for f in .github/workflows/*.yaml; do
+  # Secrets referencing something that doesn't exist in the workflow
+  grep -oP 'secrets\.\w+' "$f" | sort -u | while read -r secret; do
+    echo "REF: $f references $secret"
+  done
+done
+```
+
+---
+
+## Reference block 8
+
+```bash
+# Option A: Use act (recommended)
+if command -v act &>/dev/null; then
+  act push --dry-run
+  echo "OK: act dry-run completed"
+elif command -v gh &>/dev/null; then
+  # Option B: Use gh workflow run (remote test, no local docker)
+  gh workflow run ci.yaml --ref "$(git branch --show-current)"
+  echo "OK: CI workflow dispatched. Check status: gh run list"
+else
+  echo "NOTE: Install act (https://github.com/nektos/act) for full local dry-run"
+  echo "      Install gh CLI for remote dry-run"
+fi
+```