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

package/bundles/expo-mobile/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**: Expo
+- **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/expo-mobile/eslint.config.js

@@ -0,0 +1,7 @@
+const { defineConfig, globalIgnores } = require("eslint/config");
+const expoConfig = require("eslint-config-expo/flat");
+
+module.exports = defineConfig([
+  globalIgnores(["dist/*"]),
+  expoConfig,
+]);

package/bundles/expo-mobile/lib/supabase/client.ts

@@ -0,0 +1,22 @@
+import "react-native-url-polyfill/auto";
+import { createClient } from "@supabase/supabase-js";
+import * as SecureStore from "expo-secure-store";
+
+const url = process.env.EXPO_PUBLIC_SUPABASE_URL;
+const anonKey = process.env.EXPO_PUBLIC_SUPABASE_ANON_KEY;
+if (!url || !anonKey) throw new Error("Expo Supabase environment variables are required");
+
+const secureStorage = {
+  getItem: (key: string) => SecureStore.getItemAsync(key),
+  setItem: (key: string, value: string) => SecureStore.setItemAsync(key, value),
+  removeItem: (key: string) => SecureStore.deleteItemAsync(key),
+};
+
+export const supabase = createClient(url, anonKey, {
+  auth: {
+    storage: secureStorage,
+    autoRefreshToken: true,
+    persistSession: true,
+    detectSessionInUrl: false,
+  },
+});

package/bundles/expo-mobile/lib/supabase/realtime.ts

@@ -0,0 +1,10 @@
+import { supabase } from "@/lib/supabase/client";
+
+export function subscribeToTable(table: string, onChange: (payload: unknown) => void) {
+  const channel = supabase
+    .channel(`public:${table}`)
+    .on("postgres_changes", { event: "*", schema: "public", table }, onChange)
+    .subscribe();
+
+  return () => void supabase.removeChannel(channel);
+}

package/bundles/expo-mobile/lib/supabase/storage.ts

@@ -0,0 +1,6 @@
+import { supabase } from "@/lib/supabase/client";
+
+export async function uploadFile(bucket: string, path: string, uri: string) {
+  const body = await fetch(uri).then((response) => response.arrayBuffer());
+  return supabase.storage.from(bucket).upload(path, body, { upsert: false });
+}

package/bundles/expo-mobile/package.json

@@ -0,0 +1,65 @@
+{
+  "name": "mobile-app-starter",
+  "version": "1.0.0",
+  "main": "expo-router/entry",
+  "scripts": {
+    "start": "expo start",
+    "android": "expo start --android",
+    "ios": "expo start --ios",
+    "web": "expo start --web",
+    "lint": "eslint .",
+    "typecheck": "tsc --noEmit",
+    "test": "jest --passWithNoTests",
+    "verify": "npm run lint && npm run typecheck && npm test"
+  },
+  "dependencies": {
+    "expo": "58.0.14",
+    "expo-router": "~58.0.20",
+    "expo-constants": "~58.0.12",
+    "expo-linking": "~58.0.13",
+    "expo-secure-store": "~58.0.2",
+    "expo-status-bar": "~58.0.3",
+    "react": "19.3.0",
+    "react-native": "0.88.0",
+    "react-native-safe-area-context": "~5.10.1",
+    "@supabase/supabase-js": "^2.118.0",
+    "react-native-url-polyfill": "^3.0.0",
+    "posthog-react-native": "4.81.2",
+    "@react-native-async-storage/async-storage": "2.2.0",
+    "expo-application": "~58.1.1",
+    "expo-device": "~58.0.5",
+    "expo-file-system": "58.0.9",
+    "expo-localization": "~58.0.4",
+    "@sentry/react-native": "8.31.0"
+  },
+  "devDependencies": {
+    "@expo/config-plugins": "~58.0.9",
+    "@types/react": "~19.3.0",
+    "typescript": "~6.0.3",
+    "eslint": "^9",
+    "eslint-config-expo": "58.0.4",
+    "jest": "^30.5.2",
+    "jest-expo": "~58.0.11",
+    "@types/jest": "^30",
+    "@testing-library/react-native": "^14.1.0",
+    "test-renderer": "^1.3.1",
+    "@react-native/jest-preset": "0.88.0",
+    "react-server-dom-webpack": "19.3.0",
+    "react-dom": "19.3.0"
+  },
+  "engines": {
+    "node": "24.x"
+  },
+  "overrides": {
+    "@istanbuljs/load-nyc-config": {
+      "js-yaml": "4.3.2"
+    },
+    "uuid@<11.1.1": "11.1.1",
+    "braces": "file:vendor/m2ai-braces-3.0.3-m2ai.1.tar",
+    "node-forge": "https://github.com/matthewscottconroy/forge/archive/db05494352dd3c9a5a07c5270333dcc78866cad2.tar.gz"
+  },
+  "jest": {
+    "preset": "jest-expo",
+    "maxWorkers": 2
+  }
+}

package/bundles/expo-mobile/plugins/with-lattice-commons-io.cjs

@@ -0,0 +1,42 @@
+const { withProjectBuildGradle } = require("@expo/config-plugins");
+
+const EXPECTED_EXPO_FILE_SYSTEM_VERSION = "58.0.9";
+const EXPECTED_REQUESTED_COMMONS_IO_VERSION = "1.4";
+const SELECTED_COMMONS_IO_VERSION = "2.14.0";
+const MARKER = "// LATTICE_COMMONS_IO_2_14_0_GUARD";
+
+const resolutionRule = `${MARKER}
+allprojects {
+  configurations.configureEach {
+    resolutionStrategy.eachDependency { details ->
+      if (details.requested.group == "commons-io" && details.requested.name == "commons-io" && details.requested.version == "${EXPECTED_REQUESTED_COMMONS_IO_VERSION}") {
+        details.useVersion("${SELECTED_COMMONS_IO_VERSION}")
+        details.because("GHSA-gwrp-pvrq-jmwv and CVE-2024-47554")
+      }
+    }
+  }
+}`;
+
+module.exports = function withLatticeCommonsIo(config) {
+  const actualVersion = require("expo-file-system/package.json").version;
+  if (actualVersion !== EXPECTED_EXPO_FILE_SYSTEM_VERSION) {
+    throw new Error(
+      `Lattice Commons IO guard requires expo-file-system ${EXPECTED_EXPO_FILE_SYSTEM_VERSION}; found ${actualVersion}. Review the native dependency before changing this guard.`,
+    );
+  }
+
+  return withProjectBuildGradle(config, (projectConfig) => {
+    if (projectConfig.modResults.language !== "groovy") {
+      throw new Error("Lattice Commons IO guard supports only the generated Groovy project build.gradle.");
+    }
+
+    const contents = projectConfig.modResults.contents;
+    if (!contents.includes(MARKER)) {
+      projectConfig.modResults.contents = `${contents.trimEnd()}
+
+${resolutionRule}
+`;
+    }
+    return projectConfig;
+  });
+};

package/bundles/expo-mobile/prompts/01-feature-implementation.md

@@ -0,0 +1,48 @@
+# Prompt Recipe: Feature Implementation
+
+Use this prompt when adding a new feature to your Expo mobile app.
+
+---
+
+## Template
+
+```
+Role: You are maintaining this Expo React Native application.
+
+Goal: Implement [FEATURE NAME] that allows users to [USER GOAL].
+
+Constraints:
+- Use Expo Router for navigation
+- Use Supabase for backend operations
+- Follow existing patterns in the codebase
+- Keep components small and focused
+- Use TypeScript strict mode
+- Test on both iOS and Android
+
+Context:
+- Database schema: [RELEVANT TABLES]
+- Existing components: [RELATED COMPONENTS]
+- Navigation: [RELATED SCREENS]
+
+Files that CAN change:
+- app/[path].tsx
+- components/[name].tsx
+- lib/[module].ts
+
+Files that MUST NOT change:
+- lib/supabase.ts (client config)
+- app/_layout.tsx (root layout)
+
+Acceptance Criteria:
+- [ ] [CRITERION 1]
+- [ ] [CRITERION 2]
+- [ ] [CRITERION 3]
+- [ ] Works on iOS and Android
+- [ ] `npm run verify` passes
+
+Non-goals:
+- Do not add new dependencies without asking
+- Do not refactor unrelated code
+
+Deliverable: Working implementation with brief summary of changes.
+```

package/bundles/expo-mobile/prompts/02-bug-fix.md

@@ -0,0 +1,43 @@
+# Prompt Recipe: Bug Fix
+
+Use this prompt when fixing a bug with a clear reproduction.
+
+---
+
+## Template
+
+```
+Role: You are debugging this Expo React Native application.
+
+Bug: [DESCRIBE THE BUG]
+
+Platform: [iOS / Android / Both]
+
+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
+- Test on both platforms if applicable
+
+Acceptance Criteria:
+- [ ] Bug no longer reproduces
+- [ ] No regression in related functionality
+- [ ] Works on iOS and Android
+- [ ] `npm run verify` passes
+
+Deliverable: Minimal fix with explanation of root cause.
+```

package/bundles/expo-mobile/prompts/03-safe-refactor.md

@@ -0,0 +1,38 @@
+# Prompt Recipe: Safe Refactor
+
+Use this prompt when refactoring without changing behavior.
+
+---
+
+## Template
+
+```
+Role: You are refactoring this Expo React Native application.
+
+Goal: [WHAT YOU WANT TO IMPROVE]
+- Current: [CURRENT STATE]
+- Target: [DESIRED STATE]
+
+Scope:
+- Files to refactor: [LIST FILES]
+- Files that must not change: [LIST FILES]
+
+Constraints:
+- Behavior must remain identical
+- Keep diffs small and reviewable
+- Test on both platforms after each change
+- Do not add new dependencies
+
+Steps:
+1. [STEP 1 - SMALL CHANGE]
+2. [STEP 2 - VERIFY STILL WORKS]
+3. [STEP 3 - NEXT SMALL CHANGE]
+
+Acceptance Criteria:
+- [ ] Behavior unchanged (test manually on device)
+- [ ] Code is cleaner/more maintainable
+- [ ] Works on iOS and Android
+- [ ] `npm run verify` passes
+
+Deliverable: Refactored code with summary of what changed and why.
+```

package/bundles/expo-mobile/prompts/04-test-first.md

@@ -0,0 +1,41 @@
+# Prompt Recipe: Test-First Development
+
+Use this prompt when you want tests written before implementation.
+
+---
+
+## Template
+
+```
+Role: You are practicing test-driven development on this Expo React Native app.
+
+Feature: [FEATURE NAME]
+
+Step 1 — Write failing tests first:
+- Test file: [PATH TO TEST FILE]
+- Test cases:
+  1. [TEST CASE 1]
+  2. [TEST CASE 2]
+  3. [TEST CASE 3]
+
+Step 2 — Implement minimal code to pass:
+- Implementation file: [PATH TO IMPLEMENTATION]
+- Keep implementation simple
+
+Step 3 — Refactor if needed:
+- Only after tests pass
+- Keep tests passing
+
+Constraints:
+- Tests must fail initially (red)
+- Implementation makes tests pass (green)
+- Only then refactor
+- Use Jest + React Native Testing Library
+
+Acceptance Criteria:
+- [ ] All tests pass
+- [ ] Tests cover happy path and edge cases
+- [ ] `npm run verify` passes
+
+Deliverable: Test file + implementation + brief summary.
+```

package/bundles/expo-mobile/prompts/05-ui-polish.md

@@ -0,0 +1,44 @@
+# Prompt Recipe: UI Polish Pass
+
+Use this prompt when polishing UI details without changing functionality.
+
+---
+
+## Template
+
+```
+Role: You are polishing the UI of this Expo React Native application.
+
+Target: [COMPONENT OR SCREEN]
+
+Polish areas:
+- [ ] Spacing and alignment
+- [ ] Typography (sizes, weights)
+- [ ] Colors and contrast
+- [ ] Loading states
+- [ ] Empty states
+- [ ] Error states
+- [ ] Touch feedback (opacity, scale)
+- [ ] Safe area handling
+- [ ] Platform-specific styling (iOS vs Android)
+
+Constraints:
+- Do not change functionality
+- Do not change component structure
+- Test on both iOS and Android
+- Test on different screen sizes
+
+Current issues:
+1. [ISSUE 1]
+2. [ISSUE 2]
+3. [ISSUE 3]
+
+Acceptance Criteria:
+- [ ] Visual issues are fixed
+- [ ] Component still functions correctly
+- [ ] Looks good on iPhone SE and iPhone 15 Pro Max
+- [ ] Looks good on small and large Android devices
+- [ ] `npm run verify` passes
+
+Deliverable: Polished component with summary of changes.
+```

package/bundles/expo-mobile/prompts/06-security-review.md

@@ -0,0 +1,39 @@
+# Prompt Recipe: Security Review
+
+Use this prompt when reviewing code for security issues.
+
+---
+
+## Template
+
+```
+Role: You are performing a security review of this Expo React Native app.
+
+Scope: [FILES OR FEATURES TO REVIEW]
+
+Check for:
+- [ ] Insecure storage (AsyncStorage for sensitive data)
+- [ ] Exposed API keys in code
+- [ ] Missing auth checks on screens
+- [ ] Insecure deep link handling
+- [ ] Certificate pinning (if applicable)
+- [ ] Supabase RLS policies
+- [ ] Input validation
+- [ ] Biometric auth implementation
+
+Focus areas:
+1. [AREA 1]
+2. [AREA 2]
+
+Constraints:
+- Do not fix issues yet, just identify
+- Rank by severity (Critical, High, Medium, Low)
+- Provide specific file and line references
+
+Output format:
+| Severity | Issue | File | Line | Recommendation |
+|----------|-------|------|------|----------------|
+| Critical | ... | ... | ... | ... |
+
+Deliverable: Security report with prioritized findings.
+```

package/bundles/expo-mobile/prompts/quality.md

@@ -0,0 +1,143 @@
+# Quality & Performance Standards
+
+## Performance Rules
+
+### Critical
+
+1. **Bundle size**
+   - Keep JavaScript bundles reasonable
+   - Use dynamic imports for code splitting
+   - Avoid large libraries when smaller alternatives exist
+   - Tree-shake unused code
+
+2. **Image optimization**
+   - Use optimized image formats
+   - Provide appropriate resolutions for devices
+   - Lazy load off-screen images
+   - Use Expo's Image component
+
+3. **Navigation performance**
+   - Minimize screen transitions
+   - Preload critical screens
+   - Avoid heavy computations in render
+
+4. **Memory management**
+   - Clean up subscriptions in useEffect
+   - Avoid memory leaks in listeners
+   - Profile with React DevTools
+
+---
+
+## Accessibility (a11y) Rules
+
+### Critical
+
+1. **Touchable elements**
+   - Minimum touch target: 44×44 points
+   - Proper feedback on press
+   - Disabled state clearly visible
+
+2. **Screen reader support**
+   - Add `accessibilityLabel` to interactive elements
+   - Use `accessibilityHint` for context
+   - Mark decorative elements with `accessibilityRole="none"`
+
+3. **Text scaling**
+   - Support Dynamic Type/font scaling
+   - Test with large text sizes
+   - Don't hard-code font sizes
+
+4. **Color contrast**
+   - Text: minimum 4.5:1 ratio
+   - Icons: minimum 3:1 ratio
+   - Test in dark mode
+
+---
+
+## Functionality & Code Quality
+
+### Critical
+
+1. **Error handling**
+   - Catch async errors
+   - Show user-friendly messages
+   - Log errors to Sentry
+
+2. **Loading states**
+   - Show spinners during async operations
+   - Skeleton screens for lists
+   - Pull-to-refresh where appropriate
+
+3. **Form validation**
+   - Client-side validation for UX
+   - Clear error messages
+   - Disable submit while processing
+
+4. **Keyboard handling**
+   - Dismiss keyboard on submit
+   - Proper keyboard types (email, number, etc.)
+   - Handle keyboard avoidance
+
+---
+
+## Security Rules
+
+### Critical
+
+1. **Secure storage**
+   - Use SecureStore for sensitive data
+   - Never store tokens in AsyncStorage
+   - Validate all API responses
+
+2. **Environment variables**
+   - Never commit secrets
+   - Use `expo-constants` for config
+   - Validate env vars on startup
+
+3. **API security**
+   - Always use HTTPS
+   - Validate SSL certificates
+   - Handle auth token expiration
+
+---
+
+## Testing Requirements
+
+### Critical
+
+1. **Unit tests**
+   - Test business logic
+   - Test custom hooks
+   - Mock external dependencies
+
+2. **Component tests**
+   - Test user interactions
+   - Test conditional rendering
+   - Test error states
+
+3. **E2E tests (optional)**
+   - Test critical user flows
+   - Test on real devices
+   - Test offline scenarios
+
+---
+
+## How AI Should Apply These Rules
+
+1. **During implementation**
+   - Follow these rules by default
+   - Add proper error handling
+   - Include loading states
+
+2. **During code review**
+   - Check for violations
+   - Suggest performance improvements
+
+3. **When debugging**
+   - Use React DevTools
+   - Check performance with Profiler
+   - Test on low-end devices
+
+---
+
+*These rules are enforced by `npm run verify:quality`. Run locally before pushing.*

package/bundles/expo-mobile/supabase/migrations/001_initial_schema.sql

@@ -0,0 +1,66 @@
+-- Initial database schema
+-- Generated by Lattice Project Builder
+
+-- Enable UUID extension
+CREATE EXTENSION IF NOT EXISTS "uuid-ossp";
+
+-- Users profile table (extends auth.users)
+CREATE TABLE IF NOT EXISTS public.profiles (
+  id UUID REFERENCES auth.users(id) ON DELETE CASCADE PRIMARY KEY,
+  email TEXT,
+  full_name TEXT,
+  avatar_url TEXT,
+  created_at TIMESTAMPTZ DEFAULT NOW(),
+  updated_at TIMESTAMPTZ DEFAULT NOW()
+);
+
+-- Enable Row Level Security
+ALTER TABLE public.profiles ENABLE ROW LEVEL SECURITY;
+
+-- Profiles policies
+CREATE POLICY "Users can view own profile"
+  ON public.profiles FOR SELECT
+  USING (auth.uid() = id);
+
+CREATE POLICY "Users can update own profile"
+  ON public.profiles FOR UPDATE
+  USING (auth.uid() = id);
+
+-- Billing identifiers and any future privileged columns are server-owned.
+REVOKE INSERT, UPDATE, DELETE ON TABLE public.profiles FROM PUBLIC, anon, authenticated;
+GRANT UPDATE (full_name, avatar_url) ON TABLE public.profiles TO authenticated;
+GRANT ALL ON TABLE public.profiles TO service_role;
+
+-- Function to create profile on signup
+CREATE OR REPLACE FUNCTION public.handle_new_user()
+RETURNS TRIGGER AS $$
+BEGIN
+  INSERT INTO public.profiles (id, email, full_name)
+  VALUES (
+    NEW.id,
+    NEW.email,
+    NEW.raw_user_meta_data->>'full_name'
+  );
+  RETURN NEW;
+END;
+$$ LANGUAGE plpgsql SECURITY DEFINER SET search_path = '';
+
+-- Trigger for new user signup
+DROP TRIGGER IF EXISTS on_auth_user_created ON auth.users;
+CREATE TRIGGER on_auth_user_created
+  AFTER INSERT ON auth.users
+  FOR EACH ROW EXECUTE FUNCTION public.handle_new_user();
+
+-- Updated at trigger function
+CREATE OR REPLACE FUNCTION public.update_updated_at()
+RETURNS TRIGGER AS $$
+BEGIN
+  NEW.updated_at = NOW();
+  RETURN NEW;
+END;
+$$ LANGUAGE plpgsql;
+
+-- Apply updated_at trigger to profiles
+CREATE TRIGGER update_profiles_updated_at
+  BEFORE UPDATE ON public.profiles
+  FOR EACH ROW EXECUTE FUNCTION public.update_updated_at();