umpordez 1.1.0 → 1.2.1

package/README.md

@@ -198,6 +198,20 @@ umpordez --version                check version
 | Uploads    | AWS S3 with signed URLs |
 | Email      | Nodemailer + HTML templates |
 
+## What changed in 1.2
+
+- **Non-Negotiables** section in AGENTS.md — codifies rules per layer
+  (server, admin UI, site, mobile) so teams don't have to rediscover
+  them.
+- **Key Patterns (TL;DR)** — quick reference for adding entities,
+  context DI, route handlers, and transactions.
+- **i18n Coverage** table — shows which layers speak which
+  languages at a glance.
+- **Anonymous-first mobile** — synthetic device-account on first
+  boot, never gate behind sign-in.
+- **fetch-api** now supports PUT and PATCH methods plus safer
+  URL parameter filtering (skips null/undefined values).
+
 ## What changed in 1.1
 
 The big one. v1.0.x was server + web only. v1.1 adds:

package/package.json

@@ -1,7 +1,7 @@
 {
     "name": "umpordez",
     "type": "module",
-    "version": "1.1.0",
+    "version": "1.2.1",
     "description": "SaaS starter kit generator — server, admin SPA, public site (i18n), mobile app (offline-first, IAP, native push)",
     "main": "cli.mjs",
     "scripts": {

package/template/AGENTS.md

@@ -276,7 +276,86 @@ const ok = await confirm({
 if (!ok) return;
 ```
 
-## Multi-Tenancy
+## Non-Negotiables
+
+### Code Style
+- 4-space indent, semicolons, max 80 cols, LF, always braces
+- TypeScript strict (no `any`, use `unknown`)
+- Code in English; user-facing strings in Portuguese (pt-BR)
+- Path aliases: `#core/*`, `#shared/*`, `#api/*` (server), `@/*` (admin UI / mobile)
+- No relative paths beyond single `../`
+
+### Server
+- Routes go through models (never `req.context.knex()` in routes)
+- `buildHandler()` wraps every async handler; Zod validates input
+- Raw SQL in migrations (`knex.schema.raw()`)
+- Models extend `BaseModel` — get `this.knex`, `this.context`, `this.db`
+- Errors: `ValidationError` (400), `NotFoundError` (404), `ConflictError` (409), `ForbiddenError` (403)
+- Pagination: `{ rows, total, page, limit, totalPages }`
+- Every table: `id UUID`, `utc_created_on`, `utc_updated_on`; multi-tenant tables also `account_id`
+
+### Admin UI
+- `fetchApi()` for every API call (handles cookies, JSON, FormData)
+- React Query for all server state; `keepPreviousData` on paginated queries
+- Query keys centralized in `lib/query-keys.ts`
+- shadcn/ui primitives under `components/ui/` (compose, don't fork)
+- `useConfirm()` instead of `window.confirm()`, `toast` from sonner
+
+### Site
+- Every string through `t()` — no bare text in templates
+- URL strategy: `/` → pt-BR, `/en/...` → English (middleware strips prefix)
+- Hreflang alternates + canonical + sitemap.xml on every page
+
+### Mobile
+- **Free-first**: never gate behind sign-in; anonymous usage is the default
+- **Anonymous-first**: synthetic UUID device-account on first boot, never gate behind login
+- **Services own data access** — pages never call `getDb()` directly
+- **User-scoped writes check `demandSigned()`** — reads always work, writes no-op when gate closed
+- Every string through `t()` — no bare text in JSX
+- NitroModules crash in Expo Go — lazy-load with `try/require`
+- Never `expo prebuild --clean` (wipes native code; use `scripts/prebuild.sh`)
+
+### i18n Coverage
+| Layer | pt-BR | en | Additional |
+|-------|-------|----|------------|
+| Server | ✓ | ✓ | Extensible via i18next |
+| Admin UI | ✓ | ✗ | pt-BR only (Brazil market) |
+| Site | ✓ | ✓ | URL-prefixed (/ vs /en/) |
+| Mobile | ✓ | ✓ | Extensible per project |
+
+## Key Patterns (TL;DR)
+
+### Adding a domain entity
+1. `migrations/YYYYMMDDHHMMSS_create-thing.ts` — raw SQL
+2. `core/models/thing.ts` — extends `BaseModel`
+3. Register on `Context` in `core/context.ts`
+4. `apps/api/routes/thing.ts` — `buildHandler()` + Zod
+5. Admin UI: page + `hooks/queries/use-thing.ts`
+6. Mobile (optional): `src/services/thing/`
+
+### Context DI
+```typescript
+const users = await req.context.user.list({ page: 1 });
+this.user = new UserModel(this);  // in context.ts
+```
+
+### Route handler
+```typescript
+router.post('/things', buildHandler(async (req, res) => {
+    const data = z.object({ name: z.string().min(1) }).parse(req.body);
+    const result = await req.context.thing.create(req.accountId!, data);
+    res.json({ ok: true, result });
+}));
+```
+
+### Transaction
+```typescript
+await req.context.knexTransaction(async () => {
+    const user = await req.context.user.create(data);
+    await req.context.account.addMember(accountId, { ... });
+});
+```
+
 
 ```
 users (global identity) → user_in_accounts (many-to-many + role) → accounts (tenant) → [domain entities]

package/template/mobile/{{PROJECT_SLUG}}/App.tsx

@@ -1,6 +1,7 @@
 import { useEffect, useState } from 'react';
 import { AppState } from 'react-native';
 import { SafeAreaProvider } from 'react-native-safe-area-context';
+import { GestureHandlerRootView } from 'react-native-gesture-handler';
 import Toast from 'react-native-toast-message';
 import * as SplashScreen from 'expo-splash-screen';
 
@@ -28,6 +29,13 @@ export default function App() {
         // `splashDone` flips, and screens read from SQLite which
         // serves cached data while the network sync runs.
         SplashScreen.hideAsync().catch(() => { /* best-effort */ });
+
+        // Force-hide the splash after 5s no matter what, so a stuck
+        // animation never keeps the user out of the app. In Release
+        // there's no red box — without this timeout a render-time
+        // crash is invisible.
+        const fallback = setTimeout(() => setSplashDone(true), 5000);
+
         (async () => {
             try {
                 await initDb();
@@ -55,21 +63,26 @@ export default function App() {
                 });
             }
         });
-        return () => sub.remove();
+        return () => {
+            sub.remove();
+            clearTimeout(fallback);
+        };
     }, []);
 
     return (
-        <SafeAreaProvider>
-            <ThemeProvider>
-                <AuthProvider>
-                    <Routes />
-                    <Toast config={toastConfig} />
-                </AuthProvider>
-            </ThemeProvider>
+        <GestureHandlerRootView style={{ flex: 1 }}>
+            <SafeAreaProvider>
+                <ThemeProvider>
+                    <AuthProvider>
+                        <Routes />
+                        <Toast config={toastConfig} />
+                    </AuthProvider>
+                </ThemeProvider>
 
-            {!splashDone && (
-                <AnimatedSplash onDone={() => setSplashDone(true)} />
-            )}
-        </SafeAreaProvider>
+                {!splashDone && (
+                    <AnimatedSplash onDone={() => setSplashDone(true)} />
+                )}
+            </SafeAreaProvider>
+        </GestureHandlerRootView>
     );
 }

package/template/mobile/{{PROJECT_SLUG}}/CLAUDE.md

@@ -63,10 +63,17 @@ hasCompletedOnboarding
   render an "auth required" screen at the entry point. Wrap
   premium features in `<PremiumGate onUpgrade={openAuth} />`.
 
-- **Routes go through models** — same rule as server. Mobile
+- **Anonymous-first.** `AuthContext` fabricates a synthetic device-
+  account on first boot (`services/auth/anonymous.ts` returns a
+  UUID v4 stored in AsyncStorage). `signed: true` always;
+  `isAnonymous: true` for the default state. Never gate app entry
+  behind sign-in. The opt-in AuthStack lives in Profile's footer
+  link only.
+
+- **Services own data access** — same rule as server. Mobile
   doesn't have models; the equivalent is: **services own data
-  access**. Pages call `getContentByType('post')`, not
-  `getDb().getAllAsync(...)`. New SQLite reads/writes go in the
+  access**. Pages call `services/crops`, `services/events`, … —
+  never `getDb()` directly. New SQLite reads/writes go in the
   matching `services/<thing>/` folder.
 
 - **User-scoped writes check `demandSigned()`** at the top of the
@@ -150,7 +157,7 @@ Client → /api/auth/google/app
 ```
 
 `signOut()` clears auth + onboarding state so the next user starts
-from Welcome (matches tranqs's pattern; onboarding is per-account).
+from Welcome (onboarding is per-account).
 
 ## Premium
 

package/template/mobile/{{PROJECT_SLUG}}/app.json

@@ -48,6 +48,9 @@
                 {
                     "android": {
                         "minSdkVersion": 26
+                    },
+                    "ios": {
+                        "deploymentTarget": "17.0"
                     }
                 }
             ],

package/template/mobile/{{PROJECT_SLUG}}/index.ts

@@ -20,7 +20,53 @@ if (typeof globalThis.document === 'undefined') {
 }
 
 import { registerRootComponent } from 'expo';
-import App from './App';
+import { createElement, ComponentType } from 'react';
+import { ScrollView, Text } from 'react-native';
+import * as SplashScreen from 'expo-splash-screen';
+
+// Boot-crash catcher: if ANY module in the app's import graph
+// throws at load time, render the error on screen instead of
+// hanging forever on the native splash. In Release there is no
+// red box — without this, a load-time crash is invisible.
+let App: ComponentType;
+try {
+    // eslint-disable-next-line @typescript-eslint/no-require-imports
+    App = (require('./App') as { default: ComponentType }).default;
+} catch (err) {
+    const message = err instanceof Error
+        ? `${err.message}\n\n${err.stack ?? ''}`
+        : String(err);
+    App = function BootError() {
+        SplashScreen.hideAsync().catch(() => { /* best-effort */ });
+        return createElement(
+            ScrollView,
+            {
+                style: { flex: 1, backgroundColor: '#0F1416' },
+                contentContainerStyle: {
+                    padding: 24,
+                    paddingTop: 100
+                }
+            },
+            createElement(
+                Text,
+                {
+                    style: {
+                        color: '#f87171',
+                        fontSize: 16,
+                        fontWeight: '700',
+                        marginBottom: 12
+                    }
+                },
+                'Erro ao iniciar o aplicativo'
+            ),
+            createElement(
+                Text,
+                { style: { color: '#e4e8f2', fontSize: 12 } },
+                message
+            )
+        );
+    };
+}
 
 // registerRootComponent calls AppRegistry.registerComponent('main', () => App);
 // It also ensures that whether you load the app in Expo Go or in a native build,

package/template/mobile/{{PROJECT_SLUG}}/package.json

@@ -18,37 +18,41 @@
         "@react-navigation/bottom-tabs": "^7.7.3",
         "@react-navigation/native": "^7.1.19",
         "@react-navigation/native-stack": "^7.6.2",
-        "expo": "~54.0.33",
-        "expo-apple-authentication": "~8.0.8",
+        "expo": "~57.0.2",
+        "expo-apple-authentication": "~57.0.0",
         "expo-auth-session": "~7.0.10",
-        "expo-build-properties": "~1.0.10",
-        "expo-constants": "~18.0.13",
-        "expo-file-system": "~18.0.4",
-        "expo-localization": "~17.0.7",
-        "expo-splash-screen": "^55.0.18",
-        "expo-sqlite": "~16.0.10",
-        "expo-status-bar": "~3.0.9",
-        "expo-system-ui": "~6.0.7",
-        "expo-web-browser": "~15.0.10",
+        "expo-build-properties": "~57.0.3",
+        "expo-constants": "~57.0.3",
+        "expo-file-system": "~57.0.0",
+        "expo-linking": "~57.0.1",
+        "expo-localization": "~57.0.0",
+        "expo-share-intent": "^8.0.0",
+        "expo-splash-screen": "~57.0.2",
+        "expo-sqlite": "~57.0.0",
+        "expo-status-bar": "~57.0.0",
+        "expo-system-ui": "~57.0.0",
+        "expo-web-browser": "~57.0.0",
         "i18next": "^23.16.5",
         "lucide-react-native": "^1.8.0",
         "react": "19.1.0",
-        "react-native": "0.81.5",
+        "react-native": "0.83.10",
         "react-i18next": "^15.1.1",
+        "react-native-gesture-handler": "~3.0.2",
         "react-native-health": "^1.19.0",
         "react-native-health-connect": "^3.5.0",
         "react-native-iap": "^15.2.0",
         "react-native-nitro-modules": "^0.35.4",
-        "react-native-reanimated": "~4.1.1",
-        "react-native-safe-area-context": "^5.6.2",
-        "react-native-screens": "~4.16.0",
+        "react-native-reanimated": "~4.5.1",
+        "react-native-safe-area-context": "^5.8.0",
+        "react-native-screens": "~4.25.2",
         "react-native-svg": "15.12.1",
-        "react-native-toast-message": "^2.3.3"
+        "react-native-toast-message": "^2.3.3",
+        "react-native-worklets": "~0.10.1"
     },
     "devDependencies": {
         "@stylistic/eslint-plugin": "^2.13.0",
         "@types/react": "~19.1.0",
-        "babel-preset-expo": "~54.0.0",
+        "babel-preset-expo": "~57.0.1",
         "eslint": "^9.20.1",
         "typescript": "~5.7.0",
         "typescript-eslint": "^8.24.0"

package/template/mobile/{{PROJECT_SLUG}}/src/components/AnimatedSplash.tsx

@@ -48,6 +48,13 @@ export default function AnimatedSplash({ onDone }: Props) {
     const exitSc = useRef(new Animated.Value(1)).current;
 
     useEffect(() => {
+        // Safety timeout: if the animation callback never fires
+        // (which can happen in Release builds with Hermes/new arch),
+        // force `onDone` after 4s so the app never hangs forever.
+        const fallback = setTimeout(() => {
+            onDone?.();
+        }, 4000);
+
         Animated.sequence([
             // Phase 1: entrance
             Animated.parallel([
@@ -126,10 +133,13 @@ export default function AnimatedSplash({ onDone }: Props) {
                 })
             ])
         ]).start(() => {
+            clearTimeout(fallback);
             if (onDone) {
                 onDone();
             }
         });
+
+        return () => clearTimeout(fallback);
     }, []);
 
     return (

package/template/mobile/{{PROJECT_SLUG}}/src/contexts/AuthContext.tsx

@@ -287,9 +287,8 @@ export function AuthProvider({ children }: { children: ReactNode }) {
             console.warn('[auth] clearUserData error:', err);
         }
         // Clear onboarding state too: signing out should send the next
-        // person back through Welcome → Onboarding → FirstAction. Same
-        // pattern tranqs uses — onboarding is per-account, not
-        // per-device.
+        // person back through Welcome → Onboarding → FirstAction.
+        // Onboarding is per-account, not per-device.
         await AsyncStorage.multiRemove([
             KEYS.token,
             KEYS.refresh,

package/template/ui/admin/CLAUDE.md

@@ -70,8 +70,8 @@ Path alias: `@/*` → `./src/*`. Use it everywhere.
 
 Admin UI ships pt-BR strings inline today (the admin is for the
 operator, not the customer). If you need EN admin support later,
-mirror the mobile app's pattern: `src/i18n/{index,locales/*}` with
-`react-i18next` + `i18next`. The mobile app is the reference.
+mirror the pattern: `src/i18n/{index,locales/*}` with
+`react-i18next` + `i18next`.
 
 ## Charts
 

package/template/ui/admin/src/lib/fetch-api.ts

@@ -14,7 +14,7 @@ class FetchApi {
     async doRequest(
         url: string,
         body: unknown,
-        method: 'GET' | 'POST' | 'DELETE',
+        method: 'GET' | 'POST' | 'PUT' | 'PATCH' | 'DELETE',
         headers: Record<string, string> = {}
     ): Promise<any> {
         const isFormData = body instanceof FormData;
@@ -25,17 +25,29 @@ class FetchApi {
         }
 
         let parsedBody = body;
-
         if (parsedBody && typeof parsedBody === 'string') {
-            parsedBody = JSON.parse(parsedBody);
+            try {
+                parsedBody = JSON.parse(parsedBody);
+            } catch {
+                // Keep original string if parse fails
+            }
         }
 
         let requestUrl = `${API_BASE_URL}/api/${url}`;
         let requestBody: string | FormData | null = null;
 
-        if (method === 'GET' && parsedBody) {
-            requestUrl = `${requestUrl}?${new URLSearchParams(parsedBody as Record<string, string>)}`;
-        } else if (parsedBody) {
+        if (method === 'GET' && parsedBody && typeof parsedBody === 'object') {
+            const params = new URLSearchParams();
+            for (const [key, val] of Object.entries(parsedBody as Record<string, unknown>)) {
+                if (val !== undefined && val !== null) {
+                    params.append(key, String(val));
+                }
+            }
+            const qs = params.toString();
+            if (qs) {
+                requestUrl = `${requestUrl}?${qs}`;
+            }
+        } else if (method !== 'GET' && parsedBody) {
             requestBody = isFormData
                 ? (parsedBody as FormData)
                 : JSON.stringify(parsedBody);
@@ -92,7 +104,7 @@ class FetchApi {
 export default function fetchApi(
     url: string,
     body?: unknown,
-    method: 'GET' | 'POST' | 'DELETE' = 'GET',
+    method: 'GET' | 'POST' | 'PUT' | 'PATCH' | 'DELETE' = 'GET',
     headers?: Record<string, string>,
     abortController?: AbortController
 ): Promise<any> {