@codeyam/codeyam-cli 0.1.0-staging.8b51541 → 0.1.0-staging.8c89b23

package/codeyam-cli/templates/seed-adapters/supabase.ts

@@ -0,0 +1,363 @@
+/**
+ * CodeYam Seed Adapter for Supabase.
+ *
+ * Seeds the database and optionally signs in a user for authenticated scenarios.
+ *
+ * Usage: npx tsx .codeyam/seed-adapter.ts <path-to-seed-data.json>
+ *
+ * Input JSON format:
+ * {
+ *   "tableName": [{ "column": "value", ... }, ...],
+ *   "_auth": {                          // optional
+ *     "email": "alice@example.com",
+ *     "password": "test123"             // optional — default used if omitted
+ *   }
+ * }
+ *
+ * When _auth is present, the adapter:
+ * 1. Creates the user if they don't exist (auto-confirms email)
+ * 2. Builds a synthetic JWT with far-future expiry (no real sign-in needed)
+ * 3. Writes session cookies + auth mocks to .codeyam/tmp/seed-session.json
+ *    so the CodeYam proxy can inject them into the browser
+ *
+ * The password field is optional — if omitted, a default dev password is used.
+ * No real JWTs are stored; the preload module intercepts all auth API calls.
+ *
+ * Requirements:
+ * - A Supabase project URL (https://<ref>.supabase.co) in any env var
+ * - A secret key (sb_secret_... or legacy eyJ... service_role JWT) in any env var
+ *
+ * The adapter scans ALL env vars by value pattern — no specific naming required.
+ */
+
+import { createClient } from '@supabase/supabase-js';
+import { Prisma } from '@prisma/client';
+import * as fs from 'fs';
+import * as path from 'path';
+
+/**
+ * Scan all env vars for values matching a pattern.
+ * Returns ALL unique matches (not just the first) so callers can disambiguate.
+ */
+function findAllEnvByPattern(pattern: RegExp): string[] {
+  const matches = new Set<string>();
+  for (const value of Object.values(process.env)) {
+    if (value && pattern.test(value)) matches.add(value);
+  }
+  return [...matches];
+}
+
+/**
+ * For legacy Supabase JWTs, decode the payload to check the `role` claim.
+ * Returns the role string ("service_role", "anon", etc.) or undefined.
+ */
+function getJwtRole(jwt: string): string | undefined {
+  try {
+    const payload = jwt.split('.')[1];
+    const decoded = JSON.parse(Buffer.from(payload, 'base64url').toString());
+    return decoded.role;
+  } catch {
+    return undefined;
+  }
+}
+
+// Detect Supabase credentials by value pattern, not env var name.
+// This works regardless of what the user named their env vars.
+const supabaseUrl = findAllEnvByPattern(
+  /^https:\/\/[a-z0-9]+\.supabase\.co\b/,
+)[0];
+
+// New-format keys are unambiguous by prefix
+const newSecretKey = findAllEnvByPattern(/^sb_secret_/)[0];
+
+// Legacy JWT keys — disambiguate by decoding the role claim
+const legacyJwts = findAllEnvByPattern(
+  /^eyJ[A-Za-z0-9_-]+\.[A-Za-z0-9_-]+\.[A-Za-z0-9_-]+$/,
+);
+const legacyServiceRole = legacyJwts.find(
+  (jwt) => getJwtRole(jwt) === 'service_role',
+);
+
+const secretKey = newSecretKey || legacyServiceRole;
+
+if (!supabaseUrl || !secretKey) {
+  console.error(
+    'Could not find Supabase credentials in environment variables.',
+  );
+  console.error(
+    'Looking for: a URL matching https://<ref>.supabase.co and a key starting with sb_secret_ (or a service_role JWT)',
+  );
+  console.error(
+    'Add them to .env.local — the seed adapter scans all env vars by value pattern.',
+  );
+  process.exit(1);
+}
+
+// Admin client for user management (uses secret key to bypass RLS)
+const supabase = createClient(supabaseUrl, secretKey, {
+  auth: { autoRefreshToken: false, persistSession: false },
+});
+
+// Derive the project ref from the URL for cookie naming
+// e.g. "https://abcdefgh.supabase.co" → "abcdefgh"
+function getProjectRef(): string {
+  try {
+    const hostname = new URL(supabaseUrl!).hostname;
+    return hostname.split('.')[0];
+  } catch {
+    return 'unknown';
+  }
+}
+
+/**
+ * Build a mapping from lowercased seed-data keys to actual PostgreSQL table names.
+ * Prisma creates tables with the model name (PascalCase) unless @@map is used.
+ * PostgREST requires the exact table name, so we need this translation.
+ */
+function buildTableNameMap(): Record<string, string> {
+  const map: Record<string, string> = {};
+  for (const model of Prisma.dmmf.datamodel.models) {
+    // dbName is set when @@map is used, otherwise null → use model name
+    const dbName = (model as any).dbName || model.name;
+    // Map lowercased model name → actual table name
+    const lowered = model.name.charAt(0).toLowerCase() + model.name.slice(1);
+    map[lowered] = dbName;
+    map[model.name] = dbName; // Also map PascalCase for safety
+  }
+  return map;
+}
+
+async function seedTables(seed: Record<string, unknown[]>) {
+  if (Object.keys(seed).length === 0) return;
+
+  const tableMap = buildTableNameMap();
+
+  // Discover ALL models from the Prisma schema — not just the tables in the seed data.
+  // This ensures FK-dependent tables are cleared even when the seed only contains
+  // the parent table's data. Every editor project has Prisma installed.
+  const allTables = Prisma.dmmf.datamodel.models.map(
+    (m) => (m as any).dbName || m.name,
+  );
+
+  console.log(
+    `Clearing ${allTables.length} tables, seeding: ${Object.keys(seed).join(', ')}`,
+  );
+
+  // Clear ALL tables in reverse order (children before parents for FK safety)
+  for (const table of [...allTables].reverse()) {
+    const { error } = await supabase.from(table).delete().gte('id', 0);
+    if (error) {
+      const { error: error2 } = await supabase
+        .from(table)
+        .delete()
+        .not('id', 'is', null);
+      if (error2) {
+        console.warn(`  Could not clear ${table}: ${error2.message}`);
+      } else {
+        console.log(`  Cleared ${table}`);
+      }
+    } else {
+      console.log(`  Cleared ${table}`);
+    }
+  }
+
+  // Insert seed data — translate seed keys to actual table names
+  for (const [seedKey, rows] of Object.entries(seed)) {
+    if (!Array.isArray(rows) || rows.length === 0) continue;
+    const table = tableMap[seedKey] || seedKey;
+    const { error } = await supabase.from(table).insert(rows);
+    if (error) {
+      console.error(`  Failed to seed ${table}: ${error.message}`);
+      process.exit(1);
+    }
+    console.log(`  Seeded ${rows.length} rows into ${table}`);
+  }
+}
+
+/**
+ * Build a minimal JWT with a far-future expiry.
+ * The signature is fake — it doesn't matter because the CodeYam preload module
+ * intercepts the Supabase auth validation endpoint and returns mock data.
+ */
+function buildFakeJwt(userId: string, email: string): string {
+  const header = { alg: 'HS256', typ: 'JWT' };
+  const payload = {
+    sub: userId,
+    email,
+    role: 'authenticated',
+    aud: 'authenticated',
+    exp: 9999999999,
+    iat: Math.floor(Date.now() / 1000),
+  };
+  const encode = (obj: object) =>
+    Buffer.from(JSON.stringify(obj)).toString('base64url');
+  return `${encode(header)}.${encode(payload)}.codeyam-mock-signature`;
+}
+
+/**
+ * Build a Supabase user response object matching the /auth/v1/user endpoint format.
+ */
+function buildUserResponse(user: { id: string; email?: string }) {
+  return {
+    id: user.id,
+    aud: 'authenticated',
+    role: 'authenticated',
+    email: user.email || '',
+    email_confirmed_at: new Date().toISOString(),
+    app_metadata: { provider: 'email', providers: ['email'] },
+    user_metadata: {},
+    created_at: new Date().toISOString(),
+  };
+}
+
+const DEFAULT_AUTH_PASSWORD = 'codeyam-dev-password-123!';
+
+/**
+ * Handle auth: create user, build synthetic session, write session cookies.
+ * Returns the user ID so callers can replace __AUTH_USER_ID__ placeholders in seed data.
+ *
+ * No real sign-in is performed — the session cookie uses a synthetic JWT with
+ * far-future expiry, and externalApis mocks intercept all Supabase auth API calls.
+ * This avoids storing real tokens (security risk + expiration) in scenario files.
+ */
+async function handleAuth(auth: {
+  email: string;
+  password?: string;
+}): Promise<string> {
+  const email = auth.email;
+  const password = auth.password || DEFAULT_AUTH_PASSWORD;
+
+  // Create user if they don't exist (auto-confirm email)
+  // We still need the auth.users row for PostgREST FK relationships.
+  const { data: createData, error: createError } =
+    await supabase.auth.admin.createUser({
+      email,
+      password,
+      email_confirm: true,
+    });
+
+  let userId: string;
+
+  if (createError) {
+    if (createError.message.includes('already been registered')) {
+      // User exists — look up their ID
+      const { data: listData } = await supabase.auth.admin.listUsers();
+      const existingUser = listData?.users?.find((u) => u.email === email);
+      if (existingUser) {
+        userId = existingUser.id;
+        console.log(`  Found existing user ${email} (user: ${userId})`);
+      } else {
+        console.error(
+          `  User ${email} reported as registered but not found in listUsers`,
+        );
+        process.exit(1);
+      }
+    } else {
+      console.error(`  Failed to create auth user: ${createError.message}`);
+      process.exit(1);
+    }
+  } else {
+    userId = createData!.user.id;
+    console.log(`  Created user ${email} (user: ${userId})`);
+  }
+
+  // Build synthetic JWT and mock responses — no real sign-in needed.
+  // The preload module intercepts server-side getUser() calls so Next.js
+  // middleware returns the mock user without hitting real Supabase.
+  const fakeJwt = buildFakeJwt(userId!, email);
+  const userResponse = buildUserResponse({ id: userId!, email });
+
+  const projectRef = getProjectRef();
+  const sessionOutput = {
+    cookies: [
+      {
+        name: `sb-${projectRef}-auth-token`,
+        value: JSON.stringify({
+          access_token: fakeJwt,
+          refresh_token: 'codeyam-mock-refresh-token',
+          token_type: 'bearer',
+          expires_in: 315360000,
+          expires_at: 9999999999,
+        }),
+        path: '/',
+        sameSite: 'Lax' as const,
+      },
+    ],
+    externalApis: {
+      [`${supabaseUrl}/auth/v1/user`]: {
+        body: userResponse,
+        status: 200,
+      },
+      [`${supabaseUrl}/auth/v1/token`]: {
+        body: {
+          access_token: fakeJwt,
+          token_type: 'bearer',
+          expires_in: 315360000,
+          expires_at: 9999999999,
+          refresh_token: 'codeyam-mock-refresh-token',
+          user: userResponse,
+        },
+        status: 200,
+      },
+    },
+  };
+
+  const outputDir = path.join(process.cwd(), '.codeyam', 'tmp');
+  fs.mkdirSync(outputDir, { recursive: true });
+  const outputPath = path.join(outputDir, 'seed-session.json');
+  fs.writeFileSync(outputPath, JSON.stringify(sessionOutput, null, 2));
+  console.log(`  Session cookies + auth mocks written to ${outputPath}`);
+
+  return userId!;
+}
+
+/**
+ * Replace __AUTH_USER_ID__ placeholders in seed data with the actual Supabase user ID.
+ * This lets scenarios reference the authenticated user in foreign key columns (e.g. user_id)
+ * without knowing the UUID ahead of time.
+ */
+function replaceAuthPlaceholders(
+  seed: Record<string, unknown[]>,
+  userId: string,
+): Record<string, unknown[]> {
+  const json = JSON.stringify(seed);
+  const replaced = json.replace(/__AUTH_USER_ID__/g, userId);
+  return JSON.parse(replaced);
+}
+
+async function main() {
+  const seedDataPath = process.argv[2];
+  if (!seedDataPath) {
+    console.error('Usage: npx tsx .codeyam/seed-adapter.ts <seed-data.json>');
+    process.exit(1);
+  }
+
+  const raw = fs.readFileSync(seedDataPath, 'utf-8');
+  const data = JSON.parse(raw);
+
+  // Separate auth config from table data
+  const auth = data._auth;
+  let seed: Record<string, unknown[]> = {};
+  for (const [key, value] of Object.entries(data)) {
+    if (key === '_auth') continue;
+    seed[key] = value as unknown[];
+  }
+
+  // Auth first: we need the user ID to replace __AUTH_USER_ID__ placeholders
+  // in seed data (e.g. for user_id foreign key columns with Supabase RLS)
+  if (auth) {
+    const userId = await handleAuth(
+      auth as { email: string; password?: string },
+    );
+    seed = replaceAuthPlaceholders(seed, userId);
+  }
+
+  await seedTables(seed);
+
+  console.log('Seed complete');
+}
+
+main().catch((e) => {
+  console.error('Seed adapter error:', e);
+  process.exit(1);
+});

package/codeyam-cli/templates/skills/codeyam-editor/SKILL.md

@@ -16,6 +16,77 @@ You MUST follow a step-by-step workflow driven by `codeyam editor` commands. Eac
 
 **The rule:** After completing what a command tells you to do, run the NEXT command it specifies. The commands are your instructions — follow them one at a time.
 
+## TASK Directive
+
+Some `codeyam editor N` commands output a `━━━ TASK ━━━` section with an `EXACT_TASK_TITLE:` line. When you see one:
+
+1. Delete ALL existing tasks: run TaskList, then run TaskUpdate with status "deleted" for every task returned
+2. Run TaskCreate with the EXACT title from the `EXACT_TASK_TITLE:` line — copy it character-for-character, do NOT paraphrase
+
+This ensures only one task is ever visible. Do NOT create tasks on your own. Only create them when a `━━━ TASK ━━━` directive tells you to.
+
+## Migration Mode
+
+When `codeyam editor steps` shows **"Project Migration"** instead of "Feature Cycle", the project is being migrated from an existing codebase. Follow the `codeyam editor migrate` commands instead of the normal 13-step cycle.
+
+Migration uses a different command set:
+
+```
+codeyam editor migrate        → Survey the project (explore pages, confirm order)
+codeyam editor migrate 1-8    → Run migration step N for the current page
+codeyam editor migrate next   → Advance to the next page
+codeyam editor migrate status → Show migration progress
+```
+
+**The same rule applies:** run the command shown in the output, follow its checklist, then run the next command it specifies. Migration steps are 1-8 per page: Capture → Preview → Discuss → Decompose → Extract → Recapture → Journal → Present. Steps 4-6 (Decompose/Extract/Recapture) are optional — the user decides at step 3 whether to decompose or skip to step 7. After all pages are migrated, the project transitions to the normal feature cycle.
+
+**IMPORTANT:** When `codeyam editor steps` tells you to run a `codeyam editor migrate` command, run THAT command — do NOT run `codeyam editor 1` or any other normal step command.
+
+### Migration Survey (codeyam editor migrate)
+
+When you run `codeyam editor migrate` with no arguments and no existing migration state, follow this survey checklist:
+
+1. Read `package.json` — understand the framework, dependencies, and scripts
+2. Explore the project structure — find all page/route files
+   - Next.js App Router: `app/**/page.tsx` | Pages Router: `pages/**/*.tsx`
+   - Check for other patterns: `src/` directory, custom routing, etc.
+3. Read each page/route to assess complexity and data flow
+4. Identify how the dev server starts (check `scripts` in package.json)
+5. Note any environment variables, databases, or external services needed
+6. Present a numbered list of all pages with:
+   - Page name and route
+   - File path
+   - Complexity assessment (simple / moderate / complex)
+7. Suggest a migration order — **start with the most complex pages** (dashboards, analytics, etc.) as they best demonstrate CodeYam's value and have rich decomposition opportunities
+8. Wait for user confirmation of the order
+
+**After user confirms**, write `.codeyam/migration-state.json`:
+
+```json
+{
+  "status": "surveyed",
+  "startedAt": "<ISO>",
+  "completedAt": null,
+  "pages": [
+    {
+      "name": "Home",
+      "route": "/",
+      "filePath": "app/page.tsx",
+      "status": "pending",
+      "startedAt": null,
+      "completedAt": null,
+      "extractedComponents": [],
+      "extractedFunctions": [],
+      "scenarioCount": 0
+    }
+  ],
+  "currentPageIndex": 0,
+  "sharedComponents": []
+}
+```
+
+Then run: `codeyam editor migrate 1`
+
 ## The Cycle
 
 Every feature follows 13 gated steps:
@@ -55,6 +126,9 @@ This command gives you the post-change checklist (re-register scenarios, re-run
 ## Key Rules
 
 - **Run the commands** — they ARE your instructions, not suggestions
+- **One step at a time** — run each `codeyam editor N` command, read its FULL output, complete every checklist item, then advance. The CLI enforces a minimum time per step.
+- **NEVER batch-run steps** — `for step in 5 6 7 8; do codeyam editor $step; done` or piping to `head` defeats the entire workflow. Each step has unique instructions you must read and follow.
+- **NEVER delegate multiple steps to a subagent** — each step must be run, read, and completed in the main conversation. You MAY use subagents for parallelizable work _within_ a single step (e.g. extracting components + writing tests in step 5).
 - **Every feature gets scenarios** — this is the core value of CodeYam
 - **Always scaffold with a database** (Prisma + SQLite)
 - **Build real API routes** — the proxy handles scenario data transparently
@@ -101,6 +175,21 @@ Isolation routes are committed to git (not gitignored). They are protected by a
 
 When a collaborator clones the repo and runs `codeyam editor`, scenarios are auto-imported from `scenarios-manifest.json`. Run `codeyam editor sync` to manually re-sync after pulling new changes.
 
+## Expo / React Native Projects
+
+When working with an Expo project (tech stack `expo-react-native`):
+
+- Use `<View>`, `<Text>`, `<ScrollView>`, `<Pressable>` from `react-native` — **never use HTML elements** (`<div>`, `<span>`, `<h1>`, etc.)
+- Do NOT use `'use client'` — this is a Next.js directive that has no meaning in Expo
+- Do NOT import from `next/navigation`, `next/router`, or any `next/*` package
+- Use `expo-router` for navigation: `useRouter()`, `useLocalSearchParams()`, `<Link>`
+- Use `@/lib/theme` for all design tokens — not CSS custom properties (`var(--token)` does not work in React Native)
+- AsyncStorage maps to localStorage on web — CodeYam's `localStorage` injection in scenarios works automatically
+- Test with `npx jest`, not `npx vitest`
+- Isolation routes use Expo Router: `app/isolated-components/ComponentName.tsx` (not a `/page.tsx` subdirectory)
+- Capture wrappers use `nativeID="codeyam-capture"` (not `id="codeyam-capture"`) — `nativeID` maps to `id` on web
+- The preview renders via react-native-web in a browser — some visual differences from native devices are expected (fonts, SafeAreaView, shadows). See `MOBILE_SETUP.md` for details.
+
 ## Quick Reference
 
 ```bash
@@ -114,7 +203,13 @@ codeyam editor register '{"name":"Full Catalog","type":"application","url":"/","
 # Register app scenario with localStorage (for apps using client-side storage instead of a database)
 codeyam editor register '{"name":"Full Library","type":"application","url":"/","dimensions":["<name from screenSizes>"],"localStorage":{"articles":[...],"collections":[...]}}'
 
-# For large seed/localStorage data, write JSON to a temp file and use @ prefix:
+# BULK REGISTRATION (preferred — register all scenarios at once):
+# Write an array of scenarios to a temp file, then register with @ prefix.
+# This is faster and avoids repeated screenshot capture overhead.
+# File format: [{"name":"...","type":"...","url":"...","seed":{...}}, ...]
+codeyam editor register @.codeyam/tmp/scenarios.json
+
+# Single scenario from file (for large seed/localStorage data):
 codeyam editor register @/tmp/scenario-data.json
 
 # Journal entry (one per feature, references scenario names)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@codeyam/codeyam-cli",
-  "version": "0.1.0-staging.8b51541",
+  "version": "0.1.0-staging.8c89b23",
   "description": "Local development CLI for CodeYam analysis",
   "type": "module",
   "bin": {
@@ -46,6 +46,7 @@
     "p-queue": "^9.1.0",
     "p-retry": "^7.1.1",
     "pg": "^8.19.0",
+    "posthog-node": "^4.0.0",
     "piscina": "^5.1.4",
     "pixelmatch": "^5.3.0",
     "playwright": "1.58.0",

package/packages/ai/src/lib/astScopes/methodSemantics.js

@@ -616,6 +616,97 @@ export class UseStateSemantics {
         return true;
     }
 }
+// ─── Set/Map method semantics ──────────────────────────────────────────
+//
+// Set/Map membership operations (.has, .delete, .add, .get, .set, .clear)
+// don't create data flow equivalencies — they're membership checks or
+// mutations, not transformations that propagate schema structure.
+// Without these semantics, code like `filterRatings.has(articleId)` creates
+// spurious equivalencies (332 entries in the Margo LibraryPage case).
+/**
+ * Set.has() / Map.has() — membership check, returns boolean
+ */
+export class CollectionHasSemantics {
+    getReturnType() {
+        return 'boolean';
+    }
+    addEquivalences(methodCallPath, _sourcePath, context) {
+        context.addType(methodCallPath, 'boolean');
+    }
+    isComplete() {
+        return true;
+    }
+}
+/**
+ * Set.delete() / Map.delete() — removal, returns boolean
+ */
+export class CollectionDeleteSemantics {
+    getReturnType() {
+        return 'boolean';
+    }
+    addEquivalences(methodCallPath, _sourcePath, context) {
+        context.addType(methodCallPath, 'boolean');
+    }
+    isComplete() {
+        return true;
+    }
+}
+/**
+ * Set.add() — adds an element, returns the Set (for chaining)
+ */
+export class SetAddSemantics {
+    getReturnType() {
+        return 'object'; // Returns the Set itself
+    }
+    addEquivalences(_methodCallPath, _sourcePath, _context) {
+        // No equivalencies — add() doesn't create data flow
+    }
+    isComplete() {
+        return true;
+    }
+}
+/**
+ * Set.clear() / Map.clear() — removes all elements, returns void
+ */
+export class CollectionClearSemantics {
+    getReturnType() {
+        return 'void';
+    }
+    addEquivalences() {
+        // No equivalencies
+    }
+    isComplete() {
+        return true;
+    }
+}
+/**
+ * Map.get() — retrieves a value by key, returns unknown (value type)
+ */
+export class MapGetSemantics {
+    getReturnType() {
+        return 'unknown';
+    }
+    addEquivalences(_methodCallPath, _sourcePath, _context) {
+        // No equivalencies — the return value type depends on the map contents
+    }
+    isComplete() {
+        return true;
+    }
+}
+/**
+ * Map.set() — sets a key-value pair, returns the Map (for chaining)
+ */
+export class MapSetSemantics {
+    getReturnType() {
+        return 'object'; // Returns the Map itself
+    }
+    addEquivalences() {
+        // No equivalencies
+    }
+    isComplete() {
+        return true;
+    }
+}
 /**
  * Create and populate the registry with method semantics
  */
@@ -645,6 +736,14 @@ export function createMethodRegistry() {
     // Register React hooks
     registry.register('useState', new UseStateSemantics(), 'React');
     registry.register('useMemo', new UseMemoSemantics(), 'React');
+    // Register Set/Map collection methods.
+    // Only .has() and .delete() are safe to register by method name — they always
+    // return boolean regardless of the collection type (Set, Map, WeakSet, WeakMap,
+    // FormData, URLSearchParams, etc.).
+    // .add(), .clear(), .get(), .set() are too ambiguous across different types
+    // and can't be registered until the lookup code supports class-aware resolution.
+    registry.register('has', new CollectionHasSemantics());
+    registry.register('delete', new CollectionDeleteSemantics());
     return registry;
 }
 // Create a singleton instance of the registry for use throughout the codebase