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

package/bundles/expo-mobile/PROJECT_GUIDE.md

@@ -0,0 +1,299 @@
+# Mobile App Starter — Project Guide
+
+This is your project guide for building a mobile app with Expo, React Native, and Supabase.
+
+## Stack Overview
+
+| Layer | Technology | Purpose |
+|-------|------------|---------|
+| Framework | Expo SDK | Managed workflow, EAS Build |
+| Navigation | Expo Router | File-based routing |
+| Backend | Supabase | Auth, Database, Realtime |
+| Analytics | PostHog | Product analytics |
+| Monitoring | Sentry | Crash reporting |
+
+**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. For Expo specifically, use tilde (`~`) versioning as shown in package.json.
+
+## Project Structure
+
+```
+├── app/
+│   ├── (auth)/
+│   │   ├── login.tsx
+│   │   ├── signup.tsx
+│   │   └── _layout.tsx
+│   ├── (tabs)/
+│   │   ├── index.tsx
+│   │   ├── profile.tsx
+│   │   └── _layout.tsx
+│   ├── _layout.tsx
+│   └── index.tsx
+├── components/
+│   ├── ui/
+│   ├── auth/
+│   └── common/
+├── lib/
+│   ├── supabase.ts
+│   ├── auth.tsx
+│   └── utils.ts
+├── hooks/
+│   └── useAuth.ts
+├── types/
+│   └── database.ts
+└── app.json
+```
+
+---
+
+## Phase 1: Foundation (Days 1-2)
+
+### Goal
+Set up the project with authentication and navigation.
+
+### Tasks
+
+1. **Configure Expo project**
+   - Update `app.json` with app name, slug, icons
+   - Configure EAS Build: `eas init`
+   - Set up environment variables
+
+2. **Initialize Supabase client**
+   - Create `lib/supabase.ts`
+   - Configure secure token storage with `expo-secure-store`
+   - Set up auth state listener
+
+3. **Create auth flow**
+   - Login screen with email/password
+   - Signup screen with email verification
+   - Auth context provider
+
+4. **Set up navigation**
+   - Tab navigation for main app
+   - Auth stack for login/signup
+   - Protected routes
+
+### Acceptance Criteria
+
+- [ ] User can sign up with email
+- [ ] User can log in
+- [ ] App navigates to tabs after login
+- [ ] `npm run verify` passes
+
+---
+
+## Phase 2: Core Navigation & UI (Days 3-4)
+
+### Goal
+Build the main app structure and navigation.
+
+### Tasks
+
+1. **Create tab screens**
+   - Home tab with main content
+   - Profile tab with user info
+   - Additional tabs as needed
+
+2. **Build common components**
+   - Button, Input, Card components
+   - Loading spinner
+   - Error boundary
+
+3. **Add pull-to-refresh**
+   - RefreshControl on scrollable screens
+   - Loading states
+
+4. **Handle deep links**
+   - Configure `expo-linking`
+   - Handle auth callback URLs
+
+### Acceptance Criteria
+
+- [ ] Tab navigation works smoothly
+- [ ] Components are reusable
+- [ ] Deep links work for auth
+- [ ] `npm run verify` passes
+
+---
+
+## Phase 3: Data & Sync (Days 5-7)
+
+### Goal
+Implement data layer and offline support.
+
+### Tasks
+
+1. **Design database schema**
+   - User profiles table
+   - Your core domain tables
+   - Row Level Security policies
+
+2. **Create data hooks**
+   - `useQuery` pattern for fetching
+   - `useMutation` pattern for updates
+   - Optimistic updates
+
+3. **Add real-time subscriptions**
+   - Supabase Realtime for live data
+   - Presence for online users (if needed)
+
+4. **Handle offline state**
+   - Detect network status
+   - Queue mutations when offline
+   - Sync when back online
+
+### Acceptance Criteria
+
+- [ ] Data loads correctly
+- [ ] Real-time updates work
+- [ ] Offline mode is graceful
+- [ ] `npm run verify` passes
+
+---
+
+## 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
+   - Screens needed
+   - Data model changes
+
+2. **Feature B: [Name]**
+   - Description
+   - Screens needed
+   - Data model changes
+
+### Acceptance Criteria
+
+- [ ] Core user flow works end-to-end
+- [ ] Edge cases handled
+- [ ] Loading and error states clear
+- [ ] `npm run verify` passes
+
+---
+
+## Phase 5: Polish & Launch (Days 15-21)
+
+### Goal
+Production-ready with monitoring and app store submission.
+
+### Tasks
+
+1. **Add Sentry crash reporting**
+   - Configure `@sentry/react-native`
+   - Test error reporting
+   - Add breadcrumbs for debugging
+
+2. **Add PostHog analytics**
+   - Initialize with `posthog-react-native`
+   - Track key events
+   - Set up user identification
+
+3. **App Store preparation**
+   - App icons and splash screen
+   - App Store screenshots
+   - Privacy policy URL
+   - App description and keywords
+
+4. **Build and submit**
+   - `eas build --platform all`
+   - `eas submit --platform ios`
+   - `eas submit --platform android`
+
+5. **Performance optimization**
+   - Profile with React DevTools
+   - Optimize list rendering
+   - Reduce bundle size
+
+### Acceptance Criteria
+
+- [ ] Sentry captures crashes
+- [ ] PostHog tracks events
+- [ ] App builds successfully
+- [ ] `npm run release-check` passes
+
+---
+
+## Environment Variables
+
+Create `.env` with:
+
+```bash
+# Supabase
+EXPO_PUBLIC_SUPABASE_URL=your-project-url
+EXPO_PUBLIC_SUPABASE_ANON_KEY=your-anon-key
+
+# PostHog
+EXPO_PUBLIC_POSTHOG_KEY=phc_...
+EXPO_PUBLIC_POSTHOG_HOST=https://app.posthog.com
+
+# Sentry
+SENTRY_DSN=https://...@sentry.io/...
+```
+
+---
+
+## EAS Configuration
+
+Create `eas.json`:
+
+```json
+{
+  "cli": {
+    "version": ">= 3.0.0"
+  },
+  "build": {
+    "development": {
+      "developmentClient": true,
+      "distribution": "internal"
+    },
+    "preview": {
+      "distribution": "internal"
+    },
+    "production": {}
+  },
+  "submit": {
+    "production": {}
+  }
+}
+```
+
+---
+
+## Recommended Resources
+
+- [Expo Router Docs](https://docs.expo.dev/router/introduction/)
+- [Supabase React Native](https://supabase.com/docs/guides/getting-started/tutorials/with-expo-react-native)
+- [EAS Build](https://docs.expo.dev/build/introduction/)
+- [PostHog React Native](https://posthog.com/docs/libraries/react-native)
+- [Sentry React Native](https://docs.sentry.io/platforms/react-native/)
+
+---
+
+## Verification Commands
+
+```bash
+# Run all checks
+npm run verify
+
+# Individual checks
+npm run lint
+npm run typecheck
+npm run test
+
+# Build for testing
+eas build --platform all --profile preview
+
+# Production readiness
+npm run release-check
+```
+
+---
+
+*Generated by Lattice — AI workers are fast. Lattice keeps them building right.*

package/bundles/expo-mobile/README.md

@@ -0,0 +1,39 @@
+# Mobile App Starter
+
+Built with [Lattice Project Builder](https://latticeai.app).
+
+## Getting Started
+
+1. Install dependencies:
+   ```bash
+   npm install
+   ```
+
+2. Review `.env.example` and add only the variables you need.
+
+3. Start development:
+   ```bash
+   npm start
+   ```
+
+## 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
+- PostHog initialization
+- Sentry runtime initialization and error boundary
+
+## Commands
+
+| Command | Description |
+|---------|-------------|
+| `npm start` | Start Expo dev server |
+| `npm run ios` | Run on iOS simulator |
+| `npm run android` | Run on Android emulator |
+| `npm run lint` | Run ESLint |
+| `npm run typecheck` | Run TypeScript checks |
+| `npm run test` | Run tests |
+| `npm run verify` | Run all checks |

package/bundles/expo-mobile/__tests__/home.test.tsx

@@ -0,0 +1,22 @@
+import { render, screen, fireEvent, waitFor } from "@testing-library/react-native";
+import { Alert } from "react-native";
+import HomeScreen from "../app/index";
+import { supabase } from "../lib/supabase/client";
+
+jest.mock("../lib/supabase/client", () => ({supabase: {auth: {
+  getSession: jest.fn().mockResolvedValue({data:{session:null}}),
+  onAuthStateChange: jest.fn(() => ({data:{subscription:{unsubscribe:jest.fn()}}})),
+  signInWithPassword: jest.fn(), signUp: jest.fn(), signOut: jest.fn(),
+}}}));
+
+it("recovers from an offline sign-in and lets the user retry", async () => {
+  const alert=jest.spyOn(Alert,"alert").mockImplementation(() => {});
+  jest.mocked(supabase.auth.signInWithPassword).mockRejectedValueOnce(new Error("Offline"));
+  await render(<HomeScreen />);
+  await fireEvent.changeText(screen.getByLabelText("Email"),"qa@example.test");
+  await fireEvent.changeText(screen.getByLabelText("Password"),"synthetic-password");
+  await fireEvent.press(screen.getByRole("button",{name:"Sign in"}));
+  await waitFor(() => expect(alert).toHaveBeenCalledWith("Authentication failed","Offline"));
+  expect(screen.getByRole("button",{name:"Sign in"})).toBeEnabled();
+  alert.mockRestore();
+});

package/bundles/expo-mobile/app/_layout.tsx

@@ -0,0 +1,20 @@
+import { Stack } from "expo-router";
+import { PostHogProvider } from "posthog-react-native";
+import * as Sentry from "@sentry/react-native";
+
+Sentry.init({
+  dsn: process.env.EXPO_PUBLIC_SENTRY_DSN,
+  enabled: Boolean(process.env.EXPO_PUBLIC_SENTRY_DSN),
+  tracesSampleRate: __DEV__ ? 1 : 0.1,
+});
+
+function RootLayout() {
+  return (<PostHogProvider
+      apiKey={process.env.EXPO_PUBLIC_POSTHOG_PROJECT_TOKEN || ""}
+      options={{ host: process.env.EXPO_PUBLIC_POSTHOG_HOST || "https://us.i.posthog.com" }}
+    >
+      <Stack />
+    </PostHogProvider>);
+}
+
+export default Sentry.wrap(RootLayout);

package/bundles/expo-mobile/app/index.tsx

@@ -0,0 +1,72 @@
+import { useEffect, useState } from "react";
+import { Alert, Pressable, SafeAreaView, StyleSheet, Text, TextInput, View } from "react-native";
+import type { Session } from "@supabase/supabase-js";
+import { supabase } from "@/lib/supabase/client";
+
+export default function HomeScreen() {
+  const [session, setSession] = useState<Session | null>(null);
+  const [email, setEmail] = useState("");
+  const [password, setPassword] = useState("");
+  const [loading, setLoading] = useState(false);
+
+  useEffect(() => {
+    void supabase.auth.getSession().then(({ data }) => setSession(data.session));
+    const { data } = supabase.auth.onAuthStateChange((_event, nextSession) => setSession(nextSession));
+    return () => data.subscription.unsubscribe();
+  }, []);
+
+  async function authenticate(mode: "signin" | "signup") {
+    setLoading(true);
+    try {
+    const result = mode === "signin"
+      ? await supabase.auth.signInWithPassword({ email, password })
+      : await supabase.auth.signUp({ email, password });
+    if (result.error) Alert.alert("Authentication failed", result.error.message);
+    } catch (error) {
+      Alert.alert("Authentication failed", error instanceof Error ? error.message : "Please try again.");
+    } finally {
+      setLoading(false);
+    }
+  }
+
+  return (
+    <SafeAreaView style={styles.screen}>
+      <View style={styles.card}>
+        <Text style={styles.eyebrow}>Lattice Project Builder</Text>
+        <Text style={styles.title}>Mobile App Starter</Text>
+        {session ? (
+          <>
+            <Text style={styles.body}>Signed in as {session.user.email}</Text>
+            <Pressable accessibilityRole="button" style={styles.primary} onPress={() => void supabase.auth.signOut()}>
+              <Text style={styles.primaryText}>Sign out</Text>
+            </Pressable>
+          </>
+        ) : (
+          <>
+            <TextInput accessibilityLabel="Email" autoCapitalize="none" keyboardType="email-address" onChangeText={setEmail} placeholder="Email" style={styles.input} value={email} />
+            <TextInput accessibilityLabel="Password" onChangeText={setPassword} placeholder="Password" secureTextEntry style={styles.input} value={password} />
+            <Pressable accessibilityRole="button" disabled={loading} style={styles.primary} onPress={() => void authenticate("signin")}>
+              <Text style={styles.primaryText}>{loading ? "Working..." : "Sign in"}</Text>
+            </Pressable>
+            <Pressable accessibilityRole="button" disabled={loading} style={styles.secondary} onPress={() => void authenticate("signup")}>
+              <Text style={styles.secondaryText}>Create account</Text>
+            </Pressable>
+          </>
+        )}
+      </View>
+    </SafeAreaView>
+  );
+}
+
+const styles = StyleSheet.create({
+  screen: { flex: 1, justifyContent: "center", backgroundColor: "#f8fafc", padding: 24 },
+  card: { gap: 14, borderRadius: 8, backgroundColor: "#fff", padding: 24 },
+  eyebrow: { color: "#1d4ed8", fontSize: 13, fontWeight: "700" },
+  title: { color: "#0f172a", fontSize: 30, fontWeight: "700" },
+  body: { color: "#475569", fontSize: 16 },
+  input: { borderWidth: 1, borderColor: "#cbd5e1", borderRadius: 6, padding: 12 },
+  primary: { alignItems: "center", borderRadius: 6, backgroundColor: "#2563eb", padding: 13 },
+  primaryText: { color: "#fff", fontWeight: "700" },
+  secondary: { alignItems: "center", borderRadius: 6, borderWidth: 1, borderColor: "#2563eb", padding: 13 },
+  secondaryText: { color: "#1d4ed8", fontWeight: "700" },
+});

package/bundles/expo-mobile/app.json

@@ -0,0 +1,33 @@
+{
+  "expo": {
+    "name": "Mobile App Starter",
+    "slug": "mobile-app-starter",
+    "version": "1.0.0",
+    "orientation": "portrait",
+    "scheme": "mobile-app-starter",
+    "userInterfaceStyle": "automatic",
+    "ios": {
+      "bundleIdentifier": "com.mobileappstarter.app",
+      "supportsTablet": true
+    },
+    "android": {
+      "package": "com.mobileappstarter.app",
+      "adaptiveIcon": {
+        "backgroundColor": "#ffffff"
+      }
+    },
+    "web": {
+      "bundler": "metro",
+      "output": "static"
+    },
+    "plugins": [
+      "expo-router",
+      "expo-secure-store",
+      "@sentry/react-native/expo",
+      "./plugins/with-lattice-commons-io"
+    ],
+    "experiments": {
+      "typedRoutes": true
+    }
+  }
+}

package/bundles/expo-mobile/components/ui/Button.tsx

@@ -0,0 +1,75 @@
+import { Pressable, Text, StyleSheet, ActivityIndicator } from "react-native";
+
+interface ButtonProps {
+  title: string;
+  onPress: () => void;
+  variant?: "default" | "outline" | "destructive";
+  disabled?: boolean;
+  loading?: boolean;
+}
+
+export function Button({
+  title,
+  onPress,
+  variant = "default",
+  disabled,
+  loading,
+}: ButtonProps) {
+  const isDisabled = disabled || loading;
+
+  return (
+    <Pressable
+      style={[
+        styles.button,
+        variant === "outline" && styles.outline,
+        variant === "destructive" && styles.destructive,
+        isDisabled && styles.disabled,
+      ]}
+      onPress={onPress}
+      disabled={isDisabled}
+    >
+      {loading ? (
+        <ActivityIndicator color={variant === "outline" ? "#3b82f6" : "#fff"} />
+      ) : (
+        <Text
+          style={[
+            styles.text,
+            variant === "outline" && styles.outlineText,
+          ]}
+        >
+          {title}
+        </Text>
+      )}
+    </Pressable>
+  );
+}
+
+const styles = StyleSheet.create({
+  button: {
+    backgroundColor: "#3b82f6",
+    paddingVertical: 12,
+    paddingHorizontal: 24,
+    borderRadius: 8,
+    alignItems: "center",
+    justifyContent: "center",
+  },
+  outline: {
+    backgroundColor: "transparent",
+    borderWidth: 1,
+    borderColor: "#3b82f6",
+  },
+  destructive: {
+    backgroundColor: "#ef4444",
+  },
+  disabled: {
+    opacity: 0.5,
+  },
+  text: {
+    color: "#fff",
+    fontSize: 16,
+    fontWeight: "600",
+  },
+  outlineText: {
+    color: "#3b82f6",
+  },
+});

package/bundles/expo-mobile/components/ui/Input.tsx

@@ -0,0 +1,50 @@
+import { TextInput, View, Text, StyleSheet, TextInputProps } from "react-native";
+
+interface InputProps extends TextInputProps {
+  label?: string;
+  error?: string;
+}
+
+export function Input({ label, error, style, ...props }: InputProps) {
+  return (
+    <View style={styles.container}>
+      {label && <Text style={styles.label}>{label}</Text>}
+      <TextInput
+        style={[styles.input, error && styles.inputError, style]}
+        placeholderTextColor="#9ca3af"
+        {...props}
+      />
+      {error && <Text style={styles.error}>{error}</Text>}
+    </View>
+  );
+}
+
+const styles = StyleSheet.create({
+  container: {
+    marginBottom: 16,
+  },
+  label: {
+    fontSize: 14,
+    fontWeight: "500",
+    color: "#374151",
+    marginBottom: 4,
+  },
+  input: {
+    borderWidth: 1,
+    borderColor: "#d1d5db",
+    borderRadius: 8,
+    paddingHorizontal: 12,
+    paddingVertical: 10,
+    fontSize: 16,
+    color: "#111827",
+    backgroundColor: "#fff",
+  },
+  inputError: {
+    borderColor: "#ef4444",
+  },
+  error: {
+    fontSize: 12,
+    color: "#ef4444",
+    marginTop: 4,
+  },
+});

package/bundles/expo-mobile/components/ui/index.ts

@@ -0,0 +1,2 @@
+export { Button } from "./Button";
+export { Input } from "./Input";

package/bundles/expo-mobile/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.