@geraldmaron/construct 1.0.0

package/skills/development/shell.md

@@ -0,0 +1,127 @@
+<!--
+skills/development/shell.md — Shell Scripting Best Practices — Use this skill when writing, reviewing, or debugging Bash, Zsh, or POSIX shell s
+
+Use this skill when writing, reviewing, or debugging Bash, Zsh, or POSIX shell scripts. ## Script Header
+-->
+# Shell Scripting Best Practices
+
+Use this skill when writing, reviewing, or debugging Bash, Zsh, or POSIX shell scripts.
+
+## Script Header
+
+```bash
+#!/usr/bin/env bash
+set -euo pipefail
+```
+
+- `set -e`: exit on error
+- `set -u`: treat unset variables as errors
+- `set -o pipefail`: propagate pipe failures
+- Use `#!/usr/bin/env bash` for portability; `#!/bin/sh` for POSIX-only scripts
+
+## Variables
+
+- Always quote variables: `"$var"` prevents word splitting and globbing
+- Use `${var:-default}` for default values
+- Use `${var:?error message}` to fail on unset required variables
+- Local variables in functions: `local var="value"`
+- Uppercase for exported/environment variables; lowercase for script-local
+
+## Functions
+
+```bash
+function_name() {
+  local input="$1"
+  # function body
+}
+```
+
+- Use functions for any logic reused or exceeding 10 lines
+- Declare local variables with `local`
+- Return exit codes (0 = success, non-zero = failure)
+- Use `return` for status; use stdout for data output
+
+## Conditionals and Testing
+
+- `[[ ]]` for conditionals in Bash (safer than `[ ]`)
+- `(( ))` for arithmetic comparisons
+- String comparison: `[[ "$a" == "$b" ]]`
+- File tests: `[[ -f "$file" ]]`, `[[ -d "$dir" ]]`, `[[ -r "$file" ]]`
+- Regex: `[[ "$str" =~ ^pattern$ ]]`
+- Always quote variables inside conditionals
+
+## Input Handling
+
+- Validate all arguments before processing
+- Use `getopts` or manual parsing for flags
+- Provide usage/help output with `--help`
+- Check required tools exist: `command -v tool >/dev/null || { echo "tool required"; exit 1; }`
+- Sanitize any input used in commands to prevent injection
+
+## Error Handling
+
+- Use `trap` for cleanup: `trap cleanup EXIT`
+- Check command return codes explicitly for critical operations
+- Log errors to stderr: `echo "Error: message" >&2`
+- Exit with meaningful codes: 1 = general error, 2 = usage error
+- Use `|| true` only when a failure is genuinely acceptable
+
+## Temporary Files
+
+```bash
+tmpdir=$(mktemp -d)
+trap 'rm -rf "$tmpdir"' EXIT
+```
+
+- Always use `mktemp` for temporary files and directories
+- Clean up with EXIT trap
+- Never hardcode temporary paths
+
+## Process and Subshell
+
+- `$()` for command substitution (not backticks)
+- Avoid unnecessary subshells; they add overhead
+- Use `read` with `IFS` for parsing: `IFS=: read -r user pass <<< "$line"`
+- Process substitution `<()` for feeding command output as a file
+- `xargs` or `while read` for processing lists; avoid `for f in $(ls)`
+
+## Portability
+
+- Test on the target shell (Bash 3.x on macOS, 5.x on Linux)
+- Avoid Bash-specific features in `#!/bin/sh` scripts
+- Use `printf` over `echo` for consistent behavior across platforms
+- Check for GNU vs BSD tool differences (sed, date, grep flags)
+
+## Security
+
+- Never use `eval` with user input
+- Quote all variable expansions
+- Use `--` to terminate option parsing before user input: `grep -- "$pattern" file`
+- Validate file paths; prevent directory traversal
+- Avoid storing secrets in variables visible in `/proc` or `ps` output
+- Use `mktemp` with restrictive permissions
+
+## Testing
+
+- Use `bats` (Bash Automated Testing System) for shell script tests
+- Test exit codes, stdout, and stderr output
+- Test with various inputs: empty, spaces, special characters, long strings
+- Run with `shellcheck` for static analysis; fix all warnings
+- Test on CI with the target shell version
+
+## Performance
+
+- Avoid unnecessary external commands; use Bash builtins when possible
+- `[[ ]]` is faster than `[ ]` (no separate process)
+- Parameter expansion (`${var##*/}`) over `basename "$var"`
+- Bulk operations over loops: `find ... -exec cmd {} +` over `for f in; do cmd "$f"; done`
+- If performance matters significantly, consider Python or Go instead
+
+## Anti-Patterns
+
+- Parsing `ls` output (use glob patterns or `find`)
+- Unquoted variable expansions
+- `cat file | grep` instead of `grep pattern file`
+- `cd` without checking success: use `cd dir || exit 1`
+- Scripts longer than 200 lines without functions
+- Storing structured data in variables (use files or jq for JSON)

package/skills/development/swift.md

@@ -0,0 +1,129 @@
+<!--
+skills/development/swift.md — Swift / iOS Development — Swift 6 enforces data-race safety at compile time. Annotate isolation boundary e
+
+## Concurrency (Swift 6 Strict Concurrency) Swift 6 enforces data-race safety at compile time. Annotate isolation boundary explicitly:
+-->
+# Swift / iOS Development
+
+## Concurrency (Swift 6 Strict Concurrency)
+
+Swift 6 enforces data-race safety at compile time. Annotate isolation boundary explicitly:
+
+```swift
+@MainActor
+final class ViewModel: ObservableObject {
+  @Published var items: [Item] = []
+
+  func load() async {
+    items = await repository.fetchAll()
+  }
+}
+```
+
+Key rules:
+- `@MainActor` for all UI-touching types
+- `actor` for shared mutable state accessed off the main thread
+- `Sendable` conformance on types crossing isolation boundaries
+- Prefer `async/await` over completion handlers; avoid mixing the two
+
+Common pitfall: `Task { }` inherits the actor context of its caller — do not assume it runs on a background thread.
+
+## SwiftUI Patterns
+
+### State ownership hierarchy
+
+| Wrapper | Use when |
+|---|---|
+| `@State` | Local, view-owned, value type |
+| `@StateObject` | View-owned reference type (creates once) |
+| `@ObservedObject` | Reference type owned by a parent |
+| `@EnvironmentObject` | Shared across subtree without explicit passing |
+| `@Binding` | Two-way write access into parent state |
+
+### Prefer value semantics in models
+
+```swift
+struct Item: Identifiable, Hashable {
+  let id: UUID
+  var title: String
+}
+```
+
+Avoid `class` for model types unless reference semantics are required.
+
+### Navigation
+
+Use `NavigationStack` + `navigationDestination(for:)` for type-safe push navigation. Avoid `NavigationView` (deprecated in iOS 16+).
+
+```swift
+NavigationStack(path: $router.path) {
+  ContentView()
+    .navigationDestination(for: Route.self) { route in
+      route.view
+    }
+}
+```
+
+## Testing
+
+### Unit tests
+
+Use `XCTest` for synchronous logic and `async` test methods for concurrency:
+
+```swift
+func testFetchReturnsItems() async throws {
+  let sut = ItemRepository(api: MockAPI())
+  let result = try await sut.fetchAll()
+  XCTAssertFalse(result.isEmpty)
+}
+```
+
+### UI tests
+
+Prefer `XCUITest` for critical flows only — it is slow and flaky. Supplement with snapshot tests (`swift-snapshot-testing`) for visual regression.
+
+### Test doubles
+
+Declare protocols for dependencies; inject fakes in tests:
+
+```swift
+protocol APIClient { func fetch() async throws -> [Item] }
+struct MockAPIClient: APIClient { var stubbedItems: [Item] = [] }
+```
+
+## Memory Management
+
+- Capture lists in closures: `[weak self]` to break retain cycles
+- Actors do not need `[weak self]` captures for their own methods
+- Use Instruments → Leaks / Allocations to profile before optimizing
+
+## Build & Tooling
+
+- **Swift Package Manager** for libraries; avoid CocoaPods on new projects
+- **Xcode Cloud** or **Fastlane** for CI
+- Enable `-strict-concurrency=complete` in Swift 5.x projects to prepare for Swift 6
+- `swiftlint` for style; `swiftformat` for formatting
+- Minimum deployment targets: follow current App Store requirements (iOS 16+ as of 2025)
+
+## Architecture Patterns
+
+### MVVM + Repository
+
+```
+View → ViewModel (@MainActor) → Repository (actor) → Network/DB
+```
+
+- ViewModels hold `@Published` properties; Views observe them
+- Repositories own async data access; isolated with `actor`
+- Business logic lives in domain models, not ViewModels
+
+### The Composable Architecture (TCA)
+
+Use TCA when state fan-out is complex or testability of reducers is a priority. Adds boilerplate — evaluate against team familiarity.
+
+## Common Pitfalls
+
+- Do not call `@MainActor` methods from synchronous non-main contexts — use `Task { @MainActor in ... }`
+- Avoid `DispatchQueue.main.async` in new code; use `await MainActor.run { }` instead
+- `@StateObject` vs `@ObservedObject` confusion causes double-initialization bugs — `@StateObject` only at the owner
+- `List` with large datasets: use `lazy` loading or pagination; do not load everything into `@State`

package/skills/development/typescript.md

@@ -0,0 +1,129 @@
+<!--
+skills/development/typescript.md — TypeScript Best Practices — Use this skill when writing, reviewing, or debugging TypeScript or JavaScript co
+
+Use this skill when writing, reviewing, or debugging TypeScript or JavaScript code. ## Project Structure
+-->
+# TypeScript Best Practices
+
+Use this skill when writing, reviewing, or debugging TypeScript or JavaScript code.
+
+## Project Structure
+
+```
+src/
+  modules/
+    users/
+      user.service.ts
+      user.repository.ts
+      user.types.ts
+      user.test.ts
+  lib/
+    validation.ts
+    http.ts
+  types/
+    index.ts
+tsconfig.json
+package.json
+```
+
+- Organize by feature or domain, not by file type
+- Colocate tests with source files or in a parallel `__tests__` directory
+- Barrel exports (`index.ts`) only at module boundaries
+
+## Tooling
+
+| Tool | Purpose |
+|---|---|
+| TypeScript compiler (tsc) | Type checking |
+| ESLint | Linting |
+| Prettier | Formatting |
+| Vitest / Jest | Testing |
+| tsx / ts-node | Development execution |
+| Biome | All-in-one alternative to ESLint + Prettier |
+
+## Type System
+
+- Strict mode enabled: `"strict": true` in tsconfig
+- No `any`; use `unknown` when the type is truly unknown, then narrow
+- Prefer interfaces for object shapes; type aliases for unions and intersections
+- Use discriminated unions for state machines and variant types
+- `as const` for literal type inference on arrays and objects
+- Generics with constraints: `<T extends Record<string, unknown>>`
+- Zod or Valibot for runtime validation that infers static types
+
+## Error Handling
+
+- Use typed error classes extending `Error`
+- `Result<T, E>` pattern (custom or `neverthrow`) for expected failures
+- Try/catch only at boundaries (HTTP handler, message consumer)
+- Always catch async rejections; unhandled rejections crash Node
+- Include context in error messages: what operation, what input
+
+## Immutability
+
+- `const` by default; `let` only when reassignment is necessary
+- `Readonly<T>` and `ReadonlyArray<T>` for function parameters
+- Spread operator for object and array updates
+- `Object.freeze` for runtime enforcement when needed
+- `as const` for deeply immutable literal types
+
+## Patterns
+
+### Module Pattern
+- Named exports over default exports (better refactoring, better tree-shaking)
+- Explicit public API via barrel files
+- Internal modules not re-exported
+
+### Dependency Injection
+- Constructor injection for services
+- Factory functions for configurable instances
+- Interface-based dependencies for testability
+
+### Async Patterns
+- `async/await` over raw promises
+- `Promise.all` for independent concurrent operations
+- `Promise.allSettled` when partial failure is acceptable
+- Set timeouts with `AbortController` on fetch and long operations
+- Never fire-and-forget a promise; handle the result or error
+
+## Testing
+
+- Vitest or Jest with TypeScript support
+- Mock modules with `vi.mock()` or `jest.mock()`
+- Test behavior, not implementation
+- `@testing-library` for component tests
+- Snapshot tests sparingly; prefer explicit assertions
+- MSW (Mock Service Worker) for HTTP mocking in integration tests
+
+## Performance
+
+- Lazy imports with `import()` for code splitting
+- Avoid unnecessary object creation in hot paths
+- Use `Map` and `Set` over objects for frequent lookups/additions
+- Profile with Node inspector or Chrome DevTools
+- Monitor event loop lag and memory usage in production
+
+## Node.js Specifics
+
+- Use `node:` prefix for built-in modules
+- Streams for large data processing
+- Cluster or worker threads for CPU-bound tasks
+- Graceful shutdown: handle SIGTERM, close connections, drain requests
+- Health check endpoint for load balancers
+
+## Security
+
+- Validate all external input at API boundaries (Zod, Joi, class-validator)
+- Parameterized queries for database access (never string concatenation)
+- `helmet` middleware for HTTP security headers
+- Sanitize user content before HTML rendering
+- Use `crypto.randomUUID()` for identifiers
+- Audit dependencies: `npm audit`, `pnpm audit`
+
+## Anti-Patterns
+
+- `any` as an escape hatch instead of proper typing
+- Barrel files that re-export everything (kills tree-shaking)
+- Enums for simple unions (prefer string literal unions)
+- Class inheritance chains deeper than two levels
+- Mixing async and sync error handling styles

package/skills/devops/ci-cd.md

@@ -0,0 +1,108 @@
+<!--
+skills/devops/ci-cd.md — CI/CD — Use this skill when designing, debugging, or optimizing CI/CD pipelines.
+
+Use this skill when designing, debugging, or optimizing CI/CD pipelines. ## Pipeline Stages
+-->
+# CI/CD
+
+Use this skill when designing, debugging, or optimizing CI/CD pipelines.
+
+## Pipeline Stages
+
+| Stage | Purpose | Tools | Failure Policy |
+|---|---|---|---|
+| Build | Compile, lint, typecheck | tsc, eslint, cargo check, go vet | Fail fast — block all downstream stages |
+| Test | Unit → integration → e2e | Jest, Pytest, go test, Playwright | Fail on any; parallelize within stage |
+| Security Scan | SAST, dep audit, secrets detection | Semgrep, CodeQL, Trivy, gitleaks | Block on CRITICAL/HIGH; warn on MEDIUM |
+| Deploy | Promote artifact through environments | GitHub Actions, ArgoCD, Helm | Gate on all prior stages passing |
+
+Always run lint and typecheck before tests — they are faster and catch more errors per second of CI time.
+
+## GitHub Actions
+
+**Dependency caching:**
+```yaml
+- uses: actions/cache@v4
+  with:
+    path: ~/.npm
+    key: ${{ runner.os }}-node-${{ hashFiles('**/package-lock.json') }}
+    restore-keys: ${{ runner.os }}-node-
+```
+
+Use `hashFiles` of the lock file as the cache key. A lock file change invalidates the cache and forces a clean install. Restore keys provide a partial cache hit when the key misses.
+
+**Matrix parallelization:**
+```yaml
+strategy:
+  matrix:
+    node: [18, 20, 22]
+    os: [ubuntu-latest, macos-latest]
+```
+
+**Sequential job dependencies:**
+```yaml
+jobs:
+  build:
+    runs-on: ubuntu-latest
+  test:
+    needs: build
+  deploy:
+    needs: [build, test]
+```
+
+**Artifact passing between jobs:**
+```yaml
+- uses: actions/upload-artifact@v4
+  with:
+    name: build-output
+    path: dist/
+    retention-days: 1
+
+- uses: actions/download-artifact@v4
+  with:
+    name: build-output
+```
+
+## GitLab CI
+
+- `cache: key: $CI_COMMIT_REF_SLUG` with `paths:` for dependency directories.
+- `parallel: matrix:` for version or platform fans.
+- `artifacts: expire_in: 1 day` for build output passed between jobs.
+- `environment: name: staging` for environment tracking and deployment history.
+
+## Artifact Management
+
+| Artifact Type | Where Stored | Retention | Promotion Gate |
+|---|---|---|---|
+| Build output (JS/CSS) | CI artifact store | 1 day | Tests pass |
+| Container image | Registry (ECR, GCR, GHCR) | 90 days (untagged), permanent (tagged) | Security scan pass |
+| Test reports | CI artifact store | 30 days | N/A |
+| Release binaries | GitHub Releases / S3 | Permanent | Full pipeline pass |
+
+## Environment Promotion
+
+| Branch | Environment | Gates Required |
+|---|---|---|
+| feature/* | None (CI only) | Build + test |
+| main | Staging | Build + test + security scan |
+| main (manual approval) | Production | All staging gates + smoke test + approval |
+| hotfix/* | Production (fast-path) | Build + test + approval |
+
+Never auto-deploy to production without a passing security scan and at least one manual approval step.
+
+## Secrets in CI
+
+- Store secrets in the platform's encrypted secret store (GitHub Actions Secrets, GitLab CI Variables).
+- Never hardcode secrets in workflow files or Dockerfiles.
+- Mask secrets in logs — CI platforms do this automatically for registered secrets; verify it works before relying on it.
+- Rotate any secret immediately after a potential exposure; treat "may have leaked" the same as "did leak".
+- Use OIDC-based short-lived tokens (GitHub OIDC → AWS/GCP/Azure) over long-lived service account keys wherever the cloud provider supports it.
+
+## Speed Optimization
+
+- Cache dependency layers keyed to lock file hash; a clean install on every run is a CI antipattern.
+- Run lint and typecheck first — they fail fast and cost less than a full test suite.
+- Split slow test suites across workers using matrix or `--shard` flags (Vitest, Jest, Playwright all support sharding).
+- Parallelize independent test files; do not serialize unit tests.
+- In monorepos, run only affected packages: `turbo run test --filter=[HEAD^1]` or `nx affected --target=test`.
+- Set `fail-fast: true` in matrix builds when a single failure is sufficient signal to abort.

package/skills/devops/containerization.md

@@ -0,0 +1,106 @@
+<!--
+skills/devops/containerization.md — Containerization — Use this skill when writing Dockerfiles, optimizing image size, or securing cont
+
+Use this skill when writing Dockerfiles, optimizing image size, or securing container builds. ## Multi-Stage Builds
+-->
+# Containerization
+
+Use this skill when writing Dockerfiles, optimizing image size, or securing container builds.
+
+## Multi-Stage Builds
+
+Use a builder stage to compile and a minimal runtime stage to ship only what is needed:
+
+```dockerfile
+FROM node:20 AS builder
+WORKDIR /app
+COPY package*.json ./
+RUN npm ci
+COPY . .
+RUN npm run build
+
+FROM node:20-alpine AS runtime
+WORKDIR /app
+COPY --from=builder /app/dist ./dist
+COPY --from=builder /app/node_modules ./node_modules
+```
+
+Runtime base image selection:
+- `gcr.io/distroless/nodejs20-debian12` — no shell, no package manager, smallest attack surface for Node.
+- `node:20-alpine` — shell available for debugging; use when distroless breaks scripts.
+- `scratch` — static binaries only (Go, Rust with `musl`).
+- Never use `debian`, `ubuntu`, or `node:20` (Debian-based) as a production runtime base; they carry thousands of unnecessary packages.
+
+## Layer Caching
+
+Order layers by change frequency — least-changed first:
+
+1. Base OS packages (`RUN apk add ...`)
+2. App dependencies (`COPY package*.json ./` then `RUN npm ci`)
+3. Source code (`COPY . .`)
+4. Build output (`RUN npm run build`)
+
+Always `COPY package*.json ./` before `COPY . .`. A source change must not invalidate the dependency layer.
+
+Use BuildKit mount caches to avoid re-downloading packages across builds:
+```dockerfile
+RUN --mount=type=cache,target=/root/.npm npm ci
+RUN --mount=type=cache,target=/root/.cache/pip pip install -r requirements.txt
+```
+
+Combine related `RUN` commands and clean package manager caches in the same layer:
+```dockerfile
+RUN apk add --no-cache curl git && \
+    rm -rf /var/cache/apk/*
+```
+
+Never put cache cleanup in a separate `RUN` — it creates a new layer that does not reclaim space from the previous layer.
+
+## Security
+
+| Practice | Implementation |
+|---|---|
+| Non-root user | `RUN addgroup -S app && adduser -S app -G app` then `USER app` before CMD |
+| No secrets in layers | Use `--secret` mount at build time or runtime env injection; never `ENV SECRET=` or `ARG TOKEN=` |
+| Minimal base | distroless by default; alpine when a shell is needed; never debian/ubuntu for production |
+| Pinned base digest | `FROM node:20-alpine@sha256:<digest>` prevents silent upstream changes |
+| No `apt-get upgrade` | Pin the base image digest instead; `upgrade` produces non-reproducible layers |
+| Read-only filesystem | Pass `--read-only` at runtime; mount writable tmpfs only for paths that need writes |
+
+Never use `ADD` with a URL — it bypasses layer caching in unpredictable ways and cannot be verified. Use `COPY` for local files and `curl` + checksum verification for remote files.
+
+## Image Scanning
+
+| Tool | Integration | Default Threshold |
+|---|---|---|
+| Trivy | `aquasecurity/trivy-action` GitHub Action; `trivy image <name>` CLI | Fail CI on CRITICAL; warn on HIGH |
+| Snyk | `snyk container test <image>`; Snyk Container GitHub Action | Fail on CRITICAL/HIGH; surface fixability data |
+| Docker Scout | `docker scout cves <image>`; built into Docker Desktop | Advisory; set `--exit-code` flag for CI enforcement |
+
+Run image scanning in CI after the build stage, before the deploy stage. Scan the exact image SHA that will be deployed, not a rebuilt copy.
+
+## .dockerignore
+
+Always include a `.dockerignore`. Exclude: `.git`, `node_modules`, `.env`, `*.env`, `test/`, `tests/`, `docs/`, `*.md`, `coverage/`, `*.log`, `dist/` (only if rebuilding inside the container).
+
+A missing `.dockerignore` sends the entire repo context to the daemon on every build, including secrets and `.git` history.
+
+## Health Checks
+
+```dockerfile
+HEALTHCHECK --interval=30s --timeout=5s --start-period=10s --retries=3 \
+  CMD wget -qO- http://localhost:3000/health || exit 1
+```
+
+Use an HTTP endpoint for web services. Use a process check (`pgrep`) only for non-HTTP workloads.
+
+Kubernetes uses separate liveness, readiness, and startup probes — configure those in the deployment manifest, not in the Dockerfile. The Docker `HEALTHCHECK` is relevant for `docker run` and Docker Compose only.
+
+## Size Optimization
+
+- Use `dive <image>` to inspect layer sizes and identify waste before shipping.
+- `--no-install-recommends` with `apt-get install` eliminates suggested packages.
+- Always clean package manager caches in the same `RUN` layer as the install command.
+- Use `COPY --chown=app:app` instead of a separate `RUN chown` to avoid a wasted layer.
+- Multi-stage builds remove all build tools, source files, and intermediate artifacts automatically — they are the single highest-impact size reduction technique.
+- For Go and Rust, build a statically linked binary (`CGO_ENABLED=0` for Go, `musl` target for Rust) and copy it into `scratch` or distroless for a final image under 20 MB.