voidmachine 0.0.0 → 4.0.0

package/core-assets/packs/pack-nextjs/skills/void-cache-component-pattern/SKILL.md

@@ -0,0 +1,162 @@
+---
+name: void-cache-component-pattern
+description: Use Next.js 16 Cache Components correctly — when to opt in ('use cache'), when to opt out ('use no cache'), cache key strategy, scoping by user/org. Default is cached; uncache deliberately.
+---
+
+# cache-component-pattern
+
+Use when writing or modifying any Next.js 16 Server Component, route handler, or fetch in `app/`. Cache Components is Next 16's default-cache model — flipping the previous default-dynamic stance. Getting this right is the difference between a page rendered in 30ms (cached) and 800ms (regenerated every request).
+
+## The default
+
+Next 16 caches by default at the Server Component / fetch level. You opt out, not in. This is the inverse of Next 13/14.
+
+```tsx
+// app/blog/[slug]/page.tsx — cached by default
+export default async function Page({ params }: { params: { slug: string } }) {
+  const post = await db.query.posts.findFirst({ where: eq(posts.slug, params.slug) });
+  return <Article post={post} />;
+}
+```
+
+This page IS cached. The `params.slug` is the key. New slugs trigger a fresh render; existing slugs serve from cache.
+
+## When to opt OUT — `'use no cache'`
+
+Some content cannot be cached. Tag the component or fetch:
+
+```tsx
+// app/dashboard/page.tsx — user-specific
+'use no cache';
+
+export default async function Page() {
+  const user = await getCurrentUser();      // session-dependent
+  return <Dashboard user={user} />;
+}
+```
+
+Use `'use no cache'` when the response depends on:
+
+- Current user identity (`getCurrentUser`, `cookies()`, `headers()`)
+- Live data with sub-minute staleness requirements (real-time dashboards, inbox)
+- Random sampling, A/B tests at render time
+- `Date.now()` or similar non-deterministic inputs you don't want to key
+
+The rule: if the same URL could legitimately render two different responses to two different users, opt out.
+
+## Per-fetch opt-out
+
+Inside a component that's MOSTLY cacheable but has one dynamic call:
+
+```tsx
+export default async function Page() {
+  // Cached
+  const post = await db.query.posts.findFirst({ where: eq(posts.slug, slug) });
+
+  // Not cached — re-fetched every request
+  const liveViewerCount = await fetch('https://api/views', { cache: 'no-store' });
+
+  return <Article post={post} viewers={liveViewerCount} />;
+}
+```
+
+`{ cache: 'no-store' }` opts out one fetch. The page stays cached for the parts that can be.
+
+## Cache key strategy
+
+The key for a cached component is **automatically derived** from:
+
+- Route params (`[slug]`, `[id]`)
+- Search params used in the component (only those READ; uses are tracked)
+- Cookies / headers used (tracked similarly — but reading these usually opts you out automatically)
+
+You influence the key by what you read. To cache one variant per locale:
+
+```tsx
+// app/[locale]/page.tsx
+export default async function Page({ params }: { params: { locale: string } }) {
+  return <Home locale={params.locale} />;
+}
+```
+
+`/en` and `/fr` are separate cache entries because `locale` is in the URL.
+
+To cache one variant per org WITHOUT putting org in the URL: don't. Put it in the URL. Caching cross-cuts user scopes is a security accident waiting to happen.
+
+## The "shared cache across users" trap
+
+```tsx
+// ✗ DANGEROUS — caches user-specific data under a route-only key
+export default async function Page() {
+  const user = await getCurrentUser();
+  const posts = await db.query.posts.findMany({ where: eq(posts.authorId, user.id) });
+  return <PostList posts={posts} />;
+}
+```
+
+If Next caches this without realizing `user.id` is in play, user A could see user B's posts. The `getCurrentUser` call reads cookies, which marks the page dynamic — but only if Next is configured correctly. **Always add `'use no cache'` when the response depends on the user, even if Next "would have" detected it.** Belt and braces; the cost of being explicit is zero, the cost of a leak is unbounded.
+
+## `revalidate` for time-based freshness
+
+Cached but with a maximum age:
+
+```tsx
+export const revalidate = 60;  // seconds
+
+export default async function Page() { ... }
+```
+
+Use cases: news headlines, leaderboards, dashboards updated every minute. The cache serves stale content for up to 60s, then re-renders on the next request.
+
+For tag-based revalidation (invalidate specific entries after a mutation):
+
+```tsx
+import { revalidateTag } from 'next/cache';
+
+export async function publishPost() {
+  await db.insert(posts).values(...);
+  revalidateTag('posts-list');
+}
+```
+
+In the cached component: `fetch(url, { next: { tags: ['posts-list'] } })`. The tag links them.
+
+## `revalidatePath` vs `revalidateTag`
+
+| Function | Use when | Scope |
+|---|---|---|
+| `revalidatePath('/blog/[slug]', 'page')` | One specific page invalidated after a mutation | Single path |
+| `revalidatePath('/blog', 'layout')` | A whole subtree invalidated (rare) | Layout + all children |
+| `revalidateTag('posts-list')` | Multiple pages share the same data | Every fetch with that tag |
+
+Default to `revalidateTag`. Path-based revalidation is fragile (parameterized paths are tricky).
+
+## Anti-patterns
+
+- ✗ **`'use no cache'` at the layout level** — blanket-opts-out the entire subtree. Use it on specific routes.
+- ✗ **Caching `getCurrentUser()` results** — `cache(getCurrentUser)` is a request-scoped React `cache`, NOT a cross-request Next cache; don't confuse the two
+- ✗ **`revalidate = 0`** — equivalent to `'use no cache'` but less explicit. Use the directive.
+- ✗ **Broad `revalidatePath('/')` after every mutation** — kills cache hit rate; be surgical
+- ✗ **Mixing `cache: 'no-store'` AND `next: { revalidate }` on the same fetch** — they conflict; pick one
+
+## Debug: "is this actually cached?"
+
+Add a server-side `console.log(Date.now())` in the Server Component. Hit refresh. If the timestamp changes, the page is NOT cached. If it's stable across refreshes, it is.
+
+Or use Next's built-in `?_cache-debug=1` (if available in your version) to inspect cache hit/miss per route in DevTools.
+
+## Workflow
+
+1. **Before writing the component**, ask: does the response depend on the user, on cookies, or on "right now"?
+2. **If yes**, top of the file: `'use no cache';`. Done.
+3. **If no**, leave it cached. No directive needed.
+4. **Per-fetch overrides** for surgical exceptions (one dynamic fetch in a mostly-cached page).
+5. **Tag your fetches** if they'll need invalidation after mutations (`next: { tags: [...] }`).
+6. **Invalidate from Server Actions** via `revalidateTag` after the mutation succeeds.
+
+## Composition
+
+- `void-client-vs-server-component` — only Server Components participate in Cache Components.
+- `void-server-action` — actions call `revalidateTag` / `revalidatePath` after mutations.
+- `void-security-guidance` — explicit `'use no cache'` on user-scoped content is a security control, not just a perf one.
+- `void-observability` — log cache misses on routes you expect cached; surface as a perf signal.

package/core-assets/packs/pack-nextjs/skills/void-cache-component-pattern/harness.yaml

@@ -0,0 +1,14 @@
+# Harness metadata for this skill. Not part of the Agent Skills
+# specification, and never copied into a consumer project: the SKILL.md
+# beside it stays portable and validates against the official six fields.
+# Read by this repository's graph, and by the installer for `runtimes`.
+kind: standard
+owner: folpe
+runtimes: [claude, codex]
+enforcement:
+  floor: ci
+  inline:
+    claude: active
+    codex: active
+    hermes: ci-only
+eval_targets: [claude/anthropic/opus]

package/core-assets/packs/pack-nextjs/skills/void-instrumentation-setup/.source

@@ -0,0 +1,5 @@
+Sources for `void-instrumentation-setup` skill (see `docs/plans/skill-audits/void-instrumentation-setup.md` for the full audit):
+
+- No external source listed in the audit. Authored against the Next.js 16 instrumentation.ts mechanism (register() export, NEXT_RUNTIME edge/node split) and the Sentry + OpenTelemetry + pino composition.
+
+Strategy: distill. Wiring pattern authored natively for Next 16; no upstream skill was adapted.

package/core-assets/packs/pack-nextjs/skills/void-instrumentation-setup/SKILL.md

@@ -0,0 +1,161 @@
+---
+name: void-instrumentation-setup
+description: Wire instrumentation.ts in Next.js 16 — Sentry, pino logger, OpenTelemetry traces. Edge vs Node runtime split. The single place observability is bootstrapped.
+---
+
+# instrumentation-setup
+
+Use when setting up observability in a fresh Next.js app, OR when adding a new instrumentation tool (Sentry → +OTel, +Datadog, etc.). The pattern: ONE `instrumentation.ts` at the project root, conditionally initializes per runtime.
+
+Composes with `void-observability` (the doctrine: pino, structured logs, Sentry user scope). This skill is the Next-specific wiring.
+
+## File location
+
+```
+apps/<app>/
+├── instrumentation.ts              # the bootstrap
+├── instrumentation-node.ts         # Node-runtime-specific
+├── instrumentation-edge.ts         # Edge-runtime-specific (optional)
+└── src/
+```
+
+Next 16 auto-loads `instrumentation.ts` at server startup (both runtimes). `instrumentation-{node,edge}.ts` are convention-driven splits.
+
+## Canonical bootstrap
+
+```ts
+// apps/web/instrumentation.ts
+export async function register() {
+  if (process.env.NEXT_RUNTIME === 'nodejs') {
+    await import('./instrumentation-node');
+  }
+  if (process.env.NEXT_RUNTIME === 'edge') {
+    await import('./instrumentation-edge');
+  }
+}
+```
+
+The dynamic imports keep edge bundles slim (Sentry's Node SDK doesn't ship to Edge runtime).
+
+## Node runtime setup
+
+```ts
+// apps/web/instrumentation-node.ts
+import * as Sentry from '@sentry/nextjs';
+import { trace } from '@opentelemetry/api';
+import { NodeSDK } from '@opentelemetry/sdk-node';
+import { getNodeAutoInstrumentations } from '@opentelemetry/auto-instrumentations-node';
+import { OTLPTraceExporter } from '@opentelemetry/exporter-trace-otlp-http';
+import { logger, env } from '@repo/core';
+
+// 1. Sentry
+Sentry.init({
+  dsn: env.SENTRY_DSN,
+  environment: env.NODE_ENV,
+  tracesSampleRate: env.NODE_ENV === 'production' ? 0.1 : 1.0,
+  beforeSend: (event) => {
+    if (event.user?.id) event.user.id = hash(event.user.id);   // anonymize
+    return event;
+  },
+});
+
+// 2. OpenTelemetry (if you ship traces outside Sentry)
+if (env.OTEL_EXPORTER_OTLP_ENDPOINT) {
+  const sdk = new NodeSDK({
+    traceExporter: new OTLPTraceExporter({
+      url: env.OTEL_EXPORTER_OTLP_ENDPOINT,
+    }),
+    instrumentations: [getNodeAutoInstrumentations()],
+  });
+  sdk.start();
+}
+
+// 3. pino is initialized eagerly in @repo/core/logger — nothing to do here.
+
+logger.info({ event: 'app.boot', runtime: 'nodejs' });
+```
+
+## Edge runtime setup
+
+```ts
+// apps/web/instrumentation-edge.ts
+import * as Sentry from '@sentry/nextjs';
+import { env } from '@repo/core';
+
+Sentry.init({
+  dsn: env.SENTRY_DSN,
+  environment: env.NODE_ENV,
+  tracesSampleRate: 0.1,
+  transportOptions: { fetchOptions: { keepalive: true } },   // Edge fetch quirk
+});
+
+// No OTel, no pino — Edge runtime doesn't support them.
+// Use Sentry.captureMessage / addBreadcrumb for structured-ish logs.
+```
+
+Edge can't `fs.write`, can't load native modules, can't use Node `Buffer` outside polyfills. Keep instrumentation minimal.
+
+## What lives where (decision table)
+
+| Concern | Where |
+|---|---|
+| Sentry init | `instrumentation-node.ts` AND `instrumentation-edge.ts` |
+| OpenTelemetry | `instrumentation-node.ts` only |
+| pino logger | `@repo/core/logger` (auto-initialized on import) |
+| Sentry user scope per-request | Server Action / Route handler wrapper (`withTraceContext`) |
+| Request-level traces | OTel auto-instrumentation (Node) |
+| Client-side errors | `app/global-error.tsx` + `Sentry.init` in a `'use client'` provider |
+
+## Client-side Sentry
+
+Server `instrumentation.ts` does NOT cover the browser. For client errors, add a separate provider:
+
+```tsx
+// apps/web/src/app/sentry-provider.tsx
+'use client';
+
+import * as Sentry from '@sentry/nextjs';
+import { useEffect } from 'react';
+
+let initialized = false;
+
+export function SentryProvider({ children }: { children: React.ReactNode }) {
+  useEffect(() => {
+    if (initialized) return;
+    initialized = true;
+    Sentry.init({
+      dsn: process.env.NEXT_PUBLIC_SENTRY_DSN,
+      tracesSampleRate: 0.1,
+      replaysSessionSampleRate: 0.1,
+    });
+  }, []);
+  return <>{children}</>;
+}
+```
+
+Wire in `app/layout.tsx`. The `NEXT_PUBLIC_*` env is the only secret-ish value that's safe in the bundle.
+
+## Anti-patterns
+
+- ✗ **Calling `Sentry.init` inside route handlers** — re-inits every request, leaks event listeners
+- ✗ **Same Sentry sample rate in dev and prod** — at 1.0 prod you'll exhaust your event quota
+- ✗ **Logging PII raw** — `beforeSend` should redact user.id, email, etc. Hash or strip.
+- ✗ **OTel auto-instrumentation in Edge** — silently fails because Edge can't load Node native bindings
+- ✗ **One instrumentation.ts that branches on runtime inline** — the dynamic-import pattern keeps bundles clean
+
+## Verification checklist
+
+After setup, in dev:
+
+1. Throw in a Server Component — should surface in Sentry
+2. Throw in a Server Action — should surface
+3. Throw in a Client Component — should surface (client-side init)
+4. Check that user ID is hashed in Sentry events
+5. Check that NODE_ENV-conditional behavior (sample rate) actually differs
+
+## Composition
+
+- `void-observability` — pino + Sentry doctrine (this skill is the Next wiring).
+- `void-security-guidance` — Sentry user scope MUST be hashed; no PII in event payloads.
+- `void-env-validation` — `SENTRY_DSN`, `OTEL_EXPORTER_OTLP_ENDPOINT` validated via Zod in `@repo/core/env`.
+- `void-loading-error-boundaries` — `error.tsx` uses Sentry.captureException; this skill ensures Sentry is initialized when that fires.

package/core-assets/packs/pack-nextjs/skills/void-instrumentation-setup/harness.yaml

@@ -0,0 +1,14 @@
+# Harness metadata for this skill. Not part of the Agent Skills
+# specification, and never copied into a consumer project: the SKILL.md
+# beside it stays portable and validates against the official six fields.
+# Read by this repository's graph, and by the installer for `runtimes`.
+kind: standard
+owner: folpe
+runtimes: [claude, codex]
+enforcement:
+  floor: ci
+  inline:
+    claude: active
+    codex: active
+    hermes: ci-only
+eval_targets: [claude/anthropic/opus]

package/core-assets/packs/pack-nextjs/skills/void-loading-error-boundaries/.source

@@ -0,0 +1,5 @@
+Sources for `void-loading-error-boundaries` skill (see `docs/plans/skill-audits/void-loading-error-boundaries.md` for the full audit):
+
+- No external source listed in the audit. Authored against the App Router boundary file conventions (loading.tsx, error.tsx, not-found.tsx) and the Sentry capture point in error boundaries.
+
+Strategy: distill. Placement rules authored natively for the App Router; no upstream skill was adapted.

package/core-assets/packs/pack-nextjs/skills/void-loading-error-boundaries/SKILL.md

@@ -0,0 +1,176 @@
+---
+name: void-loading-error-boundaries
+description: Place loading.tsx, error.tsx, not-found.tsx files at the right level — neither too high (poor UX) nor too low (unhandled errors). The skeleton matches the layout it replaces.
+---
+
+# loading-error-boundaries
+
+Use when adding or restructuring routes in `app/`. Next.js boundary files (`loading.tsx`, `error.tsx`, `not-found.tsx`) define UX during Server Component rendering, server failures, and missing-resource cases. Placement matters: too high = whole page flashes on partial load; too low = errors leak past the intended catch.
+
+## The 4 boundary files
+
+| File | Wraps | Renders when |
+|---|---|---|
+| `loading.tsx` | Sibling `page.tsx` in a Suspense boundary | Async server work in progress |
+| `error.tsx` | Sibling `page.tsx` + descendants in an Error Boundary | Server throws OR client error |
+| `not-found.tsx` | Triggered by `notFound()` call | `notFound()` from a Server Component / handler |
+| `global-error.tsx` | Wraps the root `app/layout.tsx` itself | Layout throws (rare) |
+
+`error.tsx` and `global-error.tsx` MUST be Client Components (they catch React errors).
+
+## Placement: as low as practical
+
+Place boundary files **at the segment that owns the unique loading state**, not at the root.
+
+```
+app/
+├── (app)/
+│   ├── layout.tsx           # auth check, app shell
+│   ├── dashboard/
+│   │   ├── page.tsx
+│   │   ├── loading.tsx      # skeleton of dashboard widgets
+│   │   └── error.tsx        # error display in app shell context
+│   └── settings/
+│       ├── page.tsx
+│       └── loading.tsx      # skeleton of settings form
+└── (marketing)/
+    ├── layout.tsx
+    └── blog/
+        ├── [slug]/
+        │   ├── page.tsx
+        │   ├── loading.tsx  # article skeleton
+        │   └── error.tsx    # "couldn't load article" message
+        └── page.tsx          # blog index (no skeleton — small enough)
+```
+
+Per-route boundaries mean a slow `/dashboard` doesn't blank out `/settings` when the user is on `/settings`. Each route streams in independently.
+
+## Skeleton design: match the final layout
+
+A skeleton's job is to **reserve the space** the real content will occupy. The user's eye should not jump when the content arrives.
+
+```tsx
+// app/(app)/dashboard/loading.tsx
+export default function Loading() {
+  return (
+    <div className="grid grid-cols-3 gap-4 p-6">
+      <Skeleton className="h-32" />           {/* matches card height */}
+      <Skeleton className="h-32" />
+      <Skeleton className="h-32" />
+      <Skeleton className="col-span-3 h-64" />{/* matches chart */}
+    </div>
+  );
+}
+```
+
+- ✗ Spinner in the middle of the page — gives no spatial cue, content appearance is jarring
+- ✗ Skeleton that's the wrong height — layout shift on content arrival = bad CLS
+- ✓ Skeleton bricks matching the final layout shape, neutral gray fill, optional shimmer
+
+For text content: 3-5 lines of skeleton bars at varying widths look more realistic than perfect rectangles.
+
+## `error.tsx`: handle, don't display the stack
+
+Error boundary should:
+
+- Hide the technical detail from end users
+- Log to Sentry (composes with `void-observability`)
+- Offer a recovery path (reset button, link back)
+
+```tsx
+'use client';
+
+import { useEffect } from 'react';
+import * as Sentry from '@sentry/nextjs';
+
+export default function Error({ error, reset }: { error: Error & { digest?: string }; reset: () => void }) {
+  useEffect(() => {
+    Sentry.captureException(error);
+  }, [error]);
+
+  return (
+    <div className="p-6">
+      <h2>Quelque chose s'est mal passé.</h2>
+      <p>L'équipe est notifiée. Vous pouvez réessayer.</p>
+      <button onClick={() => reset()}>Réessayer</button>
+    </div>
+  );
+}
+```
+
+The `digest` prop is the server-side error ID — useful to correlate Sentry with the user report (display it discreetly: `<small>ID: {error.digest}</small>`).
+
+## `not-found.tsx` — the route's own 404
+
+```tsx
+// app/(marketing)/blog/[slug]/not-found.tsx
+export default function NotFound() {
+  return (
+    <div className="p-6 text-center">
+      <h1>Article introuvable</h1>
+      <p>Cet article n'existe pas ou a été supprimé.</p>
+      <Link href="/blog">← Retour aux articles</Link>
+    </div>
+  );
+}
+```
+
+Triggered from a Server Component:
+
+```tsx
+import { notFound } from 'next/navigation';
+
+export default async function Article({ params }) {
+  const post = await db.query.posts.findFirst({ where: eq(posts.slug, params.slug) });
+  if (!post) notFound();
+  return <ArticleView post={post} />;
+}
+```
+
+Without a `not-found.tsx` at the route, Next falls back to the nearest ancestor. Provide one at the level that knows the resource — a blog `not-found` is contextually richer than the root 404.
+
+## `global-error.tsx` — last resort
+
+Catches errors in `app/layout.tsx` itself (and its providers). Rare; usually empty until needed.
+
+```tsx
+// app/global-error.tsx
+'use client';
+
+export default function GlobalError({ error, reset }) {
+  return (
+    <html>
+      <body>
+        <h1>Application non disponible.</h1>
+        <button onClick={() => reset()}>Recharger</button>
+      </body>
+    </html>
+  );
+}
+```
+
+Must render its own `<html>` and `<body>` because it replaces the root layout entirely.
+
+## Anti-patterns
+
+- ✗ **One `loading.tsx` at app root** — every route shows the same skeleton; no granularity
+- ✗ **Spinner-only loading** — no spatial cue, content appearance is jarring
+- ✗ **Error boundary displaying the raw stack** — leaks internal info, scares users
+- ✗ **`not-found.tsx` only at the root** — every "not found" looks the same; misses context
+- ✗ **No `useEffect` Sentry capture in error.tsx** — errors swallowed silently
+- ✗ **Catching errors in components via try/catch instead of `error.tsx`** — bypasses React's error boundary mechanism
+
+## Workflow
+
+1. **At each route segment**, ask: does this content need its own loading state?
+2. **If yes**, write a `loading.tsx` whose skeleton matches the final layout's shape.
+3. **For routes that fetch data**, write an `error.tsx` with Sentry capture + recovery action.
+4. **For routes with parameterized resources** ([slug], [id]), write a `not-found.tsx` and call `notFound()` when the resource is absent.
+5. **`global-error.tsx` only when** root layout starts having logic that can fail.
+
+## Composition
+
+- `void-cache-component-pattern` — cached pages have predictable load times; loading.tsx is mostly for the cold cache case.
+- `void-parallel-routes-slots` — each `@slot` can have its own `loading.tsx` / `error.tsx`.
+- `void-observability` — `error.tsx` is the Sentry capture point for server errors.
+- `void-accessibility-check` — skeletons should have `aria-busy` or `aria-live="polite"` regions.

package/core-assets/packs/pack-nextjs/skills/void-loading-error-boundaries/harness.yaml

@@ -0,0 +1,14 @@
+# Harness metadata for this skill. Not part of the Agent Skills
+# specification, and never copied into a consumer project: the SKILL.md
+# beside it stays portable and validates against the official six fields.
+# Read by this repository's graph, and by the installer for `runtimes`.
+kind: standard
+owner: folpe
+runtimes: [claude, codex]
+enforcement:
+  floor: ci
+  inline:
+    claude: active
+    codex: active
+    hermes: ci-only
+eval_targets: [claude/anthropic/opus]

package/core-assets/packs/pack-nextjs/skills/void-parallel-routes-slots/.source

@@ -0,0 +1,5 @@
+Sources for `void-parallel-routes-slots` skill (see `docs/plans/skill-audits/void-parallel-routes-slots.md` for the full audit):
+
+- No external source listed in the audit. Authored against the Next.js routing primitives (parallel routes @slot, intercepting routes (.)foo) and their over-application traps.
+
+Strategy: distill. WIN-vs-LOSE guidance authored natively for the Next routing primitives; no upstream skill was adapted.