@jgamaraalv/ts-dev-kit 1.0.0

package/skills/composition-patterns/references/state-lift-state.md

@@ -0,0 +1,126 @@
+## Lift State into Provider Components
+
+### Table of Contents
+
+- [Incorrect: State Trapped Inside Component](#incorrect-state-trapped-inside-component)
+- [Incorrect: useEffect to Sync State Up](#incorrect-useeffect-to-sync-state-up)
+- [Incorrect: Reading State from Ref on Submit](#incorrect-reading-state-from-ref-on-submit)
+- [Correct: State Lifted to Provider](#correct-state-lifted-to-provider)
+- [Key Insight](#key-insight)
+
+Move state management into dedicated provider components. This allows sibling
+components outside the main UI to access and modify state without prop drilling
+or awkward refs.
+
+**Incorrect (state trapped inside component):**
+
+```tsx
+function ForwardMessageComposer() {
+  const [state, setState] = useState(initialState);
+  const forwardMessage = useForwardMessage();
+
+  return (
+    <Composer.Frame>
+      <Composer.Input />
+      <Composer.Footer />
+    </Composer.Frame>
+  );
+}
+
+// Problem: How does this button access composer state?
+function ForwardMessageDialog() {
+  return (
+    <Dialog>
+      <ForwardMessageComposer />
+      <MessagePreview /> {/* Needs composer state */}
+      <DialogActions>
+        <CancelButton />
+        <ForwardButton /> {/* Needs to call submit */}
+      </DialogActions>
+    </Dialog>
+  );
+}
+```
+
+**Incorrect (useEffect to sync state up):**
+
+```tsx
+function ForwardMessageDialog() {
+  const [input, setInput] = useState("");
+  return (
+    <Dialog>
+      <ForwardMessageComposer onInputChange={setInput} />
+      <MessagePreview input={input} />
+    </Dialog>
+  );
+}
+
+function ForwardMessageComposer({ onInputChange }) {
+  const [state, setState] = useState(initialState);
+  useEffect(() => {
+    onInputChange(state.input); // Sync on every change 😬
+  }, [state.input]);
+}
+```
+
+**Incorrect (reading state from ref on submit):**
+
+```tsx
+function ForwardMessageDialog() {
+  const stateRef = useRef(null);
+  return (
+    <Dialog>
+      <ForwardMessageComposer stateRef={stateRef} />
+      <ForwardButton onPress={() => submit(stateRef.current)} />
+    </Dialog>
+  );
+}
+```
+
+**Correct (state lifted to provider):**
+
+```tsx
+function ForwardMessageProvider({ children }: { children: React.ReactNode }) {
+  const [state, setState] = useState(initialState);
+  const forwardMessage = useForwardMessage();
+  const inputRef = useRef(null);
+
+  return (
+    <Composer.Provider
+      state={state}
+      actions={{ update: setState, submit: forwardMessage }}
+      meta={{ inputRef }}
+    >
+      {children}
+    </Composer.Provider>
+  );
+}
+
+function ForwardMessageDialog() {
+  return (
+    <ForwardMessageProvider>
+      <Dialog>
+        <ForwardMessageComposer />
+        <MessagePreview /> {/* Custom components can access state and actions */}
+        <DialogActions>
+          <CancelButton />
+          <ForwardButton /> {/* Custom components can access state and actions */}
+        </DialogActions>
+      </Dialog>
+    </ForwardMessageProvider>
+  );
+}
+
+function ForwardButton() {
+  const { actions } = use(Composer.Context);
+  return <Button onPress={actions.submit}>Forward</Button>;
+}
+```
+
+The ForwardButton lives outside the Composer.Frame but still has access to the
+submit action because it's within the provider. Even though it's a one-off
+component, it can still access the composer's state and actions from outside the
+UI itself.
+
+**Key insight:** Components that need shared state don't have to be visually
+nested inside each other—they just need to be within the same provider.

package/skills/conventional-commits/SKILL.md

@@ -0,0 +1,148 @@
+---
+name: conventional-commits
+description: "Write, review, and validate commit messages following the Conventional Commits v1.0.0 specification. Use when: (1) crafting a git commit message for any change, (2) reviewing or correcting an existing commit message, (3) choosing the right commit type for a change, (4) deciding how to mark a breaking change, (5) writing multi-line commits with body and footers, or (6) understanding how commits map to SemVer bumps (PATCH/MINOR/MAJOR). Covers all standard types: feat, fix, docs, chore, refactor, perf, test, build, ci, style, revert."
+---
+
+## Table of Contents
+
+- [Format](#format)
+- [Types and SemVer impact](#types-and-semver-impact)
+- [Breaking changes](#breaking-changes)
+- [Examples](#examples)
+- [Non-obvious rules](#non-obvious-rules)
+- [Choosing the right type](#choosing-the-right-type)
+- [SemVer cheatsheet](#semver-cheatsheet)
+
+## Format
+
+```
+<type>[optional scope]: <description>
+
+[optional body]
+
+[optional footer(s)]
+```
+
+- **type**: lowercase noun (see table below)
+- **scope**: optional noun in parentheses describing the affected section, e.g. `feat(auth):`
+- **description**: imperative, present tense, no period at end, immediately after `": "`
+- **body**: free-form; begins one blank line after description
+- **footers**: one blank line after body; follow git trailer format (`Token: value` or `Token #value`)
+
+## Types and SemVer impact
+
+| Type       | Use for                                      | SemVer |
+| ---------- | -------------------------------------------- | ------ |
+| `feat`     | New feature                                  | MINOR  |
+| `fix`      | Bug fix                                      | PATCH  |
+| `docs`     | Documentation only                           | none   |
+| `style`    | Formatting, whitespace (no logic change)     | none   |
+| `refactor` | Code restructure (not a fix or feature)      | none   |
+| `perf`     | Performance improvement                      | none   |
+| `test`     | Adding or fixing tests                       | none   |
+| `build`    | Build system, dependencies (npm, gradle…)    | none   |
+| `ci`       | CI configuration (GitHub Actions, CircleCI…) | none   |
+| `chore`    | Maintenance not fitting above types          | none   |
+| `revert`   | Reverts a previous commit                    | none   |
+
+Any type + `BREAKING CHANGE` → **MAJOR**.
+
+## Breaking changes
+
+Two ways to signal a breaking change (can combine both):
+
+**1. `!` after type/scope** (visible at a glance):
+
+```
+feat(api)!: remove deprecated v1 endpoints
+```
+
+**2. `BREAKING CHANGE:` footer** (required if you need a description):
+
+```
+feat: allow config object to extend other configs
+
+BREAKING CHANGE: `extends` key now used for extending config files
+```
+
+Both together:
+
+```
+chore!: drop support for Node 6
+
+BREAKING CHANGE: use JavaScript features not available in Node 6.
+```
+
+## Examples
+
+**Simple fix:**
+
+```
+fix: prevent racing of requests
+```
+
+**Feature with scope:**
+
+```
+feat(lang): add Polish language
+```
+
+**Fix with body and footers:**
+
+```
+fix: prevent racing of requests
+
+Introduce a request id and a reference to latest request. Dismiss
+incoming responses other than from latest request.
+
+Remove timeouts which were used to mitigate the racing issue but are
+obsolete now.
+
+Reviewed-by: Z
+Refs: #123
+```
+
+**Revert with footer references:**
+
+```
+revert: let us never again speak of the noodle incident
+
+Refs: 676104e, a215868
+```
+
+**Docs with no body:**
+
+```
+docs: correct spelling of CHANGELOG
+```
+
+## Non-obvious rules
+
+- **NEVER** add `Co-Authored-By` trailers to commit messages. This project does not use authorship footers.
+- Types are **case-insensitive** in parsing, but `BREAKING CHANGE` footer token **must be uppercase**.
+- `BREAKING-CHANGE` (hyphen) is a valid synonym for `BREAKING CHANGE` in footers.
+- Footer tokens use `-` instead of spaces (e.g. `Reviewed-by`), **except** `BREAKING CHANGE`.
+- Footer separator is either `": "` (colon-space) or `" #"` (space-hash for issue refs): `Refs #123`.
+- A footer value may span multiple lines; parsing stops at the next valid `Token: ` or `Token #` pair.
+- When a commit fits multiple types, split into multiple commits instead of picking one.
+- Wrong type used before merge? Ask the developer to fix manually with an interactive rebase. Claude Code cannot run interactive commands. After release, the commit is simply missed by automation tools — not catastrophic.
+- Squash workflows: lead maintainer can rewrite messages at merge time; contributors don't need to follow the spec perfectly on every WIP commit.
+
+## Choosing the right type
+
+```
+Is it a new user-facing capability?         → feat
+Is it fixing incorrect behavior?            → fix
+Is it changing docs/comments only?          → docs
+Is it improving speed/memory?               → perf
+Is it reorganizing code (no behavior Δ)?    → refactor
+Is it adding/fixing tests only?             → test
+Is it CI pipeline config?                   → ci
+Is it build tooling or dependency updates?  → build
+Is it undoing a previous commit?            → revert
+Everything else (scripts, config, etc.)?    → chore
+```
+
+## SemVer cheatsheet
+
+`fix`→PATCH, `feat`→MINOR, `BREAKING CHANGE`→MAJOR

package/skills/docker/SKILL.md

@@ -0,0 +1,55 @@
+---
+name: docker
+
+description: "Docker containerization reference — multi-stage builds, Compose configs, image optimization, and container security for Yarn 4 monorepos. Use when: (1) creating or optimizing Dockerfiles, (2) configuring docker-compose for dev or production, (3) reducing image size with multi-stage builds, (4) hardening container security, or (5) setting up health checks and resource limits."
+---
+
+# Docker — Containerization for Monorepos
+
+Docker best practices for Node.js monorepos with Yarn 4 Berry.
+
+## When to Load References
+
+| Need                                               | Reference file                                                         |
+| -------------------------------------------------- | ---------------------------------------------------------------------- |
+| Writing or reviewing a Dockerfile for the monorepo | [references/monorepo-dockerfile.md](references/monorepo-dockerfile.md) |
+| Configuring docker-compose for dev or production   | [references/compose-configs.md](references/compose-configs.md)         |
+
+## Key Principles
+
+- **Minimal images**: Alpine-based, only runtime dependencies in final stage
+- **Layer caching order**: system deps → package manifests → install → source → build
+- **Non-root users**: Create `app` user, never run as root in production
+- **One process per container**: Compose multiple containers, not multiple processes
+- **Health checks on every service**: Use the existing `/health` endpoint
+
+## Image Optimization Quick Reference
+
+- Use `node:22-alpine` as base
+- Multi-stage builds: exclude build tools from final image
+- `yarn cache clean` after install
+- `.dockerignore`: exclude `.git`, `node_modules`, `*.md`, `.env*`, `.claude`, `__tests__`, `coverage`, `.turbo`
+- `--production` flag for runtime dependencies only
+- Pin base image versions (not just `latest`)
+
+## Container Security Quick Reference
+
+- Run as non-root user (`addgroup --system app && adduser --system --ingroup app app`)
+- Don't store secrets in images — use env vars or secrets management
+- Scan images: `docker scout cves <image>`
+- Set resource limits in compose: `mem_limit`, `cpus`
+- Read-only filesystem where possible: `read_only: true`
+- Drop capabilities: `cap_drop: [ALL]`
+
+## Useful Commands
+
+```bash
+docker compose build api          # Build specific service
+docker compose up -d              # Start all services
+docker compose logs -f api        # Follow logs
+docker compose exec api sh        # Shell into container
+docker images | grep myapp    # Check image sizes
+docker system df                  # View cache usage
+docker system prune -a            # Prune unused images
+docker stats                      # Resource usage
+```

package/skills/docker/references/compose-configs.md

@@ -0,0 +1,95 @@
+# Docker Compose Configurations
+
+## Development (`docker-compose.yml`)
+
+Infrastructure services only — app runs natively via `yarn dev`.
+
+```yaml
+services:
+  postgres:
+    image: postgis/postgis:16-3.4-alpine
+    restart: unless-stopped
+    environment:
+      POSTGRES_USER: ${POSTGRES_USER:-myapp}
+      POSTGRES_PASSWORD: ${POSTGRES_PASSWORD:-myapp}
+      POSTGRES_DB: ${POSTGRES_DB:-myapp}
+    ports:
+      - "${POSTGRES_PORT:-5432}:5432"
+    volumes:
+      - postgres_data:/var/lib/postgresql/data
+    healthcheck:
+      test: ["CMD-SHELL", "pg_isready -U ${POSTGRES_USER:-myapp}"]
+      interval: 10s
+      timeout: 5s
+      retries: 5
+
+  redis:
+    image: redis:7-alpine
+    restart: unless-stopped
+    ports:
+      - "${REDIS_PORT:-6379}:6379"
+    volumes:
+      - redis_data:/data
+    healthcheck:
+      test: ["CMD", "redis-cli", "ping"]
+      interval: 10s
+      timeout: 5s
+      retries: 5
+    command: redis-server --maxmemory 256mb --maxmemory-policy allkeys-lru
+
+volumes:
+  postgres_data:
+  redis_data:
+```
+
+## Production Override (`docker-compose.prod.yml`)
+
+Adds containerized app services on top of infrastructure.
+
+```yaml
+services:
+  api:
+    build:
+      context: .
+      dockerfile: apps/api/Dockerfile
+      target: api-runner
+    restart: unless-stopped
+    ports:
+      - "3001:3001"
+    environment:
+      NODE_ENV: production
+      DATABASE_URL: postgres://${POSTGRES_USER}:${POSTGRES_PASSWORD}@postgres:5432/${POSTGRES_DB}
+      REDIS_URL: redis://redis:6379
+    depends_on:
+      postgres:
+        condition: service_healthy
+      redis:
+        condition: service_healthy
+
+  web:
+    build:
+      context: .
+      dockerfile: apps/web/Dockerfile
+      target: web-runner
+    restart: unless-stopped
+    ports:
+      - "3000:3000"
+    environment:
+      NODE_ENV: production
+      API_URL: http://api:3001
+    depends_on:
+      - api
+```
+
+## Health Checks
+
+Every service should have a health check:
+
+```yaml
+healthcheck:
+  test: ["CMD", "wget", "--spider", "--quiet", "http://localhost:3001/health"]
+  interval: 30s
+  timeout: 5s
+  start_period: 10s
+  retries: 3
+```

package/skills/docker/references/monorepo-dockerfile.md

@@ -0,0 +1,111 @@
+# Multi-Stage Dockerfile for Yarn 4 Monorepo
+
+## API Dockerfile (`apps/api/Dockerfile`)
+
+```dockerfile
+# ============================================
+# Stage 1: Base with Yarn 4 Berry
+# ============================================
+FROM node:22-alpine AS base
+ENV YARN_ENABLE_GLOBAL_CACHE=false
+WORKDIR /app
+
+# Install Yarn Berry
+COPY .yarnrc.yml ./
+COPY .yarn/ .yarn/
+COPY package.json yarn.lock ./
+
+# ============================================
+# Stage 2: Install ALL dependencies (for building)
+# ============================================
+FROM base AS deps
+# Copy all workspace package.json files
+COPY apps/api/package.json apps/api/
+COPY apps/web/package.json apps/web/
+COPY packages/shared/package.json packages/shared/
+COPY packages/config/package.json packages/config/
+RUN yarn install --immutable
+
+# ============================================
+# Stage 3: Build shared packages first
+# ============================================
+FROM deps AS builder
+COPY . .
+# Build in dependency order
+RUN yarn workspace @myapp/shared build
+RUN yarn workspace @myapp/api build
+# Or for web: RUN yarn workspace @myapp/web build
+
+# ============================================
+# Stage 4: Production runtime (API)
+# ============================================
+FROM node:22-alpine AS api-runner
+WORKDIR /app
+
+# Security: non-root user
+RUN addgroup --system app && adduser --system --ingroup app app
+
+# Copy only production dependencies and built output
+COPY --from=builder /app/apps/api/dist ./apps/api/dist
+COPY --from=builder /app/apps/api/package.json ./apps/api/
+COPY --from=builder /app/packages/shared/dist ./packages/shared/dist
+COPY --from=builder /app/packages/shared/package.json ./packages/shared/
+COPY --from=builder /app/package.json ./
+COPY --from=builder /app/yarn.lock ./
+COPY --from=builder /app/.yarnrc.yml ./
+COPY --from=builder /app/.yarn/ ./.yarn/
+
+# Install production dependencies only
+RUN yarn workspaces focus @myapp/api --production && yarn cache clean
+
+USER app
+EXPOSE 3001
+
+HEALTHCHECK --interval=30s --timeout=5s --start-period=10s --retries=3 \
+  CMD wget --no-verbose --tries=1 --spider http://localhost:3001/health || exit 1
+
+CMD ["node", "apps/api/dist/index.js"]
+```
+
+## Layer Caching Order
+
+```dockerfile
+# 1. System dependencies (rarely change)
+RUN apk add --no-cache ...
+
+# 2. Package manifests (change on dependency update)
+COPY package.json yarn.lock ./
+
+# 3. Install dependencies (cached unless manifests change)
+RUN yarn install --immutable
+
+# 4. Source code (changes most frequently)
+COPY . .
+
+# 5. Build
+RUN yarn build
+```
+
+## .dockerignore
+
+```
+.git
+node_modules
+*.md
+.env*
+.vscode
+.claude
+**/__tests__
+**/*.test.ts
+**/*.spec.ts
+coverage
+.turbo
+```
+
+## Size Reduction Tips
+
+- Use Alpine-based images (`node:22-alpine`)
+- Multi-stage builds to exclude build tools from final image
+- `yarn cache clean` after install
+- Don't copy `.git`, `node_modules`, or test files
+- Use `--production` flag for runtime dependencies only