multimodel-dev-os 1.1.0 → 2.0.1

package/docs/v2-roadmap.md

@@ -0,0 +1,95 @@
+# MultiModel Dev OS — v2.0.0 Roadmap
+
+This document outlines the development path, stabilization targets, and migration roadmap leading to the `v2.0.0` stable release of MultiModel Dev OS.
+
+---
+
+## 1. Release Objective
+
+The primary goal of the **v2.0.0 release** is to promote the experimental features introduced in `v1.2.0` (Template Galaxy, Model Compatibility Layer, and Android Expo template) into officially frozen, production-grade core components, and resume stable package publication to the public npm registry.
+
+> [!IMPORTANT]
+> **v2.0.1 is the active stable release.** NPM publishing is resumed, consolidating the Template Galaxy and Model registries.
+
+---
+
+## 2. Key Stabilization Targets
+
+### A. Template Galaxy Stabilization
+* Standardize the schema for template configurations under `.ai/schema/template.schema.json`.
+* Harden the built-in templates (`nextjs-saas`, `wordpress-site`, `ecommerce-store`, `seo-landing-page`, `expo-react-native-android`, `general-app`) to ensure they pass validation checks across diverse OS environments.
+
+### B. Model Registry Stabilization
+* Freeze the `.ai/models/` structure:
+  * `registry.yaml` — Core provider mappings and model metadata.
+  * `providers.yaml` — API endpoint declarations.
+  * `routing-presets.yaml` — Optimized task routing configurations.
+  * `local-models.yaml` — Offline execution definitions.
+* Standardize validation rules inside `validate` and `doctor` commands to verify YAML configuration syntax and compatibility.
+
+### C. Adapter Registry Stabilization
+* Freeze `.ai/adapters/registry.yaml`.
+* Extend support mapping for emerging developer tools (e.g. Continue, Cline, Roo Code, Aider, Windsurf).
+* Ensure cross-linking logic maintains strict custom boundaries so that updates in `AGENTS.md` synchronize with adapter targets without wiping user overrides.
+
+### D. Android Expo Template Stabilization
+* Hardening the `examples/expo-react-native-android/` foundation.
+* Verify clean execution of EAS Build and environment configurations on local developer machines and CI runner platforms.
+
+### E. CLI Compatibility Pass
+* Ensure the new subcommands introduced in `v1.2.0` are fully backward-compatible with `v1.0.0` and `v1.1.0` CLI patterns:
+  * `models` / `show-model`
+  * `providers`
+  * `route-model`
+  * `adapters` / `show-adapter`
+  * `skills` / `show-skill`
+  * `doctor --tokens`
+  * `validate --template`
+
+---
+
+## 3. Package Publishing Checklist
+
+Before executing the `v2.0.0` release on the npm registry, the following steps must be completed:
+
+1. [x] Set version to `2.0.0` in `package.json`.
+2. [x] Ensure `scripts/prepublish-guard.js` allows the publish (since version starts with `2.`).
+3. [x] Run all verification suites:
+   ```bash
+   npm run verify
+   ```
+4. [x] Build documentation static bundles cleanly:
+   ```bash
+   npm run docs:build
+   ```
+5. [x] Perform a dry-run publish to review package hygiene:
+   ```bash
+   npm publish --dry-run
+   ```
+6. [x] Set the required publication environment variable:
+   * **PowerShell:** `$env:MMDO_ALLOW_PUBLISH="true"`
+   * **Bash:** `export MMDO_ALLOW_PUBLISH=true`
+7. [x] Publish the package to the public registry:
+   ```bash
+   npm publish --access public
+   ```
+
+---
+
+## 4. Migration Notes: npm latest to v2.0.0
+
+* **Direct Upgrades**: Projects running the last stable npm package (e.g., `1.1.0` / `1.0.0`) can migrate to `2.0.0` by executing `npx multimodel-dev-os@latest init --force` or installing the package locally.
+* **Registry Release**: Now that v2.0.0 is released, cloning the repository is no longer required to access Layer 1 templates or model registries. Simply run:
+  ```bash
+  npx multimodel-dev-os@latest init
+  ```
+* **Configuration Upgrades**: Existing `.ai/` folders can be upgraded by running `init --force` to pull the new centralized registries (`.ai/models/` and `.ai/adapters/`) into the workspace.
+
+---
+
+## 5. Final Release Gate
+
+The `v2.0.0` release requires:
+1. 100% pass rate on all automated linter and verifier checks.
+2. Complete documentation updates across all guides and discovery indices.
+3. Explicit maintainer sign-off on local testing of the Android Expo template.

package/examples/expo-react-native-android/.ai/config.yaml

@@ -0,0 +1,22 @@
+# Mobile App configuration
+
+project:
+  name: "expo-react-native-android"
+  description: "Production-ready Android mobile app with Expo, React Native, and EAS builds."
+  version: "1.0.0"
+
+mode: "standard"
+
+adapters:
+  cursor: false
+  claude: false
+  gemini: false
+  vscode: false
+  antigravity: false
+
+skills:
+  directory: ".ai/skills/"
+  auto_load: true
+
+prompts:
+  directory: ".ai/prompts/"

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;
+    }
+  }
+}