@cubis/foundry 0.3.71 → 0.3.73

package/workflows/powers/ci-cd-pipelines/references/github-actions-patterns.md

@@ -0,0 +1,160 @@
+# GitHub Actions Patterns
+
+## Reusable workflow pattern
+
+```yaml
+# .github/workflows/ci-shared.yml
+name: Shared CI
+on:
+  workflow_call:
+    inputs:
+      node-version:
+        required: false
+        type: string
+        default: "20"
+      working-directory:
+        required: false
+        type: string
+        default: "."
+    secrets:
+      NPM_TOKEN:
+        required: false
+
+jobs:
+  build-and-test:
+    runs-on: ubuntu-latest
+    defaults:
+      run:
+        working-directory: ${{ inputs.working-directory }}
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-node@v4
+        with:
+          node-version: ${{ inputs.node-version }}
+          cache: "npm"
+          cache-dependency-path: "${{ inputs.working-directory }}/package-lock.json"
+      - run: npm ci
+      - run: npm test
+```
+
+## Composite action pattern
+
+```yaml
+# .github/actions/setup-project/action.yml
+name: Setup Project
+description: Install dependencies and restore caches
+inputs:
+  node-version:
+    required: false
+    default: "20"
+runs:
+  using: composite
+  steps:
+    - uses: actions/setup-node@v4
+      with:
+        node-version: ${{ inputs.node-version }}
+        cache: "npm"
+    - run: npm ci
+      shell: bash
+```
+
+## Matrix strategy
+
+```yaml
+jobs:
+  test:
+    strategy:
+      fail-fast: false
+      matrix:
+        os: [ubuntu-latest, windows-latest]
+        node: [18, 20, 22]
+        exclude:
+          - os: windows-latest
+            node: 18
+    runs-on: ${{ matrix.os }}
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-node@v4
+        with:
+          node-version: ${{ matrix.node }}
+      - run: npm ci
+      - run: npm test
+```
+
+## Environment protection
+
+```yaml
+jobs:
+  deploy-staging:
+    environment: staging
+    runs-on: ubuntu-latest
+    steps:
+      - run: echo "Deploying to staging"
+
+  deploy-production:
+    needs: deploy-staging
+    environment:
+      name: production
+      url: https://example.com
+    runs-on: ubuntu-latest
+    steps:
+      - run: echo "Deploying to production"
+```
+
+Settings for the `production` environment:
+
+- Required reviewers: 1+
+- Wait timer: 5 minutes (optional)
+- Deployment branches: `main` only
+- Prevent self-review: enabled
+
+## Concurrency control
+
+```yaml
+concurrency:
+  group: deploy-${{ github.ref }}
+  cancel-in-progress: false # false for deploy, true for CI
+```
+
+- Use `cancel-in-progress: true` for CI checks — no reason to test outdated code.
+- Use `cancel-in-progress: false` for deployments — cancelling mid-deploy is dangerous.
+
+## Monorepo path filtering
+
+```yaml
+on:
+  push:
+    paths:
+      - "packages/api/**"
+      - "shared/**"
+      - "package-lock.json"
+```
+
+- Filter on paths to skip unnecessary CI for unrelated changes.
+- Always include shared code and lockfile paths.
+
+## Artifact passing between jobs
+
+```yaml
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - run: npm ci && npm run build
+      - uses: actions/upload-artifact@v4
+        with:
+          name: build-output
+          path: dist/
+          retention-days: 7
+
+  deploy:
+    needs: build
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/download-artifact@v4
+        with:
+          name: build-output
+          path: dist/
+      - run: echo "Deploy dist/"
+```

package/workflows/powers/ci-cd-pipelines/references/pipeline-security-checklist.md

@@ -0,0 +1,57 @@
+# Pipeline Security Checklist
+
+## Supply chain hardening
+
+- [ ] Pin all GitHub Actions to full commit SHA, not version tags
+- [ ] Audit third-party actions before adoption — read the source
+- [ ] Prefer official actions (`actions/*`) and verified publishers
+- [ ] Use Dependabot or Renovate to track action version updates
+- [ ] Enable GitHub's dependency graph and secret scanning on the repository
+
+## Permissions
+
+- [ ] Set top-level `permissions: read-all` or `permissions: {}` as default
+- [ ] Grant write permissions per-job, not per-workflow
+- [ ] Never use `permissions: write-all`
+- [ ] Scope `GITHUB_TOKEN` to minimum required permissions per job
+- [ ] Use separate service accounts for production deployments
+
+## Secrets management
+
+- [ ] Store secrets in GitHub repository/organization secrets, not in workflow files
+- [ ] Rotate secrets on a schedule (90 days recommended)
+- [ ] Use environment-scoped secrets for production credentials
+- [ ] Never echo, log, or expose secrets in workflow output
+- [ ] Use OIDC (`id-token: write`) for cloud provider auth instead of long-lived credentials
+
+## Branch protection
+
+- [ ] Require status checks before merge
+- [ ] Require pull request reviews (1+ approver)
+- [ ] Enforce signed commits on main/release branches
+- [ ] Disable force push to protected branches
+- [ ] Use merge queue to serialize deployments
+
+## Build provenance (SLSA)
+
+- [ ] Generate SLSA provenance attestations for release artifacts
+- [ ] Sign container images with cosign or Notation
+- [ ] Publish SBOMs for distributed artifacts
+- [ ] Use hermetic builds when possible — no network access during build step
+- [ ] Tag release artifacts with the exact commit SHA
+
+## Audit trail
+
+- [ ] Log all deployment events with actor, timestamp, commit, and environment
+- [ ] Retain workflow logs for compliance period (minimum 90 days)
+- [ ] Alert on failed production deployments
+- [ ] Track who approved gated deployments
+- [ ] Review workflow run permissions monthly
+
+## Self-hosted runner hardening
+
+- [ ] Use ephemeral runners — do not reuse runner state between jobs
+- [ ] Run self-hosted runners in isolated VMs or containers
+- [ ] Do not run untrusted code (fork PRs) on self-hosted runners
+- [ ] Keep runner software and OS packages updated
+- [ ] Restrict network access from runners to required endpoints only

package/workflows/powers/cli-developer/POWER.md

@@ -1,119 +1,176 @@
 ````markdown
 ---
 inclusion: manual
-name: "cli-developer"
-displayName: "CLI Developer"
-description: "Build intuitive, cross-platform CLI tools with argument parsing, interactive prompts, progress indicators, and shell completions across Node.js, Python, and Go"
-keywords:
-  [
-    "cli",
-    "command-line",
-    "terminal",
-    "argument parsing",
-    "shell completion",
-    "interactive prompt",
-    "progress bar",
-    "commander",
-    "click",
-    "typer",
-    "cobra",
-  ]
+name: cli-developer
+description: Build command-line interfaces with argument parsing, subcommands, interactive prompts, terminal UX, output formatting, and cross-platform compatibility.
+license: Apache-2.0
+metadata:
+  author: cubis-foundry
+  version: "3.0"
+compatibility: Claude Code, Codex, GitHub Copilot, Gemini CLI
 ---
 
 # CLI Developer
 
-## Overview
+## Purpose
 
-Senior CLI developer expertise for building fast, intuitive command-line tools across Node.js, Python, and Go ecosystems. Focus on <50ms startup time, comprehensive shell completions, and delightful developer UX.
+Guide the design and implementation of command-line interfaces. Covers argument parsing, subcommand architecture, interactive prompts, terminal UX patterns, and cross-platform compatibility.
 
 ## When to Use
 
-- Building CLI tools and terminal applications
-- Implementing argument parsing and subcommands
-- Creating interactive prompts and forms
-- Adding progress bars and spinners
-- Implementing shell completions (bash, zsh, fish)
-- Optimizing CLI performance and startup time
-- Designing command hierarchies and flag conventions
+- Building a new CLI tool from scratch
+- Adding subcommands or flags to an existing CLI
+- Implementing interactive prompts and wizards
+- Designing CLI output formats (tables, JSON, progress bars)
+- Making CLIs cross-platform (Windows, macOS, Linux)
+- Reviewing CLI usability and documentation
 
-## Core Workflow
+## Instructions
 
-1. Analyze UX — identify user workflows, command hierarchy, common tasks
-2. Design commands — plan subcommands, flags, arguments, configuration
-3. Implement — build with appropriate CLI framework for the language
-4. Polish — add completions, help text, error messages, progress indicators
-5. Test — cross-platform testing, performance benchmarks
+### Step 1 — Design the Command Structure
 
-## Quick Reference
+**Naming conventions**:
 
-### Framework Selection
+- Use verb-noun pattern for commands: `create project`, `list users`, `delete cache`
+- Short flags for common options: `-v` (verbose), `-q` (quiet), `-f` (force)
+- Long flags for clarity: `--output`, `--format`, `--dry-run`
+- Positional arguments for required inputs: `mycli deploy <environment>`
 
-| Language | Recommended   | Alternative     |
-| -------- | ------------- | --------------- |
-| Node.js  | Commander.js  | Yargs, oclif    |
-| Python   | Typer         | Click, argparse |
-| Go       | Cobra + Viper | urfave/cli      |
-
-### Command Structure
+**Subcommand architecture**:
 
 ```
-mycli                           # Root command
-├── init [options]              # Simple command
+mycli
+├── init              (one-time setup)
 ├── config
-│   ├── get <key>              # Nested subcommand
+│   ├── get <key>
 │   ├── set <key> <value>
 │   └── list
-├── deploy [environment]        # Command with args
-│   ├── --dry-run              # Flag
-│   ├── --force
-│   └── --config <file>        # Option with value
-└── plugins
-    ├── install <name>
-    ├── list
-    └── remove <name>
+├── project
+│   ├── create <name>
+│   ├── list
+│   └── delete <id>
+└── deploy <env>      (positional argument)
 ```
 
-### Exit Codes
-
-| Code | Meaning           |
-| ---- | ----------------- |
-| 0    | Success           |
-| 1    | General error     |
-| 2    | Invalid arguments |
-| 77   | Permission denied |
-| 127  | Not found         |
-| 130  | Ctrl+C (SIGINT)   |
-
-## Constraints
-
-### MUST DO
-
-- Keep startup time under 50ms
-- Provide clear, actionable error messages
-- Support `--help` and `--version` flags
-- Use consistent flag naming conventions
-- Handle SIGINT (Ctrl+C) gracefully
-- Validate user input early
-- Support both interactive and non-interactive modes
-- Test on Windows, macOS, and Linux
-
-### MUST NOT DO
-
-- Block on synchronous I/O unnecessarily
-- Print to stdout if output will be piped
-- Use colors when output is not a TTY
-- Break existing command signatures (breaking changes)
-- Require interactive input in CI/CD environments
-- Hardcode paths or platform-specific logic
-- Ship without shell completions
-
-## Steering Files
-
-| File                 | Load When                                                    |
-| -------------------- | ------------------------------------------------------------ |
-| `design-patterns.md` | Command hierarchy, flags, config layers, plugin architecture |
-| `node-cli.md`        | Commander, Yargs, Inquirer, Chalk, Ora                       |
-| `python-cli.md`      | Typer, Click, argparse, Rich, questionary                    |
-| `go-cli.md`          | Cobra, Viper, Bubble Tea, progress bars                      |
-| `ux-patterns.md`     | Progress indicators, colors, help text, error messages       |
+**Rules**:
+
+- Every command has `--help` (automatic with good parsers)
+- Support `--version` at the root level
+- Common flags go on the root command, specific flags on subcommands
+- Use `--dry-run` for destructive operations
+
+### Step 2 — Implement Argument Parsing
+
+**Choose the right parser**:
+| Language | Recommended |
+|----------|-------------|
+| Node.js | Commander, yargs, citty |
+| Python | Click, Typer |
+| Go | Cobra, urfave/cli |
+| Rust | Clap |
+
+**Validation**:
+
+- Validate early, fail with clear error messages
+- Show the closest valid option on typos (did-you-mean)
+- Report all validation errors at once, not one at a time
+
+### Step 3 — Design Terminal UX
+
+**Output hierarchy**:
+
+1. Primary output goes to stdout (pipeable)
+2. Status messages go to stderr (logs, progress)
+3. Errors go to stderr with non-zero exit code
+
+**Formatting**:
+
+- Default: human-readable (tables, colors, emoji)
+- `--json`: machine-parseable JSON output
+- `--quiet`: errors only, minimal output
+- Detect TTY: disable colors and interactivity when piped
+
+**Progress feedback**:
+
+- Spinner for short operations (< 10s)
+- Progress bar for operations with known total
+- Log lines for multi-step operations (✓ Step 1... ✓ Step 2...)
+
+**Colors** (use sparingly):
+
+- Green: success
+- Red: error
+- Yellow: warning
+- Blue/cyan: information
+- Dim/gray: secondary information
+- Always support `NO_COLOR` environment variable
+
+### Step 4 — Interactive Prompts
+
+**When to prompt**:
+
+- Missing required information not provided as flags
+- Confirmation before destructive operations
+- Multi-step wizards for complex setup
+
+**Prompt types**:
+| Type | When |
+|------|------|
+| Text input | Free-form strings (names, paths) |
+| Password | Secrets (mask input) |
+| Select | Single choice from a list |
+| Multi-select | Multiple choices from a list |
+| Confirm | Yes/no decision |
+
+**Rules**:
+
+- Show defaults in brackets: `Port [3000]:`
+- Allow non-interactive mode via flags (CI environments)
+- Validate input inline and let the user retry
+- Support Ctrl+C graceful cancellation
+
+### Step 5 — Error Handling & Exit Codes
+
+**Exit codes**:
+| Code | Meaning |
+|------|---------|
+| 0 | Success |
+| 1 | General error |
+| 2 | Misuse / invalid arguments |
+| 126 | Permission denied |
+| 127 | Command not found |
+| 130 | Terminated by Ctrl+C (SIGINT) |
+
+**Error messages**:
+
+```
+Error: Could not connect to database at localhost:5432
+  Cause: Connection refused
+  Fix: Ensure PostgreSQL is running: `pg_ctl start`
+```
+
+Include: what failed, why, and how to fix.
+
+## Output Format
+
+```
+## CLI Architecture
+[command structure and flag design]
+
+## Implementation
+[code with argument parsing and command handlers]
+
+## UX Considerations
+[output formatting, interactivity, error handling]
+```
+
+## Examples
+
+**User**: "Build a CLI for managing our API deployments"
+
+**Response approach**: Design subcommand structure (deploy, rollback, status, logs). Implement with Commander/Click/Cobra. Add deploy confirmation prompt, progress bar for upload, JSON output for CI. Handle rollback with `--to-version` flag.
+
+**User**: "Our CLI has bad error messages — users don't know what went wrong"
+
+**Response approach**: Audit error handling. Add context to every error (what, why, fix). Implement did-you-mean for typos. Add `--verbose` flag for debug output. Ensure proper exit codes for scripting.
 ````