@caoscompanybr/merlin 3.5.0

package/.merlin-core/skills/domain/expo-native-ui/references/api-routes.md

@@ -0,0 +1,361 @@
+## When to Use API Routes
+
+Use API routes when you need:
+
+- **Server-side secrets** — API keys, database credentials, or tokens that must never reach the client
+- **Database operations** — Direct database queries that shouldn't be exposed
+- **Third-party API proxies** — Hide API keys when calling external services (OpenAI, Stripe, etc.)
+- **Server-side validation** — Validate data before database writes
+- **Webhook endpoints** — Receive callbacks from services like Stripe or GitHub
+- **Rate limiting** — Control access at the server level
+- **Heavy computation** — Offload processing that would be slow on mobile
+
+## When NOT to Use API Routes
+
+Avoid API routes when:
+
+- **Data is already public** — Use direct fetch to public APIs instead
+- **No secrets required** — Static data or client-safe operations
+- **Real-time updates needed** — Use WebSockets or services like Supabase Realtime
+- **Simple CRUD** — Consider Firebase, Supabase, or Convex for managed backends
+- **File uploads** — Use direct-to-storage uploads (S3 presigned URLs, Cloudflare R2)
+- **Authentication only** — Use Clerk, Auth0, or Firebase Auth instead
+
+## File Structure
+
+API routes live in the `app` directory with `+api.ts` suffix:
+
+```
+app/
+  api/
+    hello+api.ts          → GET /api/hello
+    users+api.ts          → /api/users
+    users/[id]+api.ts     → /api/users/:id
+  (tabs)/
+    index.tsx
+```
+
+## Basic API Route
+
+```ts
+// app/api/hello+api.ts
+export function GET(request: Request) {
+  return Response.json({ message: "Hello from Expo!" });
+}
+```
+
+## HTTP Methods
+
+Export named functions for each HTTP method:
+
+```ts
+// app/api/items+api.ts
+export function GET(request: Request) {
+  return Response.json({ items: [] });
+}
+
+export async function POST(request: Request) {
+  const body = await request.json();
+  return Response.json({ created: body }, { status: 201 });
+}
+
+export async function PUT(request: Request) {
+  const body = await request.json();
+  return Response.json({ updated: body });
+}
+
+export async function DELETE(request: Request) {
+  return new Response(null, { status: 204 });
+}
+```
+
+## Dynamic Routes
+
+```ts
+// app/api/users/[id]+api.ts
+export function GET(request: Request, { id }: { id: string }) {
+  return Response.json({ userId: id });
+}
+```
+
+## Request Handling
+
+### Query Parameters
+
+```ts
+export function GET(request: Request) {
+  const url = new URL(request.url);
+  const page = url.searchParams.get("page") ?? "1";
+  const limit = url.searchParams.get("limit") ?? "10";
+
+  return Response.json({ page, limit });
+}
+```
+
+### Headers
+
+```ts
+export function GET(request: Request) {
+  const auth = request.headers.get("Authorization");
+
+  if (!auth) {
+    return Response.json({ error: "Unauthorized" }, { status: 401 });
+  }
+
+  return Response.json({ authenticated: true });
+}
+```
+
+### JSON Body
+
+```ts
+export async function POST(request: Request) {
+  const { email, password } = await request.json();
+
+  if (!email || !password) {
+    return Response.json({ error: "Missing fields" }, { status: 400 });
+  }
+
+  return Response.json({ success: true });
+}
+```
+
+## Environment Variables
+
+Use `process.env` for server-side secrets:
+
+```ts
+// app/api/ai+api.ts
+export async function POST(request: Request) {
+  const { prompt } = await request.json();
+
+  const response = await fetch("https://api.openai.com/v1/chat/completions", {
+    method: "POST",
+    headers: {
+      "Content-Type": "application/json",
+      Authorization: `Bearer ${process.env.OPENAI_API_KEY}`,
+    },
+    body: JSON.stringify({
+      model: "gpt-4",
+      messages: [{ role: "user", content: prompt }],
+    }),
+  });
+
+  const data = await response.json();
+  return Response.json(data);
+}
+```
+
+Set environment variables:
+
+- **Local**: Create `.env` file (never commit)
+- **EAS Hosting**: Use `eas env:create` or Expo dashboard
+
+## CORS Headers
+
+Add CORS for web clients:
+
+```ts
+const corsHeaders = {
+  "Access-Control-Allow-Origin": "*",
+  "Access-Control-Allow-Methods": "GET, POST, PUT, DELETE, OPTIONS",
+  "Access-Control-Allow-Headers": "Content-Type, Authorization",
+};
+
+export function OPTIONS() {
+  return new Response(null, { headers: corsHeaders });
+}
+
+export function GET() {
+  return Response.json({ data: "value" }, { headers: corsHeaders });
+}
+```
+
+## Error Handling
+
+```ts
+export async function POST(request: Request) {
+  try {
+    const body = await request.json();
+    // Process...
+    return Response.json({ success: true });
+  } catch (error) {
+    console.error("API error:", error);
+    return Response.json({ error: "Internal server error" }, { status: 500 });
+  }
+}
+```
+
+## Testing Locally
+
+Start the development server with API routes:
+
+```bash
+npx expo serve
+```
+
+This starts a local server at `http://localhost:8081` with full API route support.
+
+Test with curl:
+
+```bash
+curl http://localhost:8081/api/hello
+curl -X POST http://localhost:8081/api/users -H "Content-Type: application/json" -d '{"name":"Test"}'
+```
+
+## Deployment to EAS Hosting
+
+### Prerequisites
+
+```bash
+npm install -g eas-cli
+eas login
+```
+
+### Deploy
+
+```bash
+eas deploy
+```
+
+This builds and deploys your API routes to EAS Hosting (Cloudflare Workers).
+
+### Environment Variables for Production
+
+```bash
+# Create a secret
+eas env:create --name OPENAI_API_KEY --value sk-xxx --environment production
+
+# Or use the Expo dashboard
+```
+
+### Custom Domain
+
+Configure in `eas.json` or Expo dashboard.
+
+## EAS Hosting Runtime (Cloudflare Workers)
+
+API routes run on Cloudflare Workers. Key limitations:
+
+### Missing/Limited APIs
+
+- **No Node.js filesystem** — `fs` module unavailable
+- **No native Node modules** — Use Web APIs or polyfills
+- **Limited execution time** — 30 second timeout for CPU-intensive tasks
+- **No persistent connections** — WebSockets require Durable Objects
+- **fetch is available** — Use standard fetch for HTTP requests
+
+### Use Web APIs Instead
+
+```ts
+// Use Web Crypto instead of Node crypto
+const hash = await crypto.subtle.digest(
+  "SHA-256",
+  new TextEncoder().encode("data"),
+);
+
+// Use fetch instead of node-fetch
+const response = await fetch("https://api.example.com");
+
+// Use Response/Request (already available)
+return new Response(JSON.stringify(data), {
+  headers: { "Content-Type": "application/json" },
+});
+```
+
+### Database Options
+
+Since filesystem is unavailable, use cloud databases:
+
+- **Cloudflare D1** — SQLite at the edge
+- **Turso** — Distributed SQLite
+- **PlanetScale** — Serverless MySQL
+- **Supabase** — Postgres with REST API
+- **Neon** — Serverless Postgres
+
+Example with Turso:
+
+```ts
+// app/api/users+api.ts
+import { createClient } from "@libsql/client/web";
+
+const db = createClient({
+  url: process.env.TURSO_URL!,
+  authToken: process.env.TURSO_AUTH_TOKEN!,
+});
+
+export async function GET() {
+  const result = await db.execute("SELECT * FROM users");
+  return Response.json(result.rows);
+}
+```
+
+## Calling API Routes from Client
+
+```ts
+// From React Native components
+const response = await fetch("/api/hello");
+const data = await response.json();
+
+// With body
+const response = await fetch("/api/users", {
+  method: "POST",
+  headers: { "Content-Type": "application/json" },
+  body: JSON.stringify({ name: "John" }),
+});
+```
+
+## Common Patterns
+
+### Authentication Middleware
+
+```ts
+// utils/auth.ts
+export async function requireAuth(request: Request) {
+  const token = request.headers.get("Authorization")?.replace("Bearer ", "");
+
+  if (!token) {
+    throw new Response(JSON.stringify({ error: "Unauthorized" }), {
+      status: 401,
+      headers: { "Content-Type": "application/json" },
+    });
+  }
+
+  // Verify token...
+  return { userId: "123" };
+}
+
+// app/api/protected+api.ts
+import { requireAuth } from "../../utils/auth";
+
+export async function GET(request: Request) {
+  const { userId } = await requireAuth(request);
+  return Response.json({ userId });
+}
+```
+
+### Proxy External API
+
+```ts
+// app/api/weather+api.ts
+export async function GET(request: Request) {
+  const url = new URL(request.url);
+  const city = url.searchParams.get("city");
+
+  const response = await fetch(
+    `https://api.weather.com/v1/current?city=${city}&key=${process.env.WEATHER_API_KEY}`,
+  );
+
+  return Response.json(await response.json());
+}
+```
+
+## Rules
+
+- NEVER expose API keys or secrets in client code
+- ALWAYS validate and sanitize user input
+- Use proper HTTP status codes (200, 201, 400, 401, 404, 500)
+- Handle errors gracefully with try/catch
+- Keep API routes focused — one responsibility per endpoint
+- Use TypeScript for type safety
+- Log errors server-side for debugging

package/.merlin-core/skills/domain/expo-native-ui/references/cicd-workflows.md

@@ -0,0 +1,84 @@
+# EAS Workflows Skill
+
+Help developers write and edit EAS CI/CD workflow YAML files.
+
+## Reference Documentation
+
+Fetch these resources before generating or validating workflow files. Use the fetch script (implemented using Node.js) in this skill's `scripts/` directory; it caches responses using ETags for efficiency:
+
+```bash
+# Fetch resources
+node {baseDir}/scripts/fetch.js <url>
+```
+
+1. **JSON Schema** — https://api.expo.dev/v2/workflows/schema
+   - It is NECESSARY to fetch this schema
+   - Source of truth for validation
+   - All job types and their required/optional parameters
+   - Trigger types and configurations
+   - Runner types, VM images, and all enums
+
+2. **Syntax Documentation** — https://raw.githubusercontent.com/expo/expo/refs/heads/main/docs/pages/eas/workflows/syntax.mdx
+   - Overview of workflow YAML syntax
+   - Examples and English explanations
+   - Expression syntax and contexts
+
+3. **Pre-packaged Jobs** — https://raw.githubusercontent.com/expo/expo/refs/heads/main/docs/pages/eas/workflows/pre-packaged-jobs.mdx
+   - Documentation for supported pre-packaged job types
+   - Job-specific parameters and outputs
+
+Do not rely on memorized values; these resources evolve as new features are added.
+
+## Workflow File Location
+
+Workflows live in `.eas/workflows/*.yml` (or `.yaml`).
+
+## Top-Level Structure
+
+A workflow file has these top-level keys:
+
+- `name` — Display name for the workflow
+- `on` — Triggers that start the workflow (at least one required)
+- `jobs` — Job definitions (required)
+- `defaults` — Shared defaults for all jobs
+- `concurrency` — Control parallel workflow runs
+
+Consult the schema for the full specification of each section.
+
+## Expressions
+
+Use `${{ }}` syntax for dynamic values. The schema defines available contexts:
+
+- `github.*` — GitHub repository and event information
+- `inputs.*` — Values from `workflow_dispatch` inputs
+- `needs.*` — Outputs and status from dependent jobs
+- `jobs.*` — Job outputs (alternative syntax)
+- `steps.*` — Step outputs within custom jobs
+- `workflow.*` — Workflow metadata
+
+## Generating Workflows
+
+When generating or editing workflows:
+
+1. Fetch the schema to get current job types, parameters, and allowed values
+2. Validate that required fields are present for each job type
+3. Verify job references in `needs` and `after` exist in the workflow
+4. Check that expressions reference valid contexts and outputs
+5. Ensure `if` conditions respect the schema's length constraints
+
+## Validation
+
+After generating or editing a workflow file, validate it against the schema:
+
+```sh
+# Install dependencies if missing
+[ -d "{baseDir}/scripts/node_modules" ] || npm install --prefix {baseDir}/scripts
+
+node {baseDir}/scripts/validate.js <workflow.yml> [workflow2.yml ...]
+```
+
+The validator fetches the latest schema and checks the YAML structure. Fix any reported errors before considering the workflow complete.
+
+## Answering Questions
+
+When users ask about available options (job types, triggers, runner types, etc.), fetch the schema and derive the answer from it rather than relying on potentially outdated information.

package/.merlin-core/skills/domain/expo-native-ui/references/controls.md

@@ -0,0 +1,266 @@
+# Native Controls
+
+Native iOS controls provide built-in haptics, accessibility, and platform-appropriate styling.
+
+## Switch
+
+Use for binary on/off settings. Has built-in haptics.
+
+```tsx
+import { Switch } from "react-native";
+import { useState } from "react";
+
+const [enabled, setEnabled] = useState(false);
+
+<Switch value={enabled} onValueChange={setEnabled} />;
+```
+
+### Customization
+
+```tsx
+<Switch
+  value={enabled}
+  onValueChange={setEnabled}
+  trackColor={{ false: "#767577", true: "#81b0ff" }}
+  thumbColor={enabled ? "#f5dd4b" : "#f4f3f4"}
+  ios_backgroundColor="#3e3e3e"
+/>
+```
+
+## Segmented Control
+
+Use for non-navigational tabs or mode selection. Avoid changing default colors.
+
+```tsx
+import SegmentedControl from "@react-native-segmented-control/segmented-control";
+import { useState } from "react";
+
+const [index, setIndex] = useState(0);
+
+<SegmentedControl
+  values={["All", "Active", "Done"]}
+  selectedIndex={index}
+  onChange={({ nativeEvent }) => setIndex(nativeEvent.selectedSegmentIndex)}
+/>;
+```
+
+### Rules
+
+- Maximum 4 options — use a picker for more
+- Keep labels short (1-2 words)
+- Avoid custom colors — native styling adapts to dark mode
+
+### With Icons (iOS 14+)
+
+```tsx
+<SegmentedControl
+  values={[
+    { label: "List", icon: "list.bullet" },
+    { label: "Grid", icon: "square.grid.2x2" },
+  ]}
+  selectedIndex={index}
+  onChange={({ nativeEvent }) => setIndex(nativeEvent.selectedSegmentIndex)}
+/>
+```
+
+## Slider
+
+Continuous value selection.
+
+```tsx
+import Slider from "@react-native-community/slider";
+import { useState } from "react";
+
+const [value, setValue] = useState(0.5);
+
+<Slider
+  value={value}
+  onValueChange={setValue}
+  minimumValue={0}
+  maximumValue={1}
+/>;
+```
+
+### Customization
+
+```tsx
+<Slider
+  value={value}
+  onValueChange={setValue}
+  minimumValue={0}
+  maximumValue={100}
+  step={1}
+  minimumTrackTintColor="#007AFF"
+  maximumTrackTintColor="#E5E5EA"
+  thumbTintColor="#007AFF"
+/>
+```
+
+### Discrete Steps
+
+```tsx
+<Slider
+  value={value}
+  onValueChange={setValue}
+  minimumValue={0}
+  maximumValue={10}
+  step={1}
+/>
+```
+
+## Date/Time Picker
+
+Compact pickers with popovers. Has built-in haptics.
+
+```tsx
+import DateTimePicker from "@react-native-community/datetimepicker";
+import { useState } from "react";
+
+const [date, setDate] = useState(new Date());
+
+<DateTimePicker
+  value={date}
+  onChange={(event, selectedDate) => {
+    if (selectedDate) setDate(selectedDate);
+  }}
+  mode="datetime"
+/>;
+```
+
+### Modes
+
+- `date` — Date only
+- `time` — Time only
+- `datetime` — Date and time
+
+### Display Styles
+
+```tsx
+// Compact inline (default)
+<DateTimePicker value={date} mode="date" />
+
+// Spinner wheel
+<DateTimePicker
+  value={date}
+  mode="date"
+  display="spinner"
+  style={{ width: 200, height: 150 }}
+/>
+
+// Full calendar
+<DateTimePicker value={date} mode="date" display="inline" />
+```
+
+### Time Intervals
+
+```tsx
+<DateTimePicker value={date} mode="time" minuteInterval={15} />
+```
+
+### Min/Max Dates
+
+```tsx
+<DateTimePicker
+  value={date}
+  mode="date"
+  minimumDate={new Date(2020, 0, 1)}
+  maximumDate={new Date(2030, 11, 31)}
+/>
+```
+
+## Stepper
+
+Increment/decrement numeric values.
+
+```tsx
+import { Stepper } from "react-native";
+import { useState } from "react";
+
+const [count, setCount] = useState(0);
+
+<Stepper
+  value={count}
+  onValueChange={setCount}
+  minimumValue={0}
+  maximumValue={10}
+/>;
+```
+
+## TextInput
+
+Native text input with various keyboard types.
+
+```tsx
+import { TextInput } from "react-native";
+
+<TextInput
+  placeholder="Enter text..."
+  placeholderTextColor="#999"
+  style={{
+    padding: 12,
+    fontSize: 16,
+    borderRadius: 8,
+    backgroundColor: "#f0f0f0",
+  }}
+/>;
+```
+
+### Keyboard Types
+
+```tsx
+// Email
+<TextInput keyboardType="email-address" autoCapitalize="none" />
+
+// Phone
+<TextInput keyboardType="phone-pad" />
+
+// Number
+<TextInput keyboardType="numeric" />
+
+// Password
+<TextInput secureTextEntry />
+
+// Search
+<TextInput
+  returnKeyType="search"
+  enablesReturnKeyAutomatically
+/>
+```
+
+### Multiline
+
+```tsx
+<TextInput
+  multiline
+  numberOfLines={4}
+  textAlignVertical="top"
+  style={{ minHeight: 100 }}
+/>
+```
+
+## Picker (Wheel)
+
+For selection from many options (5+ items).
+
+```tsx
+import { Picker } from "@react-native-picker/picker";
+import { useState } from "react";
+
+const [selected, setSelected] = useState("js");
+
+<Picker selectedValue={selected} onValueChange={setSelected}>
+  <Picker.Item label="JavaScript" value="js" />
+  <Picker.Item label="TypeScript" value="ts" />
+  <Picker.Item label="Python" value="py" />
+  <Picker.Item label="Go" value="go" />
+</Picker>;
+```
+
+## Best Practices
+
+- **Haptics**: Switch and DateTimePicker have built-in haptics — don't add extra
+- **Accessibility**: Native controls have proper accessibility labels by default
+- **Dark Mode**: Avoid custom colors — native styling adapts automatically
+- **Spacing**: Use consistent padding around controls (12-16pt)
+- **Labels**: Place labels above or to the left of controls
+- **Grouping**: Group related controls in sections with headers