dk-harness 0.1.0

package/templates/next-fastapi-monorepo/docs/design-docs/included-skills.md

@@ -0,0 +1,13 @@
+# Included Skills
+
+The web app ships with design and frontend reference skills in `apps/web/skills-lock.json`.
+
+- `frontend-design`
+- `shadcn`
+- `vercel-composition-patterns`
+- `vercel-react-best-practices`
+- `vercel-react-native-skills`
+- `vercel-react-view-transitions`
+- `web-design-guidelines`
+
+Treat these as scaffolded defaults for UI and interaction work.

package/templates/next-fastapi-monorepo/docs/design-docs/index.md

@@ -0,0 +1,6 @@
+# Design Docs Index
+
+- [Core Beliefs](./core-beliefs.md)
+- [Included Skills](./included-skills.md)
+
+Add new design notes here when the frontend or developer experience changes materially.

package/templates/next-fastapi-monorepo/docs/exec-plans/active/.gitkeep

@@ -0,0 +1 @@
+

package/templates/next-fastapi-monorepo/docs/exec-plans/completed/.gitkeep

@@ -0,0 +1 @@
+

package/templates/next-fastapi-monorepo/docs/exec-plans/repeated-work.md

@@ -0,0 +1,15 @@
+# Repeated Work
+
+## Doc Gardening
+
+The knowledge base needs periodic manual gardening.
+
+Repeat this work when template behavior, architecture rules, onboarding flow, or public commands change:
+
+- review `AGENTS.md` and `ARCHITECTURE.md`
+- review `docs/design-docs/`, `docs/product-specs/`, and `docs/references/`
+- move stale execution plans from `active/` to `completed/`
+- update `tech-debt-tracker.md` when cleanup work is discovered
+- remove outdated or irrelevant references that no longer match the stack
+
+This work is intentionally documented here rather than automated in CI.

package/templates/next-fastapi-monorepo/docs/exec-plans/tech-debt-tracker.md

@@ -0,0 +1,3 @@
+# Tech Debt Tracker
+
+This document should contain active cleanup items, follow-up work, and known template debt.

package/templates/next-fastapi-monorepo/docs/generated/db-schema.md

@@ -0,0 +1,3 @@
+# DB Schema
+
+This document should contain the current database schema snapshot when the template adds persistence.

package/templates/next-fastapi-monorepo/docs/product-specs/index.md

@@ -0,0 +1,5 @@
+# Product Specs Index
+
+- [New User Onboarding](./new-user-onboarding.md)
+
+Add product-specific specs here when the starter grows beyond the baseline onboarding flow.

package/templates/next-fastapi-monorepo/docs/product-specs/new-user-onboarding.md

@@ -0,0 +1,12 @@
+# New User Onboarding
+
+## Goal
+
+A freshly scaffolded project should prove both the web app and FastAPI service are wired correctly with minimal setup.
+
+## Default Experience
+
+- the home page renders immediately
+- the shared button component is already usable
+- the API exposes a minimal JSON health surface
+- the next customization step is obvious

package/templates/next-fastapi-monorepo/docs/references/design-system-reference-llms.txt

@@ -0,0 +1,13 @@
+This reference should contain only design-system facts for the shared UI package.
+
+Current baseline:
+- UI system: `shadcn`
+- style preset: `radix-lyra`
+- Tailwind base color: `neutral`
+- CSS variables: enabled
+- icon library: `lucide`
+- theme tokens live in `packages/ui/src/styles/globals.css`
+- the starter includes light and dark theme tokens using OKLCH color values
+- the radius scale is derived from `--radius: 0.625rem`
+
+Update this file when the component style, token set, icon set, or theming rules change.

package/templates/next-fastapi-monorepo/docs/references/uv-llms.txt

@@ -0,0 +1,7 @@
+uv is part of this starter.
+
+Use uv for:
+- syncing the API environment
+- running lint, typecheck, test, and supply-chain commands inside `apps/api`
+
+Keep the exact uv workflow documented here if the Python toolchain changes.

package/templates/next-fastapi-monorepo/justfile

@@ -0,0 +1,31 @@
+set shell := ["bash", "-cu"]
+
+install:
+  mise install
+  pnpm install --frozen-lockfile
+  (cd apps/api && uv sync --group dev)
+  pnpm exec playwright install chromium
+
+lint:
+  pnpm --filter web lint
+  pnpm --dir packages/ui exec depcruise --config dependency-cruiser.cjs src
+  pnpm --filter api lint
+
+typecheck:
+  pnpm --filter web typecheck
+  pnpm --filter api typecheck
+
+test:
+  pnpm --filter web test
+  pnpm --filter api test
+
+ux:
+  pnpm --filter web ux
+
+supply-chain:
+  gitleaks dir . --config .gitleaks.toml
+  osv-scanner scan source -r .
+  pnpm audit --audit-level=high
+  pnpm --filter api supply-chain
+
+ci: lint typecheck test ux supply-chain

package/templates/next-fastapi-monorepo/lefthook.yml

@@ -0,0 +1,8 @@
+pre-commit:
+  parallel: true
+  commands:
+    lint:
+      run: just lint
+    typecheck:
+      run: just typecheck
+

package/templates/next-fastapi-monorepo/mise.toml

@@ -0,0 +1,6 @@
+[tools]
+node = "20"
+pnpm = "9.15.9"
+python = "3.11"
+uv = "latest"
+

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

@@ -0,0 +1,41 @@
+{
+  "name": "next-fastapi-monorepo",
+  "version": "0.0.1",
+  "private": true,
+  "scripts": {
+    "build": "turbo build",
+    "dev": "turbo dev --filter=web --filter=api",
+    "lint": "just lint",
+    "format": "pnpm --filter web format",
+    "typecheck": "just typecheck",
+    "test": "just test",
+    "ux": "just ux",
+    "supply-chain": "just supply-chain",
+    "ci": "just ci"
+  },
+  "devDependencies": {
+    "@axe-core/playwright": "^4.11.0",
+    "@biomejs/biome": "^1.9.4",
+    "@lhci/cli": "^0.15.1",
+    "@playwright/test": "^1.51.1",
+    "@testing-library/jest-dom": "^6.8.0",
+    "@testing-library/react": "^16.3.0",
+    "@vitejs/plugin-react": "^5.0.4",
+    "@workspace/eslint-config": "workspace:*",
+    "@workspace/typescript-config": "workspace:*",
+    "dependency-cruiser": "^17.1.0",
+    "jsdom": "^26.1.0",
+    "knip": "^5.44.4",
+    "prettier": "^3.8.1",
+    "prettier-plugin-tailwindcss": "^0.7.2",
+    "start-server-and-test": "^3.0.2",
+    "turbo": "^2.8.17",
+    "typescript": "5.9.3",
+    "vite-tsconfig-paths": "^5.1.4",
+    "vitest": "^3.2.4"
+  },
+  "packageManager": "pnpm@9.15.9",
+  "engines": {
+    "node": ">=20"
+  }
+}

package/templates/next-fastapi-monorepo/packages/eslint-config/README.md

@@ -0,0 +1,3 @@
+# `@workspace/eslint-config`
+
+Shared eslint configuration for the workspace.

package/templates/next-fastapi-monorepo/packages/eslint-config/base.js

@@ -0,0 +1,32 @@
+import js from "@eslint/js"
+import eslintConfigPrettier from "eslint-config-prettier"
+import onlyWarn from "eslint-plugin-only-warn"
+import turboPlugin from "eslint-plugin-turbo"
+import tseslint from "typescript-eslint"
+
+/**
+ * A shared ESLint configuration for the repository.
+ *
+ * @type {import("eslint").Linter.Config}
+ * */
+export const config = [
+  js.configs.recommended,
+  eslintConfigPrettier,
+  ...tseslint.configs.recommended,
+  {
+    plugins: {
+      turbo: turboPlugin,
+    },
+    rules: {
+      "turbo/no-undeclared-env-vars": "warn",
+    },
+  },
+  {
+    plugins: {
+      onlyWarn,
+    },
+  },
+  {
+    ignores: ["dist/**", ".next/**", "**/.turbo/**", "**/coverage/**"],
+  },
+]

package/templates/next-fastapi-monorepo/packages/eslint-config/next.js

@@ -0,0 +1,51 @@
+import js from "@eslint/js"
+import pluginNext from "@next/eslint-plugin-next"
+import eslintConfigPrettier from "eslint-config-prettier"
+import pluginReact from "eslint-plugin-react"
+import pluginReactHooks from "eslint-plugin-react-hooks"
+import globals from "globals"
+import tseslint from "typescript-eslint"
+
+import { config as baseConfig } from "./base.js"
+
+/**
+ * A custom ESLint configuration for libraries that use Next.js.
+ *
+ * @type {import("eslint").Linter.Config}
+ * */
+export const nextJsConfig = [
+  ...baseConfig,
+  js.configs.recommended,
+  eslintConfigPrettier,
+  ...tseslint.configs.recommended,
+  {
+    ...pluginReact.configs.flat.recommended,
+    languageOptions: {
+      ...pluginReact.configs.flat.recommended.languageOptions,
+      globals: {
+        ...globals.serviceworker,
+      },
+    },
+  },
+  {
+    plugins: {
+      "@next/next": pluginNext,
+    },
+    rules: {
+      ...pluginNext.configs.recommended.rules,
+      ...pluginNext.configs["core-web-vitals"].rules,
+    },
+  },
+  {
+    plugins: {
+      "react-hooks": pluginReactHooks,
+    },
+    settings: { react: { version: "detect" } },
+    rules: {
+      ...pluginReactHooks.configs.recommended.rules,
+      // React scope no longer necessary with new JSX transform.
+      "react/react-in-jsx-scope": "off",
+      "react/prop-types": "off",
+    },
+  },
+]

package/templates/next-fastapi-monorepo/packages/eslint-config/package.json

@@ -0,0 +1,26 @@
+{
+  "name": "@workspace/eslint-config",
+  "version": "0.0.0",
+  "type": "module",
+  "private": true,
+  "exports": {
+    "./base": "./base.js",
+    "./next-js": "./next.js",
+    "./react-internal": "./react-internal.js"
+  },
+  "devDependencies": {
+    "@eslint/js": "^9.39.2",
+    "@next/eslint-plugin-next": "^16.1.6",
+    "@typescript-eslint/eslint-plugin": "^8.54.0",
+    "@typescript-eslint/parser": "^8.54.0",
+    "eslint": "^9.39.2",
+    "eslint-config-prettier": "^10.1.8",
+    "eslint-plugin-only-warn": "^1.1.0",
+    "eslint-plugin-react": "^7.37.5",
+    "eslint-plugin-react-hooks": "^7.0.1",
+    "eslint-plugin-turbo": "^2.8.1",
+    "globals": "^17.2.0",
+    "typescript": "^5.9.3",
+    "typescript-eslint": "^8.54.0"
+  }
+}

package/templates/next-fastapi-monorepo/packages/eslint-config/react-internal.js

@@ -0,0 +1,41 @@
+import js from "@eslint/js"
+import eslintConfigPrettier from "eslint-config-prettier"
+import pluginReact from "eslint-plugin-react"
+import pluginReactHooks from "eslint-plugin-react-hooks"
+import globals from "globals"
+import tseslint from "typescript-eslint"
+
+import { config as baseConfig } from "./base.js"
+
+/**
+ * A custom ESLint configuration for libraries that use React.
+ *
+ * @type {import("eslint").Linter.Config} */
+export const config = [
+  ...baseConfig,
+  js.configs.recommended,
+  eslintConfigPrettier,
+  ...tseslint.configs.recommended,
+  pluginReact.configs.flat.recommended,
+  {
+    languageOptions: {
+      ...pluginReact.configs.flat.recommended.languageOptions,
+      globals: {
+        ...globals.serviceworker,
+        ...globals.browser,
+      },
+    },
+  },
+  {
+    plugins: {
+      "react-hooks": pluginReactHooks,
+    },
+    settings: { react: { version: "detect" } },
+    rules: {
+      ...pluginReactHooks.configs.recommended.rules,
+      // React scope no longer necessary with new JSX transform.
+      "react/react-in-jsx-scope": "off",
+      "react/prop-types": "off",
+    },
+  },
+]

package/templates/next-fastapi-monorepo/packages/typescript-config/README.md

@@ -0,0 +1,3 @@
+# `@workspace/typescript-config`
+
+Shared typescript configuration for the workspace.

package/templates/next-fastapi-monorepo/packages/typescript-config/base.json

@@ -0,0 +1,20 @@
+{
+  "$schema": "https://json.schemastore.org/tsconfig",
+  "display": "Default",
+  "compilerOptions": {
+    "declaration": true,
+    "declarationMap": true,
+    "esModuleInterop": true,
+    "incremental": false,
+    "isolatedModules": true,
+    "lib": ["es2022", "DOM", "DOM.Iterable"],
+    "module": "NodeNext",
+    "moduleDetection": "force",
+    "moduleResolution": "NodeNext",
+    "noUncheckedIndexedAccess": true,
+    "resolveJsonModule": true,
+    "skipLibCheck": true,
+    "strict": true,
+    "target": "ES2022"
+  }
+}

package/templates/next-fastapi-monorepo/packages/typescript-config/nextjs.json

@@ -0,0 +1,13 @@
+{
+  "$schema": "https://json.schemastore.org/tsconfig",
+  "display": "Next.js",
+  "extends": "./base.json",
+  "compilerOptions": {
+    "plugins": [{ "name": "next" }],
+    "module": "ESNext",
+    "moduleResolution": "Bundler",
+    "allowJs": true,
+    "jsx": "preserve",
+    "noEmit": true
+  }
+}

package/templates/next-fastapi-monorepo/packages/typescript-config/package.json

@@ -0,0 +1,9 @@
+{
+  "name": "@workspace/typescript-config",
+  "version": "0.0.0",
+  "private": true,
+  "license": "PROPRIETARY",
+  "publishConfig": {
+    "access": "public"
+  }
+}

package/templates/next-fastapi-monorepo/packages/typescript-config/react-library.json

@@ -0,0 +1,8 @@
+{
+  "$schema": "https://json.schemastore.org/tsconfig",
+  "display": "React Library",
+  "extends": "./base.json",
+  "compilerOptions": {
+    "jsx": "react-jsx",
+  }
+}

package/templates/next-fastapi-monorepo/packages/ui/components.json

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

package/templates/next-fastapi-monorepo/packages/ui/dependency-cruiser.cjs

@@ -0,0 +1,100 @@
+/** @type {import("dependency-cruiser").IConfiguration} */
+module.exports = {
+  forbidden: [
+    {
+      name: "no-circular",
+      severity: "error",
+      from: {},
+      to: {
+        circular: true,
+      },
+    },
+    {
+      name: "types-do-not-import-upwards",
+      severity: "error",
+      from: {
+        path: "^src/types/",
+      },
+      to: {
+        path: "^src/(config|repo|service|runtime|providers|ui|utils)/",
+        dependencyTypesNot: ["npm", "npm-dev", "core"],
+      },
+    },
+    {
+      name: "config-does-not-import-upwards",
+      severity: "error",
+      from: {
+        path: "^src/config/",
+      },
+      to: {
+        path: "^src/(repo|service|runtime|providers|ui|utils)/",
+        dependencyTypesNot: ["npm", "npm-dev", "core"],
+      },
+    },
+    {
+      name: "repo-does-not-import-upwards",
+      severity: "error",
+      from: {
+        path: "^src/repo/",
+      },
+      to: {
+        path: "^src/(service|runtime|providers|ui|utils)/",
+        dependencyTypesNot: ["npm", "npm-dev", "core"],
+      },
+    },
+    {
+      name: "service-does-not-import-upwards",
+      severity: "error",
+      from: {
+        path: "^src/service/",
+      },
+      to: {
+        path: "^src/(runtime|ui|utils)/",
+        dependencyTypesNot: ["npm", "npm-dev", "core"],
+      },
+    },
+    {
+      name: "runtime-does-not-import-ui",
+      severity: "error",
+      from: {
+        path: "^src/runtime/",
+      },
+      to: {
+        path: "^src/(providers|ui|utils)/",
+        dependencyTypesNot: ["npm", "npm-dev", "core"],
+      },
+    },
+    {
+      name: "providers-only-import-types-and-utils",
+      severity: "error",
+      from: {
+        path: "^src/providers/",
+      },
+      to: {
+        path: "^src/(config|repo|service|runtime|ui)/",
+        dependencyTypesNot: ["npm", "npm-dev", "core"],
+      },
+    },
+    {
+      name: "utils-do-not-import-domain",
+      severity: "error",
+      from: {
+        path: "^src/utils/",
+      },
+      to: {
+        path: "^src/(types|config|repo|service|runtime|providers|ui)/",
+        dependencyTypesNot: ["npm", "npm-dev", "core"],
+      },
+    },
+  ],
+  options: {
+    doNotFollow: {
+      path: "node_modules",
+    },
+    includeOnly:
+      "^(src/types|src/config|src/repo|src/service|src/runtime|src/providers|src/ui|src/utils)",
+    tsConfig: {
+      fileName: "tsconfig.json",
+    },
+  },
+}

package/templates/next-fastapi-monorepo/packages/ui/eslint.config.js

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

package/templates/next-fastapi-monorepo/packages/ui/package.json

@@ -0,0 +1,49 @@
+{
+  "name": "@workspace/ui",
+  "version": "0.0.0",
+  "type": "module",
+  "private": true,
+  "scripts": {
+    "lint": "eslint",
+    "format": "prettier --write \"**/*.{ts,tsx}\"",
+    "typecheck": "tsc --noEmit"
+  },
+  "dependencies": {
+    "class-variance-authority": "^0.7.1",
+    "clsx": "^2.1.1",
+    "lucide-react": "^1.8.0",
+    "next-themes": "^0.4.6",
+    "radix-ui": "^1.4.3",
+    "react": "^19.2.4",
+    "react-dom": "^19.2.4",
+    "shadcn": "^4.2.0",
+    "tailwind-merge": "^3.5.0",
+    "tw-animate-css": "^1.4.0",
+    "zod": "^3.25.76"
+  },
+  "devDependencies": {
+    "@tailwindcss/postcss": "^4.1.18",
+    "@turbo/gen": "^2.8.1",
+    "@types/node": "^25.1.0",
+    "@types/react": "^19.2.10",
+    "@types/react-dom": "^19.2.3",
+    "@workspace/eslint-config": "workspace:*",
+    "@workspace/typescript-config": "workspace:*",
+    "eslint": "^9.39.2",
+    "tailwindcss": "^4.1.18",
+    "typescript": "^5.9.3"
+  },
+  "exports": {
+    "./globals.css": "./src/styles/globals.css",
+    "./postcss.config": "./postcss.config.mjs",
+    "./types/*": "./src/types/*.ts",
+    "./config/*": "./src/config/*.ts",
+    "./repo/*": "./src/repo/*.ts",
+    "./service/*": "./src/service/*.ts",
+    "./runtime/*": "./src/runtime/*.ts",
+    "./runtime/hooks/*": "./src/runtime/hooks/*.ts",
+    "./providers/*": "./src/providers/*.ts",
+    "./utils/*": "./src/utils/*.ts",
+    "./ui/*": "./src/ui/*.tsx"
+  }
+}

package/templates/next-fastapi-monorepo/packages/ui/postcss.config.mjs

@@ -0,0 +1,6 @@
+/** @type {import('postcss-load-config').Config} */
+const config = {
+    plugins: { "@tailwindcss/postcss": {} },
+};
+
+export default config;

package/templates/next-fastapi-monorepo/packages/ui/src/config/.gitkeep

@@ -0,0 +1 @@
+

package/templates/next-fastapi-monorepo/packages/ui/src/providers/.gitkeep

@@ -0,0 +1 @@
+

package/templates/next-fastapi-monorepo/packages/ui/src/repo/.gitkeep

@@ -0,0 +1 @@
+

package/templates/next-fastapi-monorepo/packages/ui/src/runtime/hooks/.gitkeep

@@ -0,0 +1 @@
+

package/templates/next-fastapi-monorepo/packages/ui/src/runtime/utils.ts

@@ -0,0 +1,6 @@
+import { clsx, type ClassValue } from "clsx"
+import { twMerge } from "tailwind-merge"
+
+export function cn(...inputs: ClassValue[]) {
+  return twMerge(clsx(inputs))
+}

package/templates/next-fastapi-monorepo/packages/ui/src/service/.gitkeep

@@ -0,0 +1 @@
+