multimodel-dev-os 1.1.0 → 2.0.0

package/examples/expo-react-native-android/.ai/context/architecture.md

@@ -0,0 +1,18 @@
+# Mobile App Architecture Map
+
+This document establishes key folder boundaries and separation of concerns.
+
+## Layout Folder Structure
+
+```
+mobile/
+  app/                      # Expo Router screens & layouts
+  components/               # Reusable UI theme primitives
+  services/                 # API Clients, storage abstractions
+  hooks/                    # Custom custom hook libraries
+  tests/                    # Jest testing configurations
+```
+
+## Core Foundations
+1. **API Communications**: Handled exclusively under `/services/api-client.ts`.
+2. **Device State**: Sensitive keys kept out of Async Storage, saved in `expo-secure-store`.

package/examples/expo-react-native-android/.ai/context/context-budget.md

@@ -0,0 +1,4 @@
+# Context Budget Settings
+
+- Max file rules size: 4000 tokens.
+- Restrict loading of `/node_modules` or `.expo/` compiler cache files in assistant requests.

package/examples/expo-react-native-android/.ai/context/model-map.md

@@ -0,0 +1,6 @@
+# Model Mapping for Mobile Codebase
+
+| Tasks | Model Choice | Rationales |
+| :--- | :--- | :--- |
+| Mocking Native Components / React Hooks | Claude 3.5 Sonnet | Strong TypeScript and code reasoning |
+| Testing configurations / layout updates | Gemini 1.5 Flash | Fast verification loops |

package/examples/expo-react-native-android/.ai/context/project-brief.md

@@ -0,0 +1,9 @@
+# Project Brief: Android Mobile Client
+
+## Overview
+Scaffolds a production-grade React Native app utilizing Expo Go, EAS CLI, and TypeScript. 
+
+## Goals
+- Establish secure storage profiles (`expo-secure-store`).
+- Construct environment splits via `eas.json` (development, staging, production).
+- Implement responsive layout layouts and offline warnings.

package/examples/expo-react-native-android/.ai/session-logs/.gitkeep

@@ -0,0 +1 @@
+# Placeholder

package/examples/expo-react-native-android/.ai/skills/expo-android-build.md

@@ -0,0 +1,11 @@
+# Skill: Expo Android EAS Build Checks
+
+## Purpose
+Ensures that app.json, eas.json, and environment variables are verified before launching an EAS Build.
+
+## Activation Trigger
+Running `EAS build` or preparing staging/production releases.
+
+## Safe Verification Check
+- Assert `android.package` is set to `com.multimodel.devos` in `app.json`.
+- Confirm `eas.json` contains `preview` and `production` profiles.

package/examples/expo-react-native-android/AGENTS.md

@@ -0,0 +1,20 @@
+# MultiModel Dev OS - Android App Agents Specification
+
+This document defines agent roles and boundaries for the Expo React Native Android application.
+
+## Development Stack Guidelines
+
+- **Framework**: Expo + React Native + TypeScript
+- **State Management**: Zustand / React Context
+- **Navigation**: Expo Router (File-based)
+- **UI System**: Vanilla React Native + Tailwind CSS (NativeWind v4)
+
+## CLI Executables Matrix
+
+| Command | Action | Agent Role |
+| :--- | :--- | :--- |
+| `npm run lint` | Code style audit | Coder / Reviewer |
+| `npm run test` | Jest test suite execution | QA Tester |
+| `npx expo start` | Local development server | Coder |
+| `npx eas build --platform android --profile preview` | Build staging APK bundle | DevOps |
+| `npx eas build --platform android --profile production` | Build Play Store AAB release | DevOps |

package/examples/expo-react-native-android/MEMORY.md

@@ -0,0 +1,13 @@
+# Android App Architecture Memory & Constraints
+
+## Technical Baseline
+- **Build Tooling**: EAS CLI (Expo Application Services)
+- **Android Target**: API level 34 (Android 14)
+- **Minimum SDK**: API level 23 (Android 6.0)
+
+## Security Guidelines
+- **No Hardcoded Secrets**: All keys (API endpoints, tokens) must be injected dynamically via Expo Config `extra` parameters using `.env` files.
+- **Secure Storage**: Sensitive auth tokens must be saved using `expo-secure-store`. Do NOT use standard `AsyncStorage` for passwords or tokens.
+
+## Package Identity
+- **Android Package Name**: `com.multimodel.devos` (defined in `app.json`)

package/examples/expo-react-native-android/README.md

@@ -0,0 +1,101 @@
+# Expo React Native Android Boilerplate
+
+This template provides a production-ready React Native boilerplate configured for Android delivery using Expo, EAS Build, secure environment profile separation, automated API retries, and unit tests.
+
+---
+
+## 1. Directory Structure
+
+```
+├── app.json                  # Expo application static configurations
+├── eas.json                  # EAS Build pipeline profiles
+├── app.config.ts             # Dynamic env profiles selector
+├── jest.config.js            # Jest testing suite configuration
+├── src/
+│   ├── app/
+│   │   └── _layout.tsx       # Root layout, NetInfo listeners, and screen boundaries
+│   ├── lib/
+│   │   └── secure-storage.ts # Safe wrapper for expo-secure-store (key/value device encryption)
+│   └── services/
+│       └── api-client.ts     # Fetch API wrapper with timeout thresholds and auto-retries
+```
+
+---
+
+## 2. Environment Variables & App Configuration
+
+We decouple environment configurations in [app.config.ts](file:///f:/multimodel-dev-os/examples/expo-react-native-android/app.config.ts) using `APP_ENV`.
+
+### Supported Profiles
+1. **Development (`development`)**:
+   * API Url: `http://10.0.2.2:3000/api` (Localhost mapping for Android Emulator)
+2. **Staging (`staging`)**:
+   * API Url: `https://staging-api.multimodel.dev`
+3. **Production (`production`)**:
+   * API Url: `https://api.multimodel.dev`
+
+### To launch a specific environment locally:
+```bash
+# Start with staging parameters
+APP_ENV=staging npx expo start
+
+# Start with production parameters
+APP_ENV=production npx expo start
+```
+
+---
+
+## 3. EAS Build Setup
+
+We configure three build targets in [eas.json](file:///f:/multimodel-dev-os/examples/expo-react-native-android/eas.json) to separate local debugging from store delivery.
+
+### Build Commands
+```bash
+# 1. Build local development client (Internal testing APK with debugging tools)
+eas build --profile development --platform android
+
+# 2. Build staging/preview release (Internal testing APK)
+eas build --profile preview --platform android
+
+# 3. Build production release (Signed Android App Bundle (.aab) ready for Google Play Store)
+eas build --profile production --platform android
+```
+
+> [!CAUTION]
+> **No-Secrets Policy**: Do not commit actual `owner` or `projectId` credentials into `app.json` or environment files. Fill in placeholders locally during project provisioning.
+
+---
+
+## 4. API Client & Secure Storage
+
+### API Retry Loop
+The [api-client.ts](file:///f:/multimodel-dev-os/examples/expo-react-native-android/src/services/api-client.ts) automatically retries requests up to 3 times on transient network failures before aborting. You can enable offline mock responses by setting:
+```typescript
+const USE_MOCK_DATA = true;
+```
+
+### Encrypted Key-Value Storage
+Use the [secure-storage.ts](file:///f:/multimodel-dev-os/examples/expo-react-native-android/src/lib/secure-storage.ts) class to securely store credentials (like JWT tokens) on the device using keychain encryption:
+```typescript
+import { SecureStorage } from '../lib/secure-storage';
+
+// Write credential
+await SecureStorage.setItem('auth_token', 'JWT-TOKEN-DATA');
+
+// Retrieve credential
+const token = await SecureStorage.getItem('auth_token');
+```
+
+---
+
+## 5. Pre-flight Play Store Release Checklist
+
+Ensure you complete these steps before submitting `production` bundles:
+1. **Change package name**: Update `"package": "com.multimodel.devos"` in `app.json` to your unique identifier.
+2. **Update version parameters**: Set unique `"version"` and incremental `"versionCode"` in `app.json` for every build.
+3. **Configure App Signing Keys**: Ensure your keystore is generated securely on EAS or imported safely from local credentials. Do not commit keystores to Git.
+4. **Permissions Audit**: Verify that only required permissions (like `INTERNET`) are enabled in `app.json`.
+5. **Run tests**:
+   ```bash
+   npm test
+   ```

package/examples/expo-react-native-android/RUNBOOK.md

@@ -0,0 +1,36 @@
+# Mobile Staging Operations & Build Runbook
+
+This document details common development, testing, and release build workflows.
+
+---
+
+## 1. Local Testing & Execution
+
+Start local bundler:
+```bash
+npm run start
+```
+Run Jest unit tests:
+```bash
+npm run test
+```
+
+---
+
+## 2. Staging / Preview Builds
+
+Build staging APK locally or remotely using EAS CLI:
+```bash
+# Preview build for internal testing (requires EAS account configured)
+npx eas build --platform android --profile preview
+```
+
+---
+
+## 3. Production Play Store release
+
+Build production Play Store package (AAB):
+```bash
+npx eas build --platform android --profile production
+```
+ Ensure that your Google Play Console credentials and key keystores are linked securely inside the EAS dashboard.

package/examples/expo-react-native-android/TASKS.md

@@ -0,0 +1,14 @@
+# Active Mobile Application Backlog
+
+- [ ] Mobile App Initialization
+  - [ ] Configure `app.json` package namespace and icon directories
+  - [ ] Setup `eas.json` profiles
+- [ ] Core Integrations
+  - [ ] Implement API client with baseUrl environment variables
+  - [ ] Implement secure storage utility using `expo-secure-store`
+- [ ] App Features
+  - [ ] Setup Expo Router layout screens
+  - [ ] Design loading states and offline warning screens
+- [ ] Quality Assurance
+  - [ ] Add Jest test setups
+  - [ ] Build staging APK via `npx eas build`

package/examples/expo-react-native-android/app.config.ts

@@ -0,0 +1,40 @@
+import { ExpoConfig, ConfigContext } from 'expo/config';
+
+/**
+ * Dynamic Expo App Configuration File
+ * Decouples staging/production URLs and binds environment variables at build-time.
+ */
+export default ({ config }: ConfigContext): ExpoConfig => {
+  const env = process.env.APP_ENV || 'development';
+
+  const extraConfig = {
+    development: {
+      apiUrl: 'http://10.0.2.2:3000/api', // Localhost mapping for Android Emulator loopbacks
+      envName: 'Development'
+    },
+    staging: {
+      apiUrl: 'https://staging-api.multimodel.dev',
+      envName: 'Staging'
+    },
+    production: {
+      apiUrl: 'https://api.multimodel.dev',
+      envName: 'Production'
+    }
+  };
+
+  const selectedEnv = extraConfig[env as keyof typeof extraConfig] || extraConfig.development;
+
+  return {
+    ...config,
+    name: config.name || "MultiModel Dev OS Mobile",
+    slug: config.slug || "multimodel-dev-os-mobile",
+    // Configure EAS parameters. Fill these in during local setup. Do not commit actual tokens to Git.
+    owner: "your-expo-username-placeholder",
+    extra: {
+      ...selectedEnv,
+      eas: {
+        projectId: "your-eas-project-id-placeholder"
+      }
+    }
+  };
+};

package/examples/expo-react-native-android/app.json

@@ -0,0 +1,34 @@
+{
+  "expo": {
+    "name": "MultiModel Dev OS Mobile",
+    "slug": "multimodel-dev-os-mobile",
+    "version": "1.0.0",
+    "orientation": "portrait",
+    "icon": "./assets/icon.png",
+    "userInterfaceStyle": "light",
+    "splash": {
+      "image": "./assets/splash.png",
+      "resizeMode": "contain",
+      "backgroundColor": "#ffffff"
+    },
+    "assetBundlePatterns": [
+      "**/*"
+    ],
+    "ios": {
+      "supportsTablet": true
+    },
+    "android": {
+      "adaptiveIcon": {
+        "foregroundImage": "./assets/adaptive-icon.png",
+        "backgroundColor": "#ffffff"
+      },
+      "package": "com.multimodel.devos",
+      "permissions": [
+        "INTERNET"
+      ]
+    },
+    "web": {
+      "favicon": "./assets/favicon.png"
+    }
+  }
+}

package/examples/expo-react-native-android/eas.json

@@ -0,0 +1,26 @@
+{
+  "cli": {
+    "version": ">= 9.0.0"
+  },
+  "build": {
+    "development": {
+      "developmentClient": true,
+      "distribution": "internal",
+      "channel": "development"
+    },
+    "preview": {
+      "distribution": "internal",
+      "channel": "preview"
+    },
+    "production": {
+      "distribution": "store",
+      "channel": "production",
+      "android": {
+        "buildType": "app-bundle"
+      }
+    }
+  },
+  "submit": {
+    "production": {}
+  }
+}

package/examples/expo-react-native-android/jest.config.js

@@ -0,0 +1,11 @@
+module.exports = {
+  preset: 'jest-expo',
+  transformIgnorePatterns: [
+    'node_modules/(?!((jest-)?react-native|@react-native(-community)?)|expo(nent)?|@expo(nent)?/.*|@expo-google-fonts/.*|react-navigation|@react-navigation/.*|@unimodules/.*|unimodules|sentry-expo|native-base|react-native-svg)'
+  ],
+  setupFilesAfterEnv: ["@testing-library/jest-native/extend-expect"],
+  testMatch: ['**/__tests__/**/*.test.[jt]s?(x)', '**/?(*.)+(spec|test).[jt]s?(x)'],
+  moduleNameMapper: {
+    '^@/(.*)$': '<rootDir>/src/$1'
+  }
+};

package/examples/expo-react-native-android/src/app/_layout.tsx

@@ -0,0 +1,89 @@
+import React, { useEffect, useState } from 'react';
+import { StyleSheet, Text, View, ActivityIndicator } from 'react-native';
+import NetInfo from '@react-native-community/netinfo';
+
+/**
+ * Root Application Layout Component
+ * Serves as the primary entry point for Expo Router.
+ * Resolves network connection states and establishes offline screen boundaries.
+ */
+export default function RootLayout() {
+  const [isConnected, setIsConnected] = useState<boolean | null>(true);
+  const [isLoading, setIsLoading] = useState<boolean>(true);
+
+  useEffect(() => {
+    // Monitor connection states dynamically across Android devices
+    const unsubscribe = NetInfo.addEventListener(state => {
+      setIsConnected(state.isConnected);
+      setIsLoading(false);
+    });
+
+    return () => unsubscribe();
+  }, []);
+
+  if (isLoading) {
+    return (
+      <View style={styles.center}>
+        <ActivityIndicator size="large" color="#6366f1" />
+      </View>
+    );
+  }
+
+  // Offline boundary gate: Render fallback UI if connection is lost
+  if (!isConnected) {
+    return (
+      <View style={styles.center}>
+        <Text style={styles.errorText}>No Internet Connection</Text>
+        <Text style={styles.subtext}>Please check your network settings and try again.</Text>
+      </View>
+    );
+  }
+
+  // Guidelines: For Expo Router navigation, replace the below container with:
+  //   import { Stack } from 'expo-router';
+  //   return <Stack screenOptions={{ headerShown: false }} />;
+  return (
+    <View style={styles.container}>
+      <Text style={styles.welcomeTitle}>MultiModel Dev OS Mobile</Text>
+      <Text style={styles.body}>Scaffolded React Native App Layout successfully mounted!</Text>
+    </View>
+  );
+}
+
+const styles = StyleSheet.create({
+  container: {
+    flex: 1,
+    backgroundColor: '#f8fafc',
+    alignItems: 'center',
+    justifyContent: 'center',
+    padding: 24
+  },
+  center: {
+    flex: 1,
+    alignItems: 'center',
+    justifyContent: 'center',
+    padding: 24
+  },
+  welcomeTitle: {
+    fontSize: 24,
+    fontWeight: 'bold',
+    color: '#0f172a',
+    marginBottom: 8
+  },
+  body: {
+    fontSize: 16,
+    color: '#475569',
+    textAlign: 'center'
+  },
+  errorText: {
+    fontSize: 20,
+    fontWeight: 'bold',
+    color: '#ef4444',
+    marginBottom: 8
+  },
+  subtext: {
+    fontSize: 14,
+    color: '#64748b',
+    textAlign: 'center'
+  }
+});

package/examples/expo-react-native-android/src/lib/secure-storage.ts

@@ -0,0 +1,63 @@
+import * as SecureStore from 'expo-secure-store';
+
+/**
+ * Encrypted Key-Value Storage Wrapper
+ * Safely accesses expo-secure-store and runs assertions to verify key structures.
+ */
+export class SecureStorage {
+  static async setItem(key: string, value: string): Promise<boolean> {
+    if (!key || key.trim() === '') {
+      console.error('SecureStorage: Key cannot be empty');
+      return false;
+    }
+    try {
+      if (SecureStore && typeof SecureStore.setItemAsync === 'function') {
+        await SecureStore.setItemAsync(key, value);
+        return true;
+      } else {
+        console.warn(`[SecureStorage Mock] setItem: ${key} = ${value}`);
+        return true;
+      }
+    } catch (e) {
+      console.error(`Failed to set item in SecureStore for key: ${key}`, e);
+      return false;
+    }
+  }
+
+  static async getItem(key: string): Promise<string | null> {
+    if (!key || key.trim() === '') {
+      console.error('SecureStorage: Key cannot be empty');
+      return null;
+    }
+    try {
+      if (SecureStore && typeof SecureStore.getItemAsync === 'function') {
+        return await SecureStore.getItemAsync(key);
+      } else {
+        console.warn(`[SecureStorage Mock] getItem: ${key}`);
+        return null;
+      }
+    } catch (e) {
+      console.error(`Failed to retrieve item from SecureStore for key: ${key}`, e);
+      return null;
+    }
+  }
+
+  static async deleteItem(key: string): Promise<boolean> {
+    if (!key || key.trim() === '') {
+      console.error('SecureStorage: Key cannot be empty');
+      return false;
+    }
+    try {
+      if (SecureStore && typeof SecureStore.deleteItemAsync === 'function') {
+        await SecureStore.deleteItemAsync(key);
+        return true;
+      } else {
+        console.warn(`[SecureStorage Mock] deleteItem: ${key}`);
+        return true;
+      }
+    } catch (e) {
+      console.error(`Failed to delete item from SecureStore for key: ${key}`, e);
+      return false;
+    }
+  }
+}

package/examples/expo-react-native-android/src/services/api-client.ts

@@ -0,0 +1,106 @@
+import Constants from 'expo-constants';
+
+export interface ApiResponse<T> {
+  data: T | null;
+  error: string | null;
+  status: number;
+}
+
+export class ApiClient {
+  private baseUrl: string;
+  private timeoutMs: number = 10000;
+  private maxRetries: number = 3;
+  private useMockData: boolean = false; // Toggle true for offline mock validations
+
+  constructor() {
+    // Dynamically retrieve base API URL configured in app.config.ts extras
+    const extra = Constants.expoConfig?.extra || {};
+    this.baseUrl = extra.apiUrl || 'http://10.0.2.2:3000/api';
+  }
+
+  async request<T>(path: string, options: RequestInit = {}): Promise<ApiResponse<T>> {
+    if (this.useMockData) {
+      // Mock response resolver
+      return new Promise((resolve) => {
+        setTimeout(() => {
+          resolve({
+            data: { message: "Mock Success data from ApiClient" } as unknown as T,
+            error: null,
+            status: 200
+          });
+        }, 500);
+      });
+    }
+
+    const url = `${this.baseUrl}${path}`;
+    const defaultHeaders = {
+      'Content-Type': 'application/json',
+      'Accept': 'application/json'
+    };
+
+    let attempt = 0;
+    while (attempt < this.maxRetries) {
+      attempt++;
+      const controller = new AbortController();
+      const id = setTimeout(() => controller.abort(), this.timeoutMs);
+
+      try {
+        const response = await fetch(url, {
+          ...options,
+          headers: {
+            ...defaultHeaders,
+            ...options.headers
+          },
+          signal: controller.signal
+        });
+
+        clearTimeout(id);
+
+        // Retry on Server Error (5xx)
+        if (response.status >= 500 && attempt < this.maxRetries) {
+          console.warn(`[ApiClient] Attempt ${attempt} failed with status ${response.status}. Retrying...`);
+          continue;
+        }
+
+        if (!response.ok) {
+          return {
+            data: null,
+            error: `HTTP Error: ${response.status} ${response.statusText}`,
+            status: response.status
+          };
+        }
+
+        const data = await response.json();
+        return {
+          data: data as T,
+          error: null,
+          status: response.status
+        };
+      } catch (e: any) {
+        clearTimeout(id);
+        const isTimeout = e.name === 'AbortError';
+        
+        // Retry on timeout or transient network failures
+        if (attempt < this.maxRetries) {
+          console.warn(`[ApiClient] Attempt ${attempt} failed: ${e.message}. Retrying...`);
+          await new Promise((res) => setTimeout(res, 1000 * attempt)); // Exponential backoff
+          continue;
+        }
+
+        return {
+          data: null,
+          error: isTimeout ? 'Request Timeout' : e.message || 'Unknown network error',
+          status: 0
+        };
+      }
+    }
+
+    return {
+      data: null,
+      error: 'Max retries exceeded',
+      status: 0
+    };
+  }
+}
+
+export const apiClient = new ApiClient();

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "multimodel-dev-os",
-  "version": "1.1.0",
+  "version": "2.0.0",
   "bin": {
     "multimodel-dev-os": "bin/multimodel-dev-os.js"
   },
@@ -45,7 +45,8 @@
     "pack": "bash scripts/pack-template.sh",
     "docs:dev": "vitepress dev docs",
     "docs:build": "vitepress build docs",
-    "docs:preview": "vitepress preview docs"
+    "docs:preview": "vitepress preview docs",
+    "prepublishOnly": "node scripts/prepublish-guard.js"
   },
   "devDependencies": {
     "vitepress": "^1.6.4"