@m2-ai/lattice-cli 0.0.0-stage → 0.8.7

package/bundles/nextjs-trpc/docs/rules/codex.md

@@ -0,0 +1,62 @@
+# Codex Rules
+
+Use this file with `AGENTS.md` when you open the project in Codex. `AGENTS.md` is the durable entrypoint; this file is the deeper workflow reference.
+
+## Stack
+
+- **Framework**: Next.js
+- **Language**: TypeScript (strict mode)
+- **Styling**: Tailwind CSS
+- **Testing**: Jest + React Testing Library
+
+## Operating Rules
+
+1. **Stay aligned with PROJECT_GUIDE.md** - implement what was planned before expanding scope
+2. **Prefer small diffs** - keep changes reviewable and localized
+3. **Check existing patterns first** - match the codebase before introducing new structure
+4. **Verify versions and APIs** - do not guess package behavior
+5. **Run verification before handoff** - lint, typecheck, test, build, and verify when available
+6. **Protect secrets** - never commit credentials, tokens, or private keys
+
+## Codex Surfaces
+
+- `AGENTS.md` is loaded before work begins. Keep it concise and repo-scoped.
+- `docs/rules/codex.md` is the full execution playbook.
+- `.agents/skills/lattice-verify/SKILL.md` is a portable Agent Skill for final verification and release checks.
+- `.mcp.json` contains disabled MCP examples. Enable only the tools the task needs and keep credentials in environment variables.
+- Use hooks or project config for mechanical enforcement; use skills for repeatable procedures.
+
+## Workflow
+
+1. Read `AGENTS.md` and `PROJECT_GUIDE.md`
+2. Identify the exact files you need to touch
+3. Keep implementation deterministic and production-ready
+4. Use the `lattice-verify` skill when asked to verify, ship, or prepare handoff
+5. Explain risky commands before running them
+6. Note assumptions or follow-ups in your final handoff
+
+## Verification Commands
+
+```bash
+npm run lint
+npm run typecheck
+npm run test
+npm run build
+npm run verify
+```
+
+## Related Files
+
+- `.cursor/rules.md` for shared project guardrails
+- `.cursor/rules/lattice-core.mdc` for current Cursor Agent rules
+- `.agents/skills/lattice-verify/SKILL.md` for portable verification workflow
+- `CLAUDE.md` for Claude Code compatibility
+- `.claude/rules/lattice-core.md` for Claude path-scoped code guidance
+- `.claude/settings.json` for Claude Code permissions and hooks
+
+## Hard Stops
+
+- Requirements conflict with `PROJECT_GUIDE.md`
+- A command would overwrite unrelated user work
+- Required environment variables are missing
+- You cannot verify an API or package behavior

package/bundles/nextjs-trpc/eslint.config.mjs

@@ -0,0 +1,16 @@
+import { defineConfig, globalIgnores } from "eslint/config";
+import nextVitals from "eslint-config-next/core-web-vitals";
+import nextTs from "eslint-config-next/typescript";
+
+const eslintConfig = defineConfig([
+  ...nextVitals,
+  ...nextTs,
+  globalIgnores([
+    ".next/**",
+    "out/**",
+    "build/**",
+    "next-env.d.ts",
+  ]),
+]);
+
+export default eslintConfig;

package/bundles/nextjs-trpc/instrumentation-client.ts

@@ -0,0 +1,20 @@
+import * as Sentry from "@sentry/nextjs";
+
+if (process.env.NEXT_PUBLIC_SENTRY_DSN) {
+  Sentry.init({
+    dsn: process.env.NEXT_PUBLIC_SENTRY_DSN,
+    tracesSampleRate: process.env.NODE_ENV === "development" ? 1 : 0.1,
+    dataCollection: {
+      userInfo: false, cookies: false,
+      httpHeaders: { request: false, response: false }, urlQueryParams: false,
+      httpBodies: [], genAI: { inputs: false, outputs: false },
+      databaseQueryData: false, queues: false,
+      graphQL: { document: false, variables: false },
+    },
+    replaysSessionSampleRate: 0.1,
+    replaysOnErrorSampleRate: 1,
+    integrations: [Sentry.replayIntegration()],
+  });
+}
+
+export const onRouterTransitionStart = Sentry.captureRouterTransitionStart;

package/bundles/nextjs-trpc/instrumentation.ts

@@ -0,0 +1,12 @@
+import * as Sentry from "@sentry/nextjs";
+
+export async function register() {
+  if (process.env.NEXT_RUNTIME === "nodejs") {
+    await import("./sentry.server.config");
+  }
+  if (process.env.NEXT_RUNTIME === "edge") {
+    await import("./sentry.edge.config");
+  }
+}
+
+export const onRequestError = Sentry.captureRequestError;

package/bundles/nextjs-trpc/jest.config.mjs

@@ -0,0 +1,16 @@
+import nextJest from "next/jest.js";
+
+const createJestConfig = nextJest({
+  dir: "./",
+});
+
+const customJestConfig = {
+  maxWorkers: 2,
+  setupFilesAfterEnv: ["<rootDir>/jest.setup.js"],
+  testEnvironment: "jest-environment-jsdom",
+  moduleNameMapper: {
+    "^@/(.*)$": "<rootDir>/$1",
+  },
+};
+
+export default createJestConfig(customJestConfig);

package/bundles/nextjs-trpc/jest.setup.js

@@ -0,0 +1 @@
+import "@testing-library/jest-dom";

package/bundles/nextjs-trpc/lib/db.ts

@@ -0,0 +1,17 @@
+import { PrismaPg } from "@prisma/adapter-pg";
+import { PrismaClient } from "@/generated/prisma/client";
+
+const globalForPrisma = globalThis as unknown as {
+  prisma: PrismaClient | undefined;
+};
+
+export function getPrisma() {
+  const connectionString = process.env.DATABASE_URL;
+  if (!connectionString) throw new Error("DATABASE_URL is required");
+
+  const prisma = globalForPrisma.prisma ?? new PrismaClient({
+    adapter: new PrismaPg({ connectionString }),
+  });
+  if (process.env.NODE_ENV !== "production") globalForPrisma.prisma = prisma;
+  return prisma;
+}

package/bundles/nextjs-trpc/lib/trpc/react.tsx

@@ -0,0 +1,7 @@
+"use client";
+
+import { createTRPCContext } from "@trpc/tanstack-react-query";
+import type { AppRouter } from "@/server/routers/_app";
+
+export const { TRPCProvider, useTRPC, useTRPCClient } =
+  createTRPCContext<AppRouter>();

package/bundles/nextjs-trpc/lib/utils.ts

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

package/bundles/nextjs-trpc/next-env.d.ts

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

package/bundles/nextjs-trpc/next.config.ts

@@ -0,0 +1,15 @@
+import type { NextConfig } from "next";
+import { withSentryConfig } from "@sentry/nextjs/config";
+
+const nextConfig: NextConfig = {
+  agentRules: false,
+  experimental: { cpus: 4 },
+  turbopack: { root: process.cwd() },
+};
+
+export default withSentryConfig(nextConfig, {
+  org: process.env.SENTRY_ORG,
+  project: process.env.SENTRY_PROJECT,
+  authToken: process.env.SENTRY_AUTH_TOKEN,
+  silent: !process.env.CI,
+});

package/bundles/nextjs-trpc/package.json

@@ -0,0 +1,62 @@
+{
+  "name": "next-js---trpc-starter",
+  "version": "0.1.0",
+  "private": true,
+  "type": "module",
+  "scripts": {
+    "dev": "next dev",
+    "build": "next build",
+    "start": "next start",
+    "lint": "eslint .",
+    "typecheck": "tsc --noEmit",
+    "test": "jest --passWithNoTests",
+    "verify": "npm run lint && npm run typecheck && npm test && npm run build",
+    "postinstall": "prisma generate",
+    "db:generate": "prisma generate",
+    "db:migrate": "prisma migrate dev",
+    "db:studio": "prisma studio"
+  },
+  "dependencies": {
+    "next": "16.4.2",
+    "react": "19.3.1",
+    "react-dom": "19.3.1",
+    "clsx": "^2.1.1",
+    "tailwind-merge": "^3.4.0",
+    "@prisma/client": "7.10.1",
+    "@prisma/adapter-pg": "7.10.1",
+    "pg": "8.23.1",
+    "dotenv": "^17.2.3",
+    "@trpc/server": "11.19.0",
+    "@trpc/client": "11.19.0",
+    "@trpc/tanstack-react-query": "11.19.0",
+    "@tanstack/react-query": "5.104.4",
+    "zod": "4.6.7",
+    "@sentry/nextjs": "11.8.0"
+  },
+  "devDependencies": {
+    "@tailwindcss/postcss": "^4",
+    "@types/node": "^24",
+    "@types/react": "^19",
+    "@types/react-dom": "^19",
+    "eslint": "^9",
+    "eslint-config-next": "16.4.2",
+    "tailwindcss": "^4",
+    "typescript": "6.0.3",
+    "jest": "^30",
+    "@types/jest": "^30",
+    "@testing-library/react": "^16",
+    "@testing-library/jest-dom": "^7",
+    "jest-environment-jsdom": "^30",
+    "prisma": "7.10.1",
+    "@types/pg": "8.23.1"
+  },
+  "engines": {
+    "node": "24.x"
+  },
+  "overrides": {
+    "@istanbuljs/load-nyc-config": {
+      "js-yaml": "4.3.2"
+    },
+    "braces": "file:vendor/m2ai-braces-3.0.3-m2ai.1.tar"
+  }
+}

package/bundles/nextjs-trpc/postcss.config.mjs

@@ -0,0 +1,7 @@
+const config = {
+  plugins: {
+    '@tailwindcss/postcss': {},
+  },
+};
+
+export default config;

package/bundles/nextjs-trpc/prisma/schema.prisma

@@ -0,0 +1,41 @@
+// Prisma Schema
+// Generated by Lattice Project Builder
+// Docs: https://pris.ly/d/prisma-schema
+
+generator client {
+  provider = "prisma-client"
+  output   = "../generated/prisma"
+}
+
+datasource db {
+  provider = "postgresql"
+}
+
+model User {
+  id        String   @id @default(cuid())
+  email     String   @unique
+  name      String?
+  avatarUrl String?
+  createdAt DateTime @default(now())
+  updatedAt DateTime @updatedAt
+
+  // Add your relations here
+  // posts     Post[]
+  // comments  Comment[]
+
+  @@map("users")
+}
+
+// Add your models below
+// model Post {
+//   id        String   @id @default(cuid())
+//   title     String
+//   content   String?
+//   published Boolean  @default(false)
+//   authorId  String
+//   author    User     @relation(fields: [authorId], references: [id])
+//   createdAt DateTime @default(now())
+//   updatedAt DateTime @updatedAt
+//
+//   @@map("posts")
+// }

package/bundles/nextjs-trpc/prisma.config.ts

@@ -0,0 +1,10 @@
+import "dotenv/config";
+import { defineConfig } from "prisma/config";
+
+export default defineConfig({
+  schema: "prisma/schema.prisma",
+  migrations: { path: "prisma/migrations" },
+  datasource: {
+    url: process.env.DATABASE_URL ?? "postgresql://postgres:postgres@localhost:5432/app",
+  },
+});

package/bundles/nextjs-trpc/prompts/01-feature-implementation.md

@@ -0,0 +1,9 @@
+# Feature Implementation
+
+```
+Role: You are building this tRPC application.
+Goal: Implement [FEATURE] with [ROUTER] procedures.
+Constraints: Use Zod for validation, Prisma for DB
+Files: server/routers/[name].ts, app/[path]/page.tsx
+Acceptance: [ ] Types flow end-to-end, [ ] verify passes
+```

package/bundles/nextjs-trpc/prompts/02-bug-fix.md

@@ -0,0 +1,9 @@
+# Bug Fix
+
+```
+Role: You are debugging this tRPC app.
+Bug: [DESCRIPTION]
+Expected: [WHAT SHOULD HAPPEN]
+Actual: [WHAT HAPPENS]
+Fix only the bug, keep diff minimal.
+```

package/bundles/nextjs-trpc/prompts/03-safe-refactor.md

@@ -0,0 +1,8 @@
+# Safe Refactor
+
+```
+Role: You are refactoring this tRPC app.
+Goal: [IMPROVEMENT]
+Scope: [FILES]
+Constraints: Types must remain correct, behavior unchanged.
+```

package/bundles/nextjs-trpc/prompts/04-test-first.md

@@ -0,0 +1,8 @@
+# Test-First Development
+
+```
+Role: Write tests for tRPC procedures.
+Feature: [NAME]
+Test cases: 1. [CASE] 2. [CASE]
+Then implement minimal code to pass.
+```

package/bundles/nextjs-trpc/prompts/05-ui-polish.md

@@ -0,0 +1,7 @@
+# UI Polish
+
+```
+Role: You are polishing this app's UI.
+Target: [COMPONENT]
+Polish: loading states, error handling, optimistic updates
+```

package/bundles/nextjs-trpc/prompts/06-security-review.md

@@ -0,0 +1,7 @@
+# Security Review
+
+```
+Role: Security review of tRPC procedures.
+Check: Input validation, auth checks, SQL injection, exposed data
+Output: | Severity | Issue | File | Recommendation |
+```

package/bundles/nextjs-trpc/prompts/quality.md

@@ -0,0 +1,269 @@
+# Quality & Performance Standards
+
+## Performance Rules
+
+### Critical
+
+1. **No CDN dependencies in production**
+   - ❌ Tailwind CSS CDN
+   - ❌ External font CDN without optimization
+   - ✅ Build process with optimized bundles
+   - ✅ Self-hosted fonts or optimized Google Fonts
+
+2. **Font loading optimization**
+   - Use `font-display: swap` for web fonts
+   - Combine multiple font requests
+   - Preload critical fonts
+   - Remove duplicate font imports
+
+3. **CSS optimization**
+   - No massive blur effects (`blur-[100px]`)
+   - Use `will-change` for animations
+   - Prefer `transform` and `opacity` for GPU acceleration
+   - Avoid expensive filter operations
+
+4. **Bundle size**
+   - Keep JavaScript bundles under thresholds:
+     - Initial bundle: < 200KB (gzipped)
+     - Route chunks: < 100KB (gzipped)
+   - Use dynamic imports for code splitting
+   - Tree-shake unused code
+
+### Medium Priority
+
+5. **Resource hints**
+   - Add `dns-prefetch` for external domains
+   - Use `preconnect` for critical resources
+   - Preload critical assets
+
+6. **Image optimization**
+   - Use Next.js `Image` component
+   - Add `loading="lazy"` for below-fold images
+   - Use modern formats (WebP, AVIF)
+   - Provide proper width/height
+
+7. **Inline code**
+   - Extract large inline styles to external CSS
+   - Move scripts to separate files with caching
+   - Keep HTML size reasonable
+
+---
+
+## Accessibility (a11y) Rules
+
+### Critical
+
+1. **Interactive elements MUST have handlers**
+   - Buttons need `onClick` or form `type="submit"`
+   - Links need valid `href` (not `#`)
+   - Form inputs need labels
+
+2. **ARIA labels for icon buttons**
+   ```tsx
+   ❌ <button><MenuIcon /></button>
+   ✅ <button aria-label="Open menu"><MenuIcon /></button>
+   ```
+
+3. **Alt text for images**
+   - Decorative images: `alt=""`
+   - Meaningful images: descriptive alt text
+   - No missing alt attributes
+
+4. **Keyboard navigation**
+   - All interactive elements reachable via keyboard
+   - Visible focus states (`:focus-visible`)
+   - Logical tab order
+
+### Medium Priority
+
+5. **Color contrast**
+   - Text: minimum 4.5:1 ratio
+   - Large text: minimum 3:1 ratio
+   - Use tools to verify
+
+6. **Semantic HTML**
+   - Use proper heading hierarchy (h1 → h2 → h3)
+   - Use `<nav>`, `<main>`, `<article>`, `<section>`
+   - No generic `<div>` for everything
+
+7. **Form accessibility**
+   - Labels properly associated
+   - Error messages announced
+   - Required fields marked
+   - Validation feedback
+
+---
+
+## SEO & Metadata Rules
+
+### Critical
+
+1. **Required meta tags**
+   ```tsx
+   <title>Page Title - Site Name</title>
+   <meta name="description" content="..." />
+   <meta name="viewport" content="width=device-width, initial-scale=1" />
+   ```
+
+2. **Open Graph tags**
+   ```tsx
+   <meta property="og:title" content="..." />
+   <meta property="og:description" content="..." />
+   <meta property="og:image" content="..." />
+   <meta property="og:url" content="..." />
+   ```
+
+3. **Twitter Card tags**
+   ```tsx
+   <meta name="twitter:card" content="summary_large_image" />
+   <meta name="twitter:title" content="..." />
+   <meta name="twitter:description" content="..." />
+   <meta name="twitter:image" content="..." />
+   ```
+
+### Medium Priority
+
+4. **Favicon**
+   - Include `favicon.ico`
+   - Add Apple touch icon
+   - Include manifest.json
+
+5. **Canonical URL**
+   ```tsx
+   <link rel="canonical" href="https://..." />
+   ```
+
+6. **Structured data**
+   - Add JSON-LD for Organization, Product, etc.
+   - Use Schema.org vocabulary
+
+---
+
+## Functionality & Code Quality
+
+### Critical
+
+1. **No broken links**
+   - All `href` must point to valid routes
+   - Use Next.js `Link` for internal navigation
+   - External links open in new tab if appropriate
+
+2. **Mobile menu implementation**
+   - If mobile menu button exists, menu must work
+   - Toggle open/close state properly
+   - Close on outside click or route change
+
+3. **Copy-to-clipboard**
+   - Use `navigator.clipboard.writeText()`
+   - Show success feedback (toast, checkmark)
+   - Handle errors gracefully
+
+4. **Form validation**
+   - Client-side validation for UX
+   - Server-side validation for security
+   - Clear error messages
+
+### Medium Priority
+
+5. **Smooth scrolling**
+   ```css
+   html {
+     scroll-behavior: smooth;
+   }
+   ```
+
+6. **Loading states**
+   - Show spinners/skeletons during async operations
+   - Disable buttons while submitting
+   - Prevent duplicate submissions
+
+7. **Error boundaries**
+   - Catch errors in components
+   - Show fallback UI
+   - Log errors to Sentry
+
+---
+
+## Security Rules
+
+### Critical
+
+1. **No external CDN without SRI**
+   - If using CDN, add Subresource Integrity hash
+   - Or self-host dependencies
+
+2. **Content Security Policy**
+   ```tsx
+   <meta http-equiv="Content-Security-Policy" content="..." />
+   ```
+
+3. **Environment variables**
+   - Never expose secrets in client code
+   - Use `NEXT_PUBLIC_` prefix for client vars
+   - Validate env vars on startup
+
+---
+
+## Testing Requirements
+
+### Critical
+
+1. **Lighthouse CI**
+   - Performance: ≥ 80
+   - Accessibility: ≥ 90
+   - Best Practices: ≥ 90
+   - SEO: ≥ 90
+
+2. **Accessibility testing**
+   - Run axe-core checks
+   - Zero critical violations
+   - Address all serious violations
+
+3. **Visual regression**
+   - Key pages render correctly
+   - Responsive layouts work
+   - No layout shifts (CLS)
+
+---
+
+## When to Run Quality Checks
+
+1. **Pre-commit**
+   - Quick checks (linting, type-check)
+
+2. **Pre-push**
+   - Full verification (`npm run verify:quality`)
+
+3. **CI/CD**
+   - All quality checks must pass
+   - Block merge if quality gates fail
+
+4. **Pre-production**
+   - Full Lighthouse audit
+   - Manual QA on staging
+
+---
+
+## How AI Should Apply These Rules
+
+1. **During implementation**
+   - Follow these rules by default
+   - Don't add non-functional buttons
+   - Don't use CDN for production code
+
+2. **During code review**
+   - Check for violations
+   - Suggest fixes proactively
+
+3. **When generating documentation**
+   - Include quality considerations
+   - Mention performance implications
+
+4. **When debugging**
+   - Use browser DevTools Performance tab
+   - Check Network tab for unnecessary requests
+   - Verify accessibility tree
+
+---
+
+*These rules are enforced by `npm run verify:quality`. Run locally before pushing.*

package/bundles/nextjs-trpc/sentry.edge.config.ts

@@ -0,0 +1,15 @@
+import * as Sentry from "@sentry/nextjs";
+
+if (process.env.SENTRY_DSN || process.env.NEXT_PUBLIC_SENTRY_DSN) {
+  Sentry.init({
+    dsn: process.env.SENTRY_DSN || process.env.NEXT_PUBLIC_SENTRY_DSN,
+    tracesSampleRate: process.env.NODE_ENV === "development" ? 1 : 0.1,
+    dataCollection: {
+      userInfo: false, cookies: false,
+      httpHeaders: { request: false, response: false }, urlQueryParams: false,
+      httpBodies: [], genAI: { inputs: false, outputs: false },
+      databaseQueryData: false, queues: false,
+      graphQL: { document: false, variables: false },
+    },
+  });
+}

package/bundles/nextjs-trpc/sentry.server.config.ts

@@ -0,0 +1,15 @@
+import * as Sentry from "@sentry/nextjs";
+
+if (process.env.SENTRY_DSN || process.env.NEXT_PUBLIC_SENTRY_DSN) {
+  Sentry.init({
+    dsn: process.env.SENTRY_DSN || process.env.NEXT_PUBLIC_SENTRY_DSN,
+    tracesSampleRate: process.env.NODE_ENV === "development" ? 1 : 0.1,
+    dataCollection: {
+      userInfo: false, cookies: false,
+      httpHeaders: { request: false, response: false }, urlQueryParams: false,
+      httpBodies: [], genAI: { inputs: false, outputs: false },
+      databaseQueryData: false, queues: false,
+      graphQL: { document: false, variables: false },
+    },
+  });
+}