@codeyam/codeyam-cli 0.1.0-staging.483fdc2 → 0.1.0-staging.50df560

package/codeyam-cli/templates/rules-instructions.md

@@ -4,123 +4,75 @@ Rules provide context-specific guidance when working in files matching their `pa
 
 ## Core Principles
 
-1. **One concept per rule** - Each rule should cover a single topic. If you're documenting two unrelated things, create two rules.
-2. **Paths must match content scope** - A rule about one specific file should have that file in `paths`, not a broad `**/*.ts` pattern.
-3. **Be concise** - Every word costs context. Use bullets and tables.
+1. **One concept per rule** — If you're documenting two unrelated things, create two rules.
+2. **Paths must match content scope** — A rule about one file should have that file in `paths`, not a broad `**/*.ts` pattern.
+3. **Keep rules SHORT** — Most rules should be **1-4 bullets**. Only complex multi-file architectures should exceed ~10 lines.
 
-## When to Create a New Rule
+**Example** — a typical rule:
 
-Create a new rule when:
-
-- You learn something non-obvious about the codebase
-- You make a mistake and want to prevent it in the future
-- The user explains something that isn't clear from the code
-- An existing rule is covering multiple unrelated topics (split it)
-
-## Before Creating: The Confusion Test
-
-Before writing a rule, verify it passes these tests:
-
-**1. Could Claude figure this out by reading the code?**
-
-- If YES → don't create the rule (it documents the obvious)
-- If NO → the rule is valuable
-
-**2. Does this explain "why" not just "what"?**
-
-- Good: Explains historical context, gotchas, or non-obvious behavior
-- Bad: Describes what functions do or how files are structured
-
-**3. Would this have prevented a past mistake?**
-
-- If you can point to a commit, bug, or confusion this would have prevented → create it
-- If it's just "nice to know" information → skip it
-
-### Examples
-
-**✅ Worth documenting:**
-
-- "Path prefix matching must check boundaries" (learned from a bug)
-- "These files must change together because of X invariant" (hidden dependency)
-- "This pattern exists because the obvious approach causes Y problem" (non-obvious design)
-
-**❌ Not worth documenting:**
-
-- "Use `pnpm jest` to run tests" (obvious from package.json)
-- "The auth module handles authentication" (obvious from reading code)
-- "This function takes X and returns Y" (Claude can read the signature)
+```markdown
+---
+paths:
+  - 'packages/ai/src/lib/generateMockData.ts'
+---
 
-## Path Specificity
+# Mock Data Generation
 
-The `paths` field controls when the rule is shown. Match the scope of your content:
+- Entry point: `generateMockData()` in `generateMockData.ts`
+- Uses `convertDotNotation` to transform flat schema into nested objects
+- Schema entry ORDER matters — `key[]` must come before `key[].property` or arrays get overwritten
+- Test with exact ordering from database, not just same entries
+```
 
-| Content Scope | Path Pattern            | Example                                                |
-| ------------- | ----------------------- | ------------------------------------------------------ |
-| Single file   | `'path/to/file.ts'`     | Rule about `processExpression.ts` specifically         |
-| Related files | `'path/to/feature*.ts'` | Rule about `generateExecutionFlows*.ts` files          |
-| Directory     | `'path/to/dir/**/*.ts'` | Rule about the queue system in `utils/queue/`          |
-| Cross-cutting | Multiple specific paths | Testing rule with paths to test configs and test files |
+## When to Create a Rule
 
-**Anti-pattern**: Don't use `'**/*.ts'` for a rule about one specific feature.
+Create a rule when you learn something that **reading the code alone wouldn't reveal**:
 
-## File Structure
+- Non-obvious gotchas or behavior that caused real confusion or bugs
+- Architecture, file relationships, or data flows that take time to piece together
+- Debugging strategies for a tricky area of the codebase
+- Preferred commands or workflows when multiple options exist (e.g. "Use `pnpm test` to run tests")
+- User corrections or explanations that aren't captured in the code itself
 
-Rules mirror the source code structure:
+**Skip** rules that restate what the code says — function signatures, type definitions, "this module handles X." Claude can read the code.
 
-| Source Location      | Rule Location                           |
-| -------------------- | --------------------------------------- |
-| `src/api/auth.ts`    | `.claude/rules/src/api/auth.md`         |
-| `src/utils/queue/**` | `.claude/rules/src/utils/queue.md`      |
-| Test configuration   | `.claude/rules/testing/jest-configs.md` |
+## Frontmatter & Paths
 
-## Required Frontmatter
+Every rule needs a `paths` frontmatter field. Be specific to avoid loading rules unnecessarily:
 
 ```yaml
 ---
 paths:
   - 'specific/path/to/file.ts'
   - 'another/specific/path/*.ts'
-category: architecture | testing | faq
-timestamp: 2026-01-30T00:00:00Z
 ---
 ```
 
-| Field       | Purpose                                                                                            |
-| ----------- | -------------------------------------------------------------------------------------------------- |
-| `paths`     | Glob patterns - be specific to avoid loading rules unnecessarily                                   |
-| `category`  | `architecture` (design/data flow), `testing` (test commands/patterns), `faq` (gotchas/workarounds) |
-| `timestamp` | ISO 8601 - update when rule is reviewed                                                            |
-
-## Content Guidelines
-
-### Be Actionable
+| Content Scope | Path Pattern            | Example                                        |
+| ------------- | ----------------------- | ---------------------------------------------- |
+| Single file   | `'path/to/file.ts'`     | Rule about `processExpression.ts` specifically |
+| Related files | `'path/to/feature*.ts'` | Rule about `generateExecutionFlows*.ts` files  |
+| Directory     | `'path/to/dir/**/*.ts'` | Rule about the queue system in `utils/queue/`  |
+| Cross-cutting | Multiple specific paths | Testing rule spanning test configs and tests   |
 
-- Good: "Run `pnpm test:api` for API tests"
-- Bad: "Make sure to run the appropriate tests"
+Audit dates live in `.claude/codeyam-rule-state.json` (managed by `codeyam memory touch`). Keep frontmatter limited to `paths`.
 
-### Focus on What, Not What Not
+## File Placement
 
-- Good: "Auth tokens are stored in httpOnly cookies via `src/auth/cookies.ts`"
-- Bad: "WARNING: Don't store tokens in localStorage!"
+Rules must be written to `.claude/rules/`, NOT `.codeyam/rules/`. The instructions file lives in `.codeyam/` but actual rule files go in `.claude/rules/`.
 
-### Keep Rules Short
+Use `codeyam memory rule-path` to compute the correct directory from your frontmatter paths:
 
-- Target 30-50 lines
-- If a rule exceeds 60 lines, consider splitting it
-
-## Categories
-
-**architecture** - Design decisions, file relationships, data flow
-
-- "These three files must change together because..."
-- "Data flows from X → Y → Z"
-
-**testing** - Test commands, mock patterns, fixtures
+```
+$ codeyam memory rule-path packages/ai/src/lib/foo.ts packages/ai/src/utils/bar.ts
+{"result":".claude/rules/packages/ai/src/"}
+```
 
-- "Run tests with: `pnpm test path/to/test.ts`"
-- "Must run `pnpm pretest` first because..."
+The command computes the deepest common directory shared by all paths and returns the `.claude/rules/` subdirectory where the rule file should live. Reserve the top level of `.claude/rules/` for rules whose paths genuinely span the entire repo.
 
-**faq** - Gotchas, workarounds, common questions
+## Content Guidelines
 
-- "If you see error X, it means Y"
-- "This looks wrong but is intentional because..."
+- **Be actionable** — "Run `pnpm test:api` for API tests" not "Make sure to run the appropriate tests"
+- **Focus on why, not what** — Gotchas, non-obvious behavior, architectural decisions. The code already shows "what."
+- **Point to specifics** — "Auth tokens are stored in httpOnly cookies via `src/auth/cookies.ts`" beats a vague description.
+- **Be short!** - Context window space is precious! Do not ramble, use bullets, focus on providing clear actionable information.

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/{codeyam:debug.md → skills/codeyam-debug/SKILL.md}

@@ -1,5 +1,5 @@
 ---
-name: codeyam:debug
+name: codeyam-debug
 autoApprove: true
 description: |
   Use this skill when entity analysis or capture fails with errors.