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

package/bundles/nextjs-saas/docs/LATTICE_RELEASE_WORKFLOW.md

@@ -0,0 +1,53 @@
+# Lattice Release Workflow
+
+This repository uses a portable feature-to-release contract. It coordinates work across Codex, Claude Code, GitHub Copilot, Cursor, and other tools without assuming that every provider has direct peer messaging.
+
+## Source of Truth
+
+- Policy: `.lattice/release-workflow.json`
+- Handoff schema: `.lattice/schemas/feature-handoff.schema.json`
+- Handoff template: `.lattice/templates/feature-handoff.json`
+- Feature procedure: `.agents/skills/lattice-feature-handoff/SKILL.md`
+- Release review procedure: `.agents/skills/lattice-release-manager/SKILL.md`
+- Mutable local state: `.lattice/runtime/` (Git-ignored)
+
+Stable instructions define roles and contracts. Live task IDs, production SHAs, deployment IDs, and provider state belong in current handoffs or ignored runtime state.
+
+## Workflow
+
+1. **Feature work** — A feature agent starts from an approved base in an isolated worktree, implements only the assigned scope, and runs proportionate checks.
+2. **Handoff** — The feature agent records exact base/head SHAs, diff scope, verification, operational impacts, risks, and approvals in the JSON handoff.
+3. **Release audit** — The Release Manager independently resolves the repository and reviews the exact candidate. The manager accepts for owner approval, requests rework, or blocks.
+4. **Candidate preparation** — A release candidate may be prepared only after its constituent handoffs pass review.
+5. **Owner approval** — Production promotion, migrations, provider/account writes, secret or environment changes, and destructive actions require explicit owner approval.
+6. **Deployment and live proof** — Deployment and live verification are separate states. A successful build or preview is not a production release.
+7. **Cleanup** — Feature worktrees and branches are cleaned only after the authorized candidate is proven live and rollback evidence is current.
+
+## Transport
+
+Use the narrowest available transport:
+
+1. A native task message when the environment exposes the capability and the exact destination is bound.
+2. The shared GitHub issue, pull request, or comment.
+3. The versioned handoff artifact, with its exact path surfaced to the owner.
+
+Never claim that a handoff was delivered unless the transport returned evidence. The message is notification; the handoff is the durable evidence.
+
+## Status Meanings
+
+- `READY_FOR_RELEASE`: ready for independent Release Manager review.
+- `NEEDS_REWORK`: a confirmed defect, failed gate, incomplete proof, or scope mismatch remains.
+- `BLOCKED`: lineage, authority, environment, or another prerequisite prevents safe progress.
+
+None of these statuses means merged, deployed, released, or live.
+
+## Provider Adapters
+
+- **Codex:** project custom agents in `.codex/agents/` plus the shared skills.
+- **Claude Code:** project subagents in `.claude/agents/`; the feature role requests worktree isolation.
+- **GitHub Copilot:** custom agents in `.github/agents/`; issues, pull requests, and comments are the portable control plane.
+- **Cursor:** shared `AGENTS.md`, `.cursor/rules.md`, and `.agents/skills/`. Native peer messaging is not required by this contract.
+
+## Secret and Data Boundary
+
+Do not put credentials, tokens, private keys, payment data, direct personal contact data, or secret values in a handoff. Name an environment variable or provider surface when needed; do not copy its value.

package/bundles/nextjs-saas/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-saas/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-saas/instrumentation-client.ts

@@ -0,0 +1,30 @@
+import * as Sentry from "@sentry/nextjs";
+import posthog from "posthog-js";
+
+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()],
+  });
+}
+
+if (process.env.NEXT_PUBLIC_POSTHOG_PROJECT_TOKEN) {
+  posthog.init(process.env.NEXT_PUBLIC_POSTHOG_PROJECT_TOKEN, {
+    api_host: process.env.NEXT_PUBLIC_POSTHOG_HOST || "https://us.i.posthog.com",
+    defaults: "2026-05-30",
+    capture_pageview: "history_change",
+    capture_pageleave: true,
+  });
+}
+
+export const onRouterTransitionStart = Sentry.captureRouterTransitionStart;

package/bundles/nextjs-saas/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-saas/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-saas/jest.setup.js

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

package/bundles/nextjs-saas/lib/auth/password-recovery.ts

@@ -0,0 +1,94 @@
+export interface PasswordRecoveryAuth {
+  getUser(): Promise<{ data: { user: unknown | null }; error: { message?: string } | null }>;
+  updateUser(attributes: { password: string }): Promise<{ error: { message?: string } | null }>;
+}
+
+export type PasswordRecoveryResult =
+  | { ok: true }
+  | { ok: false; reason: "mismatch" | "weak-password" | "invalid-session" | "update-failed"; message: string };
+
+const INVALID_SESSION_MESSAGE = "This password reset link is invalid or expired. Request a new one.";
+const UPDATE_FAILED_MESSAGE = "We couldn't update your password. Request a new reset link and try again.";
+
+export function safeInternalRedirectPath(value: string | null, fallback = "/dashboard"): string {
+  if (!value) return fallback;
+  try {
+    const base = new URL("https://lattice.local");
+    const parsed = new URL(value, base);
+    if (parsed.origin !== base.origin || !value.startsWith("/") || value.startsWith("//")) return fallback;
+    return parsed.pathname + parsed.search + parsed.hash;
+  } catch {
+    return fallback;
+  }
+}
+
+export function isPasswordRecoveryRedirectPath(value: string | null): boolean {
+  const safePath = safeInternalRedirectPath(value, "");
+  if (!safePath) return false;
+
+  try {
+    return new URL(safePath, "https://lattice.local").pathname === "/reset-password";
+  } catch {
+    return false;
+  }
+}
+
+export function authCallbackFailureRedirectPath(next: string | null): string {
+  return isPasswordRecoveryRedirectPath(next)
+    ? "/reset-password?recovery_error=1"
+    : "/login?error=auth_callback_failed";
+}
+
+export async function resolveAuthCallbackRedirectPath(
+  code: string | null,
+  next: string | null,
+  exchangeCodeForSession: (code: string) => Promise<{ error: unknown }>,
+): Promise<string> {
+  if (code) {
+    try {
+      const { error } = await exchangeCodeForSession(code);
+      if (!error) return safeInternalRedirectPath(next);
+    } catch {
+      // Use the same bounded failure destination for provider and transport errors.
+    }
+  }
+
+  return authCallbackFailureRedirectPath(next);
+}
+
+export function hasPasswordRecoveryCallbackError(search: string): boolean {
+  return new URLSearchParams(search).get("recovery_error") === "1";
+}
+
+export async function hasValidPasswordRecoverySession(auth: PasswordRecoveryAuth): Promise<boolean> {
+  try {
+    const { data, error } = await auth.getUser();
+    return !error && !!data.user;
+  } catch {
+    return false;
+  }
+}
+
+export async function updateRecoveredPassword(
+  auth: PasswordRecoveryAuth,
+  password: string,
+  confirmation: string,
+): Promise<PasswordRecoveryResult> {
+  if (password !== confirmation) {
+    return { ok: false, reason: "mismatch", message: "Passwords do not match." };
+  }
+  if (password.length < 8) {
+    return { ok: false, reason: "weak-password", message: "Password must be at least 8 characters." };
+  }
+  if (!(await hasValidPasswordRecoverySession(auth))) {
+    return { ok: false, reason: "invalid-session", message: INVALID_SESSION_MESSAGE };
+  }
+
+  try {
+    const { error } = await auth.updateUser({ password });
+    if (error) return { ok: false, reason: "update-failed", message: UPDATE_FAILED_MESSAGE };
+    return { ok: true };
+  } catch {
+    return { ok: false, reason: "update-failed", message: UPDATE_FAILED_MESSAGE };
+  }
+}

package/bundles/nextjs-saas/lib/stripe.ts

@@ -0,0 +1,10 @@
+import Stripe from "stripe";
+
+let stripeClient: Stripe | undefined;
+
+export function getStripe() {
+  const secretKey = process.env.STRIPE_SECRET_KEY;
+  if (!secretKey) throw new Error("STRIPE_SECRET_KEY is required");
+  stripeClient ??= new Stripe(secretKey);
+  return stripeClient;
+}

package/bundles/nextjs-saas/lib/supabase/admin.ts

@@ -0,0 +1,14 @@
+import { createClient, type SupabaseClient } from "@supabase/supabase-js";
+import type { Database } from "@/types/database.types";
+
+let adminClient: SupabaseClient<Database> | undefined;
+
+export function getSupabaseAdmin() {
+  const url = process.env.NEXT_PUBLIC_SUPABASE_URL;
+  const serviceRoleKey = process.env.SUPABASE_SERVICE_ROLE_KEY;
+  if (!url || !serviceRoleKey) throw new Error("Supabase service-role configuration is required");
+  adminClient ??= createClient<Database>(url, serviceRoleKey, {
+    auth: { autoRefreshToken: false, persistSession: false },
+  });
+  return adminClient;
+}

package/bundles/nextjs-saas/lib/supabase/client.ts

@@ -0,0 +1,8 @@
+import { createBrowserClient } from "@supabase/ssr";
+
+export function createClient() {
+  return createBrowserClient(
+    process.env.NEXT_PUBLIC_SUPABASE_URL!,
+    process.env.NEXT_PUBLIC_SUPABASE_ANON_KEY!
+  );
+}

package/bundles/nextjs-saas/lib/supabase/server.ts

@@ -0,0 +1,27 @@
+import { createServerClient } from "@supabase/ssr";
+import { cookies } from "next/headers";
+
+export async function createClient() {
+  const cookieStore = await cookies();
+
+  return createServerClient(
+    process.env.NEXT_PUBLIC_SUPABASE_URL!,
+    process.env.NEXT_PUBLIC_SUPABASE_ANON_KEY!,
+    {
+      cookies: {
+        getAll() {
+          return cookieStore.getAll();
+        },
+        setAll(cookiesToSet) {
+          try {
+            cookiesToSet.forEach(({ name, value, options }) =>
+              cookieStore.set(name, value, options)
+            );
+          } catch {
+            // Called from Server Component - ignore
+          }
+        },
+      },
+    }
+  );
+}

package/bundles/nextjs-saas/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-saas/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-saas/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-saas/package.json

@@ -0,0 +1,50 @@
+{
+  "name": "saas-starter",
+  "version": "0.1.0",
+  "private": true,
+  "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"
+  },
+  "dependencies": {
+    "next": "16.4.2",
+    "react": "19.3.1",
+    "react-dom": "19.3.1",
+    "clsx": "^2.1.1",
+    "tailwind-merge": "^3.4.0",
+    "@supabase/supabase-js": "^2.118.0",
+    "@supabase/ssr": "^0.12.7",
+    "stripe": "23.0.0",
+    "posthog-js": "1.438.12",
+    "@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"
+  },
+  "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-saas/postcss.config.mjs

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

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

@@ -0,0 +1,92 @@
+# Prompt Recipe: Feature Implementation
+
+Use this prompt when adding a new feature to your SaaS app.
+
+---
+
+## Template
+
+```
+Role: You are maintaining this Next.js SaaS application.
+
+Goal: Implement [FEATURE NAME] that allows users to [USER GOAL].
+
+Constraints:
+- Use Next.js 15 App Router with Server Components where possible
+- Use Supabase for database operations
+- Follow existing patterns in the codebase
+- Keep components small and focused
+- Use TypeScript strict mode
+
+Context:
+- Database schema: [RELEVANT TABLES]
+- Existing components: [RELATED COMPONENTS]
+- API routes: [RELATED ENDPOINTS]
+
+Files that CAN change:
+- app/[path]/page.tsx
+- components/[name].tsx
+- lib/[module].ts
+
+Files that MUST NOT change:
+- lib/supabase/client.ts (auth config)
+- middleware.ts (unless adding routes)
+
+Acceptance Criteria:
+- [ ] [CRITERION 1]
+- [ ] [CRITERION 2]
+- [ ] [CRITERION 3]
+- [ ] `npm run verify` passes
+
+Non-goals:
+- Do not add new dependencies without asking
+- Do not refactor unrelated code
+- Do not add features beyond the scope
+
+Deliverable: Working implementation with brief summary of changes.
+```
+
+---
+
+## Example
+
+```
+Role: You are maintaining this Next.js SaaS application.
+
+Goal: Implement a "Team Invites" feature that allows users to invite team members via email.
+
+Constraints:
+- Use Next.js 15 App Router with Server Components where possible
+- Use Supabase for database operations
+- Follow existing patterns in the codebase
+- Keep components small and focused
+- Use TypeScript strict mode
+
+Context:
+- Database schema: users, teams, team_members tables
+- Existing components: TeamList, MemberCard
+- API routes: /api/teams/[id]
+
+Files that CAN change:
+- app/(dashboard)/team/invite/page.tsx
+- components/team/InviteForm.tsx
+- lib/teams.ts
+
+Files that MUST NOT change:
+- lib/supabase/client.ts
+- middleware.ts
+
+Acceptance Criteria:
+- [ ] User can enter email and send invite
+- [ ] Invite creates pending record in team_members
+- [ ] Email is sent via Supabase Edge Function
+- [ ] Invited user sees pending invite on signup
+- [ ] `npm run verify` passes
+
+Non-goals:
+- Do not implement role-based permissions yet
+- Do not add bulk invite functionality
+- Do not refactor existing team code
+
+Deliverable: Working implementation with brief summary of changes.
+```

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

@@ -0,0 +1,78 @@
+# Prompt Recipe: Bug Fix
+
+Use this prompt when fixing a bug with a clear reproduction.
+
+---
+
+## Template
+
+```
+Role: You are debugging this Next.js SaaS application.
+
+Bug: [DESCRIBE THE BUG]
+
+Reproduction Steps:
+1. [STEP 1]
+2. [STEP 2]
+3. [STEP 3]
+
+Expected: [WHAT SHOULD HAPPEN]
+Actual: [WHAT HAPPENS INSTEAD]
+
+Error (if any):
+[PASTE ERROR MESSAGE OR STACK TRACE]
+
+Suspected Files:
+- [FILE 1]
+- [FILE 2]
+
+Constraints:
+- Fix only the bug, do not refactor
+- Keep the diff minimal
+- Add a test if the fix is non-trivial
+
+Acceptance Criteria:
+- [ ] Bug no longer reproduces
+- [ ] No regression in related functionality
+- [ ] `npm run verify` passes
+
+Deliverable: Minimal fix with explanation of root cause.
+```
+
+---
+
+## Example
+
+```
+Role: You are debugging this Next.js SaaS application.
+
+Bug: Users are logged out after page refresh on the dashboard.
+
+Reproduction Steps:
+1. Log in with email/password
+2. Navigate to /dashboard
+3. Refresh the page (F5)
+4. User is redirected to /login
+
+Expected: User remains logged in after refresh.
+Actual: User is redirected to login page.
+
+Error (if any):
+Console shows: "Auth session missing"
+
+Suspected Files:
+- middleware.ts
+- lib/supabase/server.ts
+
+Constraints:
+- Fix only the bug, do not refactor
+- Keep the diff minimal
+- Add a test if the fix is non-trivial
+
+Acceptance Criteria:
+- [ ] User stays logged in after refresh
+- [ ] Session persists across tabs
+- [ ] `npm run verify` passes
+
+Deliverable: Minimal fix with explanation of root cause.
+```