dk-harness 0.1.0

package/templates/next-axum-monorepo/docs/FRONTEND.md

@@ -0,0 +1,26 @@
+# Frontend
+
+## Scope
+
+Frontend work lives in `apps/web` and `packages/ui`.
+Backend work lives separately in `apps/axum`.
+
+## Shared UI Package
+
+Use these public paths from `@workspace/ui`:
+
+- `@workspace/ui/ui/*`
+- `@workspace/ui/runtime/*`
+- `@workspace/ui/providers/*`
+
+Keep shared UI work aligned with the enforced stack and do not reintroduce the old `components/hooks/lib` package layers.
+
+## Component Workflow
+
+Add shared primitives with:
+
+```bash
+pnpm dlx shadcn@latest add button -c apps/web
+```
+
+Generated shared components should land in `packages/ui/src/ui`.

package/templates/next-axum-monorepo/docs/PLANS.md

@@ -0,0 +1,25 @@
+# Plans
+
+Plans are first-class artifacts in this template.
+
+## Planning Model
+
+- small, transient work may use a short local plan without a committed plan file
+- complex or multi-step work should create an execution plan in `docs/exec-plans/active/`
+- finished execution plans move to `docs/exec-plans/completed/`
+- known cleanup and follow-up items live in `docs/exec-plans/tech-debt-tracker.md`
+- repeated operational work belongs in `docs/exec-plans/repeated-work.md`
+
+## Required Sections For Execution Plans
+
+Every execution plan in `active/` or `completed/` should include:
+
+- `## Status`
+- `## Scope`
+- `## Steps`
+- `## Progress Log`
+- `## Decision Log`
+
+## Operating Rule
+
+Execution plans, completed plans, and tech debt are all versioned and stored in the repository so agents can work without hidden external context.

package/templates/next-axum-monorepo/docs/PRODUCT_SENSE.md

@@ -0,0 +1,11 @@
+# Product Sense
+
+This starter is optimized for teams that want a Next.js frontend and a Rust service with clear boundaries from day one.
+
+The default experience should communicate:
+
+- the frontend is ready immediately
+- the backend has a minimal health surface
+- architecture boundaries are not optional
+
+Detailed specs live in `product-specs/`.

package/templates/next-axum-monorepo/docs/QUALITY_SCORE.md

@@ -0,0 +1,16 @@
+# Quality Score
+
+Use this rubric when reviewing the starter or changes to it.
+
+## High Quality Means
+
+- frontend and backend layer rules are mechanically enforced
+- shared UI imports are obvious
+- Rust startup and service logic stay separated
+- docs match the actual command surface
+
+## Red Flags
+
+- UI code bypassing `providers`
+- backend logic drifting into `main.rs`
+- docs that lag behind the template

package/templates/next-axum-monorepo/docs/RELIABILITY.md

@@ -0,0 +1,39 @@
+# Reliability
+
+## Local Commands
+
+Run from the repository root unless noted otherwise:
+
+```bash
+just install
+pnpm dev
+just lint
+just typecheck
+just test
+just ux
+just supply-chain
+just ci
+```
+
+Run the Rust service directly when needed:
+
+```bash
+cd apps/axum
+cargo run
+```
+
+## Lane Responsibilities
+
+- `just lint`: web lint, shared UI layer checks, Rust layer check, `cargo fmt`, `clippy`, and `cargo udeps`
+- `just typecheck`: Next.js typecheck plus `cargo check --all-targets`
+- `just test`: Vitest plus `cargo nextest run`
+- `just ux`: Playwright, axe, and Lighthouse for the web app
+- `just supply-chain`: gitleaks, osv-scanner, `pnpm audit`, `cargo deny`, and `cargo audit`
+
+## CI
+
+GitHub Actions runs the build and test lanes defined in `.github/workflows/ci.yml`.
+
+## Doc Gardening
+
+Doc gardening is a repeated manual task tracked in `docs/exec-plans/repeated-work.md`.

package/templates/next-axum-monorepo/docs/SECURITY.md

@@ -0,0 +1,16 @@
+# Security
+
+This starter includes basic Node and Rust supply-chain checks.
+
+## Included Checks
+
+- `gitleaks`
+- `osv-scanner`
+- `pnpm audit`
+- `cargo deny`
+- `cargo audit`
+
+## Expectations
+
+- do not commit secrets
+- keep Rust and Node dependencies current

package/templates/next-axum-monorepo/docs/design-docs/core-beliefs.md

@@ -0,0 +1,6 @@
+# Core Beliefs
+
+- the starter should feel production-minded without feeling heavy
+- frontend and backend boundaries should be explicit from the first commit
+- Rust service code should stay small, direct, and layered
+- shared UI should remain easy to extend safely

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

@@ -0,0 +1,16 @@
+# Included Skills
+
+The web app ships with design and frontend reference skills in `apps/web/skills-lock.json`.
+
+- `frontend-design`
+- `shadcn`
+
+The workspace also includes additional reference skills in `skills-lock.json`.
+
+- `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-axum-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-axum-monorepo/docs/exec-plans/active/.gitkeep

@@ -0,0 +1 @@
+

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

@@ -0,0 +1 @@
+

package/templates/next-axum-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-axum-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-axum-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-axum-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-axum-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 Rust service are wired correctly with minimal setup.
+
+## Default Experience
+
+- the home page renders immediately
+- the shared button component is already usable
+- the Rust service exposes a small health surface
+- the next customization step is obvious

package/templates/next-axum-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-axum-monorepo/justfile

@@ -0,0 +1,36 @@
+set shell := ["bash", "-cu"]
+
+install:
+  mise install
+  pnpm install --frozen-lockfile
+  rustup toolchain install nightly --component rust-src
+  cargo install cargo-nextest cargo-udeps cargo-deny cargo-audit --locked
+  pnpm exec playwright install chromium
+
+lint:
+  pnpm --filter web lint
+  pnpm --dir packages/ui exec depcruise --config dependency-cruiser.cjs src
+  node ./scripts/check-rust-layers.mjs
+  (cd apps/axum && cargo fmt --check)
+  (cd apps/axum && cargo clippy --all-targets --all-features -- -D warnings)
+  (cd apps/axum && cargo +nightly udeps --all-targets)
+
+typecheck:
+  pnpm --filter web typecheck
+  (cd apps/axum && cargo check --all-targets)
+
+test:
+  pnpm --filter web test
+  (cd apps/axum && cargo nextest run)
+
+ux:
+  pnpm --filter web ux
+
+supply-chain:
+  gitleaks dir . --config .gitleaks.toml
+  osv-scanner scan source -r .
+  pnpm audit --audit-level=high
+  (cd apps/axum && cargo deny check)
+  (cd apps/axum && cargo audit)
+
+ci: lint typecheck test ux supply-chain

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

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

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

@@ -0,0 +1,5 @@
+[tools]
+node = "20"
+pnpm = "9.15.9"
+rust = "stable"
+

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

@@ -0,0 +1,41 @@
+{
+  "name": "next-axum-monorepo",
+  "version": "0.0.1",
+  "private": true,
+  "scripts": {
+    "build": "turbo build",
+    "dev": "turbo dev --filter=web",
+    "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-axum-monorepo/packages/eslint-config/README.md

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

package/templates/next-axum-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-axum-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-axum-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-axum-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-axum-monorepo/packages/typescript-config/README.md

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

package/templates/next-axum-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-axum-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-axum-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-axum-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-axum-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"
+}