start-vibing-stacks 2.32.0 → 2.34.0

package/stacks/_shared/skills/podman-patterns/SKILL.md

@@ -0,0 +1,260 @@
+---
+name: podman-patterns
+version: 1.0.0
+description: "Podman 2026 patterns: rootless containers (no daemon, no root), Quadlet (systemd units), podman play kube, podman compose (Docker Compose compatibility), podman machine (macOS/Windows), healthchecks, secrets via --secret, distroless images. Replaces Docker daemon in CI and production for security and simplicity."
+---
+
+# Podman Patterns (2026)
+
+**Invoke when writing container definitions, systemd services for containers, Kubernetes manifests for single pods, or migrating from Docker daemon.**
+
+> 2026 reality: **Rootless is the default**. No container runtime should run as root. Podman + Quadlet is the recommended path on Linux for production services. `podman play kube` replaces simple `kubectl apply` for single-pod workloads. Dockerfiles are fully compatible.
+
+## Why Podman in 2026
+
+| Aspect | Docker | Podman | Winner |
+|--------|--------|--------|--------|
+| Daemon | Required (root) | None | Podman |
+| Root | Required for daemon | Rootless by default | Podman |
+| Kubernetes | Separate (kind/minikube) | `podman play kube` | Podman |
+| Systemd | Manual units | Quadlet (native) | Podman |
+| macOS/Windows | Docker Desktop | `podman machine` | Tie |
+| CI | Docker-in-Docker | Native rootless | Podman |
+
+**Rule:** If the target is Linux (server or CI), prefer Podman. If you need Docker Compose syntax, use `podman compose` — it is a drop-in replacement.
+
+---
+
+## 1. Rootless + Distroless (Node.js example)
+
+```dockerfile
+# syntax=docker/dockerfile:1.7
+ARG NODE_VERSION=22.11.0
+
+FROM node:${NODE_VERSION}-alpine AS builder
+WORKDIR /app
+COPY package*.json ./
+RUN --mount=type=cache,target=/root/.npm \
+    npm ci --ignore-scripts
+COPY . .
+RUN npm run build && npm prune --omit=dev
+
+FROM gcr.io/distroless/nodejs22-debian12:nonroot
+WORKDIR /app
+COPY --from=builder --chown=nonroot:nonroot /app/node_modules ./node_modules
+COPY --from=builder --chown=nonroot:nonroot /app/dist         ./dist
+COPY --from=builder --chown=nonroot:nonroot /app/package.json ./
+USER nonroot
+EXPOSE 3000
+ENV NODE_ENV=production
+HEALTHCHECK --interval=30s --timeout=3s --start-period=5s --retries=3 \
+  CMD ["/nodejs/bin/node", "-e", "fetch('http://127.0.0.1:3000/healthz').then(r=>process.exit(r.ok?0:1)).catch(()=>process.exit(1))"]
+CMD ["dist/server.js"]
+```
+
+Run rootless:
+
+```bash
+podman run -d --name app \
+  --user 10001:10001 \
+  --read-only \
+  --security-opt no-new-privileges \
+  -p 3000:3000 \
+  localhost/myapp:latest
+```
+
+---
+
+## 2. Quadlet — The 2026 Way to Run Containers as Services
+
+Instead of writing systemd units by hand, use **Quadlet** (`.container` files).
+
+### Example: `myapp.container`
+
+```ini
+[Unit]
+Description=My Node.js App
+After=network-online.target
+Wants=network-online.target
+
+[Container]
+Image=localhost/myapp:latest
+ContainerName=myapp
+PublishPort=3000:3000
+Environment=NODE_ENV=production
+HealthCmd=/nodejs/bin/node -e "fetch('http://127.0.0.1:3000/healthz').then(r=>process.exit(r.ok?0:1)).catch(()=>process.exit(1))"
+HealthInterval=30s
+HealthTimeout=3s
+HealthStartPeriod=5s
+HealthRetries=3
+ReadOnly=true
+User=10001
+Group=10001
+SecurityLabelDisable=false
+
+[Service]
+Restart=always
+RestartSec=5
+
+[Install]
+WantedBy=multi-user.target
+```
+
+Install:
+
+```bash
+sudo cp myapp.container /etc/containers/systemd/
+sudo systemctl daemon-reload
+sudo systemctl start myapp.service
+```
+
+Quadlet automatically creates the proper systemd service, handles restarts, and integrates with `podman`.
+
+---
+
+## 3. `podman play kube` — Single-Pod Kubernetes
+
+For simple workloads, avoid full Kubernetes. Use a Pod manifest:
+
+```yaml
+apiVersion: v1
+kind: Pod
+metadata:
+  name: myapp
+  labels:
+    app: myapp
+spec:
+  containers:
+  - name: app
+    image: localhost/myapp:latest
+    ports:
+    - containerPort: 3000
+    env:
+    - name: NODE_ENV
+      value: production
+    securityContext:
+      runAsNonRoot: true
+      runAsUser: 10001
+      readOnlyRootFilesystem: true
+    livenessProbe:
+      exec:
+        command:
+        - /nodejs/bin/node
+        - -e
+        - "fetch('http://127.0.0.1:3000/healthz').then(r=>process.exit(r.ok?0:1)).catch(()=>process.exit(1))"
+      initialDelaySeconds: 5
+      periodSeconds: 30
+  restartPolicy: Always
+```
+
+Deploy:
+
+```bash
+podman play kube myapp.yaml
+```
+
+Stop:
+
+```bash
+podman play kube --down myapp.yaml
+```
+
+This is dramatically simpler than Helm or full K8s for single-service apps.
+
+---
+
+## 4. Secrets (Better Than Docker Build Secrets)
+
+Podman supports `--secret` natively:
+
+```bash
+podman run --secret id=stripe_key,src=.env.d/local/secrets/stripe.key \
+  -e STRIPE_SECRET_KEY_FILE=/run/secrets/stripe_key \
+  localhost/myapp
+```
+
+Inside the container, the secret is available at `/run/secrets/stripe_key` and is never stored in the image layer.
+
+See `secrets-management` for the full `.env.d/` + secret file pattern.
+
+---
+
+## 5. Podman Machine (macOS / Windows)
+
+On non-Linux hosts:
+
+```bash
+podman machine init
+podman machine start
+podman machine ssh          # for debugging
+```
+
+Use the same Dockerfiles and Quadlet files — Podman abstracts the VM.
+
+---
+
+## 6. Migration from Docker
+
+| Docker Command | Podman Equivalent | Notes |
+|----------------|-------------------|-------|
+| `docker build` | `podman build` | Same syntax |
+| `docker compose up` | `podman compose up` | Full compatibility |
+| `docker run --user` | `podman run --user` | Rootless is default |
+| Manual systemd unit | Quadlet `.container` | Much simpler |
+| `docker ps` | `podman ps` | Identical output |
+| `docker system prune` | `podman system prune` | Same |
+
+**Rule:** Keep using `docker-compose.yml` if you want — just run it with `podman compose`. The compose file is unchanged.
+
+---
+
+## 7. Integration With Other Skills
+
+- `secrets-management` — Use `.env.d/` + `--secret` mounts.
+- `security-baseline` — Rootless + read-only + no-new-privileges is the baseline.
+- `ci-pipelines` — Run `podman` instead of `docker` in GitHub Actions (no DinD needed).
+- `docker-patterns` — Podman can consume the exact same Dockerfiles. The two skills are complementary.
+
+---
+
+## FORBIDDEN
+
+| Pattern | Reason |
+|---------|--------|
+| Running Podman as root | Defeats the entire security model |
+| Using `sudo podman` in scripts | Indicates misconfiguration |
+| Storing secrets in image layers | Use `--secret` or mounted files |
+| Running containers with `--privileged` | Never needed with rootless + proper capabilities |
+| Ignoring healthchecks | Quadlet and `podman play kube` both support them natively |
+
+---
+
+## Pre-Deployment Checklist
+
+- [ ] Image built with multi-stage + distroless/chiseled
+- [ ] Non-root user (10001:10001 or higher)
+- [ ] Read-only root filesystem
+- [ ] Healthcheck defined
+- [ ] Secrets passed via `--secret` (not ENV or COPY)
+- [ ] If Linux server → Quadlet `.container` file
+- [ ] If simple K8s workload → `podman play kube` manifest
+- [ ] `.dockerignore` present (same as Docker)
+
+---
+
+## See Also
+
+- `docker-patterns` — the Docker side of the same story (compatible)
+- `secrets-management` — how to structure `.env.d/` and secret files
+- `security-baseline` — rootless is now table stakes
+- `ci-pipelines` — rootless CI runners
+
+---
+
+## Memory Optimization Trigger
+
+If this skill grows beyond ~250 lines or accumulates many near-duplicate Quadlet examples, run:
+
+```bash
+npx start-vibing-stacks memory optimize --dry-run
+```

package/stacks/_shared/skills/react-server-components/SKILL.md

@@ -0,0 +1,194 @@
+---
+name: react-server-components
+version: 1.0.0
+description: "React 19 Server Components (RSC) production patterns for 2026: Server Components as default, 'use client' only on interactive leaves, streaming with Suspense, parallel data fetching with Promise.all, serialization rules (no functions/classes across boundary), layered caching (React cache + framework unstable_cache), Server Actions for mutations. Use with Next.js 16+ App Router."
+---
+
+# React Server Components (2026 Production)
+
+**Invoke when building any React 19+ application using the App Router (Next.js 16+, Remix RSC, TanStack Start, etc.).**
+
+> 2026 reality: Server Components are the default. 40%+ bundle size reduction is common when done correctly. The mental model is: **Server Components fetch and render on the server. Client Components add interactivity. Keep the boundary small and explicit.**
+
+---
+
+## 1. The Core Mental Model
+
+| Component Type | Runs Where | Bundle Impact | Data Fetching | Interactivity |
+|----------------|------------|---------------|---------------|---------------|
+| **Server Component** (default) | Server | 0 KB to client | Direct (DB, API, FS) | None |
+| **Client Component** (`'use client'`) | Client | Full JS shipped | Via props or API | Full (useState, useEffect, etc.) |
+
+**Rule of thumb:**
+- Default to Server Component.
+- Add `'use client'` **only** when you need interactivity, browser APIs, or hooks.
+- Keep Client Components as **small leaf components** near the user interaction.
+
+---
+
+## 2. Data Fetching — No Waterfalls
+
+**Wrong (sequential):**
+
+```tsx
+// app/page.tsx
+export default async function Page() {
+  const user = await getUser();        // 200ms
+  const posts = await getPosts(user);  // waits for user
+  const comments = await getComments(); // waits for posts
+  return <Dashboard ... />;
+}
+```
+
+**Correct (parallel):**
+
+```tsx
+export default async function Page() {
+  const [user, posts, comments] = await Promise.all([
+    getUser(),
+    getPosts(),
+    getComments(),
+  ]);
+  return <Dashboard user={user} posts={posts} comments={comments} />;
+}
+```
+
+Or use React's `cache()` for deduplication across the component tree.
+
+---
+
+## 3. Passing Data Across the Server → Client Boundary
+
+**Only plain serializable data is allowed:**
+
+- Primitives (`string`, `number`, `boolean`, `null`)
+- Plain objects and arrays
+- Dates (serialized as ISO strings in Next.js)
+- Promises (React will suspend)
+
+**Forbidden:**
+
+- Functions
+- Class instances
+- `Map`, `Set`, `Date` (raw), `Error`, `RegExp`
+- React elements (JSX) from Server to Client
+
+**Correct pattern:**
+
+```tsx
+// Server Component
+const user = await getUser();
+const safeUser = {
+  id: user.id,
+  name: user.name,
+  createdAt: user.createdAt.toISOString(),
+};
+
+return <UserProfile user={safeUser} />; // Client Component
+```
+
+---
+
+## 4. Streaming with Suspense
+
+Slow data should be wrapped in `<Suspense>` so the rest of the page streams immediately.
+
+```tsx
+import { Suspense } from 'react';
+import { Comments } from './comments';
+
+export default function Page() {
+  return (
+    <div>
+      <Header />                    {/* streams first */}
+      <Suspense fallback={<CommentsSkeleton />}>
+        <Comments />                {/* streams when ready */}
+      </Suspense>
+    </div>
+  );
+}
+```
+
+---
+
+## 5. Server Actions (`'use server'`)
+
+For mutations, use Server Actions instead of API routes.
+
+```tsx
+// app/actions.ts
+'use server';
+
+export async function createPost(formData: FormData) {
+  const title = formData.get('title');
+  await db.post.create({ data: { title } });
+  revalidatePath('/posts');
+}
+```
+
+```tsx
+// app/new-post.tsx (Client Component)
+'use client';
+
+import { createPost } from './actions';
+
+export function NewPostForm() {
+  return (
+    <form action={createPost}>
+      <input name="title" />
+      <button type="submit">Create</button>
+    </form>
+  );
+}
+```
+
+---
+
+## 6. Caching Layers (Next.js 16+)
+
+1. **React `cache()`** — per-request memoization
+2. **`unstable_cache`** — shared across requests (with tags)
+3. **Route segment config** — `export const revalidate = 3600`
+4. **Dynamic functions** (`cookies()`, `headers()`) — opt out of static rendering
+
+---
+
+## 7. Common Pitfalls in 2026
+
+| Mistake | Fix |
+|---------|-----|
+| Putting `'use client'` at the root layout | Only add it to interactive leaves |
+| Passing functions or class instances as props | Serialize on the server first |
+| Sequential `await` in Server Components | Use `Promise.all` |
+| Using Context at the root layout | Context only works inside Client Components |
+| Forgetting to handle loading states with Suspense | Wrap slow sections in `<Suspense>` |
+| Using `Date` objects directly across boundary | Convert to ISO string on the server |
+
+---
+
+## 8. When to Use Client Components
+
+Only when you need:
+
+- `useState`, `useEffect`, `useReducer`, `useContext`
+- Browser APIs (`localStorage`, `window`, `document`)
+- Event handlers (`onClick`, `onSubmit`)
+- Third-party libraries that require the browser (many chart libs, drag-and-drop, etc.)
+
+---
+
+## See Also
+
+- `nextjs-app-router` — framework-specific patterns on top of RSC
+- `react-patterns` — general React 19 best practices
+- Official React docs: https://react.dev/reference/rsc/server-components
+
+---
+
+## Memory Optimization Trigger
+
+If this skill accumulates many near-duplicate examples or grows beyond ~200 lines, run:
+
+```bash
+npx start-vibing-stacks memory optimize --dry-run
+```

package/stacks/nodejs/stack.json

@@ -81,7 +81,8 @@
       "icon": "⚛️",
       "skillsDir": "react",
       "default": true,
-      "frameworks": ["nextjs", "express", "fastify", "vanilla"]
+      "frameworks": ["nextjs", "express", "fastify", "vanilla"],
+      "skills": ["react-server-components"]
     },
     {
       "id": "vue",
@@ -109,7 +110,9 @@
     "bun-runtime",
     "zod-validation",
     "api-security-node",
-    "openapi-design"
+    "openapi-design",
+    "docker-patterns",
+    "podman-patterns"
   ],
   "requirements": [
     {

package/stacks/php/stack.json

@@ -33,7 +33,8 @@
         "laravel-patterns",
         "laravel-octane",
         "laravel-api-architecture",
-        "api-security"
+        "api-security",
+        "laravel-octane-inertia"
       ]
     },
     {
@@ -44,7 +45,8 @@
       "skills": [
         "laravel-patterns",
         "laravel-api-architecture",
-        "api-security"
+        "api-security",
+        "laravel-octane-inertia"
       ]
     }
   ],
@@ -98,7 +100,9 @@
     "api-design",
     "api-security",
     "laravel-api-architecture",
-    "openapi-design"
+    "openapi-design",
+    "docker-patterns",
+    "podman-patterns"
   ],
   "requirements": [
     {

package/stacks/python/stack.json

@@ -70,7 +70,9 @@
     "pydantic-validation",
     "pytest-testing",
     "python-performance",
-    "api-security-python"
+    "api-security-python",
+    "docker-patterns",
+    "podman-patterns"
   ],
   "requirements": [
     {