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

package/bundles/nextjs-saas/.mcp.json

@@ -0,0 +1,35 @@
+{
+  "mcpServers": {
+    "filesystem": {
+      "command": "npx",
+      "args": [
+        "-y",
+        "@modelcontextprotocol/server-filesystem@1.0.0",
+        "."
+      ],
+      "disabled": true
+    },
+    "github": {
+      "type": "http",
+      "url": "https://api.githubcopilot.com/mcp/readonly",
+      "headers": {
+        "Authorization": "Bearer ${GITHUB_TOKEN}"
+      },
+      "disabled": true
+    },
+    "supabase": {
+      "command": "npx",
+      "args": [
+        "-y",
+        "@supabase/mcp-server-supabase@0.14.0",
+        "--read-only",
+        "--project-ref",
+        "${SUPABASE_PROJECT_REF}"
+      ],
+      "env": {
+        "SUPABASE_ACCESS_TOKEN": "${SUPABASE_ACCESS_TOKEN}"
+      },
+      "disabled": true
+    }
+  }
+}

package/bundles/nextjs-saas/AGENTS.md

@@ -0,0 +1,58 @@
+# AGENTS
+
+## Read This First
+- Codex workspace rules live in `docs/rules/codex.md`.
+- Portable Agent Skills live in `.agents/skills/`.
+- Multi-agent release workflow lives in `docs/LATTICE_RELEASE_WORKFLOW.md`.
+- Cursor Agent rules live in `.cursor/rules/lattice-core.mdc`.
+- Claude Code rules and skills live in `.claude/rules/` and `.claude/skills/`.
+- GitHub Copilot instructions live in `.github/copilot-instructions.md` and `.github/instructions/lattice-core.instructions.md`.
+- Keep implementation aligned with `PROJECT_GUIDE.md`.
+
+## Mission
+- Keep implementation aligned with PROJECT_GUIDE.md.
+- Prioritize small, reviewable diffs and deterministic behavior.
+- Keep security boundaries explicit and avoid privilege escalation by default.
+
+## Stack Baseline
+- Framework: Next.js
+- Language: TypeScript strict mode
+- Styling: Tailwind CSS
+- Test command: `npm run test`
+- Verify command: `npm run verify`
+
+## Execution Policy
+- Default mode: ask before risky commands.
+- Always explain why a command or change is needed.
+- Never write secrets to source control.
+
+## Tooling
+- Codex rules: `docs/rules/codex.md`
+- Portable verification skill: `.agents/skills/lattice-verify/SKILL.md`
+- Cursor rules: `.cursor/rules.md` and `.cursor/rules/lattice-core.mdc`
+- Cursor MCP: `.cursor/mcp.json`
+- Claude rules: `.claude/rules/lattice-core.md`
+- Claude skill: `.claude/skills/lattice-verify/SKILL.md`
+- Claude config: `.claude/settings.json`
+- Claude hooks: `.claude/hooks/*`
+- GitHub Copilot repo instructions: `.github/copilot-instructions.md`
+- GitHub Copilot path instructions: `.github/instructions/lattice-core.instructions.md`
+- MCP template: `.mcp.json`
+
+## Agent Skills
+- Use `lattice-verify` before final handoff, release work, or PR prep.
+- Use `lattice-feature-handoff` after scoped implementation and `lattice-release-manager` for independent release review.
+- Keep new reusable procedures in skills instead of bloating always-loaded instruction files.
+- Keep skills deterministic: clear trigger, exact commands, and explicit pass/fail reporting.
+
+## Required Checks Before Completion
+1. `npm run lint`
+2. `npm run typecheck`
+3. `npm run test`
+4. `npm run build`
+5. `npm run verify`
+
+## Hard Stops
+- Requirements conflict with PROJECT_GUIDE.md.
+- Any command would delete or overwrite unrelated user data.
+- Missing env vars required for delivery path.

package/bundles/nextjs-saas/CLAUDE.md

@@ -0,0 +1,76 @@
+# Project Instructions
+
+This file provides context for Claude Code. For Cursor users, see `.cursor/rules.md` and `.cursor/rules/lattice-core.mdc`. For GitHub Copilot, see `.github/copilot-instructions.md` and `.github/instructions/lattice-core.instructions.md`. For Codex users, see `AGENTS.md` and `docs/rules/codex.md`.
+
+## Stack
+
+- **Framework**: Next.js
+- **Language**: TypeScript (strict mode)
+- **Styling**: Tailwind CSS
+- **Testing**: Jest + React Testing Library
+
+## Core Rules
+
+1. **Stay in scope** - Only implement what's explicitly requested
+2. **No placeholders** - All code must be production-ready
+3. **Verify before coding** - Check current package versions and API compatibility
+4. **Minimal changes** - Keep modifications localized and simple
+5. **Test everything** - Run lint, typecheck, test, and build before submitting
+6. **Never expose secrets** - API keys, tokens, passwords, and credentials must NEVER be committed to version control
+
+## Claude Code Surfaces
+
+- `CLAUDE.md` is the shared project instruction file.
+- `.claude/rules/lattice-core.md` is path-scoped source guidance for code edits.
+- `.claude/skills/lattice-verify/SKILL.md` defines the repeatable verification workflow. Use `/lattice-verify` before final handoff or release work.
+- `.claude/settings.json` contains project permissions and hook wiring.
+- `.mcp.json` contains disabled MCP server templates. Approve and enable only the servers this project actually needs.
+
+## Verification Commands
+
+```bash
+npm run lint       # ESLint check
+npm run typecheck  # TypeScript check
+npm test           # Run tests
+npm run build      # Production build
+npm run verify     # All checks via Lattice
+```
+
+## Security Rules (CRITICAL)
+
+- **NEVER** commit API keys, secrets, tokens, or credentials to version control
+- **ALWAYS** use environment variables (`.env.local`, `.env`) for sensitive data
+- **ALWAYS** ensure `.env*` files are in `.gitignore`
+- **NEVER** hardcode secrets in source code, even in comments
+- **ONLY** access sensitive keys server-side (never expose to client-side code)
+
+## Next.js Guidelines
+
+- Use App Router (`app/` directory)
+- Server Components by default, `"use client"` only when needed
+- Follow Next.js file conventions: `layout.tsx`, `page.tsx`, `loading.tsx`, `error.tsx`
+- Use Next.js Image component for optimized images
+
+## Before Making Changes
+
+1. Restate the scope in one paragraph
+2. Identify files to create or modify
+3. Check existing patterns in the codebase
+4. Verify package versions are current
+
+## After Making Changes
+
+1. Run all verification commands
+2. Fix any failures before proceeding
+3. Report verification results
+
+## Hard Stops
+
+- If requirements conflict -> ask for clarification
+- If verification fails -> fix before continuing
+- If scope is unclear -> ask for clarification
+- If you can't verify an API or version -> ask
+- If code contains hardcoded secrets -> STOP and use environment variables
+
+---
+*Generated by Lattice Project Builder*

package/bundles/nextjs-saas/PROJECT_GUIDE.md

@@ -0,0 +1,279 @@
+# SaaS Starter — Project Guide
+
+This is your project guide for building a SaaS application with Next.js, Supabase, and Stripe.
+
+## Stack Overview
+
+| Layer | Technology | Purpose |
+|-------|------------|---------|
+| Frontend | Next.js + React | App Router, Server Components |
+| Database | Supabase (Postgres) | Auth, DB, Realtime |
+| Payments | Stripe | Subscriptions, billing |
+| Analytics | PostHog | Product analytics |
+| Monitoring | Sentry | Error tracking |
+
+**IMPORTANT FOR AI:** Always check `package.json` for the exact versions of dependencies before referencing them in code or documentation. Never hardcode version numbers—they change frequently.
+
+## Project Structure
+
+```
+├── app/
+│   ├── (auth)/
+│   │   ├── login/page.tsx
+│   │   ├── signup/page.tsx
+│   │   └── callback/route.ts
+│   ├── (dashboard)/
+│   │   ├── layout.tsx
+│   │   └── page.tsx
+│   ├── api/
+│   │   ├── webhooks/stripe/route.ts
+│   │   └── checkout/route.ts
+│   ├── layout.tsx
+│   └── page.tsx
+├── components/
+│   ├── ui/
+│   ├── auth/
+│   └── billing/
+├── lib/
+│   ├── supabase/
+│   │   ├── client.ts
+│   │   ├── server.ts
+│   │   └── middleware.ts
+│   ├── stripe/
+│   │   ├── client.ts
+│   │   └── server.ts
+│   └── utils.ts
+├── types/
+│   └── database.ts
+└── middleware.ts
+```
+
+---
+
+## Phase 1: Foundation (Days 1-2)
+
+### Goal
+Set up the project with authentication and basic layout.
+
+### Tasks
+
+1. **Initialize Supabase client**
+   - Create `lib/supabase/client.ts` for browser
+   - Create `lib/supabase/server.ts` for Server Components
+   - Set up middleware for auth session refresh
+
+2. **Create auth pages**
+   - Login page with email/password
+   - Signup page with email verification
+   - Auth callback handler for OAuth
+
+3. **Create dashboard layout**
+   - Protected route with auth check
+   - Navigation sidebar
+   - User menu with logout
+
+### Acceptance Criteria
+
+- [ ] User can sign up with email
+- [ ] User can log in
+- [ ] Dashboard is protected (redirects if not logged in)
+- [ ] `npm run verify` passes
+
+---
+
+## Phase 2: Database & Data Model (Days 3-4)
+
+### Goal
+Set up the database schema and data access patterns.
+
+### Tasks
+
+1. **Design database schema**
+   - Users table (extends Supabase auth.users)
+   - Subscriptions table
+   - Your core domain tables
+
+2. **Create Supabase migrations**
+   - Use Supabase CLI: `supabase migration new <name>`
+   - Apply migrations: `supabase db push`
+
+3. **Generate TypeScript types**
+   - Run: `supabase gen types typescript --local > types/database.ts`
+
+4. **Create data access functions**
+   - Server-side queries in Server Components
+   - Client-side mutations with RPC or REST
+
+### Acceptance Criteria
+
+- [ ] Database schema is defined
+- [ ] TypeScript types are generated
+- [ ] CRUD operations work for main entity
+- [ ] Row Level Security policies are in place
+
+---
+
+## Phase 3: Billing Integration (Days 5-7)
+
+### Goal
+Integrate Stripe for subscription billing.
+
+### Tasks
+
+1. **Set up Stripe products**
+   - Create products in Stripe Dashboard
+   - Define pricing tiers (Free, Pro, Team)
+
+2. **Create checkout flow**
+   - API route: `POST /api/checkout`
+   - Redirect to Stripe Checkout
+
+3. **Handle webhooks**
+   - API route: `POST /api/webhooks/stripe`
+   - Handle: `checkout.session.completed`
+   - Handle: `customer.subscription.updated`
+   - Handle: `customer.subscription.deleted`
+
+4. **Sync subscription status**
+   - Update Supabase when webhook fires
+   - Add subscription status to user context
+
+5. **Create billing UI**
+   - Current plan display
+   - Upgrade/downgrade buttons
+   - Billing portal link
+
+### Acceptance Criteria
+
+- [ ] User can subscribe to a plan
+- [ ] Webhook updates database correctly
+- [ ] User can access billing portal
+- [ ] Plan-gated features work
+
+---
+
+## Phase 4: Core Features (Days 8-14)
+
+### Goal
+Build your main product features.
+
+### Tasks
+
+*Define your specific features here. Examples:*
+
+1. **Feature A: [Name]**
+   - Description
+   - UI components needed
+   - Data model changes
+   - API routes
+
+2. **Feature B: [Name]**
+   - Description
+   - UI components needed
+   - Data model changes
+   - API routes
+
+### Acceptance Criteria
+
+- [ ] Core user flow works end-to-end
+- [ ] Edge cases are handled
+- [ ] Loading and error states are clear
+- [ ] `npm run verify` passes
+
+---
+
+## Phase 5: Polish & Launch (Days 15-21)
+
+### Goal
+Production-ready with monitoring and analytics.
+
+### Tasks
+
+1. **Add Sentry error tracking**
+   - Configure `sentry.client.config.ts`
+   - Configure `sentry.server.config.ts`
+   - Test error reporting
+
+2. **Add PostHog analytics**
+   - Initialize in `app/layout.tsx`
+   - Track key events (signup, subscription, core actions)
+   - Set up feature flags if needed
+
+3. **SEO & Meta**
+   - Open Graph images
+   - Meta descriptions
+   - Sitemap
+
+4. **Performance**
+   - Lighthouse audit
+   - Core Web Vitals check
+   - Image optimization
+
+5. **Documentation**
+   - README with setup instructions
+   - Environment variable documentation
+   - API documentation if applicable
+
+### Acceptance Criteria
+
+- [ ] Sentry captures errors
+- [ ] PostHog tracks events
+- [ ] Lighthouse score > 90
+- [ ] `npm run release-check` passes
+
+---
+
+## Environment Variables
+
+Create `.env.local` with:
+
+```bash
+# Supabase
+NEXT_PUBLIC_SUPABASE_URL=your-project-url
+NEXT_PUBLIC_SUPABASE_ANON_KEY=your-anon-key
+SUPABASE_SERVICE_ROLE_KEY=your-service-role-key
+
+# Stripe
+STRIPE_SECRET_KEY=sk_test_...
+NEXT_PUBLIC_STRIPE_PUBLISHABLE_KEY=pk_test_...
+STRIPE_WEBHOOK_SECRET=whsec_...
+
+# PostHog
+NEXT_PUBLIC_POSTHOG_KEY=phc_...
+NEXT_PUBLIC_POSTHOG_HOST=https://app.posthog.com
+
+# Sentry
+SENTRY_DSN=https://...@sentry.io/...
+```
+
+---
+
+## Recommended Resources
+
+- [Next.js App Router Docs](https://nextjs.org/docs/app)
+- [Supabase Auth Helpers](https://supabase.com/docs/guides/auth/server-side)
+- [Stripe Checkout](https://stripe.com/docs/checkout)
+- [PostHog Next.js](https://posthog.com/docs/libraries/next-js)
+- [Sentry Next.js](https://docs.sentry.io/platforms/javascript/guides/nextjs/)
+
+---
+
+## Verification Commands
+
+```bash
+# Run all checks
+npm run verify
+
+# Individual checks
+npm run lint
+npm run typecheck
+npm run test
+npm run build
+
+# Production readiness
+npm run release-check
+```
+
+---
+
+*Generated by Lattice — AI workers are fast. Lattice keeps them building right.*

package/bundles/nextjs-saas/README.md

@@ -0,0 +1,42 @@
+# SaaS Starter
+
+Built with [Lattice Project Builder](https://latticeai.app).
+
+## Getting Started
+
+1. Install dependencies:
+   ```bash
+   npm install
+   ```
+
+2. Review `.env.example` and fill in the variables your selected services need.
+
+3. Run the development server:
+   ```bash
+   npm run dev
+   ```
+
+4. Open [http://localhost:3000](http://localhost:3000)
+
+## Included Scaffold
+
+- PROJECT_GUIDE.md with the planned build scope
+- AI guardrails for Cursor, Codex, and Claude Code
+- GitHub Actions CI and shared verification commands
+- Supabase auth starter files
+- Supabase migration starter files
+- Stripe Checkout, billing portal, and webhook routes
+- PostHog initialization
+- Sentry runtime initialization and error boundary
+
+## Commands
+
+| Command | Description |
+|---------|-------------|
+| `npm run dev` | Start development server |
+| `npm run build` | Build for production |
+| `npm run start` | Start production server |
+| `npm run lint` | Run ESLint |
+| `npm run typecheck` | Run TypeScript checks |
+| `npm run test` | Run tests |
+| `npm run verify` | Run all checks |

package/bundles/nextjs-saas/app/(auth)/forgot-password/page.tsx

@@ -0,0 +1,101 @@
+"use client";
+
+import { useState } from "react";
+import Link from "next/link";
+import { createClient } from "@/lib/supabase/client";
+
+export default function ForgotPasswordPage() {
+  const [email, setEmail] = useState("");
+  const [error, setError] = useState("");
+  const [loading, setLoading] = useState(false);
+  const [success, setSuccess] = useState(false);
+
+  const handleSubmit = async (e: React.FormEvent) => {
+    e.preventDefault();
+    setError("");
+    setLoading(true);
+
+    const supabase = createClient();
+    const { error } = await supabase.auth.resetPasswordForEmail(email, {
+      redirectTo: `${window.location.origin}/auth/callback?next=/reset-password`,
+    });
+
+    if (error) {
+      setError(error.message);
+      setLoading(false);
+      return;
+    }
+
+    setSuccess(true);
+    setLoading(false);
+  };
+
+  if (success) {
+    return (
+      <div className="min-h-screen flex items-center justify-center bg-gray-50 py-12 px-4">
+        <div className="max-w-md w-full text-center">
+          <div className="bg-green-50 border border-green-200 rounded-lg p-6">
+            <h2 className="text-xl font-bold text-green-800 mb-2">Check your email</h2>
+            <p className="text-green-700">
+              If an account exists with that email, we&apos;ve sent password reset instructions.
+            </p>
+          </div>
+          <Link href="/login" className="mt-4 inline-block text-blue-600 hover:text-blue-500">
+            Back to login
+          </Link>
+        </div>
+      </div>
+    );
+  }
+
+  return (
+    <div className="min-h-screen flex items-center justify-center bg-gray-50 py-12 px-4 sm:px-6 lg:px-8">
+      <div className="max-w-md w-full space-y-8">
+        <div>
+          <h2 className="mt-6 text-center text-3xl font-bold tracking-tight text-gray-900">
+            Reset your password
+          </h2>
+          <p className="mt-2 text-center text-sm text-gray-600">
+            Enter your email and we&apos;ll send you a reset link.
+          </p>
+        </div>
+        <form method="post" className="mt-8 space-y-6" onSubmit={handleSubmit}>
+          {error && (
+            <div className="bg-red-50 border border-red-200 text-red-600 px-4 py-3 rounded-lg text-sm">
+              {error}
+            </div>
+          )}
+          <div>
+            <label htmlFor="email" className="block text-sm font-medium text-gray-700">
+              Email address
+            </label>
+            <input
+              id="email"
+              name="email"
+              type="email"
+              autoComplete="email"
+              required
+              value={email}
+              onChange={(e) => setEmail(e.target.value)}
+              className="mt-1 block w-full px-3 py-2 border border-gray-300 rounded-lg shadow-sm focus:outline-none focus:ring-blue-500 focus:border-blue-500"
+            />
+          </div>
+
+          <button
+            type="submit"
+            disabled={loading}
+            className="w-full flex justify-center py-2 px-4 border border-transparent rounded-lg shadow-sm text-sm font-medium text-white bg-blue-600 hover:bg-blue-700 focus:outline-none focus:ring-2 focus:ring-offset-2 focus:ring-blue-500 disabled:opacity-50 disabled:cursor-not-allowed"
+          >
+            {loading ? "Sending..." : "Send reset link"}
+          </button>
+
+          <div className="text-center">
+            <Link href="/login" className="text-sm text-blue-600 hover:text-blue-500">
+              Back to login
+            </Link>
+          </div>
+        </form>
+      </div>
+    </div>
+  );
+}

package/bundles/nextjs-saas/app/(auth)/layout.tsx

@@ -0,0 +1,7 @@
+export default function AuthLayout({
+  children,
+}: {
+  children: React.ReactNode;
+}) {
+  return <>{children}</>;
+}