@assistkick/create 1.0.0

package/templates/product-system/packages/shared/tools/migrate_to_turso.ts

@@ -0,0 +1,385 @@
+#!/usr/bin/env node
+
+/**
+ * migrate_to_turso — One-time migration tool that reads all existing local .md files
+ * (nodes/, sessions/) and graph.json/kanban.json, then inserts everything into the
+ * Turso database.
+ *
+ * Usage:
+ *   node tools/migrate_to_turso.js
+ *   node tools/migrate_to_turso.js --dry-run    # Report what would be migrated without writing
+ */
+
+import { program } from 'commander';
+import chalk from 'chalk';
+import matter from 'gray-matter';
+import { readFileSync, readdirSync, existsSync } from 'node:fs';
+import { join } from 'node:path';
+import { getDb, getProjectRoot, closeDb } from '../lib/db.js';
+import { nodes, edges, kanban, sessions, reviewMeta } from '../db/schema.js';
+import { scoreNode } from '../lib/completeness.js';
+
+program
+  .option('--dry-run', 'Report what would be migrated without writing to database')
+  .parse();
+
+const opts = program.opts();
+
+/**
+ * Parse a markdown body into sections map { sectionName: content }.
+ */
+const parseSections = (body) => {
+  const sectionMap = {};
+  const lines = body.split('\n');
+  let currentSection = null;
+  let currentLines = [];
+
+  for (const line of lines) {
+    const match = line.match(/^## (.+)$/);
+    if (match) {
+      if (currentSection !== null) {
+        sectionMap[currentSection] = currentLines.join('\n').trim();
+      }
+      currentSection = match[1].trim();
+      currentLines = [];
+    } else if (currentSection !== null) {
+      currentLines.push(line);
+    }
+  }
+  if (currentSection !== null) {
+    sectionMap[currentSection] = currentLines.join('\n').trim();
+  }
+
+  return sectionMap;
+};
+
+/**
+ * Extract text under a ### subsection header from raw markdown content.
+ * Session files use h3 subsections (### Summary, ### Notes, etc.) within h2 sections.
+ */
+const extractSubsection = (content, name) => {
+  const regex = new RegExp(`^### ${name}\\s*$`, 'm');
+  const match = content.match(regex);
+  if (!match) return '';
+
+  const start = match.index + match[0].length;
+  const rest = content.slice(start);
+  // Find the next heading (## or ###)
+  const nextHeading = rest.search(/^#{2,3} /m);
+  const block = nextHeading === -1 ? rest : rest.slice(0, nextHeading);
+  return block.trim();
+};
+
+/**
+ * Count open questions (unchecked checkboxes) in a sections map.
+ */
+const countOpenQuestions = (sectionMap) => {
+  const oq = sectionMap['Open Questions'] || '';
+  return oq.split('\n').filter(l => l.trim().startsWith('- [ ]')).length;
+};
+
+/**
+ * Migrate all node .md files from nodes/ directory.
+ */
+const migrateNodes = async (db, projectRoot, dryRun) => {
+  const nodesDir = join(projectRoot, 'nodes');
+  if (!existsSync(nodesDir)) {
+    console.log(chalk.yellow('  No nodes/ directory found. Skipping nodes migration.'));
+    return { migrated: 0, errors: [] };
+  }
+
+  const files = readdirSync(nodesDir).filter(f => f.endsWith('.md')).sort();
+  const errors = [];
+  let migrated = 0;
+
+  for (const file of files) {
+    const filepath = join(nodesDir, file);
+    try {
+      const raw = readFileSync(filepath, 'utf8');
+      const { data: fm, content } = matter(raw);
+
+      const sectionMap = parseSections(content);
+      const completeness = scoreNode(fm.type, fm, sectionMap);
+      const openQuestionsCount = countOpenQuestions(sectionMap);
+
+      const body = content.trim();
+
+      if (!dryRun) {
+        await db.insert(nodes).values({
+          id: fm.id,
+          type: fm.type,
+          name: fm.name,
+          status: fm.status || 'draft',
+          priority: fm.priority || 'medium',
+          completeness,
+          openQuestionsCount,
+          kind: fm.kind || null,
+          createdAt: fm.created_at || new Date().toISOString(),
+          updatedAt: fm.updated_at || new Date().toISOString(),
+          body,
+        }).onConflictDoUpdate({
+          target: nodes.id,
+          set: {
+            type: fm.type,
+            name: fm.name,
+            status: fm.status || 'draft',
+            priority: fm.priority || 'medium',
+            completeness,
+            openQuestionsCount,
+            kind: fm.kind || null,
+            updatedAt: fm.updated_at || new Date().toISOString(),
+            body,
+          },
+        });
+      }
+
+      migrated++;
+    } catch (err) {
+      errors.push({ file, error: err.message });
+    }
+  }
+
+  return { migrated, errors };
+};
+
+/**
+ * Migrate edges from graph.json.
+ */
+const migrateEdges = async (db, projectRoot, dryRun) => {
+  const graphPath = join(projectRoot, 'graph.json');
+  if (!existsSync(graphPath)) {
+    console.log(chalk.yellow('  No graph.json found. Skipping edges migration.'));
+    return { migrated: 0, errors: [] };
+  }
+
+  const graph = JSON.parse(readFileSync(graphPath, 'utf8'));
+  const edgeList = graph.edges || [];
+  const errors = [];
+  let migrated = 0;
+
+  for (const edge of edgeList) {
+    try {
+      if (!dryRun) {
+        await db.insert(edges).values({
+          fromId: edge.from,
+          relation: edge.relation,
+          toId: edge.to,
+        }).onConflictDoNothing();
+      }
+      migrated++;
+    } catch (err) {
+      errors.push({ edge: `${edge.from} -${edge.relation}-> ${edge.to}`, error: err.message });
+    }
+  }
+
+  return { migrated, errors };
+};
+
+/**
+ * Migrate kanban state from kanban.json.
+ */
+const migrateKanban = async (db, projectRoot, dryRun) => {
+  const kanbanPath = join(projectRoot, 'kanban.json');
+  if (!existsSync(kanbanPath)) {
+    console.log(chalk.yellow('  No kanban.json found. Skipping kanban migration.'));
+    return { migrated: 0, errors: [] };
+  }
+
+  const kanbanData = JSON.parse(readFileSync(kanbanPath, 'utf8'));
+  const errors = [];
+  let migrated = 0;
+  let position = 0;
+
+  for (const [featureId, entry] of Object.entries(kanbanData)) {
+    try {
+      if (!dryRun) {
+        await db.insert(kanban).values({
+          nodeId: featureId,
+          columnName: entry.column,
+          position: position++,
+        }).onConflictDoUpdate({
+          target: kanban.nodeId,
+          set: {
+            columnName: entry.column,
+            position: position - 1,
+          },
+        });
+
+        // Store extra metadata (rejection_count, notes, moved_at) in review_meta
+        const metaKey = `kanban:${featureId}`;
+        const metaValue = JSON.stringify({
+          rejection_count: entry.rejection_count || 0,
+          notes: entry.notes || [],
+          ...(entry.dev_blocked ? { dev_blocked: true } : {}),
+          ...(entry.moved_at ? { moved_at: entry.moved_at } : {}),
+        });
+
+        await db.insert(reviewMeta).values({
+          key: metaKey,
+          value: metaValue,
+        }).onConflictDoUpdate({
+          target: reviewMeta.key,
+          set: { value: metaValue },
+        });
+      }
+
+      migrated++;
+    } catch (err) {
+      errors.push({ featureId, error: err.message });
+    }
+  }
+
+  return { migrated, errors };
+};
+
+/**
+ * Migrate session .md files from sessions/ directory.
+ */
+const migrateSessions = async (db, projectRoot, dryRun) => {
+  const sessionsDir = join(projectRoot, 'sessions');
+  if (!existsSync(sessionsDir)) {
+    console.log(chalk.yellow('  No sessions/ directory found. Skipping sessions migration.'));
+    return { migrated: 0, errors: [] };
+  }
+
+  const files = readdirSync(sessionsDir).filter(f => f.endsWith('.md')).sort();
+  const errors = [];
+  let migrated = 0;
+
+  for (const file of files) {
+    const filepath = join(sessionsDir, file);
+    try {
+      const raw = readFileSync(filepath, 'utf8');
+      const { data: fm, content } = matter(raw);
+
+      const sessionNumber = fm.session;
+      if (sessionNumber == null) {
+        errors.push({ file, error: 'Missing session number in frontmatter' });
+        continue;
+      }
+
+      const nodesTouched = Array.isArray(fm.nodes_touched)
+        ? fm.nodes_touched.join(',')
+        : (fm.nodes_touched || '');
+
+      // Extract summary — sessions use ### Summary (h3 subsections)
+      const summary = extractSubsection(content, 'Summary');
+
+      if (!dryRun) {
+        await db.insert(sessions).values({
+          sessionNumber,
+          startedAt: fm.started_at || new Date().toISOString(),
+          endedAt: fm.ended_at || null,
+          summary,
+          nodesTouched,
+          questionsResolved: fm.questions_resolved || 0,
+          body: content.trim(),
+        }).onConflictDoUpdate({
+          target: sessions.sessionNumber,
+          set: {
+            startedAt: fm.started_at || new Date().toISOString(),
+            endedAt: fm.ended_at || null,
+            summary,
+            nodesTouched,
+            questionsResolved: fm.questions_resolved || 0,
+            body: content.trim(),
+          },
+        });
+      }
+
+      migrated++;
+    } catch (err) {
+      errors.push({ file, error: err.message });
+    }
+  }
+
+  return { migrated, errors };
+};
+
+/**
+ * Main migration entry point.
+ */
+const main = async () => {
+  const projectRoot = getProjectRoot();
+  const dryRun = opts.dryRun || false;
+
+  if (dryRun) {
+    console.log(chalk.cyan('=== DRY RUN — no database writes will occur ===\n'));
+  }
+
+  console.log(chalk.bold('Migrating local files to Turso database...\n'));
+
+  const db = getDb();
+
+  // Step 1: Migrate nodes
+  console.log(chalk.blue('1. Migrating nodes...'));
+  const nodesResult = await migrateNodes(db, projectRoot, dryRun);
+  console.log(`   ${chalk.green(nodesResult.migrated)} nodes migrated`);
+  if (nodesResult.errors.length > 0) {
+    for (const e of nodesResult.errors) {
+      console.log(`   ${chalk.red('ERROR')} ${e.file}: ${e.error}`);
+    }
+  }
+
+  // Step 2: Migrate edges
+  console.log(chalk.blue('\n2. Migrating edges...'));
+  const edgesResult = await migrateEdges(db, projectRoot, dryRun);
+  console.log(`   ${chalk.green(edgesResult.migrated)} edges migrated`);
+  if (edgesResult.errors.length > 0) {
+    for (const e of edgesResult.errors) {
+      console.log(`   ${chalk.red('ERROR')} ${e.edge}: ${e.error}`);
+    }
+  }
+
+  // Step 3: Migrate kanban
+  console.log(chalk.blue('\n3. Migrating kanban state...'));
+  const kanbanResult = await migrateKanban(db, projectRoot, dryRun);
+  console.log(`   ${chalk.green(kanbanResult.migrated)} kanban entries migrated`);
+  if (kanbanResult.errors.length > 0) {
+    for (const e of kanbanResult.errors) {
+      console.log(`   ${chalk.red('ERROR')} ${e.featureId}: ${e.error}`);
+    }
+  }
+
+  // Step 4: Migrate sessions
+  console.log(chalk.blue('\n4. Migrating sessions...'));
+  const sessionsResult = await migrateSessions(db, projectRoot, dryRun);
+  console.log(`   ${chalk.green(sessionsResult.migrated)} sessions migrated`);
+  if (sessionsResult.errors.length > 0) {
+    for (const e of sessionsResult.errors) {
+      console.log(`   ${chalk.red('ERROR')} ${e.file}: ${e.error}`);
+    }
+  }
+
+  // Summary
+  const totalErrors = [
+    ...nodesResult.errors,
+    ...edgesResult.errors,
+    ...kanbanResult.errors,
+    ...sessionsResult.errors,
+  ];
+
+  console.log(chalk.bold('\n=== Migration Summary ==='));
+  console.log(`  Nodes:    ${nodesResult.migrated}`);
+  console.log(`  Edges:    ${edgesResult.migrated}`);
+  console.log(`  Kanban:   ${kanbanResult.migrated}`);
+  console.log(`  Sessions: ${sessionsResult.migrated}`);
+
+  if (totalErrors.length > 0) {
+    console.log(chalk.red(`\n  Errors: ${totalErrors.length}`));
+  } else {
+    console.log(chalk.green('\n  No errors.'));
+  }
+
+  if (dryRun) {
+    console.log(chalk.cyan('\n=== DRY RUN complete — no changes were made ==='));
+  }
+
+  closeDb();
+};
+
+main().catch((err) => {
+  console.error(chalk.red(`Migration failed: ${err.message}`));
+  closeDb();
+  process.exit(1);
+});

package/templates/product-system/packages/shared/tools/move_card.ts

@@ -0,0 +1,143 @@
+#!/usr/bin/env node
+
+/**
+ * move_card — Moves a feature card to a new column on the kanban board.
+ * Validates that the transition is allowed.
+ *
+ * Usage:
+ *   node tools/move_card.js feat_010 in_progress                    # todo → in_progress
+ *   node tools/move_card.js feat_010 in_review                      # in_progress → in_review
+ *   node tools/move_card.js feat_010 qa                             # in_review → qa (approve)
+ *   node tools/move_card.js feat_010 todo --note "Missing tests"    # in_review → todo (reject)
+ *
+ * Allowed transitions (AI via CLI):
+ *   todo → in_progress       (developer picks up feature)
+ *   in_progress → in_review  (developer submits for review)
+ *   in_review → qa           (reviewer approves)
+ *   in_review → todo         (reviewer rejects — increments rejection_count)
+ *
+ * User-only transitions:
+ *   qa → done
+ *   qa → todo  (user QA rejection — increments rejection_count)
+ */
+
+import { program } from 'commander';
+import chalk from 'chalk';
+import { getKanbanEntry, saveKanbanEntry, kanbanExists } from '../lib/kanban.js';
+
+const VALID_COLUMNS = ['todo', 'in_progress', 'in_review', 'qa', 'done'];
+
+// AI-allowed transitions (via CLI)
+const ALLOWED_TRANSITIONS = {
+  'todo': ['in_progress'],
+  'in_progress': ['in_review'],
+  'in_review': ['qa', 'todo'],
+  'qa': ['todo'],
+  'done': [],
+};
+
+program
+  .argument('<feature_id>', 'Feature ID (e.g., feat_010)')
+  .argument('<target_column>', `Target column (${VALID_COLUMNS.join(', ')})`)
+  .requiredOption('--project-id <id>', 'Project ID')
+  .option('--note <text>', 'Add a note (required for rejections)')
+  .option('--unblock', 'Remove dev_blocked flag from the feature')
+  .parse();
+
+const [featureId, targetColumn] = program.args;
+
+(async () => {
+  try {
+    const opts = program.opts();
+    if (!(await kanbanExists(opts.projectId))) {
+      throw new Error('No kanban entries found. No features are being tracked yet.');
+    }
+
+    if (!VALID_COLUMNS.includes(targetColumn)) {
+      throw new Error(`Invalid column "${targetColumn}". Valid columns: ${VALID_COLUMNS.join(', ')}`);
+    }
+
+    const entry = await getKanbanEntry(featureId);
+    if (!entry) {
+      throw new Error(`Feature "${featureId}" not found on the kanban board.`);
+    }
+
+    const currentColumn = entry.column;
+
+    // Handle --unblock flag
+    if (opts.unblock) {
+      if (!entry.dev_blocked) {
+        console.log(chalk.yellow(`Feature "${featureId}" is not blocked.`));
+      } else {
+        delete entry.dev_blocked;
+        await saveKanbanEntry(featureId, entry);
+        console.log(chalk.green(`✓ Unblocked ${featureId}`));
+      }
+      process.exit(0);
+    }
+
+    // Check dev_blocked
+    if (entry.dev_blocked && targetColumn === 'in_progress') {
+      throw new Error(
+        `Feature "${featureId}" is dev_blocked (failed 3 automated dev cycles). ` +
+        `Use --unblock flag to remove the block first.`
+      );
+    }
+
+    if (currentColumn === targetColumn) {
+      throw new Error(`Feature "${featureId}" is already in "${targetColumn}".`);
+    }
+
+    const allowed = ALLOWED_TRANSITIONS[currentColumn] || [];
+    if (!allowed.includes(targetColumn)) {
+      const allowedStr = allowed.length > 0 ? allowed.join(', ') : 'none (terminal state)';
+      throw new Error(
+        `Invalid transition: "${currentColumn}" → "${targetColumn}" is not allowed.\n` +
+        `  Allowed transitions from "${currentColumn}": ${allowedStr}`
+      );
+    }
+
+    // Handle rejections (in_review → todo or qa → todo)
+    const isRejection = targetColumn === 'todo' && (currentColumn === 'in_review' || currentColumn === 'qa');
+    if (isRejection) {
+      if (!opts.note) {
+        throw new Error('Rejections require a --note explaining what needs to be fixed.');
+      }
+      entry.rejection_count = (entry.rejection_count || 0) + 1;
+      if (!entry.notes) entry.notes = [];
+      entry.notes.push({
+        from: currentColumn,
+        text: opts.note,
+        timestamp: new Date().toISOString(),
+      });
+      const count = entry.rejection_count;
+      const source = currentColumn === 'in_review' ? 'Review' : 'QA';
+      console.log(chalk.yellow(`⚠ ${source} rejection #${count} for ${featureId}`));
+      console.log(chalk.gray(`  Note: ${opts.note}`));
+      if (count >= 3) {
+        console.log(chalk.red.bold(`⚠ WARNING: ${featureId} has been rejected ${count} times — needs attention`));
+      }
+    }
+
+    // Perform the transition
+    const previousColumn = entry.column;
+    entry.column = targetColumn;
+    entry.moved_at = new Date().toISOString();
+
+    await saveKanbanEntry(featureId, entry);
+
+    const arrow = `${previousColumn} → ${targetColumn}`;
+    console.log(chalk.green(`✓ Moved ${featureId}: ${arrow}`));
+
+    console.log('\n' + JSON.stringify({
+      feature_id: featureId,
+      previous_column: previousColumn,
+      new_column: targetColumn,
+      rejection_count: entry.rejection_count || 0,
+    }));
+
+  } catch (err) {
+    console.error(chalk.red(`Error: ${err.message}`));
+    process.exit(1);
+  }
+})();

package/templates/product-system/packages/shared/tools/rebuild_index.ts

@@ -0,0 +1,77 @@
+#!/usr/bin/env node
+
+/**
+ * rebuild_index — Regenerates the nodes table metadata by re-deriving completeness
+ * and status from each node's body content. With Turso as source of truth,
+ * this recalculates derived fields rather than rebuilding from .md files.
+ */
+
+import { program } from 'commander';
+import chalk from 'chalk';
+import { readGraph, writeGraph } from '../lib/graph.js';
+import { readNode, deriveMetadata } from '../lib/markdown.js';
+import { getDb } from '../lib/db.js';
+import { nodes } from '../db/schema.js';
+
+program
+  .requiredOption('--project-id <id>', 'Project ID')
+  .option('--dry-run', 'Show what would change without writing')
+  .parse();
+
+const opts = program.opts();
+
+(async () => {
+  try {
+    const db = getDb();
+    const allNodes = await db.select().from(nodes);
+
+    if (allNodes.length === 0) {
+      console.log(chalk.yellow('No nodes in the database. Nothing to rebuild.'));
+      process.exit(0);
+    }
+
+    const oldGraph = await readGraph();
+
+    const newGraph = {
+      version: '1.0',
+      project: oldGraph.project,
+      nodes: [],
+      edges: oldGraph.edges,
+    };
+
+    for (const row of allNodes) {
+      const { frontmatter, sections } = await readNode(row.id);
+      const meta = deriveMetadata(frontmatter, sections, row.type);
+
+      const nodeEntry = {
+        id: row.id,
+        type: row.type,
+        name: row.name,
+        status: meta.status,
+        completeness: meta.completeness,
+        open_questions_count: meta.open_questions_count,
+        priority: row.priority,
+        created_at: row.createdAt,
+        updated_at: row.updatedAt,
+        ...(row.kind ? { kind: row.kind } : {}),
+        body: row.body,
+      };
+      newGraph.nodes.push(nodeEntry);
+    }
+
+    if (opts.dryRun) {
+      console.log(chalk.cyan('Dry run — would produce:'));
+      console.log(`  Nodes: ${newGraph.nodes.length} (was ${oldGraph.nodes.length})`);
+      console.log(`  Edges: ${newGraph.edges.length}`);
+      for (const node of newGraph.nodes) {
+        console.log(`  ${node.id}: ${node.name} (${node.type}) — ${Math.round(node.completeness * 100)}%`);
+      }
+    } else {
+      await writeGraph(newGraph, opts.projectId);
+      console.log(chalk.green(`✓ Rebuilt index: ${newGraph.nodes.length} nodes, ${newGraph.edges.length} edges`));
+    }
+  } catch (err) {
+    console.error(chalk.red(`Error: ${err.message}`));
+    process.exit(1);
+  }
+})();

package/templates/product-system/packages/shared/tools/remove_edge.ts

@@ -0,0 +1,59 @@
+#!/usr/bin/env node
+
+/**
+ * remove_edge — Removes a relationship between two nodes.
+ */
+
+import { program } from 'commander';
+import chalk from 'chalk';
+import { readGraph, removeEdge as graphRemoveEdge } from '../lib/graph.js';
+import { readNode, writeNode } from '../lib/markdown.js';
+import { assertNodeExists, assertValidRelation } from '../lib/validator.js';
+
+program
+  .argument('<from>', 'Source node ID')
+  .argument('<relation>', 'Relation type')
+  .argument('<to>', 'Target node ID')
+  .requiredOption('--project-id <id>', 'Project ID')
+  .parse();
+
+const [from, relation, to] = program.args;
+
+(async () => {
+  try {
+    await assertNodeExists(from);
+    await assertNodeExists(to);
+    assertValidRelation(relation);
+
+    // Get node metadata before removing edge
+    const graph = await readGraph();
+    const fromNode = graph.nodes.find(n => n.id === from);
+    const toNode = graph.nodes.find(n => n.id === to);
+
+    // Remove edge from DB
+    await graphRemoveEdge(from, relation, to);
+
+    // Remove relation lines from body content
+    const fromData = await readNode(from);
+    const fromRelations = (fromData.sections['Relations'] || '').split('\n');
+    fromData.sections['Relations'] = fromRelations
+      .filter(l => !l.includes(`${relation} → ${to}`))
+      .join('\n')
+      .trim();
+    await writeNode(from, fromData.frontmatter, fromData.sections);
+
+    const toData = await readNode(to);
+    const toRelations = (toData.sections['Relations'] || '').split('\n');
+    toData.sections['Relations'] = toRelations
+      .filter(l => !l.includes(`${relation} ← ${from}`))
+      .join('\n')
+      .trim();
+    await writeNode(to, toData.frontmatter, toData.sections);
+
+    console.log(chalk.green(`✓ Removed edge: ${from} --${relation}--> ${to}`));
+    console.log(JSON.stringify({ from, relation, to }));
+  } catch (err) {
+    console.error(chalk.red(`Error: ${err.message}`));
+    process.exit(1);
+  }
+})();