@assistkick/create 1.0.0

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

@@ -0,0 +1,101 @@
+#!/usr/bin/env node
+
+/**
+ * add_node — Creates a new node in the knowledge graph.
+ * Generates a unique ID, writes to DB, and adds the entry to the graph.
+ */
+
+import { program } from 'commander';
+import chalk from 'chalk';
+import { eq } from 'drizzle-orm';
+import { NODE_TYPES, VALID_FEATURE_KINDS } from '../lib/constants.js';
+import { readGraph, patchNode } from '../lib/graph.js';
+import { getDb } from '../lib/db.js';
+import { nodes } from '../db/schema.js';
+import { writeNode, deriveMetadata, templateSections } from '../lib/markdown.js';
+import { assertValidType, assertUniqueName } from '../lib/validator.js';
+
+program
+  .requiredOption('--type <type>', 'Node type (e.g., feature, component, decision)')
+  .requiredOption('--name <name>', 'Node name (must be unique within type)')
+  .requiredOption('--project-id <id>', 'Project ID')
+  .option('--description <text>', 'Initial description text', '')
+  .option('--priority <level>', 'Priority level (low, medium, high, blocking)', 'medium')
+  .option('--kind <kind>', 'Feature kind (new, improvement, bugfix). Only applies to features.', 'new')
+  .parse();
+
+const opts = program.opts();
+
+(async () => {
+  try {
+    assertValidType(opts.type);
+    await assertUniqueName(opts.type, opts.name, opts.projectId);
+
+    // Validate kind (only applies to features)
+    if (opts.type === 'feature' && !VALID_FEATURE_KINDS.includes(opts.kind)) {
+      throw new Error(`Invalid kind "${opts.kind}". Valid: ${VALID_FEATURE_KINDS.join(', ')}`);
+    }
+
+    // Generate next ID: prefix_NNN
+    const prefix = NODE_TYPES[opts.type];
+    const graph = await readGraph(opts.projectId);
+    const existing = graph.nodes.filter(n => n.type === opts.type);
+    const maxNum = existing.reduce((max, n) => {
+      const num = parseInt(n.id.split('_').pop(), 10);
+      return num > max ? num : max;
+    }, 0);
+    const id = `${prefix}_${String(maxNum + 1).padStart(3, '0')}`;
+
+    // Build frontmatter and sections
+    const now = new Date().toISOString();
+    const frontmatter = {
+      id,
+      type: opts.type,
+      name: opts.name,
+      status: 'draft',
+      priority: opts.priority,
+      ...(opts.type === 'feature' ? { kind: opts.kind } : {}),
+      created_at: now,
+      updated_at: now,
+    };
+
+    const sections = templateSections(opts.type);
+    if (opts.description) {
+      sections['Description'] = opts.description;
+    }
+
+    // Derive metadata
+    const meta = deriveMetadata(frontmatter, sections, opts.type);
+
+    // Serialize sections to body
+    const body = Object.entries(sections)
+      .map(([name, content]) => {
+        if (content.trim()) return `## ${name}\n${content.trim()}\n`;
+        return `## ${name}\n`;
+      })
+      .join('\n');
+
+    // Insert directly into DB
+    const db = getDb();
+    await db.insert(nodes).values({
+      id,
+      type: opts.type,
+      name: opts.name,
+      status: meta.status,
+      priority: opts.priority,
+      completeness: meta.completeness,
+      openQuestionsCount: meta.open_questions_count,
+      kind: opts.type === 'feature' ? opts.kind : null,
+      createdAt: now,
+      updatedAt: now,
+      body,
+      projectId: opts.projectId,
+    });
+
+    console.log(chalk.green(`✓ Created ${opts.type} node: ${id}`));
+    console.log(JSON.stringify({ id, type: opts.type, name: opts.name }));
+  } catch (err) {
+    console.error(chalk.red(`Error: ${err.message}`));
+    process.exit(1);
+  }
+})();

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

@@ -0,0 +1,87 @@
+#!/usr/bin/env node
+
+/**
+ * end_session — Finalizes the current session with summary and gap analysis.
+ */
+
+import { program } from 'commander';
+import chalk from 'chalk';
+import { readGraph } from '../lib/graph.js';
+import { getLatestSession, endSession } from '../lib/session.js';
+
+program
+  .requiredOption('--project-id <id>', 'Project ID')
+  .option('--summary <text>', 'Session summary (3-5 sentences)')
+  .option('--nodes-touched <ids>', 'Comma-separated list of node IDs touched this session')
+  .option('--questions-resolved <count>', 'Number of questions resolved', parseInt)
+  .parse();
+
+const opts = program.opts();
+
+(async () => {
+  try {
+    const session = await getLatestSession(opts.projectId);
+    if (!session) {
+      throw new Error('No sessions found. Run start_session first.');
+    }
+
+    if (session.endedAt) {
+      throw new Error(`Session ${session.sessionNumber} is already ended. Start a new session first.`);
+    }
+
+    // Build updated body
+    let updatedBody = session.body || '';
+    if (opts.summary) {
+      updatedBody = updatedBody.replace('### Summary\n', `### Summary\n${opts.summary}\n`);
+    }
+
+    // Add gap analysis
+    const graph = await readGraph();
+    const graphNodes = graph.nodes;
+    const totalNodes = graphNodes.length;
+    const avgCompleteness = totalNodes > 0
+      ? graphNodes.reduce((s, n) => s + n.completeness, 0) / totalNodes
+      : 0;
+    const totalOpenQuestions = graphNodes.reduce((s, n) => s + n.open_questions_count, 0);
+    const blockingGaps = graphNodes.filter(n => {
+      return n.status === 'draft' && graph.edges.some(e => e.to === n.id);
+    }).length;
+
+    updatedBody += `\n### Status at End
+- Total nodes: ${totalNodes}
+- Overall completeness: ${Math.round(avgCompleteness * 100)}%
+- Open questions: ${totalOpenQuestions}
+- Blocking gaps: ${blockingGaps}
+`;
+
+    // Remaining gaps
+    const gapNodes = graphNodes
+      .filter(n => n.open_questions_count > 0 || n.status !== 'defined')
+      .sort((a, b) => a.completeness - b.completeness)
+      .slice(0, 10);
+
+    if (gapNodes.length > 0) {
+      updatedBody += '\n### Remaining Gaps\n';
+      for (const n of gapNodes) {
+        updatedBody += `- ${n.id} ${n.name} — ${Math.round(n.completeness * 100)}%, ${n.open_questions_count} open question(s)\n`;
+      }
+    }
+
+    // Update session
+    await endSession(session.sessionNumber, {
+      ended_at: new Date().toISOString(),
+      summary: opts.summary || null,
+      nodes_touched: opts.nodesTouched ? opts.nodesTouched.split(',').map(s => s.trim()) : [],
+      questions_resolved: opts.questionsResolved,
+      body: updatedBody,
+    });
+
+    console.log(chalk.green(`✓ Session ${session.sessionNumber} ended`));
+    console.log(`Nodes: ${totalNodes} — ${Math.round(avgCompleteness * 100)}% complete`);
+    console.log(`Open questions remaining: ${totalOpenQuestions}`);
+    console.log(`Blocking gaps: ${blockingGaps}`);
+  } catch (err) {
+    console.error(chalk.red(`Error: ${err.message}`));
+    process.exit(1);
+  }
+})();

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

@@ -0,0 +1,87 @@
+#!/usr/bin/env node
+
+/**
+ * get_gaps — Returns a prioritized list of incomplete or unresolved items across the graph.
+ */
+
+import { program } from 'commander';
+import chalk from 'chalk';
+import { readGraph } from '../lib/graph.js';
+
+program
+  .requiredOption('--project-id <id>', 'Project ID')
+  .option('--blocking-only', 'Only show blocking gaps')
+  .option('--type <type>', 'Filter by node type')
+  .parse();
+
+const opts = program.opts();
+
+(async () => {
+  try {
+    const graph = await readGraph(opts.projectId);
+    let nodes = [...graph.nodes];
+
+    if (opts.type) {
+      nodes = nodes.filter(n => n.type === opts.type);
+    }
+
+    // Build set of nodes that are referenced by edges (depended upon)
+    const referenced = new Set();
+    for (const edge of graph.edges) {
+      referenced.add(edge.to);
+    }
+
+    const gaps = { BLOCKING: [], HIGH: [], MEDIUM: [], LOW: [] };
+
+    for (const node of nodes) {
+      // BLOCKING: draft nodes that are referenced by other nodes
+      if (node.status === 'draft' && referenced.has(node.id)) {
+        gaps.BLOCKING.push(node);
+      }
+      // HIGH: nodes with open questions and completeness < 0.5
+      else if (node.open_questions_count > 0 && node.completeness < 0.5) {
+        gaps.HIGH.push(node);
+      }
+      // MEDIUM: nodes with open questions and completeness >= 0.5
+      else if (node.open_questions_count > 0 && node.completeness >= 0.5) {
+        gaps.MEDIUM.push(node);
+      }
+      // LOW: partially defined but no open questions (optional sections missing)
+      else if (node.status === 'partially_defined' || (node.status === 'draft' && !referenced.has(node.id))) {
+        gaps.LOW.push(node);
+      }
+    }
+
+    if (opts.blockingOnly) {
+      printSection('BLOCKING', gaps.BLOCKING);
+    } else {
+      printSection('BLOCKING', gaps.BLOCKING);
+      printSection('HIGH', gaps.HIGH);
+      printSection('MEDIUM', gaps.MEDIUM);
+      printSection('LOW', gaps.LOW);
+    }
+
+    const total = gaps.BLOCKING.length + gaps.HIGH.length + gaps.MEDIUM.length + gaps.LOW.length;
+    if (total === 0) {
+      console.log(chalk.green('\n✓ No gaps found!'));
+    } else {
+      console.log(`\nTotal: ${total} gap(s) — ${gaps.BLOCKING.length} blocking, ${gaps.HIGH.length} high, ${gaps.MEDIUM.length} medium, ${gaps.LOW.length} low`);
+    }
+
+    // JSON output
+    console.log('\n' + JSON.stringify(gaps));
+  } catch (err) {
+    console.error(chalk.red(`Error: ${err.message}`));
+    process.exit(1);
+  }
+})();
+
+function printSection(severity, items) {
+  if (items.length === 0) return;
+  const colors = { BLOCKING: chalk.red, HIGH: chalk.yellow, MEDIUM: chalk.cyan, LOW: chalk.gray };
+  const color = colors[severity] || chalk.white;
+  console.log(color(`\n${severity} (${items.length}):`));
+  for (const n of items) {
+    console.log(`  ${n.id} ${n.name} [${n.type}] — ${Math.round(n.completeness * 100)}% complete, ${n.open_questions_count} open question(s)`);
+  }
+}

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

@@ -0,0 +1,125 @@
+#!/usr/bin/env node
+
+/**
+ * get_kanban — Reads kanban state from the database and displays cards, optionally filtered by column.
+ *
+ * Usage:
+ *   node tools/get_kanban.js                  # show all columns
+ *   node tools/get_kanban.js --column todo    # only todo items
+ *   node tools/get_kanban.js --column qa      # only qa items
+ */
+
+import { program } from 'commander';
+import chalk from 'chalk';
+import { readGraph } from '../lib/graph.js';
+import { loadKanban, kanbanExists } from '../lib/kanban.js';
+
+const VALID_COLUMNS = ['todo', 'in_progress', 'in_review', 'qa', 'done'];
+
+const COLUMN_COLORS = {
+  todo: chalk.gray,
+  in_progress: chalk.blue,
+  in_review: chalk.magenta,
+  qa: chalk.yellow,
+  done: chalk.green,
+};
+
+program
+  .requiredOption('--project-id <id>', 'Project ID')
+  .option('--column <column>', 'Filter by column (todo, in_progress, qa, done)')
+  .parse();
+
+const opts = program.opts();
+
+(async () => {
+  try {
+    if (!(await kanbanExists(opts.projectId))) {
+      console.log(chalk.yellow('No kanban entries found. No features are being tracked yet.'));
+      process.exit(0);
+    }
+
+    if (opts.column && !VALID_COLUMNS.includes(opts.column)) {
+      throw new Error(`Invalid column "${opts.column}". Valid columns: ${VALID_COLUMNS.join(', ')}`);
+    }
+
+    const kanban = await loadKanban(opts.projectId);
+    const graph = await readGraph(opts.projectId);
+
+    // Build lookups from graph nodes
+    const nameMap = {};
+    const kindMap = {};
+    for (const node of graph.nodes) {
+      nameMap[node.id] = node.name;
+      if (node.type === 'feature') {
+        kindMap[node.id] = node.kind || 'new';
+      }
+    }
+
+    // Group entries by column
+    const columns = { todo: [], in_progress: [], qa: [], done: [] };
+
+    for (const [featureId, entry] of Object.entries(kanban)) {
+      const col = entry.column;
+      if (!columns[col]) columns[col] = [];
+      columns[col].push({
+        id: featureId,
+        name: nameMap[featureId] || featureId,
+        kind: kindMap[featureId] || 'new',
+        rejection_count: entry.rejection_count || 0,
+        notes_count: (entry.notes || []).length,
+      });
+    }
+
+    // Display
+    const columnsToShow = opts.column ? [opts.column] : VALID_COLUMNS;
+
+    for (const col of columnsToShow) {
+      const items = columns[col] || [];
+      const colorFn = COLUMN_COLORS[col] || chalk.white;
+      const label = col.replace('_', ' ').toUpperCase();
+
+      console.log(colorFn.bold(`\n${label} (${items.length})`));
+
+      if (items.length === 0) {
+        console.log(chalk.gray('  (empty)'));
+        continue;
+      }
+
+      for (const item of items) {
+        let line = `  ${item.id} ${item.name}`;
+        if (item.kind !== 'new') {
+          const kindColors = { improvement: chalk.blue, bugfix: chalk.yellow };
+          const kindFn = kindColors[item.kind] || chalk.white;
+          line += ` ${kindFn(`[${item.kind}]`)}`;
+        }
+        if (item.rejection_count > 0) {
+          const rejLabel = item.rejection_count >= 3
+            ? chalk.red.bold(`[${item.rejection_count}x rejected]`)
+            : chalk.yellow(`[${item.rejection_count}x rejected]`);
+          line += ` ${rejLabel}`;
+        }
+        if (item.notes_count > 0) {
+          line += chalk.gray(` (${item.notes_count} note${item.notes_count > 1 ? 's' : ''})`);
+        }
+        console.log(line);
+      }
+    }
+
+    // JSON output
+    const jsonOutput = {};
+    for (const col of columnsToShow) {
+      jsonOutput[col] = (columns[col] || []).map(item => ({
+        id: item.id,
+        name: item.name,
+        kind: item.kind,
+        rejection_count: item.rejection_count,
+        notes_count: item.notes_count,
+      }));
+    }
+    console.log('\n' + JSON.stringify(jsonOutput));
+
+  } catch (err) {
+    console.error(chalk.red(`Error: ${err.message}`));
+    process.exit(1);
+  }
+})();

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

@@ -0,0 +1,78 @@
+#!/usr/bin/env node
+
+/**
+ * get_node — Loads and prints the full content of a node from the database, plus its relations.
+ *
+ * Usage:
+ *   node tools/get_node.js feat_001
+ *   node tools/get_node.js --name "Node Name"
+ */
+
+import { program } from 'commander';
+import chalk from 'chalk';
+import matter from 'gray-matter';
+import { readGraph } from '../lib/graph.js';
+import { readNode } from '../lib/markdown.js';
+
+program
+  .argument('[id]', 'Node ID (e.g., feat_001)')
+  .requiredOption('--project-id <id>', 'Project ID')
+  .option('--name <name>', 'Look up node by name instead of ID')
+  .parse();
+
+const args = program.args;
+const opts = program.opts();
+
+(async () => {
+  try {
+    const graph = await readGraph(opts.projectId);
+    let node;
+
+    if (args[0]) {
+      node = graph.nodes.find(n => n.id === args[0]);
+      if (!node) {
+        throw new Error(`Node not found: ${args[0]}`);
+      }
+    } else if (opts.name) {
+      node = graph.nodes.find(n => n.name.toLowerCase() === opts.name.toLowerCase());
+      if (!node) {
+        throw new Error(`No node named "${opts.name}"`);
+      }
+    } else {
+      throw new Error('Provide a node ID or --name');
+    }
+
+    // Read node content from DB
+    const { frontmatter, sections } = await readNode(node.id);
+
+    // Reconstruct the markdown output for display
+    const body = Object.entries(sections)
+      .map(([name, content]) => content.trim() ? `## ${name}\n${content.trim()}\n` : `## ${name}\n`)
+      .join('\n');
+    const content = matter.stringify(body, frontmatter);
+    console.log(content);
+
+    // Print relations
+    const edges = graph.edges.filter(e => e.from === node.id || e.to === node.id);
+
+    if (edges.length > 0) {
+      console.log(chalk.cyan.bold('\n── Relations ──\n'));
+
+      for (const edge of edges) {
+        const isOutgoing = edge.from === node.id;
+        const otherId = isOutgoing ? edge.to : edge.from;
+        const other = graph.nodes.find(n => n.id === otherId);
+        const otherLabel = other ? `${other.name} [${other.type}] ${other.status}` : otherId;
+
+        if (isOutgoing) {
+          console.log(`  ${chalk.bold(node.id)} ${chalk.gray(`--${edge.relation}-->`)} ${chalk.bold(otherId)} ${otherLabel}`);
+        } else {
+          console.log(`  ${chalk.bold(otherId)} ${otherLabel} ${chalk.gray(`--${edge.relation}-->`)} ${chalk.bold(node.id)}`);
+        }
+      }
+    }
+  } catch (err) {
+    console.error(chalk.red(`Error: ${err.message}`));
+    process.exit(1);
+  }
+})();

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

@@ -0,0 +1,98 @@
+#!/usr/bin/env node
+
+/**
+ * get_status — Returns overall completeness across the whole project, grouped by domain.
+ */
+
+import { program } from 'commander';
+import chalk from 'chalk';
+import { readGraph } from '../lib/graph.js';
+
+program
+  .requiredOption('--project-id <id>', 'Project ID')
+  .parse();
+
+const opts = program.opts();
+
+(async () => {
+  try {
+    const graph = await readGraph(opts.projectId);
+    const nodes = graph.nodes;
+
+    if (nodes.length === 0) {
+      console.log(chalk.yellow('No nodes in the graph yet.'));
+      process.exit(0);
+    }
+
+    // Project header
+    const projectName = graph.project.name || '(unnamed project)';
+    const overallCompleteness = nodes.reduce((sum, n) => sum + n.completeness, 0) / nodes.length;
+
+    console.log(chalk.bold(`Project: ${projectName}`));
+    console.log(chalk.bold(`Overall: ${Math.round(overallCompleteness * 100)}% complete\n`));
+
+    // Group by type
+    const groups = {};
+    for (const node of nodes) {
+      if (!groups[node.type]) groups[node.type] = [];
+      groups[node.type].push(node);
+    }
+
+    // Display order (most common types first)
+    const typeOrder = [
+      'feature', 'component', 'data_entity', 'decision', 'tech_choice',
+      'non_functional_requirement', 'flow', 'user_role',
+      'design_token', 'design_pattern', 'assumption', 'open_question',
+    ];
+
+    for (const type of typeOrder) {
+      const items = groups[type];
+      if (!items) continue;
+
+      const avgCompleteness = items.reduce((s, n) => s + n.completeness, 0) / items.length;
+      const defined = items.filter(n => n.status === 'defined').length;
+      const partial = items.filter(n => n.status === 'partially_defined').length;
+      const draft = items.filter(n => n.status === 'draft').length;
+      const bar = progressBar(avgCompleteness);
+
+      const label = formatType(type).padEnd(20);
+      const detail = `(${defined} defined, ${partial} partial, ${draft} draft)`;
+      console.log(`${label} ${bar}  ${Math.round(avgCompleteness * 100)}%  ${detail}`);
+    }
+
+    // Summary stats
+    const blockingGaps = nodes.filter(n => {
+      const isReferenced = graph.edges.some(e => e.to === n.id);
+      return n.status === 'draft' && isReferenced;
+    }).length;
+
+    const totalOpenQuestions = nodes.reduce((s, n) => s + n.open_questions_count, 0);
+    const unresolvedDecisions = nodes.filter(n => n.type === 'decision' && n.status !== 'defined').length;
+
+    console.log(`\nBlocking gaps: ${blockingGaps}`);
+    console.log(`Open questions: ${totalOpenQuestions}`);
+    console.log(`Unresolved decisions: ${unresolvedDecisions}`);
+
+    // JSON output
+    console.log('\n' + JSON.stringify({
+      project: projectName,
+      overall_completeness: Math.round(overallCompleteness * 100) / 100,
+      total_nodes: nodes.length,
+      blocking_gaps: blockingGaps,
+      open_questions: totalOpenQuestions,
+      unresolved_decisions: unresolvedDecisions,
+    }));
+  } catch (err) {
+    console.error(chalk.red(`Error: ${err.message}`));
+    process.exit(1);
+  }
+})();
+
+function progressBar(value, width = 10) {
+  const filled = Math.round(value * width);
+  return chalk.green('█'.repeat(filled)) + chalk.gray('░'.repeat(width - filled));
+}
+
+function formatType(type) {
+  return type.split('_').map(w => w[0].toUpperCase() + w.slice(1)).join(' ');
+}