@assistkick/create 1.0.0

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

@@ -0,0 +1,96 @@
+#!/usr/bin/env node
+
+/**
+ * remove_node — Deletes a node and all its edges from the knowledge graph.
+ */
+
+import { program } from 'commander';
+import chalk from 'chalk';
+import { eq, or } from 'drizzle-orm';
+import { createInterface } from 'node:readline';
+import { getDb } from '../lib/db.js';
+import { getNode } from '../lib/graph.js';
+import { assertNodeExists } from '../lib/validator.js';
+import { nodes, edges, kanban, reviewMeta } from '../db/schema.js';
+
+program
+  .argument('<id>', 'Node ID to delete (e.g. feat_034)')
+  .requiredOption('--project-id <id>', 'Project ID')
+  .option('--force', 'Skip confirmation prompt')
+  .parse();
+
+const [id] = program.args;
+const opts = program.opts();
+
+const confirm = async (message: string): Promise<boolean> => {
+  const rl = createInterface({ input: process.stdin, output: process.stdout });
+  return new Promise((resolve) => {
+    rl.question(message, (answer) => {
+      rl.close();
+      resolve(answer.trim().toLowerCase() === 'y');
+    });
+  });
+};
+
+(async () => {
+  try {
+    await assertNodeExists(id);
+
+    const node = await getNode(id);
+    const db = getDb();
+
+    // Count edges that will be removed
+    const relatedEdges = await db.select().from(edges).where(
+      or(eq(edges.fromId, id), eq(edges.toId, id))
+    );
+
+    // Check kanban status
+    const kanbanRows = await db.select().from(kanban).where(eq(kanban.nodeId, id));
+    const kanbanStatus = kanbanRows[0]?.columnName ?? '(none)';
+
+    // Print summary
+    console.log(chalk.yellow('\n⚠  About to delete:'));
+    console.log(`   Node:   ${chalk.bold(id)} — ${node.name}`);
+    console.log(`   Type:   ${node.type}`);
+    console.log(`   Status: ${node.status}`);
+    console.log(`   Kanban: ${kanbanStatus}`);
+    console.log(`   Edges:  ${relatedEdges.length} will be removed\n`);
+
+    if (!opts.force) {
+      const ok = await confirm(chalk.red('Type "y" to confirm deletion: '));
+      if (!ok) {
+        console.log(chalk.gray('Aborted.'));
+        process.exit(0);
+      }
+    }
+
+    // Delete everything in a single transaction
+    await db.transaction(async (tx) => {
+      // kanban row (FK to nodes — must go first)
+      await tx.delete(kanban).where(eq(kanban.nodeId, id));
+
+      // review_meta row with key kanban:<id>
+      await tx.delete(reviewMeta).where(eq(reviewMeta.key, `kanban:${id}`));
+
+      // All edges where from_id = id OR to_id = id
+      await tx.delete(edges).where(
+        or(eq(edges.fromId, id), eq(edges.toId, id))
+      );
+
+      // The node itself
+      await tx.delete(nodes).where(eq(nodes.id, id));
+    });
+
+    console.log(chalk.green(`\n✓ Deleted node: ${id}`));
+    console.log(JSON.stringify({
+      id,
+      name: node.name,
+      type: node.type,
+      edgesRemoved: relatedEdges.length,
+      kanbanRemoved: kanbanRows.length > 0,
+    }));
+  } catch (err) {
+    console.error(chalk.red(`Error: ${err.message}`));
+    process.exit(1);
+  }
+})();

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

@@ -0,0 +1,75 @@
+#!/usr/bin/env node
+
+/**
+ * resolve_question — Marks an open question as resolved and records the answer.
+ */
+
+import { program } from 'commander';
+import chalk from 'chalk';
+import { readGraph, patchNode } from '../lib/graph.js';
+import { readNode, writeNode, deriveMetadata } from '../lib/markdown.js';
+import { assertNodeExists } from '../lib/validator.js';
+
+program
+  .argument('<id>', 'Node ID containing the question')
+  .requiredOption('--project-id <id>', 'Project ID')
+  .requiredOption('--question <text>', 'The open question text to resolve (substring match)')
+  .requiredOption('--answer <text>', 'The answer to record')
+  .parse();
+
+const id = program.args[0];
+const opts = program.opts();
+
+(async () => {
+  try {
+    await assertNodeExists(id);
+
+    const graph = await readGraph();
+    const nodeMeta = graph.nodes.find(n => n.id === id);
+    let { frontmatter, sections } = await readNode(id);
+
+    // Find the open question line
+    const oqContent = sections['Open Questions'] || '';
+    const oqLines = oqContent.split('\n');
+    const matchIdx = oqLines.findIndex(l => l.includes(opts.question));
+
+    if (matchIdx === -1) {
+      throw new Error(`Open question not found containing: "${opts.question}"`);
+    }
+
+    // Remove from Open Questions
+    const matchedLine = oqLines[matchIdx];
+    oqLines.splice(matchIdx, 1);
+    sections['Open Questions'] = oqLines.join('\n').trim();
+
+    // Extract the question text (strip the checkbox prefix)
+    const questionText = matchedLine.replace(/^-\s*\[\s*\]\s*/, '').trim();
+
+    // Add to Resolved Questions with answer
+    const resolvedLine = `- [x] ${questionText} → ${opts.answer}`;
+    const rqContent = sections['Resolved Questions'] || '';
+    sections['Resolved Questions'] = rqContent ? rqContent + '\n' + resolvedLine : resolvedLine;
+
+    frontmatter.updated_at = new Date().toISOString();
+    await writeNode(id, frontmatter, sections);
+
+    // Re-derive metadata and update graph
+    const meta = deriveMetadata(frontmatter, sections, nodeMeta.type);
+    await patchNode(id, {
+      status: meta.status,
+      completeness: meta.completeness,
+      open_questions_count: meta.open_questions_count,
+    });
+
+    console.log(chalk.green(`✓ Resolved question on ${id}`));
+    console.log(JSON.stringify({
+      id,
+      question: questionText,
+      answer: opts.answer,
+      open_questions_remaining: meta.open_questions_count,
+    }));
+  } catch (err) {
+    console.error(chalk.red(`Error: ${err.message}`));
+    process.exit(1);
+  }
+})();

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

@@ -0,0 +1,106 @@
+#!/usr/bin/env node
+
+/**
+ * search_nodes — Graph-aware relevance search with ranking.
+ *
+ * When --query is provided:
+ *   1. Direct keyword matches (name or body) scored highest
+ *   2. 1-hop graph neighbors of matches scored by edge type weight
+ *   3. Cold start fallback: top-5 most-connected per type if zero matches
+ *
+ * Filters (--type, --status, --has-open-questions, --completeness-below) are
+ * applied after relevance ranking.
+ */
+
+import { program } from 'commander';
+import chalk from 'chalk';
+import { eq } from 'drizzle-orm';
+import { readGraph } from '../lib/graph.js';
+import { getDb } from '../lib/db.js';
+import { nodes } from '../db/schema.js';
+import { relevanceSearch } from '../lib/relevance_search.js';
+
+program
+  .requiredOption('--project-id <id>', 'Project ID')
+  .option('--query <keyword>', 'Search by keyword in name and body content')
+  .option('--type <type>', 'Filter by node type')
+  .option('--status <status>', 'Filter by status')
+  .option('--has-open-questions', 'Only nodes with open questions')
+  .option('--completeness-below <threshold>', 'Only nodes below completeness threshold', parseFloat)
+  .parse();
+
+const opts = program.opts();
+
+(async () => {
+  try {
+    const graph = await readGraph(opts.projectId);
+
+    let results;
+
+    if (opts.query) {
+      const db = getDb();
+      const getBody = async (nodeId) => {
+        const rows = await db.select({ body: nodes.body }).from(nodes).where(eq(nodes.id, nodeId));
+        return rows[0]?.body ?? null;
+      };
+
+      results = await relevanceSearch(opts.query, graph.nodes, graph.edges, getBody);
+    } else {
+      // No keyword — return all nodes without relevance (backward compat)
+      results = graph.nodes.map(n => ({
+        id: n.id,
+        name: n.name,
+        type: n.type,
+        status: n.status,
+        completeness: n.completeness,
+        open_questions_count: n.open_questions_count,
+        relevance: null,
+        _score: 0,
+      }));
+    }
+
+    // Apply post-ranking filters
+    if (opts.type) {
+      results = results.filter(n => n.type === opts.type);
+    }
+
+    if (opts.status) {
+      results = results.filter(n => n.status === opts.status);
+    }
+
+    if (opts.hasOpenQuestions) {
+      results = results.filter(n => n.open_questions_count > 0);
+    }
+
+    if (opts.completenessBelow !== undefined) {
+      results = results.filter(n => n.completeness < opts.completenessBelow);
+    }
+
+    if (results.length === 0) {
+      console.log(chalk.yellow('No matching nodes found.'));
+    } else {
+      console.log(chalk.cyan(`Found ${results.length} node(s):\n`));
+      for (const n of results) {
+        const bar = progressBar(n.completeness);
+        const oq = n.open_questions_count > 0 ? chalk.yellow(` (${n.open_questions_count} open questions)`) : '';
+        const rel = n.relevance ? chalk.gray(` [${n.relevance}]`) : '';
+        console.log(`  ${chalk.bold(n.id)} ${n.name} [${n.type}] ${n.status} ${bar} ${Math.round(n.completeness * 100)}%${oq}${rel}`);
+      }
+    }
+
+    // JSON output includes relevance label
+    console.log('\n' + JSON.stringify(results.map(n => ({
+      id: n.id, name: n.name, type: n.type, status: n.status,
+      completeness: n.completeness, open_questions_count: n.open_questions_count,
+      relevance: n.relevance,
+    }))));
+  } 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));
+}

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

@@ -0,0 +1,144 @@
+#!/usr/bin/env node
+
+/**
+ * start_session — Creates a session record in the database, runs get_status logic,
+ * loads context from recent sessions, and prints resume context.
+ */
+
+import { program } from 'commander';
+import chalk from 'chalk';
+import { readGraph } from '../lib/graph.js';
+import {
+  getNextSessionNumber,
+  createSession,
+  getRecentSessions,
+  getRecentlyModifiedNodes,
+  getRecentDecisions,
+} from '../lib/session.js';
+
+program
+  .requiredOption('--project-id <id>', 'Project ID')
+  .parse();
+
+const opts = program.opts();
+
+/**
+ * Extract a short description excerpt from a node body (first non-empty line after ## Description).
+ */
+const extractDescriptionExcerpt = (body, maxLen = 120) => {
+  if (!body) return '';
+  const match = body.match(/## Description\s*\n+(.+)/);
+  if (!match) return '';
+  const line = match[1].trim();
+  return line.length > maxLen ? line.slice(0, maxLen) + '…' : line;
+};
+
+(async () => {
+  try {
+    const sessionNum = await getNextSessionNumber(opts.projectId);
+    const graph = await readGraph(opts.projectId);
+    const graphNodes = graph.nodes;
+
+    // Compute status summary
+    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;
+
+    // Load context recall data
+    const recentSessions = await getRecentSessions(3, opts.projectId);
+    const recentNodes = await getRecentlyModifiedNodes(10, opts.projectId);
+    const recentDecisions = await getRecentDecisions(recentSessions);
+
+    // Create session body
+    const body = `## Session ${sessionNum}
+
+### Status at Start
+- Total nodes: ${totalNodes}
+- Overall completeness: ${Math.round(avgCompleteness * 100)}%
+- Open questions: ${totalOpenQuestions}
+- Blocking gaps: ${blockingGaps}
+
+### Notes
+
+### Summary
+`;
+
+    await createSession(sessionNum, body, opts.projectId);
+
+    // Print resume context
+    const sessionId = `session_${String(sessionNum).padStart(3, '0')}`;
+    console.log(chalk.bold(`\n📋 Session ${sessionNum} started`));
+    console.log(chalk.cyan(`Session: ${sessionId}\n`));
+
+    if (totalNodes === 0) {
+      console.log('No nodes yet. Start by adding the first feature or component.');
+    } else {
+      console.log(`Project: ${graph.project.name || '(unnamed)'}`);
+      console.log(`Nodes: ${totalNodes} — ${Math.round(avgCompleteness * 100)}% overall completeness`);
+      console.log(`Open questions: ${totalOpenQuestions}`);
+      console.log(`Blocking gaps: ${blockingGaps}`);
+
+      // Show top gaps
+      const highPriority = graphNodes
+        .filter(n => n.open_questions_count > 0 || n.status === 'draft')
+        .sort((a, b) => a.completeness - b.completeness)
+        .slice(0, 5);
+
+      if (highPriority.length > 0) {
+        console.log(chalk.yellow('\nSuggested focus:'));
+        for (const n of highPriority) {
+          console.log(`  ${n.id} ${n.name} — ${Math.round(n.completeness * 100)}%, ${n.open_questions_count} open question(s)`);
+        }
+      }
+
+      // --- Context Recall ---
+      if (recentSessions.length > 0) {
+        console.log(chalk.bold('\n── Recent Session Context ──'));
+
+        // Recent session summaries
+        console.log(chalk.yellow('\nLast sessions:'));
+        for (const s of recentSessions) {
+          const nodesTouched = s.nodesTouched ? JSON.parse(s.nodesTouched) : [];
+          console.log(`  Session ${s.sessionNumber} (${s.startedAt} → ${s.endedAt})`);
+          if (s.summary) {
+            console.log(`    Summary: ${s.summary}`);
+          }
+          if (nodesTouched.length > 0) {
+            console.log(`    Nodes touched: ${nodesTouched.join(', ')}`);
+          }
+          console.log(`    Questions resolved: ${s.questionsResolved || 0}`);
+        }
+
+        // Recently modified nodes
+        if (recentNodes.length > 0) {
+          console.log(chalk.yellow('\nRecently modified nodes:'));
+          for (const n of recentNodes) {
+            console.log(`  ${n.id} ${n.name} [${n.type}] ${n.status} — ${Math.round(n.completeness * 100)}% (updated ${n.updatedAt})`);
+          }
+        }
+
+        // Recent decisions
+        if (recentDecisions.length > 0) {
+          console.log(chalk.yellow('\nRecent decisions:'));
+          for (const d of recentDecisions) {
+            const excerpt = extractDescriptionExcerpt(d.body);
+            console.log(`  ${d.id} ${d.name} [${d.status}]`);
+            if (excerpt) {
+              console.log(`    ${excerpt}`);
+            }
+          }
+        }
+      }
+    }
+
+    console.log('\n' + JSON.stringify({ session: sessionNum, id: sessionId }));
+  } catch (err) {
+    console.error(chalk.red(`Error: ${err.message}`));
+    process.exit(1);
+  }
+})();

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

@@ -0,0 +1,133 @@
+#!/usr/bin/env node
+
+/**
+ * update_node — Modifies content within an existing node and re-derives metadata.
+ */
+
+import { program } from 'commander';
+import chalk from 'chalk';
+import { readGraph, patchNode } from '../lib/graph.js';
+import { readNode, writeNode, appendToSection, setSection, deriveMetadata } from '../lib/markdown.js';
+import { assertNodeExists } from '../lib/validator.js';
+import { VALID_STATUSES, VALID_PRIORITIES, VALID_FEATURE_KINDS } from '../lib/constants.js';
+import { getKanbanEntry, saveKanbanEntry } from '../lib/kanban.js';
+
+program
+  .argument('<id>', 'Node ID to update')
+  .requiredOption('--project-id <id>', 'Project ID')
+  .option('--set-status <status>', 'Set node status (draft, partially_defined, defined)')
+  .option('--set-priority <priority>', 'Set priority (low, medium, high, blocking)')
+  .option('--add-acceptance-criteria <text>', 'Append an acceptance criterion')
+  .option('--add-open-question <text>', 'Append an open question')
+  .option('--add-note <text>', 'Append a note')
+  .option('--set-section <name=content>', 'Set a section\'s content (name=content format)')
+  .option('--set-description <text>', 'Set the Description section content')
+  .option('--set-kind <kind>', 'Set feature kind (new, improvement, bugfix). Only applies to features.')
+  .option('--set-name <name>', 'Rename the node')
+  .parse();
+
+const id = program.args[0];
+const opts = program.opts();
+
+(async () => {
+  try {
+    await assertNodeExists(id);
+
+    const graph = await readGraph();
+    const nodeMeta = graph.nodes.find(n => n.id === id);
+    let { frontmatter, sections } = await readNode(id);
+
+    if (opts.setStatus) {
+      if (!VALID_STATUSES.includes(opts.setStatus)) {
+        throw new Error(`Invalid status "${opts.setStatus}". Valid: ${VALID_STATUSES.join(', ')}`);
+      }
+      frontmatter.status = opts.setStatus;
+    }
+
+    if (opts.setPriority) {
+      if (!VALID_PRIORITIES.includes(opts.setPriority)) {
+        throw new Error(`Invalid priority "${opts.setPriority}". Valid: ${VALID_PRIORITIES.join(', ')}`);
+      }
+      frontmatter.priority = opts.setPriority;
+    }
+
+    if (opts.setKind) {
+      if (nodeMeta.type !== 'feature') {
+        throw new Error('--set-kind is only valid for feature nodes');
+      }
+      if (!VALID_FEATURE_KINDS.includes(opts.setKind)) {
+        throw new Error(`Invalid kind "${opts.setKind}". Valid: ${VALID_FEATURE_KINDS.join(', ')}`);
+      }
+      frontmatter.kind = opts.setKind;
+    }
+
+    if (opts.setName) {
+      frontmatter.name = opts.setName;
+    }
+
+    if (opts.addAcceptanceCriteria) {
+      appendToSection(sections, 'Acceptance Criteria', `- ${opts.addAcceptanceCriteria}`);
+    }
+
+    if (opts.addOpenQuestion) {
+      appendToSection(sections, 'Open Questions', `- [ ] ${opts.addOpenQuestion}`);
+    }
+
+    if (opts.addNote) {
+      appendToSection(sections, 'Notes', `> ${opts.addNote}`);
+    }
+
+    if (opts.setDescription) {
+      setSection(sections, 'Description', opts.setDescription);
+    }
+
+    if (opts.setSection) {
+      const eqIdx = opts.setSection.indexOf('=');
+      if (eqIdx === -1) {
+        throw new Error('--set-section must be in "SectionName=content" format');
+      }
+      const sectionName = opts.setSection.slice(0, eqIdx);
+      const sectionContent = opts.setSection.slice(eqIdx + 1);
+      setSection(sections, sectionName, sectionContent);
+    }
+
+    frontmatter.updated_at = new Date().toISOString();
+    await writeNode(id, frontmatter, sections);
+
+    // Re-derive metadata and update graph
+    const meta = deriveMetadata(frontmatter, sections, nodeMeta.type);
+    const patch = {
+      status: opts.setStatus || meta.status,
+      completeness: meta.completeness,
+      open_questions_count: meta.open_questions_count,
+    };
+    if (opts.setKind) {
+      patch.kind = opts.setKind;
+    }
+    if (opts.setName) {
+      patch.name = opts.setName;
+    }
+    await patchNode(id, patch);
+
+    // Auto-add feature to kanban when it reaches defined + 100% completeness
+    const finalStatus = opts.setStatus || meta.status;
+    if (nodeMeta.type === 'feature' && finalStatus === 'defined' && meta.completeness >= 1) {
+      const existing = await getKanbanEntry(id);
+      if (!existing) {
+        await saveKanbanEntry(id, { column: 'todo', rejection_count: 0, notes: [] }, opts.projectId);
+        console.log(chalk.green(`✓ Auto-added ${id} to kanban board (todo)`));
+      }
+    }
+
+    console.log(chalk.green(`✓ Updated ${id}`));
+    console.log(JSON.stringify({
+      id,
+      status: opts.setStatus || meta.status,
+      completeness: meta.completeness,
+      open_questions_count: meta.open_questions_count,
+    }));
+  } catch (err) {
+    console.error(chalk.red(`Error: ${err.message}`));
+    process.exit(1);
+  }
+})();

package/templates/product-system/packages/shared/tsconfig.json

@@ -0,0 +1,24 @@
+{
+  "compilerOptions": {
+    "strict": false,
+    "allowJs": true,
+    "module": "NodeNext",
+    "moduleResolution": "NodeNext",
+    "target": "ESNext",
+    "esModuleInterop": true,
+    "skipLibCheck": true,
+    "forceConsistentCasingInFileNames": true,
+    "outDir": "build",
+    "rootDir": ".",
+    "sourceMap": true,
+    "declaration": true
+  },
+  "include": [
+    "lib/**/*.ts",
+    "tools/**/*.ts",
+    "db/**/*.ts"
+  ],
+  "exclude": [
+    "node_modules"
+  ]
+}

package/templates/product-system/pnpm-workspace.yaml

@@ -0,0 +1,2 @@
+packages:
+  - 'packages/*'