@dennisrongo/skills 0.1.0

package/skills/nextjs-app-router/references/templates/ci-and-hooks.md

@@ -0,0 +1,94 @@
+# CI workflow + Husky + lint-staged
+
+## `.github/workflows/ci.yml`
+
+```yaml
+name: ci
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+
+concurrency:
+  group: ci-${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: true
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    timeout-minutes: 15
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: pnpm/action-setup@v4
+        with:
+          version: 9
+
+      - uses: actions/setup-node@v4
+        with:
+          node-version: 20
+          cache: pnpm
+
+      - run: pnpm install --frozen-lockfile
+
+      - run: pnpm lint --max-warnings=0
+      - run: pnpm typecheck
+      - run: pnpm test
+      - run: pnpm build
+        env:
+          NEXT_PUBLIC_API_BASE_URL: http://localhost:5000
+
+  # Optional separate job for E2E — only run on push to main to save CI minutes.
+  e2e:
+    if: github.event_name == 'push'
+    runs-on: ubuntu-latest
+    timeout-minutes: 20
+    needs: build
+    steps:
+      - uses: actions/checkout@v4
+      - uses: pnpm/action-setup@v4
+        with: { version: 9 }
+      - uses: actions/setup-node@v4
+        with: { node-version: 20, cache: pnpm }
+      - run: pnpm install --frozen-lockfile
+      - run: pnpm exec playwright install --with-deps chromium
+      - run: pnpm test:e2e
+        env:
+          NEXT_PUBLIC_API_BASE_URL: http://localhost:5000
+```
+
+**Notes:**
+- `--frozen-lockfile` ensures the lockfile is honored — CI fails if `package.json` and lockfile drift.
+- `--max-warnings=0` on lint means even warnings fail CI. On a fresh scaffold there are none; this catches regressions early.
+- E2E is split into its own job behind `if: github.event_name == 'push'` so PRs stay fast.
+
+## Husky + lint-staged
+
+After `pnpm install`, run:
+
+```bash
+pnpm exec husky init
+```
+
+Then write `.husky/pre-commit`:
+
+```sh
+#!/usr/bin/env sh
+. "$(dirname -- "$0")/_/husky.sh"
+
+pnpm exec lint-staged
+```
+
+The `lint-staged` config lives in `package.json` (see [`package.md`](package.md)):
+
+```jsonc
+"lint-staged": {
+  "*.{ts,tsx}": ["prettier --write", "eslint --fix"],
+  "*.{json,md,css,yml,yaml}": ["prettier --write"]
+}
+```
+
+**Notes:**
+- Do not put `tsc --noEmit` in lint-staged — it's per-staged-file and TypeScript is project-wide; let CI handle it.
+- Do not skip hooks (`--no-verify`) as a workflow. If a hook is annoying, fix the underlying issue.

package/skills/nextjs-app-router/references/templates/components-json.md

@@ -0,0 +1,41 @@
+# `components.json` template (shadcn config)
+
+```jsonc
+{
+  "$schema": "https://ui.shadcn.com/schema.json",
+  "style": "default",
+  "rsc": true,
+  "tsx": true,
+  "tailwind": {
+    "config": "tailwind.config.ts",
+    "css": "src/app/globals.css",
+    "baseColor": "neutral",
+    "cssVariables": true,
+    "prefix": ""
+  },
+  "aliases": {
+    "components": "@/components",
+    "utils": "@/lib/utils",
+    "ui": "@/components/ui",
+    "lib": "@/lib",
+    "hooks": "@/lib/hooks"
+  }
+}
+```
+
+**Initial components to generate** (only what the scaffolded templates actually import — add more on demand via `pnpm dlx shadcn@latest add <name>`):
+
+- `button`
+- `input`
+- `label`
+- `form` (the RHF-aware wrapper)
+- `dialog`
+- `dropdown-menu`
+- `select`
+- `popover`
+- `calendar` (only if forms need a date picker)
+- `toast` + `toaster` + `use-toast`
+- `card`
+- `separator`
+
+**Do not** bulk-install every shadcn primitive at scaffold time. Each one is owned code that needs to be reviewed and maintained.

package/skills/nextjs-app-router/references/templates/env-and-utils.md

@@ -0,0 +1,110 @@
+# Env validation, `cn()`, and shared utils
+
+## `src/config/env.ts` (runtime-validated env)
+
+```ts
+import { z } from 'zod';
+
+const envSchema = z.object({
+  NEXT_PUBLIC_API_BASE_URL: z.string().url(),
+  // Add more vars here as needed. Keep client-readable ones prefixed with NEXT_PUBLIC_.
+});
+
+function loadEnv() {
+  const parsed = envSchema.safeParse({
+    NEXT_PUBLIC_API_BASE_URL: process.env.NEXT_PUBLIC_API_BASE_URL,
+  });
+  if (!parsed.success) {
+    // Fail fast at module load.
+    console.error('Invalid environment configuration:', parsed.error.flatten().fieldErrors);
+    throw new Error('Invalid environment configuration. See .env.example for required variables.');
+  }
+  return parsed.data;
+}
+
+export const env = loadEnv();
+```
+
+**Why:** misconfiguration (`NEXT_PUBLIC_API_BASE_URL` undefined, typo'd) blows up at startup with a clear error, not via a confusing 404 on the first network request.
+
+## `.env.example` (committed)
+
+```
+# Backend API base URL. Required.
+NEXT_PUBLIC_API_BASE_URL=http://localhost:5000
+
+# Optional: real-time
+# NEXT_PUBLIC_PUSHER_KEY=
+# NEXT_PUBLIC_PUSHER_CLUSTER=
+
+# Server-only: JWT verification key (only for Variant B middleware).
+# JWT_VERIFY_KEY=
+```
+
+`.env`, `.env.local`, `.env.*.local` go in `.gitignore`. Only `.env.example` is committed.
+
+## `src/lib/utils.ts`
+
+```ts
+import { clsx, type ClassValue } from 'clsx';
+import { twMerge } from 'tailwind-merge';
+
+export function cn(...inputs: ClassValue[]): string {
+  return twMerge(clsx(inputs));
+}
+```
+
+That's the entire file. No bag of unrelated helpers — those go in `src/lib/formatters/` or feature-local utility files.
+
+## `src/lib/formatters/date.ts`
+
+```ts
+import { format, formatDistanceToNow, parseISO } from 'date-fns';
+
+export function formatDate(value: string | Date, pattern = 'PP'): string {
+  const d = typeof value === 'string' ? parseISO(value) : value;
+  return format(d, pattern);
+}
+
+export function formatRelative(value: string | Date): string {
+  const d = typeof value === 'string' ? parseISO(value) : value;
+  return formatDistanceToNow(d, { addSuffix: true });
+}
+```
+
+**No `moment`. Anywhere. Ever.** ESLint's `no-restricted-imports` blocks new imports of it.
+
+## `src/components/UnsavedChangesWarning.tsx`
+
+```tsx
+'use client';
+
+import { useEffect } from 'react';
+
+interface Props {
+  when: boolean;
+  message?: string;
+}
+
+export function UnsavedChangesWarning({ when, message = 'You have unsaved changes. Leave anyway?' }: Props) {
+  useEffect(() => {
+    if (!when) return;
+
+    const onBeforeUnload = (e: BeforeUnloadEvent) => {
+      e.preventDefault();
+      e.returnValue = message;
+    };
+
+    window.addEventListener('beforeunload', onBeforeUnload);
+    return () => window.removeEventListener('beforeunload', onBeforeUnload);
+  }, [when, message]);
+
+  // Next's App Router does not yet expose a stable router-events API for intercepting client-side navigation.
+  // The pattern below (overriding history.pushState) is a workaround — review and adjust per the Next version
+  // resolved at scaffold time (use context7 to check whether the official `useBeforeUnload` / `unstable_*` API has landed).
+
+  return null;
+}
+```
+
+**Adjust at scaffold time:** if the Next.js version resolved in Step 1 exposes a stable navigation-intercept hook, use it instead of the `beforeunload`-only fallback. Verify via context7.

package/skills/nextjs-app-router/references/templates/eslint-prettier.md

@@ -0,0 +1,82 @@
+# ESLint + Prettier templates
+
+## `.eslintrc.json`
+
+```jsonc
+{
+  "root": true,
+  "extends": [
+    "next/core-web-vitals",
+    "next/typescript",
+    "plugin:@typescript-eslint/recommended",
+    "plugin:react-hooks/recommended",
+    "plugin:jsx-a11y/recommended",
+    "prettier"
+  ],
+  "plugins": ["@typescript-eslint", "react-hooks", "jsx-a11y"],
+  "rules": {
+    "no-console": ["warn", { "allow": ["warn", "error"] }],
+    "@typescript-eslint/no-explicit-any": "error",
+    "@typescript-eslint/no-unused-vars": ["error", { "argsIgnorePattern": "^_", "varsIgnorePattern": "^_" }],
+    "@typescript-eslint/consistent-type-imports": ["error", { "prefer": "type-imports" }],
+    "react-hooks/exhaustive-deps": "error",
+    "prefer-const": "error",
+    "eqeqeq": ["error", "always", { "null": "ignore" }],
+    "no-restricted-imports": [
+      "error",
+      {
+        "paths": [
+          { "name": "moment", "message": "Use date-fns. moment is in maintenance mode." },
+          { "name": "styled-components", "message": "This project uses Tailwind. Do not add CSS-in-JS." },
+          { "name": "lodash", "message": "Import the specific lodash function: 'lodash/debounce'. Or write a one-line helper." }
+        ]
+      }
+    ]
+  },
+  "overrides": [
+    {
+      "files": ["tests/**/*", "**/*.test.{ts,tsx}"],
+      "rules": {
+        "@typescript-eslint/no-explicit-any": "off",
+        "no-console": "off"
+      }
+    }
+  ]
+}
+```
+
+## `.prettierrc`
+
+```jsonc
+{
+  "singleQuote": true,
+  "semi": true,
+  "trailingComma": "all",
+  "printWidth": 100,
+  "tabWidth": 2,
+  "plugins": ["prettier-plugin-tailwindcss"]
+}
+```
+
+## `.prettierignore`
+
+```
+.next/
+node_modules/
+out/
+dist/
+build/
+coverage/
+playwright-report/
+test-results/
+*.lock
+*.lockb
+pnpm-lock.yaml
+package-lock.json
+yarn.lock
+```
+
+**Notes:**
+- `prettier-plugin-tailwindcss` sorts Tailwind class names automatically — keep class lists alphabetized without bikeshedding.
+- The `no-restricted-imports` rule is the scaffolder's enforcement of the date library / styling system choices. Removing these rules requires a discussion, not a unilateral edit.
+- Keep ESLint warnings *off* a fresh scaffold; warnings only show up after the project adds something that triggers them. CI runs `--max-warnings=0` so they fail loud.

package/skills/nextjs-app-router/references/templates/feature-slice.md

@@ -0,0 +1,184 @@
+# Feature slice template (Mode 2 — `add-feature`)
+
+A feature is a route folder under a route group, with its own private `_components/` and `_hooks/`, a local Zod `schema.ts`, and (usually) one or more RTK Query endpoints injected into the appropriate domain slice.
+
+## Layout for feature `{{feature}}` under `(app)`
+
+```
+src/app/(app)/{{feature}}/
+├── page.tsx                   # SERVER component (renders client child if interactive)
+├── loading.tsx
+├── error.tsx                  # optional but recommended
+├── schema.ts                  # Zod schemas owned by this feature
+├── _components/
+│   ├── {{Feature}}Table.tsx   # 'use client' if it has interactions
+│   └── {{Feature}}Form.tsx    # 'use client'
+└── _hooks/
+    └── use{{Feature}}Filters.ts
+```
+
+For a feature with sub-routes (list + detail + new):
+
+```
+src/app/(app)/{{feature}}/
+├── page.tsx                   # list
+├── new/
+│   └── page.tsx               # SERVER renders <{{Feature}}Form mode="create" />
+├── [id]/
+│   ├── page.tsx               # SERVER renders <{{Feature}}Form mode="edit" id={id} />
+│   ├── loading.tsx
+│   └── _components/{{Feature}}DetailPanel.tsx
+├── schema.ts
+├── _components/
+│   ├── {{Feature}}Table.tsx
+│   └── {{Feature}}Form.tsx
+└── _hooks/
+```
+
+## `page.tsx` for the list view (SERVER)
+
+```tsx
+import { Suspense } from 'react';
+import { {{Feature}}Table } from './_components/{{Feature}}Table';
+
+export const metadata = { title: '{{Feature}}s' };
+
+export default function {{Feature}}sPage() {
+  return (
+    <section className="space-y-4">
+      <header className="flex items-center justify-between">
+        <h1 className="text-2xl font-semibold">{{Feature}}s</h1>
+      </header>
+      <Suspense fallback={<div>Loading…</div>}>
+        <{{Feature}}Table />
+      </Suspense>
+    </section>
+  );
+}
+```
+
+## `_components/{{Feature}}Table.tsx` (CLIENT)
+
+```tsx
+'use client';
+
+import { use{{Feature}}sQuery } from '@/redux/api/{{feature}}sApi';
+
+export function {{Feature}}sTable() {
+  const { data, isLoading, error } = use{{Feature}}sQuery();
+
+  if (isLoading) return <p className="text-muted-foreground">Loading…</p>;
+  if (error) return <p className="text-destructive">Failed to load.</p>;
+  if (!data?.length) return <p className="text-muted-foreground">No {{feature}}s yet.</p>;
+
+  return (
+    <table className="w-full text-left">
+      <thead>
+        <tr className="border-b">
+          <th className="py-2">Name</th>
+          <th className="py-2">Created</th>
+        </tr>
+      </thead>
+      <tbody>
+        {data.map((row) => (
+          <tr key={row.id} className="border-b">
+            <td className="py-2">{row.name}</td>
+            <td className="py-2 text-muted-foreground">{row.createdAt}</td>
+          </tr>
+        ))}
+      </tbody>
+    </table>
+  );
+}
+```
+
+## `schema.ts`
+
+```ts
+import { z } from 'zod';
+
+export const {{feature}}Schema = z.object({
+  name: z.string().min(1).max(120),
+  email: z.string().email(),
+});
+
+export type {{Feature}}FormValues = z.infer<typeof {{feature}}Schema>;
+```
+
+## `_components/{{Feature}}Form.tsx` (CLIENT)
+
+```tsx
+'use client';
+
+import { useRouter } from 'next/navigation';
+import { useForm } from 'react-hook-form';
+import { zodResolver } from '@hookform/resolvers/zod';
+import { Form } from '@/components/ui/form';
+import { Button } from '@/components/ui/button';
+import { FormInputField } from '@/components/forms/FormInputField';
+import { UnsavedChangesWarning } from '@/components/UnsavedChangesWarning';
+import { useToast } from '@/components/ui/use-toast';
+import { useCreate{{Feature}}Mutation } from '@/redux/api/{{feature}}sApi';
+import { getDefaultValuesFromSchema, unwrapZodEffects } from '@/lib/zod-utils';
+import { {{feature}}Schema, type {{Feature}}FormValues } from '../schema';
+
+export function {{Feature}}Form() {
+  const router = useRouter();
+  const { toast } = useToast();
+  const [create, { isLoading }] = useCreate{{Feature}}Mutation();
+
+  const form = useForm<{{Feature}}FormValues>({
+    resolver: zodResolver({{feature}}Schema),
+    defaultValues: getDefaultValuesFromSchema(unwrapZodEffects({{feature}}Schema)) as {{Feature}}FormValues,
+  });
+
+  const onSubmit = async (values: {{Feature}}FormValues) => {
+    try {
+      const created = await create(values).unwrap();
+      toast({ title: '{{Feature}} created.' });
+      router.replace(`/app/{{feature}}s/${created.id}`);
+    } catch {
+      toast({ title: 'Could not save', variant: 'destructive' });
+    }
+  };
+
+  return (
+    <Form {...form}>
+      <UnsavedChangesWarning when={form.formState.isDirty && !form.formState.isSubmitting} />
+      <form onSubmit={form.handleSubmit(onSubmit)} className="max-w-lg space-y-4">
+        <FormInputField form={form} schema={{feature}}Schema} fieldName="name" label="Name" />
+        <FormInputField form={form} schema={{feature}}Schema} fieldName="email" label="Email" type="email" />
+        <div className="flex gap-2">
+          <Button type="submit" disabled={isLoading}>{isLoading ? 'Saving…' : 'Save'}</Button>
+          <Button type="button" variant="ghost" onClick={() => router.back()}>Cancel</Button>
+        </div>
+      </form>
+    </Form>
+  );
+}
+```
+
+## Schema unit test — `tests/unit/{{feature}}.schema.test.ts`
+
+```ts
+import { describe, expect, it } from 'vitest';
+import { {{feature}}Schema } from '@/app/(app)/{{feature}}s/schema';
+
+describe('{{feature}}Schema', () => {
+  it('accepts a valid payload', () => {
+    expect({{feature}}Schema.safeParse({ name: 'Acme', email: 'ops@acme.test' }).success).toBe(true);
+  });
+
+  it('rejects empty name', () => {
+    expect({{feature}}Schema.safeParse({ name: '', email: 'ops@acme.test' }).success).toBe(false);
+  });
+
+  it('rejects invalid email', () => {
+    expect({{feature}}Schema.safeParse({ name: 'Acme', email: 'nope' }).success).toBe(false);
+  });
+});
+```
+
+## Endpoint additions
+
+If the domain slice doesn't exist yet, run Mode 3 first (`add-api-slice`). Then add the feature's query/mutation pair to that slice — see [`api-slice.md`](api-slice.md).