@assistkick/create 1.18.0 → 1.21.0

package/templates/assistkick-product-system/packages/shared/tools/agent_builder.ts

@@ -0,0 +1,341 @@
+#!/usr/bin/env node
+
+/**
+ * agent_builder — Create and edit AI agents stored in the database.
+ *
+ * Actions:
+ *   list                    — List all agents
+ *   get <id>                — Get an agent with full details
+ *   create                  — Create a new agent
+ *   update <id>             — Update agent fields
+ *   delete <id>             — Delete an agent
+ *   reset <id>              — Reset a default agent's grounding to original
+ *   list-skills             — List available skills from disk
+ *   list-models             — List supported Claude models
+ *   list-placeholders       — Show available grounding template placeholders
+ */
+
+import { program } from 'commander';
+import chalk from 'chalk';
+import { eq, isNull } from 'drizzle-orm';
+import { agents, workflows } from '../db/schema.js';
+import { getDb } from '../lib/db.js';
+import { randomUUID } from 'node:crypto';
+import { readdir, readFile } from 'node:fs/promises';
+import { join, dirname } from 'node:path';
+import { existsSync } from 'node:fs';
+import { fileURLToPath } from 'node:url';
+
+// ── Constants ──────────────────────────────────────────────────────────────────
+
+const SUPPORTED_MODELS = [
+  { id: 'claude-opus-4-6', label: 'Claude Opus 4.6', description: 'Most capable, best for complex reasoning' },
+  { id: 'claude-sonnet-4-6', label: 'Claude Sonnet 4.6', description: 'Balanced performance and speed' },
+  { id: 'claude-haiku-4-5-20251001', label: 'Claude Haiku 4.5', description: 'Fastest, best for simple tasks' },
+];
+
+const GROUNDING_PLACEHOLDERS = [
+  { placeholder: '{{featureId}}', description: 'The feature ID being worked on', context: 'All stages' },
+  { placeholder: '{{projectId}}', description: 'Current project ID', context: 'All stages' },
+  { placeholder: '{{mainToolsDir}}', description: 'Absolute path to tools directory', context: 'All stages' },
+  { placeholder: '{{mainSkillDir}}', description: 'Absolute path to shared data directory', context: 'All stages' },
+  { placeholder: '{{pidFlag}}', description: 'The --project-id flag string', context: 'All stages' },
+  { placeholder: '{{cycle}}', description: 'Current development cycle number', context: 'Developer' },
+  { placeholder: '{{previousReviewNotes}}', description: 'Review feedback from prior cycle', context: 'Developer' },
+  { placeholder: '{{debuggerFindings}}', description: 'Root cause analysis from debugger', context: 'Developer' },
+  { placeholder: '{{unaddressedNotes}}', description: 'QA rejection notes to investigate', context: 'Debugger' },
+];
+
+// ── Skills discovery ──────────────────────────────────────────────────────────
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+let SKILLS_DIR = join(__dirname, '..', '..', '..', '..', '.claude', 'skills');
+
+// Walk up to find the project root with .claude/skills
+function findSkillsDir(): string {
+  let dir = join(__dirname, '..');
+  while (dir !== dirname(dir)) {
+    if (existsSync(join(dir, 'pnpm-workspace.yaml'))) {
+      const candidate = join(dir, '..', '.claude', 'skills');
+      if (existsSync(candidate)) return candidate;
+    }
+    dir = dirname(dir);
+  }
+  return SKILLS_DIR;
+}
+
+async function listSkillsFromDisk(): Promise<Array<{ id: string; name: string; preview: string }>> {
+  const skillsDir = findSkillsDir();
+  if (!existsSync(skillsDir)) return [];
+
+  const entries = await readdir(skillsDir, { withFileTypes: true });
+  const skills: Array<{ id: string; name: string; preview: string }> = [];
+
+  for (const entry of entries) {
+    if (!entry.isDirectory()) continue;
+    const skillMdPath = join(skillsDir, entry.name, 'SKILL.md');
+    let name = entry.name;
+    let preview = '';
+
+    if (existsSync(skillMdPath)) {
+      try {
+        const content = await readFile(skillMdPath, 'utf-8');
+        const lines = content.split('\n');
+        for (const line of lines) {
+          if (line.trim().startsWith('# ')) {
+            name = line.trim().slice(2).trim();
+            break;
+          }
+        }
+        const headingEnd = content.indexOf('\n', content.indexOf('# '));
+        const body = content.slice(headingEnd >= 0 ? headingEnd + 1 : 0).trim();
+        preview = body.length > 200 ? body.slice(0, 200) + '…' : body;
+      } catch {
+        // Use folder name as fallback
+      }
+    }
+    skills.push({ id: entry.name, name, preview });
+  }
+  return skills;
+}
+
+// ── Helpers ───────────────────────────────────────────────────────────────────
+
+function formatSkillsList(skillsJson: string): string {
+  try {
+    const arr = JSON.parse(skillsJson);
+    return Array.isArray(arr) && arr.length > 0 ? arr.join(', ') : '(none)';
+  } catch {
+    return skillsJson || '(none)';
+  }
+}
+
+function printAgent(agent: any) {
+  const scope = agent.projectId ? chalk.gray(` (project: ${agent.projectId})`) : chalk.gray(' (global)');
+  const def = agent.isDefault ? chalk.yellow(' [DEFAULT]') : '';
+
+  console.log(chalk.cyan.bold(`\nAgent: ${agent.name}${def}${scope}\n`));
+  console.log(`  ID: ${agent.id}`);
+  console.log(`  Model: ${chalk.bold(agent.model)}`);
+  console.log(`  Skills: ${formatSkillsList(agent.skills)}`);
+  console.log(`  Has default grounding: ${agent.defaultGrounding ? 'yes' : 'no'}`);
+  console.log(`  Created: ${agent.createdAt}`);
+  console.log(`  Updated: ${agent.updatedAt}`);
+  console.log();
+  console.log(chalk.cyan('  Grounding:'));
+  const groundingLines = agent.grounding.split('\n');
+  for (const line of groundingLines) {
+    console.log(`    ${line}`);
+  }
+}
+
+// ── CLI ───────────────────────────────────────────────────────────────────────
+
+program
+  .argument('<action>', 'Action to perform')
+  .argument('[target]', 'Agent ID')
+  .option('--project-id <id>', 'Project ID (scope filter)')
+  .option('--scope <scope>', 'Scope filter: global or project', 'global')
+  .option('--name <name>', 'Agent name')
+  .option('--model <model>', 'Claude model ID')
+  .option('--skills <json>', 'Skills as JSON array (e.g. \'["assistkick-developer"]\')')
+  .option('--grounding <text>', 'Agent grounding/system prompt')
+  .option('--grounding-file <path>', 'Read grounding from a file instead of --grounding')
+  .parse();
+
+const [action, target] = program.args;
+const opts = program.opts();
+
+(async () => {
+  const db = getDb();
+
+  try {
+    switch (action) {
+
+      // ── List agents ─────────────────────────────────────────────────────────
+      case 'list': {
+        let rows;
+        if (opts.scope === 'project' && opts.projectId) {
+          rows = await db.select().from(agents).where(eq(agents.projectId, opts.projectId));
+        } else if (opts.projectId) {
+          // Show both global and project-scoped
+          const allRows = await db.select().from(agents);
+          rows = allRows.filter((r: any) => r.projectId === null || r.projectId === opts.projectId);
+        } else {
+          rows = await db.select().from(agents).where(isNull(agents.projectId));
+        }
+
+        console.log(chalk.cyan.bold('Agents:\n'));
+        for (const row of rows) {
+          const def = row.isDefault ? chalk.yellow(' [DEFAULT]') : '';
+          const scope = row.projectId ? chalk.gray(` (project: ${row.projectId})`) : chalk.gray(' (global)');
+          console.log(`  ${chalk.bold(row.name)}${def}${scope}`);
+          console.log(`    ID: ${row.id}  Model: ${row.model}  Skills: ${formatSkillsList(row.skills)}`);
+        }
+        console.log('\n' + JSON.stringify({
+          agents: rows.map((r: any) => ({
+            id: r.id, name: r.name, model: r.model, skills: r.skills,
+            projectId: r.projectId, isDefault: r.isDefault,
+          })),
+        }));
+        break;
+      }
+
+      // ── Get agent ───────────────────────────────────────────────────────────
+      case 'get': {
+        if (!target) throw new Error('Usage: agent_builder get <agent-id>');
+        const [row] = await db.select().from(agents).where(eq(agents.id, target));
+        if (!row) throw new Error(`Agent not found: ${target}`);
+
+        printAgent(row);
+        console.log('\n' + JSON.stringify({ agent: row }));
+        break;
+      }
+
+      // ── Create agent ────────────────────────────────────────────────────────
+      case 'create': {
+        if (!opts.name) throw new Error('--name is required');
+
+        let grounding = opts.grounding || '';
+        if (opts.groundingFile) {
+          if (!existsSync(opts.groundingFile)) throw new Error(`Grounding file not found: ${opts.groundingFile}`);
+          grounding = await readFile(opts.groundingFile, 'utf-8');
+        }
+        if (!grounding) throw new Error('--grounding or --grounding-file is required');
+
+        const now = new Date().toISOString();
+        const id = randomUUID();
+
+        const record = {
+          id,
+          name: opts.name.trim(),
+          model: opts.model || 'claude-opus-4-6',
+          skills: opts.skills || '[]',
+          grounding,
+          defaultGrounding: null,
+          projectId: opts.projectId || null,
+          isDefault: 0,
+          createdAt: now,
+          updatedAt: now,
+        };
+
+        await db.insert(agents).values(record);
+        console.log(chalk.green(`Created agent: ${opts.name} (${id})`));
+        console.log(JSON.stringify({ id, name: opts.name, model: record.model }));
+        break;
+      }
+
+      // ── Update agent ────────────────────────────────────────────────────────
+      case 'update': {
+        if (!target) throw new Error('Usage: agent_builder update <agent-id> [options]');
+        const [existing] = await db.select().from(agents).where(eq(agents.id, target));
+        if (!existing) throw new Error(`Agent not found: ${target}`);
+
+        const now = new Date().toISOString();
+        const updates: Record<string, any> = { updatedAt: now };
+
+        if (opts.name) updates.name = opts.name.trim();
+        if (opts.model) updates.model = opts.model;
+        if (opts.skills) updates.skills = opts.skills;
+
+        if (opts.groundingFile) {
+          if (!existsSync(opts.groundingFile)) throw new Error(`Grounding file not found: ${opts.groundingFile}`);
+          updates.grounding = await readFile(opts.groundingFile, 'utf-8');
+        } else if (opts.grounding) {
+          updates.grounding = opts.grounding;
+        }
+
+        await db.update(agents).set(updates).where(eq(agents.id, target));
+        console.log(chalk.green(`Updated agent: ${existing.name} (${target})`));
+        console.log(JSON.stringify({ id: target, ...updates }));
+        break;
+      }
+
+      // ── Delete agent ────────────────────────────────────────────────────────
+      case 'delete': {
+        if (!target) throw new Error('Usage: agent_builder delete <agent-id>');
+        const [existing] = await db.select().from(agents).where(eq(agents.id, target));
+        if (!existing) throw new Error(`Agent not found: ${target}`);
+
+        if (existing.isDefault) throw new Error('Cannot delete a default agent');
+
+        // Check if agent is referenced in any workflow
+        const allWorkflows = await db.select().from(workflows);
+        const referencing = allWorkflows.find((w: any) => w.graphData.includes(target));
+        if (referencing) {
+          throw new Error(`Cannot delete agent — referenced in workflow "${referencing.name}" (${referencing.id})`);
+        }
+
+        await db.delete(agents).where(eq(agents.id, target));
+        console.log(chalk.green(`Deleted agent: ${existing.name} (${target})`));
+        console.log(JSON.stringify({ deleted: target }));
+        break;
+      }
+
+      // ── Reset default agent ─────────────────────────────────────────────────
+      case 'reset': {
+        if (!target) throw new Error('Usage: agent_builder reset <agent-id>');
+        const [existing] = await db.select().from(agents).where(eq(agents.id, target));
+        if (!existing) throw new Error(`Agent not found: ${target}`);
+        if (!existing.isDefault) throw new Error('Only default agents can be reset');
+        if (!existing.defaultGrounding) throw new Error('No default grounding available for this agent');
+
+        const now = new Date().toISOString();
+        await db.update(agents)
+          .set({ grounding: existing.defaultGrounding, updatedAt: now })
+          .where(eq(agents.id, target));
+
+        console.log(chalk.green(`Reset agent grounding to default: ${existing.name} (${target})`));
+        console.log(JSON.stringify({ id: target, reset: true }));
+        break;
+      }
+
+      // ── List skills ─────────────────────────────────────────────────────────
+      case 'list-skills': {
+        const skills = await listSkillsFromDisk();
+
+        console.log(chalk.cyan.bold('Available Skills:\n'));
+        for (const skill of skills) {
+          console.log(`  ${chalk.bold(skill.id)}`);
+          if (skill.name !== skill.id) console.log(`    Name: ${skill.name}`);
+          if (skill.preview) {
+            const short = skill.preview.split('\n')[0].slice(0, 100);
+            console.log(`    ${chalk.gray(short)}`);
+          }
+        }
+        console.log('\n' + JSON.stringify({ skills }));
+        break;
+      }
+
+      // ── List models ─────────────────────────────────────────────────────────
+      case 'list-models': {
+        console.log(chalk.cyan.bold('Supported Models:\n'));
+        for (const m of SUPPORTED_MODELS) {
+          console.log(`  ${chalk.bold(m.id)}`);
+          console.log(`    ${m.label} — ${m.description}`);
+        }
+        console.log('\n' + JSON.stringify({ models: SUPPORTED_MODELS }));
+        break;
+      }
+
+      // ── List placeholders ───────────────────────────────────────────────────
+      case 'list-placeholders': {
+        console.log(chalk.cyan.bold('Grounding Template Placeholders:\n'));
+        console.log('  Use these in agent grounding text. They are resolved at execution time.\n');
+        for (const p of GROUNDING_PLACEHOLDERS) {
+          console.log(`  ${chalk.bold(p.placeholder)}`);
+          console.log(`    ${p.description}`);
+          console.log(`    Context: ${chalk.gray(p.context)}`);
+        }
+        console.log('\n' + JSON.stringify({ placeholders: GROUNDING_PLACEHOLDERS }));
+        break;
+      }
+
+      default:
+        throw new Error(`Unknown action "${action}". Valid actions: list, get, create, update, delete, reset, list-skills, list-models, list-placeholders`);
+    }
+  } catch (err) {
+    console.error(chalk.red(`Error: ${(err as Error).message}`));
+    process.exit(1);
+  }
+})();

package/templates/assistkick-product-system/packages/shared/tools/app_use_record.ts

@@ -0,0 +1,268 @@
+#!/usr/bin/env node
+
+/**
+ * app_use_record — Record flow sessions by accumulating steps into a YAML flow file.
+ *
+ * The agent calls `start` to begin a session, `add-step` / `add-assert` to log actions,
+ * and `stop` to write the final YAML. Steps and comments are accumulated in a temp file.
+ *
+ * Usage:
+ *   pnpm tsx packages/shared/tools/app_use_record.ts start --output flows/login.yaml --url http://localhost:5173 [--name "Login Flow"]
+ *   pnpm tsx packages/shared/tools/app_use_record.ts add-step --type click --selector "@e1" [--value "..."] [--label "Click submit"]
+ *   pnpm tsx packages/shared/tools/app_use_record.ts add-assert --type assertVisible --value "Welcome" [--label "Check welcome msg"]
+ *   pnpm tsx packages/shared/tools/app_use_record.ts add-comment "Snapshot taken - found 5 interactive elements"
+ *   pnpm tsx packages/shared/tools/app_use_record.ts status
+ *   pnpm tsx packages/shared/tools/app_use_record.ts stop
+ *   pnpm tsx packages/shared/tools/app_use_record.ts discard
+ */
+
+import { program } from 'commander';
+import chalk from 'chalk';
+import { existsSync, readFileSync, writeFileSync, unlinkSync, mkdirSync } from 'node:fs';
+import { dirname, join } from 'node:path';
+import { tmpdir } from 'node:os';
+import {
+  type FlowConfig, type FlowStep, type FlowFile,
+  writeFlowFile, serializeFlowYaml,
+} from '../lib/app_use_flow.js';
+
+// ── Session state persistence ─────────────────────────────────────────────────
+
+const SESSION_FILE = join(tmpdir(), 'app-use-recording-session.json');
+
+interface RecordingSession {
+  outputPath: string;
+  config: FlowConfig;
+  steps: FlowStep[];
+  comments: string[];
+  startedAt: string;
+}
+
+function loadSession(): RecordingSession | null {
+  if (!existsSync(SESSION_FILE)) return null;
+  try {
+    return JSON.parse(readFileSync(SESSION_FILE, 'utf-8'));
+  } catch {
+    return null;
+  }
+}
+
+function saveSession(session: RecordingSession): void {
+  writeFileSync(SESSION_FILE, JSON.stringify(session, null, 2), 'utf-8');
+}
+
+function clearSession(): void {
+  if (existsSync(SESSION_FILE)) unlinkSync(SESSION_FILE);
+}
+
+function requireSession(): RecordingSession {
+  const session = loadSession();
+  if (!session) {
+    throw new Error('No active recording session. Start one with: app_use_record start --output <path> --url <url>');
+  }
+  return session;
+}
+
+// ── CLI ───────────────────────────────────────────────────────────────────────
+
+program
+  .argument('<action>', 'Action: start, add-step, add-assert, add-comment, status, stop, discard')
+  .argument('[text]', 'Comment text (for add-comment)')
+  .option('--output <path>', 'Output YAML file path (for start)')
+  .option('--url <url>', 'App URL (for start, sets appId)')
+  .option('--name <name>', 'Flow name (for start)')
+  .option('--platform <platform>', 'Platform: web, ios, android (for start)', 'web')
+  .option('--auto-session <bool>', 'Auto-manage browser session', 'true')
+  .option('--type <type>', 'Step type (for add-step / add-assert)')
+  .option('--selector <sel>', 'Element selector')
+  .option('--value <val>', 'Step value')
+  .option('--params <json>', 'Additional params as JSON')
+  .option('--label <label>', 'Human-readable label for the step')
+  .option('--optional', 'Mark step as optional (failure won\'t abort)')
+  .parse();
+
+const [action, text] = program.args;
+const opts = program.opts();
+
+(async () => {
+  try {
+    switch (action) {
+
+      // ── Start recording ───────────────────────────────────────────────────
+      case 'start': {
+        if (!opts.output) throw new Error('--output is required');
+
+        const existing = loadSession();
+        if (existing) {
+          throw new Error(`Recording already in progress (output: ${existing.outputPath}). Use "stop" or "discard" first.`);
+        }
+
+        const config: FlowConfig = {
+          platform: opts.platform || 'web',
+          autoSession: opts.autoSession !== 'false',
+        };
+        if (opts.url) config.appId = opts.url;
+        if (opts.name) config.name = opts.name;
+
+        const session: RecordingSession = {
+          outputPath: opts.output,
+          config,
+          steps: [],
+          comments: [],
+          startedAt: new Date().toISOString(),
+        };
+
+        saveSession(session);
+        console.log(chalk.green(`Recording started`));
+        console.log(`  Output: ${opts.output}`);
+        console.log(`  Platform: ${config.platform}`);
+        if (opts.url) console.log(`  URL: ${opts.url}`);
+        console.log(JSON.stringify({ status: 'recording', output: opts.output }));
+        break;
+      }
+
+      // ── Add a step ────────────────────────────────────────────────────────
+      case 'add-step': {
+        if (!opts.type) throw new Error('--type is required for add-step');
+        const session = requireSession();
+
+        const step: FlowStep = { type: opts.type };
+        if (opts.selector) step.selector = opts.selector;
+        if (opts.value) step.value = opts.value;
+        if (opts.label) step.label = opts.label;
+        if (opts.optional) step.optional = true;
+        if (opts.params) step.params = JSON.parse(opts.params);
+
+        session.steps.push(step);
+        saveSession(session);
+
+        const idx = session.steps.length;
+        console.log(chalk.green(`Step ${idx} added: ${step.type}${step.selector ? ' ' + step.selector : ''}${step.value ? ' ' + step.value : ''}`));
+        console.log(JSON.stringify({ stepIndex: idx, step }));
+        break;
+      }
+
+      // ── Add an assertion ──────────────────────────────────────────────────
+      case 'add-assert': {
+        if (!opts.type) throw new Error('--type is required for add-assert');
+        const session = requireSession();
+
+        const step: FlowStep = { type: opts.type };
+        if (opts.selector) step.selector = opts.selector;
+        if (opts.value) step.value = opts.value;
+        if (opts.label) step.label = opts.label;
+        if (opts.optional) step.optional = true;
+        if (opts.params) step.params = JSON.parse(opts.params);
+
+        session.steps.push(step);
+        saveSession(session);
+
+        const idx = session.steps.length;
+        console.log(chalk.green(`Assertion ${idx} added: ${step.type} "${step.value || ''}"`));
+        console.log(JSON.stringify({ stepIndex: idx, step }));
+        break;
+      }
+
+      // ── Add a comment ─────────────────────────────────────────────────────
+      case 'add-comment': {
+        if (!text) throw new Error('Comment text is required');
+        const session = requireSession();
+
+        // Comments are associated with the step count at the time of recording
+        const comment = `[after step ${session.steps.length}] ${text}`;
+        session.comments.push(comment);
+        saveSession(session);
+
+        console.log(chalk.gray(`Comment added: ${text}`));
+        console.log(JSON.stringify({ comment: text, afterStep: session.steps.length }));
+        break;
+      }
+
+      // ── Show status ───────────────────────────────────────────────────────
+      case 'status': {
+        const session = loadSession();
+        if (!session) {
+          console.log(chalk.yellow('No active recording session'));
+          console.log(JSON.stringify({ status: 'idle' }));
+          break;
+        }
+
+        console.log(chalk.cyan.bold('Recording Session'));
+        console.log(`  Output: ${session.outputPath}`);
+        console.log(`  Platform: ${session.config.platform}`);
+        console.log(`  Steps: ${session.steps.length}`);
+        console.log(`  Comments: ${session.comments.length}`);
+        console.log(`  Started: ${session.startedAt}`);
+        console.log();
+
+        if (session.steps.length > 0) {
+          console.log(chalk.cyan('  Steps:'));
+          for (let i = 0; i < session.steps.length; i++) {
+            const s = session.steps[i];
+            const label = s.label || `${s.type}${s.selector ? ' ' + s.selector : ''}${s.value ? ' ' + s.value : ''}`;
+            console.log(`    ${i + 1}. ${label}`);
+          }
+        }
+
+        console.log('\n' + JSON.stringify({
+          status: 'recording', output: session.outputPath,
+          steps: session.steps.length, comments: session.comments.length,
+        }));
+        break;
+      }
+
+      // ── Stop and save ─────────────────────────────────────────────────────
+      case 'stop': {
+        const session = requireSession();
+
+        const flow: FlowFile = {
+          config: session.config,
+          steps: session.steps,
+        };
+
+        // Ensure output directory exists
+        const dir = dirname(session.outputPath);
+        if (!existsSync(dir)) mkdirSync(dir, { recursive: true });
+
+        writeFlowFile(session.outputPath, flow, session.comments);
+        clearSession();
+
+        console.log(chalk.green(`Flow saved: ${session.outputPath}`));
+        console.log(`  Steps: ${session.steps.length}`);
+        console.log(`  Comments: ${session.comments.length}`);
+
+        // Preview the file
+        console.log(chalk.gray('\n--- Preview ---'));
+        console.log(chalk.gray(serializeFlowYaml(flow, session.comments)));
+        console.log(chalk.gray('--- End preview ---'));
+
+        console.log('\n' + JSON.stringify({
+          status: 'saved', output: session.outputPath,
+          steps: session.steps.length,
+        }));
+        break;
+      }
+
+      // ── Discard ───────────────────────────────────────────────────────────
+      case 'discard': {
+        const session = loadSession();
+        if (!session) {
+          console.log(chalk.yellow('No active recording session to discard'));
+          break;
+        }
+
+        const stepCount = session.steps.length;
+        clearSession();
+        console.log(chalk.yellow(`Discarded recording (${stepCount} steps)`));
+        console.log(JSON.stringify({ status: 'discarded', stepsLost: stepCount }));
+        break;
+      }
+
+      default:
+        throw new Error(`Unknown action "${action}". Valid: start, add-step, add-assert, add-comment, status, stop, discard`);
+    }
+  } catch (err) {
+    console.error(chalk.red(`Error: ${(err as Error).message}`));
+    process.exit(1);
+  }
+})();