dk-harness 0.1.0

package/templates/next-fastapi-monorepo/pnpm-workspace.yaml

@@ -0,0 +1,3 @@
+packages:
+  - "apps/*"
+  - "packages/*"

package/templates/next-fastapi-monorepo/renovate.json

@@ -0,0 +1,6 @@
+{
+  "$schema": "https://docs.renovatebot.com/renovate-schema.json",
+  "extends": ["config:best-practices"],
+  "labels": ["dependencies"]
+}
+

package/templates/next-fastapi-monorepo/tsconfig.json

@@ -0,0 +1,4 @@
+{
+  "extends": "@workspace/typescript-config/base.json"
+}
+

package/templates/next-fastapi-monorepo/turbo.json

@@ -0,0 +1,27 @@
+{
+  "$schema": "https://turbo.build/schema.json",
+  "ui": "tui",
+  "tasks": {
+    "build": {
+      "dependsOn": ["^build"],
+      "inputs": ["$TURBO_DEFAULT$", ".env*"],
+      "outputs": [".next/**", "!.next/cache/**"]
+    },
+    "lint": {
+      "dependsOn": ["^lint"]
+    },
+    "format": {
+      "dependsOn": ["^format"]
+    },
+    "typecheck": {
+      "dependsOn": ["^typecheck"]
+    },
+    "test": {
+      "dependsOn": ["^test"]
+    },
+    "dev": {
+      "cache": false,
+      "persistent": true
+    }
+  }
+}

package/templates/next-monorepo/.eslintrc.js

@@ -0,0 +1,13 @@
+// Root-level ESLint config for a Turborepo workspace.
+// App/package lint rules live in each workspace's eslint.config.js.
+/** @type {import("eslint").Linter.Config} */
+module.exports = {
+  root: true,
+  ignorePatterns: [
+    "**/node_modules/**",
+    "**/.next/**",
+    "**/dist/**",
+    "**/.turbo/**",
+    "**/coverage/**",
+  ],
+}

package/templates/next-monorepo/.github/workflows/ci.yml

@@ -0,0 +1,76 @@
+name: CI
+
+on:
+  pull_request:
+  push:
+    branches:
+      - main
+
+jobs:
+  fast:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-node@v4
+        with:
+          node-version: 20
+      - uses: extractions/setup-just@v2
+      - uses: pnpm/action-setup@v4
+        with:
+          version: 9.15.9
+      - run: pnpm install --frozen-lockfile
+      - run: just lint
+      - run: just typecheck
+
+  test:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-node@v4
+        with:
+          node-version: 20
+      - uses: extractions/setup-just@v2
+      - uses: pnpm/action-setup@v4
+        with:
+          version: 9.15.9
+      - run: pnpm install --frozen-lockfile
+      - run: just test
+
+  ux:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-node@v4
+        with:
+          node-version: 20
+      - uses: extractions/setup-just@v2
+      - uses: pnpm/action-setup@v4
+        with:
+          version: 9.15.9
+      - run: pnpm install --frozen-lockfile
+      - run: pnpm exec playwright install --with-deps chromium
+      - run: just ux
+
+  supply-chain:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+      - uses: actions/setup-node@v4
+        with:
+          node-version: 20
+      - uses: actions/setup-go@v5
+        with:
+          go-version: "1.24"
+      - uses: pnpm/action-setup@v4
+        with:
+          version: 9.15.9
+      - run: pnpm install --frozen-lockfile
+      - run: go install github.com/google/osv-scanner/v2/cmd/osv-scanner@v2.3.5
+      - uses: gitleaks/gitleaks-action@v2
+        env:
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+          GITLEAKS_CONFIG: .gitleaks.toml
+      - run: $(go env GOPATH)/bin/osv-scanner scan source -r .
+      - run: pnpm audit --audit-level=high

package/templates/next-monorepo/.gitleaks.toml

@@ -0,0 +1,5 @@
+title = "next-monorepo gitleaks config"
+
+[extend]
+useDefault = true
+

package/templates/next-monorepo/.prettierignore

@@ -0,0 +1,7 @@
+dist/
+node_modules/
+.next/
+.turbo/
+coverage/
+pnpm-lock.yaml
+.pnpm-store/

package/templates/next-monorepo/.prettierrc

@@ -0,0 +1,11 @@
+{
+  "endOfLine": "lf",
+  "semi": false,
+  "singleQuote": false,
+  "tabWidth": 2,
+  "trailingComma": "es5",
+  "printWidth": 80,
+  "plugins": ["prettier-plugin-tailwindcss"],
+  "tailwindStylesheet": "packages/ui/src/styles/globals.css",
+  "tailwindFunctions": ["cn", "cva"]
+}

package/templates/next-monorepo/AGENTS.md

@@ -0,0 +1,35 @@
+# Project Context
+
+This file is a short table of contents for the template knowledge base.
+
+## Architecture
+
+System structure and enforced dependency layers: [ARCHITECTURE.md](ARCHITECTURE.md)
+
+## Design
+
+Design notes and core beliefs: [docs/DESIGN.md](docs/DESIGN.md), [docs/design-docs/index.md](docs/design-docs/index.md)
+
+## Frontend
+
+Frontend conventions, UI package structure, and shared component rules: [docs/FRONTEND.md](docs/FRONTEND.md)
+
+## Product
+
+Starter goals and onboarding expectations: [docs/PRODUCT_SENSE.md](docs/PRODUCT_SENSE.md), [docs/product-specs/index.md](docs/product-specs/index.md)
+
+## Plans
+
+Execution plans and tech debt tracking: [docs/PLANS.md](docs/PLANS.md), [docs/exec-plans/tech-debt-tracker.md](docs/exec-plans/tech-debt-tracker.md)
+
+## Reliability
+
+Build, test, CI, and operational expectations: [docs/RELIABILITY.md](docs/RELIABILITY.md)
+
+## Quality And Security
+
+Quality rubric and security posture: [docs/QUALITY_SCORE.md](docs/QUALITY_SCORE.md), [docs/SECURITY.md](docs/SECURITY.md)
+
+## References And Generated Artifacts
+
+Reference material and generated snapshots: [docs/references/design-system-reference-llms.txt](docs/references/design-system-reference-llms.txt), [docs/generated/db-schema.md](docs/generated/db-schema.md)

package/templates/next-monorepo/ARCHITECTURE.md

@@ -0,0 +1,67 @@
+# Architecture
+
+## Repository Shape
+
+- `apps/web`: the main Next.js application
+- `packages/ui`: the shared UI package used by the app
+- `packages/eslint-config`: shared lint config
+- `packages/typescript-config`: shared TypeScript config
+
+## Web App Layers
+
+`apps/web` uses `dependency-cruiser` to enforce a small app-level stack:
+
+- `app`
+- `components`
+- `hooks`
+- `lib`
+
+The important constraints are:
+
+- `components` must not import `app`
+- `hooks` may only import `lib`
+- `lib` stays leaf-like
+
+The rules live in `apps/web/dependency-cruiser.cjs` and run through `just lint`.
+
+## Shared UI Domain Stack
+
+`packages/ui` follows the business-domain stack:
+
+- `Types`
+- `Config`
+- `Repo`
+- `Service`
+- `Runtime`
+- `UI`
+
+In filesystem terms that is:
+
+- `src/types`
+- `src/config`
+- `src/repo`
+- `src/service`
+- `src/runtime`
+- `src/ui`
+
+Imports must only move forward through that chain.
+
+## Explicit Cross-Cutting Boundary
+
+Cross-cutting concerns do not enter the stack directly.
+They enter through:
+
+- `src/providers`
+
+Provider-only helper code lives in:
+
+- `src/utils`
+
+`src/providers` may support `src/service` and `src/ui`.
+`src/utils` is reserved for provider support and must not depend on domain code.
+
+The rules live in `packages/ui/dependency-cruiser.cjs` and run through `just lint`.
+
+## No Backend By Default
+
+This template does not include a separate API server or database by default.

package/templates/next-monorepo/README.md

@@ -0,0 +1,45 @@
+# Next.js Monorepo Template
+
+This template ships a README-aligned harness for `apps/web`.
+
+## Harness Commands
+
+Run all top-level checks from the template root:
+
+```bash
+just install
+just lint
+just typecheck
+just test
+just ux
+just supply-chain
+just ci
+```
+
+`packages/ui` is still generated and updated through `shadcn` commands, but its internal layer boundaries are checked as part of the harness.
+
+## What Each Lane Covers
+
+- `just lint`: Biome, dependency-cruiser, and knip for `apps/web`; dependency-cruiser layer checks for `packages/ui`
+- `just typecheck`: `tsc --noEmit` for `apps/web`
+- `just test`: Vitest smoke coverage for `apps/web`
+- `just ux`: Playwright, axe, and Lighthouse against the running Next.js app
+- `just supply-chain`: gitleaks, osv-scanner, and `pnpm audit`
+
+## Adding Components
+
+To add components to your app, run the following command at the root of your `web` app:
+
+```bash
+pnpm dlx shadcn@latest add button -c apps/web
+```
+
+This places generated UI components in `packages/ui/src/ui`.
+
+## Using Components
+
+Import shared components from the `ui` package.
+
+```tsx
+import { Button } from "@workspace/ui/ui/button"
+```

package/templates/next-monorepo/apps/web/app/layout.tsx

@@ -0,0 +1,43 @@
+import type { Metadata } from "next"
+import { Geist_Mono, Inter } from "next/font/google"
+
+import "@workspace/ui/globals.css"
+import { ThemeProvider } from "@/components/theme-provider"
+import { cn } from "@workspace/ui/runtime/utils"
+
+const inter = Inter({
+  subsets: ["latin"],
+  variable: "--font-sans",
+})
+
+const fontMono = Geist_Mono({
+  subsets: ["latin"],
+  variable: "--font-mono",
+})
+
+export const metadata: Metadata = {
+  title: "Project ready",
+}
+
+export default function RootLayout({
+  children,
+}: Readonly<{
+  children: React.ReactNode
+}>) {
+  return (
+    <html
+      lang="en"
+      suppressHydrationWarning
+      className={cn(
+        "antialiased",
+        fontMono.variable,
+        "font-sans",
+        inter.variable,
+      )}
+    >
+      <body>
+        <ThemeProvider>{children}</ThemeProvider>
+      </body>
+    </html>
+  )
+}

package/templates/next-monorepo/apps/web/app/page.tsx

@@ -0,0 +1,19 @@
+import { Button } from "@workspace/ui/ui/button"
+
+export default function Page() {
+  return (
+    <main className="flex min-h-svh p-6">
+      <div className="flex max-w-md min-w-0 flex-col gap-4 text-sm leading-loose">
+        <section>
+          <h1 className="font-medium">Project ready!</h1>
+          <p>You may now add components and start building.</p>
+          <p>We&apos;ve already added the button component for you.</p>
+          <Button className="mt-2">Button</Button>
+        </section>
+        <div className="text-muted-foreground font-mono text-xs">
+          (Press <kbd>d</kbd> to toggle dark mode)
+        </div>
+      </div>
+    </main>
+  )
+}

package/templates/next-monorepo/apps/web/biome.json

@@ -0,0 +1,16 @@
+{
+  "$schema": "https://biomejs.dev/schemas/1.9.4/schema.json",
+  "formatter": {
+    "enabled": true,
+    "indentStyle": "space"
+  },
+  "linter": {
+    "enabled": true
+  },
+  "javascript": {
+    "formatter": {
+      "quoteStyle": "double",
+      "semicolons": "asNeeded"
+    }
+  }
+}

package/templates/next-monorepo/apps/web/components/theme-provider.tsx

@@ -0,0 +1,71 @@
+"use client"
+
+import { ThemeProvider as NextThemesProvider, useTheme } from "next-themes"
+import * as React from "react"
+
+function ThemeProvider({
+  children,
+  ...props
+}: React.ComponentProps<typeof NextThemesProvider>) {
+  return (
+    <NextThemesProvider
+      attribute="class"
+      defaultTheme="system"
+      enableSystem
+      disableTransitionOnChange
+      {...props}
+    >
+      <ThemeHotkey />
+      {children}
+    </NextThemesProvider>
+  )
+}
+
+function isTypingTarget(target: EventTarget | null) {
+  if (!(target instanceof HTMLElement)) {
+    return false
+  }
+
+  return (
+    target.isContentEditable ||
+    target.tagName === "INPUT" ||
+    target.tagName === "TEXTAREA" ||
+    target.tagName === "SELECT"
+  )
+}
+
+function ThemeHotkey() {
+  const { resolvedTheme, setTheme } = useTheme()
+
+  React.useEffect(() => {
+    function onKeyDown(event: KeyboardEvent) {
+      if (event.defaultPrevented || event.repeat) {
+        return
+      }
+
+      if (event.metaKey || event.ctrlKey || event.altKey) {
+        return
+      }
+
+      if (event.key.toLowerCase() !== "d") {
+        return
+      }
+
+      if (isTypingTarget(event.target)) {
+        return
+      }
+
+      setTheme(resolvedTheme === "dark" ? "light" : "dark")
+    }
+
+    window.addEventListener("keydown", onKeyDown)
+
+    return () => {
+      window.removeEventListener("keydown", onKeyDown)
+    }
+  }, [resolvedTheme, setTheme])
+
+  return null
+}
+
+export { ThemeProvider }

package/templates/next-monorepo/apps/web/components.json

@@ -0,0 +1,23 @@
+{
+  "$schema": "https://ui.shadcn.com/schema.json",
+  "style": "radix-lyra",
+  "rsc": true,
+  "tsx": true,
+  "tailwind": {
+    "config": "",
+    "css": "../../packages/ui/src/styles/globals.css",
+    "baseColor": "neutral",
+    "cssVariables": true
+  },
+  "iconLibrary": "lucide",
+  "aliases": {
+    "components": "@/components",
+    "hooks": "@/hooks",
+    "lib": "@/lib",
+    "utils": "@workspace/ui/runtime/utils",
+    "ui": "@workspace/ui/ui"
+  },
+  "rtl": true,
+  "menuColor": "default",
+  "menuAccent": "subtle"
+}

package/templates/next-monorepo/apps/web/dependency-cruiser.cjs

@@ -0,0 +1,66 @@
+/** @type {import("dependency-cruiser").IConfiguration} */
+module.exports = {
+  forbidden: [
+    {
+      name: "no-circular",
+      severity: "error",
+      from: {},
+      to: {
+        circular: true,
+      },
+    },
+    {
+      name: "app-does-not-import-upwards",
+      severity: "error",
+      from: {
+        path: "^app/",
+      },
+      to: {
+        path: "^(?!app/|components/|hooks/|lib/)",
+        dependencyTypesNot: ["npm", "npm-dev", "core"],
+      },
+    },
+    {
+      name: "components-do-not-import-app",
+      severity: "error",
+      from: {
+        path: "^components/",
+      },
+      to: {
+        path: "^(app/|(?!(components/|hooks/|lib/)).+)",
+        dependencyTypesNot: ["npm", "npm-dev", "core"],
+      },
+    },
+    {
+      name: "hooks-only-import-lib",
+      severity: "error",
+      from: {
+        path: "^hooks/",
+      },
+      to: {
+        path: "^(app/|components/|hooks/|(?!(lib/)).+)",
+        dependencyTypesNot: ["npm", "npm-dev", "core"],
+      },
+    },
+    {
+      name: "lib-does-not-import-upwards",
+      severity: "error",
+      from: {
+        path: "^lib/",
+      },
+      to: {
+        path: "^(app/|components/|hooks/|(?!(lib/)).+)",
+        dependencyTypesNot: ["npm", "npm-dev", "core"],
+      },
+    },
+  ],
+  options: {
+    doNotFollow: {
+      path: "node_modules",
+    },
+    includeOnly: "^(app|components|hooks|lib)",
+    tsConfig: {
+      fileName: "tsconfig.json",
+    },
+  },
+}

package/templates/next-monorepo/apps/web/eslint.config.js

@@ -0,0 +1,4 @@
+import { nextJsConfig } from "@workspace/eslint-config/next-js"
+
+/** @type {import("eslint").Linter.Config} */
+export default nextJsConfig

package/templates/next-monorepo/apps/web/knip.json

@@ -0,0 +1,17 @@
+{
+  "$schema": "https://unpkg.com/knip@5/schema.json",
+  "entry": [
+    "app/page.tsx",
+    "components/theme-provider.tsx",
+    "next.config.mjs",
+    "postcss.config.mjs",
+    "playwright.config.ts",
+    "vitest.config.ts"
+  ],
+  "project": [
+    "app/**/*.{ts,tsx}",
+    "components/**/*.{ts,tsx}",
+    "tests/**/*.{ts,tsx}"
+  ],
+  "ignoreDependencies": ["@workspace/ui", "@tailwindcss/postcss"]
+}

package/templates/next-monorepo/apps/web/lighthouserc.json

@@ -0,0 +1,23 @@
+{
+  "ci": {
+    "collect": {
+      "numberOfRuns": 1,
+      "url": ["http://127.0.0.1:3000/"],
+      "settings": {
+        "preset": "desktop",
+        "chromeFlags": "--headless --no-sandbox"
+      }
+    },
+    "assert": {
+      "assertions": {
+        "categories:accessibility": ["error", { "minScore": 0.9 }],
+        "categories:best-practices": ["error", { "minScore": 0.9 }],
+        "categories:performance": ["warn", { "minScore": 0.6 }],
+        "categories:seo": "off"
+      }
+    },
+    "upload": {
+      "target": "temporary-public-storage"
+    }
+  }
+}

package/templates/next-monorepo/apps/web/next-env.d.ts

@@ -0,0 +1,6 @@
+/// <reference types="next" />
+/// <reference types="next/image-types/global" />
+import "./.next/dev/types/routes.d.ts"
+
+// NOTE: This file should not be edited
+// see https://nextjs.org/docs/app/api-reference/config/typescript for more information.

package/templates/next-monorepo/apps/web/next.config.mjs

@@ -0,0 +1,6 @@
+/** @type {import('next').NextConfig} */
+const nextConfig = {
+  transpilePackages: ["@workspace/ui"],
+}
+
+export default nextConfig

package/templates/next-monorepo/apps/web/package.json

@@ -0,0 +1,46 @@
+{
+  "name": "web",
+  "version": "0.0.1",
+  "type": "module",
+  "private": true,
+  "scripts": {
+    "dev": "next dev --turbopack",
+    "build": "next build",
+    "start": "next start",
+    "lint": "biome check . && depcruise --config dependency-cruiser.cjs . && knip --config knip.json --no-config-hints",
+    "format": "biome format --write .",
+    "typecheck": "tsc --noEmit",
+    "test": "vitest run --config vitest.config.ts",
+    "test:e2e": "playwright test",
+    "lighthouse": "lhci autorun --config ./lighthouserc.json",
+    "ux": "start-server-and-test \"pnpm dev\" http://127.0.0.1:3000 \"pnpm test:e2e && pnpm lighthouse\""
+  },
+  "dependencies": {
+    "@workspace/ui": "workspace:*",
+    "next": "16.1.6",
+    "next-themes": "^0.4.6",
+    "react": "^19.2.4",
+    "react-dom": "^19.2.4"
+  },
+  "devDependencies": {
+    "@axe-core/playwright": "^4.11.0",
+    "@biomejs/biome": "^1.9.4",
+    "@lhci/cli": "^0.15.1",
+    "@playwright/test": "^1.51.1",
+    "@tailwindcss/postcss": "^4.1.18",
+    "@testing-library/jest-dom": "^6.8.0",
+    "@testing-library/react": "^16.3.0",
+    "@vitejs/plugin-react": "^5.0.4",
+    "@types/node": "^25.1.0",
+    "@types/react": "^19.2.10",
+    "@types/react-dom": "^19.2.3",
+    "@workspace/typescript-config": "workspace:*",
+    "dependency-cruiser": "^17.1.0",
+    "jsdom": "^26.1.0",
+    "knip": "^5.44.4",
+    "start-server-and-test": "^3.0.2",
+    "typescript": "^5.9.3",
+    "vite-tsconfig-paths": "^5.1.4",
+    "vitest": "^3.2.4"
+  }
+}