@codeyam/codeyam-cli 0.1.0-staging.ae0de75 → 0.1.0-staging.b6c4c78

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

@@ -0,0 +1,282 @@
+/**
+ * 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"
+ *   }
+ * }
+ *
+ * When _auth is present, the adapter:
+ * 1. Creates the user if they don't exist (auto-confirms email)
+ * 2. Signs in with signInWithPassword to get a valid session
+ * 3. Writes session cookies to .codeyam/tmp/seed-session.json
+ *    so the CodeYam proxy can inject them into the browser
+ *
+ * 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 * 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];
+const newAnonKey = findAllEnvByPattern(/^sb_publishable_/)[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 legacyAnon = legacyJwts.find((jwt) => getJwtRole(jwt) === 'anon');
+
+const secretKey = newSecretKey || legacyServiceRole;
+const anonKey = newAnonKey || legacyAnon;
+
+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';
+  }
+}
+
+async function seedTables(seed: Record<string, unknown[]>) {
+  const tableNames = Object.keys(seed);
+  if (tableNames.length === 0) return;
+
+  console.log(`Seeding tables: ${tableNames.join(', ')}`);
+
+  // Wipe tables in reverse order (to respect foreign keys)
+  for (const table of [...tableNames].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
+  for (const [table, rows] of Object.entries(seed)) {
+    if (!Array.isArray(rows) || rows.length === 0) continue;
+    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}`);
+  }
+}
+
+/**
+ * Handle auth: create user, sign in, write session cookies.
+ * Returns the user ID so callers can replace __AUTH_USER_ID__ placeholders in seed data.
+ */
+async function handleAuth(auth: {
+  email: string;
+  password: string;
+}): Promise<string> {
+  const { email, password } = auth;
+
+  // Create user if they don't exist (auto-confirm email so sign-in works)
+  const { data: createData, error: createError } =
+    await supabase.auth.admin.createUser({
+      email,
+      password,
+      email_confirm: true,
+    });
+
+  if (createError) {
+    if (createError.message.includes('already been registered')) {
+      // User exists — update their password so sign-in works even if the
+      // scenario specifies a different password than a previous run.
+      const { data: listData } = await supabase.auth.admin.listUsers();
+      const existingUser = listData?.users?.find((u) => u.email === email);
+      if (existingUser) {
+        await supabase.auth.admin.updateUserById(existingUser.id, {
+          password,
+        });
+        console.log(`  Updated password for existing user ${email}`);
+      }
+    } else {
+      console.error(`  Failed to create auth user: ${createError.message}`);
+      process.exit(1);
+    }
+  }
+
+  // Sign in to get a valid session
+  // Use a separate client with the publishable/anon key for sign-in (if available)
+  const signInClient =
+    anonKey && anonKey !== secretKey
+      ? createClient(supabaseUrl!, anonKey, {
+          auth: { autoRefreshToken: false, persistSession: false },
+        })
+      : supabase;
+
+  const { data: signInData, error: signInError } =
+    await signInClient.auth.signInWithPassword({ email, password });
+
+  if (signInError || !signInData.session) {
+    console.error(
+      `  Failed to sign in as ${email}: ${signInError?.message || 'no session returned'}`,
+    );
+    process.exit(1);
+  }
+
+  const userId = signInData.user.id;
+  console.log(`  Signed in as ${email} (user: ${userId})`);
+
+  // Write session cookies for the proxy to inject
+  const projectRef = getProjectRef();
+  const sessionOutput = {
+    cookies: [
+      {
+        name: `sb-${projectRef}-auth-token`,
+        value: JSON.stringify({
+          access_token: signInData.session.access_token,
+          refresh_token: signInData.session.refresh_token,
+          token_type: 'bearer',
+          expires_in: signInData.session.expires_in,
+          expires_at: signInData.session.expires_at,
+        }),
+        path: '/',
+        sameSite: 'Lax' as const,
+      },
+    ],
+  };
+
+  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 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-dev-mode/SKILL.md

@@ -53,7 +53,7 @@ Then present a **concise** overview to the user:
 
 1. **Component Summary** — 2-3 sentences on what the component does and the current scenario being previewed.
 
-2. **Suggested Tests** — Compare the component's code paths (conditionals, edge cases, visual states) against the existing scenarios from the database. Recommend 2-4 specific ways to test the component that are **not yet covered** by saved scenarios. Focus on interesting visual states — e.g. "What does this look like with a very long title?", "What happens when the list is empty?", "How does the error state render?". Be specific to this component, not generic.
+2. **Suggested Tests** — Compare the component's code paths (conditionals, edge cases, visual states) against the existing scenarios from the database. Recommend 2-4 specific ways to test the component that are **not yet covered** by saved scenarios. Focus on interesting visual states — e.g. "What does this look like with a very long title?", "What happens when the list is empty?", "How does the error state render?". Also suggest ways to enrich the _existing_ scenario's data to better exercise the component (more realistic content, populated optional fields, diverse values). Be specific to this component, not generic.
 
 Keep it brief — no tables, no exhaustive attribute lists. The user can see the preview and wants actionable suggestions, not a data dump.
 
@@ -229,7 +229,7 @@ tail -50 <server log path from context file>
 ## Tips
 
 - **NEVER modify shimmed component files** (`*_Scenario.tsx`) to change rendering behavior — only edit `MockData_*.tsx` files to change what the component displays. Shimmed components are auto-generated; functional changes to them won't persist and can't be saved as scenarios.
-- Keep edits small and incremental so the user can see changes in the preview as you go
+- **Refresh the preview frequently** — the user is watching the preview panel as you work. Make small changes, then refresh so they see visual progress. Don't batch multiple edits into one big refresh at the end. Aim for a refresh after every meaningful edit (new data values, layout changes, style tweaks).
 - **Always add `[CY-DEBUG]` logging before refreshing** — never refresh without a way to verify the result
 - Mock data files are TypeScript (`.tsx`) — they export scenario-specific props/data
 - The database at `.codeyam/db.sqlite3` has entity and scenario metadata if you need deeper investigation

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

@@ -12,16 +12,78 @@ You are in **Editor Mode**. The user sees a split-screen: this terminal on the l
 
 You MUST follow a step-by-step workflow driven by `codeyam editor` commands. Each command tells you exactly what to do next. **You do NOT have all the instructions upfront** — the commands provide them incrementally.
 
-**Your first action:** Run `codeyam editor`.
+**Your first action:** Run `codeyam editor steps`.
 
 **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.
 
+## 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 12 gated steps:
+Every feature follows 13 gated steps:
 
 ```
-codeyam editor      → Setup (if new) or cycle overview
+codeyam editor steps → Setup (if new) or cycle overview
 codeyam editor 1    → Plan the feature (confirm with user)
 codeyam editor 2    → Build a working prototype fast
 codeyam editor 3    → Confirm prototype with user
@@ -33,10 +95,24 @@ codeyam editor 8    → Create app-level scenarios
 codeyam editor 9    → Create user-persona scenarios
 codeyam editor 10   → Verify screenshots and check for errors
 codeyam editor 11   → Create/update journal entry
-codeyam editor 12   → Present summary, get final approval
+codeyam editor 12   → Verify screenshots and audit
+codeyam editor 13   → Present summary, get final approval
 ```
 
-**You MUST run each command and follow its checklist before moving to the next.** Steps 1, 3, and 12 require user confirmation. After step 12, loop back to step 1.
+**You MUST run each command and follow its checklist before moving to the next.** Steps 1, 3, and 13 require user confirmation. After step 13, loop back to step 1.
+
+## Handling User Feedback / Changes
+
+When the user asks for changes — whether through the menu, a direct request, or even a question that implies a change (e.g., "Can the cards have images?") — you MUST run `codeyam editor change` **before** making any modifications. This includes:
+
+- Code changes (components, routes, lib functions, styles)
+- Scenario data updates (seed data, localStorage data, mock data)
+- Style adjustments (CSS, Tailwind classes, layout tweaks)
+- Even small fixes (typos, color tweaks, spacing)
+
+This command gives you the post-change checklist (re-register scenarios, re-run tests, update journal, etc.). Never make changes without running the change workflow first.
+
+**CRITICAL:** The change workflow MUST end with `codeyam editor 13`, which shows Working Session Results to the user. Skipping this step is a broken experience — the user will not see what changed and cannot approve or request further changes. Every change, no matter how small, must conclude with results being shown.
 
 ## Key Rules
 
@@ -45,25 +121,91 @@ codeyam editor 12   → Present summary, get final approval
 - **Always scaffold with a database** (Prisma + SQLite)
 - **Build real API routes** — the proxy handles scenario data transparently
 - **Start the dev server via the CodeYam API** — it handles proxy setup automatically
-- **Verify the preview after changes** — check the dev server URL, not the proxy
+- **Keep the preview moving** — the user watches the preview panel as you work. Refresh it frequently so they see progress, not a static screen. See below.
+
+## Keep the Preview Moving
+
+The user is watching the live preview panel while you work. A static preview makes it feel like nothing is happening. **Refresh the preview after every meaningful change** — not just at the end of a step.
+
+**During prototyping (step 2):**
+
+- Refresh after creating the first visible page, even if it's bare
+- Refresh after adding each major UI section (header, list, form, etc.)
+- Refresh after seeding data so the user sees real content appear
+- Refresh after styling changes so the user sees the visual progress
+
+**During extraction (step 5):**
+
+- Refresh after extracting each batch of components to confirm nothing broke
+
+**During changes:**
+
+- Refresh after each individual change, not after all changes are done
+
+**How to refresh:**
+
+```
+codeyam editor preview '{"dimension":"<name from screenSizes>"}'
+```
+
+Navigate to a specific path or switch scenario:
+
+```
+codeyam editor preview '{"path":"/drinks/1","dimension":"<name from screenSizes>"}'
+codeyam editor preview '{"scenarioId":"abc-123"}'
+```
+
+The goal: the user should see the preview update 4-8+ times during a typical building session, not just once at the end.
+
+## Collaboration
+
+Isolation routes are committed to git (not gitignored). They are protected by a layout guard at `app/isolated-components/layout.tsx` that returns `notFound()` in production, so they are safe to commit. Scenarios, screenshots, journal entries, and the glossary are also committed. Only the local database and secrets are gitignored.
+
+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.
 
 ## Quick Reference
 
 ```bash
-# Register scenario (auto-captures screenshot)
-curl -s -X POST http://localhost:${CODEYAM_PORT:-3111}/api/editor-register-scenario \
-  -H 'Content-Type: application/json' \
-  -d '{"name":"...","description":"...","mockData":{"routes":{"/api/...":{"body":[...]}}}}'
+# Register component scenario (auto-captures screenshot)
+# ALWAYS include "dimensions" — use the project's default screen size name from setup
+codeyam editor register '{"name":"DrinkCard - Default","componentName":"DrinkCard","componentPath":"app/components/DrinkCard.tsx","url":"/isolated-components/DrinkCard?s=Default","dimensions":["<name from screenSizes>"],"mockData":{"routes":{"/api/...":{"body":[...]}}}}'
+
+# Register app scenario with seed data (ALWAYS include "url" and "dimensions")
+codeyam editor register '{"name":"Full Catalog","type":"application","url":"/","dimensions":["<name from screenSizes>"],"seed":{"drinks":[...]}}'
+
+# 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:
+codeyam editor register @/tmp/scenario-data.json
 
 # Journal entry (one per feature, references scenario names)
-curl -s -X POST http://localhost:${CODEYAM_PORT:-3111}/api/editor-journal-entry \
-  -H 'Content-Type: application/json' \
-  -d '{"title":"...","type":"feature","description":"...","scenarios":["..."]}'
+codeyam editor journal '{"title":"...","type":"feature","description":"..."}'
+
+# Update journal with commit info
+codeyam editor journal-update '{"time":"...","commitSha":"...","commitMessage":"..."}'
 
-# Refresh preview
-curl -s -X POST http://localhost:${CODEYAM_PORT:-3111}/api/dev-mode-preview
+# Refresh preview / navigate / switch scenario (ALWAYS include "dimension")
+codeyam editor preview '{"dimension":"<name from screenSizes>"}'
+codeyam editor preview '{"path":"/drinks/1","dimension":"<name from screenSizes>"}'
+codeyam editor preview '{"scenarioId":"abc-123"}'
+
+# Show/hide results panel
+codeyam editor show-results
+codeyam editor hide-results
+
+# Commit feature
+codeyam editor commit '{"message":"feat: Add drinks page"}'
 
 # Restart dev server (only for config/dependency changes)
-curl -s -X POST http://localhost:${CODEYAM_PORT:-3111}/api/editor-dev-server \
-  -H 'Content-Type: application/json' -d '{"action":"restart"}'
+codeyam editor dev-server '{"action":"restart"}'
+
+# Check for client-side errors
+codeyam editor client-errors
+
+# Verify all images load (extracts URLs from pages, HTTP-checks each one)
+codeyam editor verify-images '{"paths":["/","/drinks/1"]}'
+
+# Sync scenarios from manifest (after pulling collaborator changes)
+codeyam editor sync
 ```

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

@@ -225,31 +225,31 @@ rm -rf /tmp/codeyam-memory/ /tmp/cc-session-analysis/
 ```
 
 ```bash
-bash .claude/skills/codeyam-memory/scripts/holistic-analysis/detect-deprecated-patterns.sh
+node .claude/skills/codeyam-memory/scripts/holistic-analysis/detect-deprecated-patterns.mjs
 ```
 
 ```bash
-bash .claude/skills/codeyam-memory/scripts/holistic-analysis/find-exports.sh
+node .claude/skills/codeyam-memory/scripts/holistic-analysis/find-exports.mjs
 ```
 
 ```bash
-bash .claude/skills/codeyam-memory/scripts/session-mining/preprocess.sh 2>/dev/null
+node .claude/skills/codeyam-memory/scripts/session-mining/preprocess.mjs 2>/dev/null
 ```
 
-Capture the stdout of `preprocess.sh` — each line is a path to a filtered session file.
+Capture the stdout of `preprocess.mjs` — each line is a path to a filtered session file.
 
 ### Step 2: Extract sizing metrics
 
-Use quick `jq` one-liners to extract counts — do NOT read the full JSON files into the main context:
+Use quick one-liners to extract counts — do NOT read the full JSON files into the main context:
 
 ```bash
-jq '.dependencies | length' /tmp/codeyam-memory/deprecated-scan.json
-jq '.explicit_markers | length' /tmp/codeyam-memory/deprecated-scan.json
-jq '.stats.total_exports' /tmp/codeyam-memory/exports-scan.json
-jq '.stats.total_files' /tmp/codeyam-memory/exports-scan.json
+node .claude/skills/codeyam-memory/scripts/lib/read-json-field.mjs /tmp/codeyam-memory/deprecated-scan.json '.dependencies | length'
+node .claude/skills/codeyam-memory/scripts/lib/read-json-field.mjs /tmp/codeyam-memory/deprecated-scan.json '.explicit_markers | length'
+node .claude/skills/codeyam-memory/scripts/lib/read-json-field.mjs /tmp/codeyam-memory/exports-scan.json '.stats.total_exports'
+node .claude/skills/codeyam-memory/scripts/lib/read-json-field.mjs /tmp/codeyam-memory/exports-scan.json '.stats.total_files'
 ```
 
-The session count is the number of lines from `preprocess.sh` stdout.
+The session count is the number of lines from `preprocess.mjs` stdout.
 
 **Time estimate formulas:**