bigpowers 2.7.5 → 2.9.0

package/.pi/skills/publish-package/SKILL.md

@@ -0,0 +1,262 @@
+---
+name: publish-package
+description: "\"Package registry publishing for npm, crates.io, PyPI, and Homebrew. Verifies prerequisites, runs the publish command, confirms success, and surfaces actionable error hints on failure.\""
+model: sonnet
+---
+
+
+# Publish Package
+
+> **HARD GATE** — Do not attempt to publish without verifying prerequisites. Missing auth tokens, stale builds, or duplicate versions cause CI failures that are hard to debug post-push.
+>
+> **HARD GATE** — Always run `--dry-run` first. Package registries are append-only — a bad publish cannot be fully undone on most registries.
+
+Publish packages to language-specific registries. Detects package type from manifest files, verifies publish prerequisites, runs the registry-specific publish command, and confirms the version appears on the registry.
+
+## Process
+
+### 1. Detect package type
+
+Read the project root for manifest files to determine the package type:
+
+| Manifest | Registry | Publish command |
+|----------|----------|----------------|
+| `package.json` | npm | `npm publish --access public` |
+| `Cargo.toml` | crates.io | `cargo publish` |
+| `setup.py` / `pyproject.toml` | PyPI | `twine upload dist/*` or `flit publish` |
+| `Formula/<name>.rb` | Homebrew | `brew bump-formula-pr` |
+| Multiple detected | Polyglot | Error: specify registry with `--registry <npm|crates.io|pypi|brew>` |
+
+If no manifest is found, prompt the user to specify the type or pass `--type <npm|crates.io|pypi|brew>`.
+
+### 2. Verify prerequisites
+
+Before attempting any publish, run all applicable checks:
+
+**npm (`package.json`):**
+```bash
+# Check auth token exists
+if [ -z "${NPM_TOKEN:-}" ]; then
+  if [ ! -f ~/.npmrc ] || ! grep -q "_authToken" ~/.npmrc; then
+    echo "FAIL: NPM_TOKEN not set. Set via: export NPM_TOKEN=<token> or add //registry.npmjs.org/:_authToken=<token> to .npmrc"
+    exit 1
+  fi
+fi
+
+# Check version not already published
+PACKAGE_NAME=$(node -p "require('./package.json').name")
+CURRENT_VER=$(node -p "require('./package.json').version")
+if npm view "$PACKAGE_NAME@$CURRENT_VER" version 2>/dev/null; then
+  echo "FAIL: Version $CURRENT_VER already published for $PACKAGE_NAME. Bump version first."
+  exit 1
+fi
+
+# Check build artifacts are fresh
+if [ -d dist ] || [ -d lib ]; then
+  LATEST_BUILD=$(find dist lib 2>/dev/null -name "*.js" -o -name "*.cjs" -o -name "*.mjs" | xargs ls -t 2>/dev/null | head -1)
+  PACKAGE_MODIFIED=$(stat -f %m package.json 2>/dev/null || stat -c %Y package.json 2>/dev/null)
+  if [ -n "$LATEST_BUILD" ] && [ -n "$PACKAGE_MODIFIED" ]; then
+    BUILD_TIME=$(stat -f %m "$LATEST_BUILD" 2>/dev/null || stat -c %Y "$LATEST_BUILD" 2>/dev/null)
+    if [ "$BUILD_TIME" -lt "$PACKAGE_MODIFIED" ]; then
+      echo "WARNING: Build artifacts may be stale (package.json modified after last build). Run npm run build first."
+    fi
+  fi
+fi
+
+# Check CHANGELOG is updated
+if [ -f CHANGELOG.md ]; then
+  if ! grep -q "$CURRENT_VER" CHANGELOG.md 2>/dev/null; then
+    echo "WARNING: Version $CURRENT_VER not found in CHANGELOG.md. Update changelog before publish."
+  fi
+fi
+```
+
+**crates.io (`Cargo.toml`):**
+```bash
+# Check auth token exists
+if [ -z "${CARGO_REGISTRY_TOKEN:-}" ]; then
+  if [ ! -f ~/.cargo/config.toml ] || ! grep -q "token" ~/.cargo/config.toml; then
+    echo "FAIL: CARGO_REGISTRY_TOKEN not set. Set via: export CARGO_REGISTRY_TOKEN=<token> or add to ~/.cargo/config.toml"
+    exit 1
+  fi
+fi
+
+# Check version not already published
+CRATE_NAME=$(grep '^name' Cargo.toml | head -1 | sed 's/.*"\(.*\)"/\1/')
+CURRENT_VER=$(grep '^version' Cargo.toml | head -1 | sed 's/.*"\(.*\)"/\1/')
+if cargo search "$CRATE_NAME" 2>/dev/null | grep -q "^${CRATE_NAME}.*\"$CURRENT_VER\""; then
+  echo "FAIL: Version $CURRENT_VER already published for $CRATE_NAME. Bump version in Cargo.toml first."
+  exit 1
+fi
+```
+
+**PyPI (`setup.py` / `pyproject.toml`):**
+```bash
+# Check auth token exists
+if [ -z "${TWINE_PASSWORD:-}" ] && [ -z "${POETRY_PYPI_TOKEN_PYPI:-}" ]; then
+  if [ ! -f ~/.pypirc ]; then
+    echo "FAIL: PyPI token not configured. Set TWINE_PASSWORD or create ~/.pypirc"
+    exit 1
+  fi
+fi
+
+# Check for build artifacts
+if [ ! -d dist ] || [ -z "$(ls dist/*.whl 2>/dev/null)" ]; then
+  echo "WARNING: No .whl files found in dist/. Run: python -m build"
+fi
+```
+
+### 3. Run publish
+
+After all prerequisite checks pass, run the registry-specific command:
+
+```bash
+# npm
+npm publish --access public
+
+# crates.io
+cargo publish
+
+# PyPI
+python -m twine upload dist/*  # or: poetry publish
+
+# Homebrew (opens PR, does not publish directly)
+brew bump-formula-pr --url=<tarball-url> <formula-name>
+```
+
+### 4. Verify publish success
+
+After publish, confirm the version appears on the registry:
+
+```bash
+# npm
+npm view "$PACKAGE_NAME" versions --json 2>/dev/null | grep -q "\"$CURRENT_VER\"" && echo "OK: npm publish confirmed"
+
+# crates.io
+cargo search "$CRATE_NAME" 2>/dev/null | grep -q "^${CRATE_NAME}.*\"$CURRENT_VER\"" && echo "OK: crates.io publish confirmed"
+
+# PyPI
+pip index versions "$PACKAGE_NAME" 2>/dev/null | grep -q "$CURRENT_VER" && echo "OK: PyPI publish confirmed"
+```
+
+### 5. Error handling
+
+On failure, surface actionable hints:
+
+```bash
+# Generic failure handler
+if [ $? -ne 0 ]; then
+  case "$REGISTRY" in
+    npm)
+      echo "FAIL: npm publish failed."
+      echo "  Common causes:"
+      echo "  - NPM_TOKEN not set in secrets: add to GitHub repo secrets"
+      echo "  - Version already published: bump version in package.json"
+      echo "  - Two-factor auth required: use --otp=<code> flag"
+      echo "  - Package scoped but not public: add --access public"
+      ;;
+    crates.io)
+      echo "FAIL: cargo publish failed."
+      echo "  Common causes:"
+      echo "  - CARGO_REGISTRY_TOKEN not configured: see ~/.cargo/config.toml"
+      echo "  - Version already published: bump version in Cargo.toml"
+      echo "  - Local changes not committed: cargo publish requires clean working tree"
+      ;;
+    pypi)
+      echo "FAIL: PyPI publish failed."
+      echo "  Common causes:"
+      echo "  - TWINE_PASSWORD not configured: set env var or ~/.pypirc"
+      echo "  - Build artifacts missing: run python -m build first"
+      echo "  - Version conflict: version already exists on PyPI"
+      ;;
+  esac
+  exit 1
+fi
+```
+
+### 6. Dry-run mode (`--dry-run`)
+
+Run `--dry-run` to verify all prerequisites without actually publishing:
+
+```bash
+# Example output
+$ publish-package --dry-run
+
+[DRY-RUN] Detected package type: npm
+[DRY-RUN] Package: my-package v0.4.0
+[DRY-RUN] Checking NPM_TOKEN... OK
+[DRY-RUN] Checking version 0.4.0 not already published... OK
+[DRY-RUN] Checking build artifacts... WARNING: package.json modified after build
+[DRY-RUN] Checking CHANGELOG... OK
+[DRY-RUN] Would run: npm publish --access public
+[DRY-RUN] Exiting without publishing.
+```
+
+### 7. Dry-run mode per registry
+
+```bash
+# npm dry-run
+npm publish --access public --dry-run
+
+# crates.io dry-run (cargo does not have a publish dry-run; use --dry-run flag for validation only)
+cargo package --list 2>/dev/null
+
+# PyPI dry-run
+python -m twine upload --repository testpypi dist/*  # test.pypi.org
+```
+
+## Options
+
+| Flag | Description |
+|------|-------------|
+| `--dry-run` | Verify prerequisites and show publish command without executing |
+| `--registry <type>` | Force registry type (skip auto-detection) |
+| `--otp <code>` | One-time password for npm 2FA |
+| `--no-verify` | Skip prerequisite checks (use with caution) |
+
+## Examples
+
+### Publish an npm package
+
+```bash
+# Verify first
+publish-package --dry-run
+
+# Publish
+publish-package
+
+# Output:
+#   [npm] Publishing my-package v0.4.0...
+#   OK: npm publish confirmed (my-package@0.4.0 on registry)
+```
+
+### Publish a Rust crate
+
+```bash
+export CARGO_REGISTRY_TOKEN=<token>
+publish-package --dry-run
+publish-package
+```
+
+### Missing token scenario
+
+```bash
+$ publish-package
+FAIL: NPM_TOKEN not set. Set via: export NPM_TOKEN=<token> or add to .npmrc
+```
+
+## Integration with release-branch
+
+When wired into `release-branch`, add a step after git push:
+
+```
+6a. Run publish-package to publish to package registries
+    → verify: publish-package --dry-run && publish-package
+```
+
+## Verify
+
+→ verify: `test -f publish-package/SKILL.md && echo "OK: skill file exists" || echo "FAIL: no skill file"`
+→ verify: `grep -q "name: publish-package" publish-package/SKILL.md && echo "OK: frontmatter" || echo "FAIL: frontmatter"`
+→ verify: `grep -ci "npm\|crates.io\|pypi\|publish\|registry" publish-package/SKILL.md | awk '{if($1>=4) print "OK: semantics"; else print "FAIL: missing"}'`
+→ verify: `grep -q "publish-package" SKILL-INDEX.md && echo "OK: in SKILL-INDEX" || echo "FAIL: not indexed"`

package/.pi/skills/wire-ci/SKILL.md

@@ -0,0 +1,309 @@
+---
+name: wire-ci
+description: "\"CI pipeline setup with pre-built templates and local validation. Generates GitHub Actions workflows, validates YAML syntax and permissions, supports dry-run via act/gh. The CI equivalent of wire-observability.\""
+model: sonnet
+---
+
+
+# Wire CI
+
+> **HARD GATE** — Do not ship a project without CI. Run this skill before first merge to main or when adding CI to an existing project.
+>
+> **HARD GATE** — CI that is untestable locally will break every cycle. Always run `--validate` after generating workflows and `--dry-run` before pushing.
+
+Generate, validate, and test CI workflows. Detects your project type, produces platform-appropriate GitHub Actions configurations, and provides local verification to catch auth, permissions, and syntax issues before they reach CI.
+
+## What this sets up
+
+1. **CI workflow** — `.github/workflows/ci.yaml` with test, lint, typecheck, build steps
+2. **Release workflow** — `.github/workflows/release.yaml` with semantic-release (if applicable)
+3. **`--validate` mode** — checks YAML syntax, workflow permissions, required secrets, and common pitfalls
+4. **`--dry-run` mode** — runs workflows locally via `act` or `gh workflow run` to prove correctness before push
+5. **Failure pattern documentation** — common CI failure categories and their fixes
+
+## Process
+
+### 1. Detect project type
+
+Read the project root for manifest files to determine which template to use:
+
+| Manifest | Type | Template |
+|----------|------|----------|
+| `Cargo.toml` | Rust | Rust CI: test, clippy, fmt, build |
+| `package.json` | Node | Node CI: test, lint, typecheck, build |
+| `setup.py` / `pyproject.toml` | Python | Python CI: pytest, ruff/mypy/flake8, build |
+| `go.mod` | Go | Go CI: test, vet, staticcheck, build |
+| `CMakeLists.txt` | C/C++ | C/C++ CI: cmake build, ctest |
+| Multiple detected | Polyglot | Combined workflows or error if ambiguous |
+
+If no manifest is found, prompt the user to specify the type or pass `--type <rust|node|python|go|cpp>`.
+
+### 2. Generate CI workflow
+
+Create `.github/workflows/ci.yaml` with standard steps derived from the project type and its manifest:
+
+**Rust template (`Cargo.toml`):**
+```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
+```
+
+**Node template (`package.json`):**
+```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
+```
+
+**Python template (`setup.py` / `pyproject.toml`):**
+```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
+```
+
+**Go template (`go.mod`):**
+```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 ./...
+```
+
+**C/C++ template (`CMakeLists.txt`):**
+```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
+```
+
+### 3. Generate release workflow (if semantic-release detected)
+
+If the project has semantic-release configured (in `package.json`, `.releaserc`, or `release.config.js`), also generate `.github/workflows/release.yaml`:
+
+```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 }}
+```
+
+> **NPM_TOKEN is required** for publishing to npm. Without it, semantic-release will fail at the publish step. See `--validate` to check this.
+
+### 4. Validate workflows (`--validate`)
+
+Run `wire-ci --validate` to check all generated workflow files:
+
+```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
+```
+
+**Exit codes:**
+- `0` — all checks pass (no errors)
+- `1` — YAML syntax errors found
+- `2` — validation warnings only (missing permissions, secrets, etc.)
+
+### 5. Dry-run workflows (`--dry-run`)
+
+Attempt to run the generated workflows locally to catch errors before push:
+
+```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
+```
+
+> **act** runs workflows in a local Docker environment — the most accurate pre-push validation.
+> **gh workflow run** sends the workflow to GitHub but doesn't execute locally — useful for checking YAML parsing but not for testing the actual steps.
+
+### 6. Document common CI failure patterns
+
+Add the following to the project's documentation or CLAUDE.md after setup:
+
+| Failure | Cause | Fix |
+|---------|-------|-----|
+| `npm publish` fails | `NPM_TOKEN` not set as repo secret | Add `NPM_TOKEN` to GitHub repo secrets |
+| `semantic-release` fails on push | Missing `permissions: contents: write` | Add `permissions: contents: write` to release job |
+| `cargo publish` auth fail | `CARGO_REGISTRY_TOKEN` not set | Add token to `~/.cargo/config.toml` or env |
+| `go vet` fails | Go version mismatch | Match `go.mod` `go` directive with setup-go version |
+| `cargo clippy` errors | New lints in Rust nightly | `cargo clippy --fix` or allow specific lints |
+| `act` not found | Docker not running or act not installed | `brew install act` / `docker ps` to verify Docker |
+| Hardcoded Node version stale | `.nvmrc` exists but workflow uses hardcoded version | Use `node-version-file: .nvmrc` instead |
+
+## 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
+
+## Verify
+
+→ verify: `test -f wire-ci/SKILL.md && echo "OK: skill file exists" || echo "FAIL: no skill file"`
+→ verify: `grep -q "name: wire-ci" wire-ci/SKILL.md && echo "OK: frontmatter" || echo "FAIL: frontmatter"`
+→ verify: `grep -ci "template\|workflow\|validate\|dry.run" wire-ci/SKILL.md | awk '{if($1>=3) print "OK: semantics"; else print "FAIL: missing"}'`
+→ verify: `grep -q "wire-ci" SKILL-INDEX.md && echo "OK: in SKILL-INDEX" || echo "FAIL: not indexed"`

package/CHANGELOG.md

@@ -1,3 +1,17 @@
+# [2.9.0](https://github.com/danielvm-git/bigpowers/compare/v2.8.0...v2.9.0) (2026-06-20)
+
+
+### Features
+
+* **skills:** add publish-package skill for multi-registry publishing ([945a481](https://github.com/danielvm-git/bigpowers/commit/945a481cef07335c59277c82137e4a6bec78655a))
+
+# [2.8.0](https://github.com/danielvm-git/bigpowers/compare/v2.7.5...v2.8.0) (2026-06-20)
+
+
+### Features
+
+* **skills:** add wire-ci CI pipeline skill ([7196579](https://github.com/danielvm-git/bigpowers/commit/71965799376ec894f48a957626455142beb5080b))
+
 ## [2.7.5](https://github.com/danielvm-git/bigpowers/compare/v2.7.4...v2.7.5) (2026-06-20)