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

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

@@ -12,16 +12,87 @@ 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.
 
+## 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 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,37 +104,126 @@ 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
 
 - **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
 - **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":[...]}}'
+
+# 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)
-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":"..."}'
 
-# Refresh preview
-curl -s -X POST http://localhost:${CODEYAM_PORT:-3111}/api/dev-mode-preview
+# Update journal with commit info
+codeyam editor journal-update '{"time":"...","commitSha":"...","commitMessage":"..."}'
+
+# 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:**
 

package/codeyam-cli/templates/skills/codeyam-memory/scripts/holistic-analysis/detect-deprecated-patterns.mjs

@@ -0,0 +1,139 @@
+#!/usr/bin/env node
+// Gathers deprecation signals from package.json, source markers, and git history.
+// Outputs structured JSON to /tmp/codeyam-memory/deprecated-scan.json
+
+import { readdir, readFile, mkdir, writeFile } from 'node:fs/promises';
+import { execFileSync } from 'node:child_process';
+import { join } from 'node:path';
+import { ripgrepSearch } from '../lib/ripgrep-fallback.mjs';
+
+const OUTPUT_DIR = '/tmp/codeyam-memory';
+const OUTPUT_FILE = join(OUTPUT_DIR, 'deprecated-scan.json');
+await mkdir(OUTPUT_DIR, { recursive: true });
+
+// --- Dependency scan ---
+// Collect all dependency names from package.json files
+const allDeps = new Set();
+const packageFiles = await findFiles('.', 'package.json', ['node_modules', 'dist', '.next']);
+
+for (const pkgPath of packageFiles) {
+  try {
+    const pkg = JSON.parse(await readFile(pkgPath, 'utf-8'));
+    for (const key of ['dependencies', 'devDependencies']) {
+      if (pkg[key] && typeof pkg[key] === 'object') {
+        for (const dep of Object.keys(pkg[key])) allDeps.add(dep);
+      }
+    }
+  } catch {
+    // Skip unparseable package.json
+  }
+}
+
+const dependencies = [...allDeps].sort();
+
+// --- Explicit marker scan ---
+let explicitMarkers = [];
+
+const markerOutput = await ripgrepSearch(
+  '@deprecated|// legacy|// deprecated|// old approach|TODO.*deprecat|FIXME.*deprecat',
+  {
+    types: ['ts', 'js'],
+    globs: ['!node_modules', '!dist', '!build', '!.next'],
+    context: 2,
+    lineNumbers: true,
+  },
+);
+
+if (markerOutput.trim()) {
+  // Parse ripgrep output into structured entries
+  for (const line of markerOutput.split('\n')) {
+    // Match "file:line:text" (colons in file path unlikely for these repos)
+    const match = line.match(/^([^:]+):(\d+):(.*)$/);
+    if (match) {
+      explicitMarkers.push({
+        file: match[1],
+        line: parseInt(match[2], 10),
+        text: match[3].trim(),
+      });
+    }
+  }
+}
+
+// --- Git recency comparison ---
+const gitRecency = {};
+
+if (dependencies.length > 0) {
+  const recentImports = gitImports('3 months ago', undefined);
+  const oldImports = gitImports('12 months ago', '3 months ago');
+
+  for (const dep of dependencies) {
+    if (dep.length < 3) continue; // Skip short names that match too broadly
+
+    const pattern = `from ['"]${dep}`;
+    const recent = countMatches(recentImports, pattern);
+    const old = countMatches(oldImports, pattern);
+
+    if (recent > 0 || old > 0) {
+      gitRecency[dep] = { recent_imports: recent, old_imports: old };
+    }
+  }
+}
+
+// --- Assemble final output ---
+const output = {
+  dependencies,
+  explicit_markers: explicitMarkers,
+  git_recency: gitRecency,
+};
+
+await writeFile(OUTPUT_FILE, JSON.stringify(output, null, 2));
+
+console.log(`Deprecated pattern scan complete: ${OUTPUT_FILE}`);
+console.log(`  Dependencies found: ${dependencies.length}`);
+console.log(`  Explicit markers found: ${explicitMarkers.length}`);
+console.log(`  Deps with git activity: ${Object.keys(gitRecency).length}`);
+
+// --- Helpers ---
+
+async function findFiles(dir, filename, ignoreDirs) {
+  const results = [];
+  const ignoreSet = new Set(ignoreDirs);
+
+  let entries;
+  try {
+    entries = await readdir(dir, { recursive: true, withFileTypes: true });
+  } catch {
+    return results;
+  }
+
+  for (const entry of entries) {
+    if (!entry.isFile() || entry.name !== filename) continue;
+    const parentPath = entry.parentPath ?? entry.path; // parentPath in Node 22+
+    const parts = parentPath.split('/');
+    if (parts.some((p) => ignoreSet.has(p))) continue;
+    results.push(join(parentPath, entry.name));
+  }
+  return results;
+}
+
+function gitImports(since, until) {
+  const args = ['log', `--since=${since}`, '-p', '--', '*.ts', '*.tsx', '*.js', '*.jsx'];
+  if (until) args.splice(2, 0, `--until=${until}`);
+
+  try {
+    const output = execFileSync('git', args, {
+      maxBuffer: 100 * 1024 * 1024,
+      encoding: 'utf-8',
+      stdio: ['pipe', 'pipe', 'pipe'],
+    });
+    return output;
+  } catch {
+    return '';
+  }
+}
+
+function countMatches(text, pattern) {
+  const regex = new RegExp(pattern, 'g');
+  const matches = text.match(regex);
+  return matches ? matches.length : 0;
+}

package/codeyam-cli/templates/skills/codeyam-memory/scripts/holistic-analysis/find-exports.mjs

@@ -0,0 +1,52 @@
+#!/usr/bin/env node
+// Indexes the project's public API surface by finding all exports.
+// Outputs structured JSON to /tmp/codeyam-memory/exports-scan.json
+
+import { mkdir, writeFile } from 'node:fs/promises';
+import { join } from 'node:path';
+import { ripgrepSearch } from '../lib/ripgrep-fallback.mjs';
+
+const OUTPUT_DIR = '/tmp/codeyam-memory';
+const OUTPUT_FILE = join(OUTPUT_DIR, 'exports-scan.json');
+await mkdir(OUTPUT_DIR, { recursive: true });
+
+const exportOutput = await ripgrepSearch(
+  '^export (function|const|class|default|async function|type|interface|enum)',
+  {
+    types: ['ts', 'js'],
+    globs: ['!node_modules', '!dist', '!build', '!.next', '!*.d.ts', '!*.map'],
+    lineNumbers: true,
+  },
+);
+
+if (!exportOutput.trim()) {
+  const empty = { files: {}, stats: { total_files: 0, total_exports: 0 } };
+  await writeFile(OUTPUT_FILE, JSON.stringify(empty, null, 2));
+  console.log(`Export scan complete: ${OUTPUT_FILE} (no exports found)`);
+  process.exit(0);
+}
+
+// Parse ripgrep output and group by file
+const files = {};
+for (const line of exportOutput.split('\n')) {
+  const match = line.match(/^([^:]+):(\d+):(.*)$/);
+  if (!match) continue;
+
+  const [, file, lineNum, text] = match;
+  if (!files[file]) files[file] = [];
+  files[file].push({ line: parseInt(lineNum, 10), text: text.trim() });
+}
+
+const totalFiles = Object.keys(files).length;
+const totalExports = Object.values(files).reduce((sum, arr) => sum + arr.length, 0);
+
+const output = {
+  files,
+  stats: { total_files: totalFiles, total_exports: totalExports },
+};
+
+await writeFile(OUTPUT_FILE, JSON.stringify(output, null, 2));
+
+console.log(`Export scan complete: ${OUTPUT_FILE}`);
+console.log(`  Files with exports: ${totalFiles}`);
+console.log(`  Total exports: ${totalExports}`);

package/codeyam-cli/templates/skills/codeyam-memory/scripts/lib/read-json-field.mjs

@@ -0,0 +1,61 @@
+#!/usr/bin/env node
+// Lightweight jq replacement for simple field lookups.
+// Usage: node read-json-field.mjs <file> '<expression>'
+// Supports: .field.subfield, .field | length
+
+import { readFile } from 'node:fs/promises';
+
+const [, , filePath, expression] = process.argv;
+
+if (!filePath || !expression) {
+  console.error('Usage: node read-json-field.mjs <file> <expression>');
+  process.exit(1);
+}
+
+try {
+  const raw = await readFile(filePath, 'utf-8');
+  const data = JSON.parse(raw);
+  const result = evaluate(data, expression);
+  console.log(typeof result === 'string' ? result : JSON.stringify(result));
+} catch (err) {
+  console.error(err.message);
+  process.exit(1);
+}
+
+function evaluate(data, expr) {
+  const trimmed = expr.trim();
+
+  // Handle pipe: ".field | length"
+  const pipeIdx = trimmed.indexOf('|');
+  if (pipeIdx !== -1) {
+    const left = trimmed.slice(0, pipeIdx).trim();
+    const right = trimmed.slice(pipeIdx + 1).trim();
+    const intermediate = resolvePath(data, left);
+
+    if (right === 'length') {
+      if (Array.isArray(intermediate)) return intermediate.length;
+      if (typeof intermediate === 'object' && intermediate !== null) return Object.keys(intermediate).length;
+      if (typeof intermediate === 'string') return intermediate.length;
+      throw new Error(`Cannot get length of ${typeof intermediate}`);
+    }
+    throw new Error(`Unsupported pipe function: ${right}`);
+  }
+
+  return resolvePath(data, trimmed);
+}
+
+function resolvePath(data, pathExpr) {
+  // Strip leading dot: ".foo.bar" -> "foo.bar"
+  const cleaned = pathExpr.startsWith('.') ? pathExpr.slice(1) : pathExpr;
+  if (cleaned === '') return data;
+
+  const keys = cleaned.split('.');
+  let current = data;
+  for (const key of keys) {
+    if (current == null || typeof current !== 'object') {
+      throw new Error(`Cannot access '${key}' on ${JSON.stringify(current)}`);
+    }
+    current = current[key];
+  }
+  return current;
+}