@assistkick/create 1.2.0 → 1.4.0

package/templates/assistkick-product-system/packages/shared/lib/pipeline_orchestrator.ts

@@ -0,0 +1,186 @@
+/**
+ * PipelineOrchestrator — runs the Play All loop server-side.
+ * Iterates through TODO features sequentially, respecting dependency ordering.
+ * Continues across browser sessions. On server restart, does NOT auto-resume.
+ */
+
+export class PipelineOrchestrator {
+  private pipeline: any;
+  private loadKanban: (projectId?: string) => Promise<any>;
+  private readGraph: (projectId?: string) => Promise<any>;
+  private log: (tag: string, ...args: any[]) => void;
+
+  private active = false;
+  private aborted = false;
+  private currentFeatureId: string | null = null;
+  private projectId: string | null = null;
+  private processedCount = 0;
+  private skippedFeatures: string[] = [];
+
+  constructor({ pipeline, loadKanban, readGraph, log }: {
+    pipeline: any;
+    loadKanban: (projectId?: string) => Promise<any>;
+    readGraph: (projectId?: string) => Promise<any>;
+    log: (tag: string, ...args: any[]) => void;
+  }) {
+    this.pipeline = pipeline;
+    this.loadKanban = loadKanban;
+    this.readGraph = readGraph;
+    this.log = log;
+  }
+
+  startPlayAll = async (projectId?: string) => {
+    if (this.active) {
+      return { error: 'Play All is already running', status: 409 };
+    }
+
+    this.active = true;
+    this.aborted = false;
+    this.currentFeatureId = null;
+    this.projectId = projectId || null;
+    this.processedCount = 0;
+    this.skippedFeatures = [];
+
+    this.log('ORCHESTRATOR', `Play All started${projectId ? ` for project ${projectId}` : ''}`);
+
+    // Fire-and-forget — loop runs in the background
+    this.runLoop().catch(err => {
+      this.log('ORCHESTRATOR', `Play All UNCAUGHT ERROR: ${err.message}`);
+    }).finally(() => {
+      this.active = false;
+      this.currentFeatureId = null;
+      this.log('ORCHESTRATOR', `Play All ended. Processed ${this.processedCount} features.`);
+    });
+
+    return { started: true, status: 200 };
+  };
+
+  stopPlayAll = () => {
+    if (!this.active) {
+      return { error: 'Play All is not running', status: 400 };
+    }
+    this.aborted = true;
+    this.log('ORCHESTRATOR', 'Play All stop requested');
+    return { stopped: true, status: 200 };
+  };
+
+  getStatus = () => {
+    return {
+      active: this.active,
+      currentFeatureId: this.currentFeatureId,
+      projectId: this.projectId,
+      processedCount: this.processedCount,
+      skippedFeatures: this.skippedFeatures,
+    };
+  };
+
+  private runLoop = async () => {
+    while (!this.aborted) {
+      // Fetch fresh kanban and graph data each iteration
+      let kanbanData: any;
+      let graphData: any;
+      try {
+        kanbanData = await this.loadKanban(this.projectId || undefined);
+        graphData = await this.readGraph(this.projectId || undefined);
+      } catch (err: any) {
+        this.log('ORCHESTRATOR', `Failed to fetch data: ${err.message}`);
+        break;
+      }
+
+      // Build feature node lookup
+      const featureNodes = new Map<string, any>();
+      graphData.nodes
+        .filter((n: any) => n.type === 'feature')
+        .forEach((n: any) => featureNodes.set(n.id, n));
+
+      // Get TODO cards that aren't dev_blocked, sorted by completeness (highest first)
+      const todoCards = Object.entries(kanbanData)
+        .filter(([id, entry]: [string, any]) =>
+          entry.column === 'todo' && featureNodes.has(id) && !entry.dev_blocked
+        )
+        .map(([id]: [string, any]) => ({
+          id,
+          completeness: featureNodes.get(id).completeness || 0,
+        }))
+        .sort((a, b) => b.completeness - a.completeness);
+
+      if (todoCards.length === 0) {
+        this.log('ORCHESTRATOR', 'No TODO cards remaining — stopping');
+        break;
+      }
+
+      // Try to find an unblocked card
+      let processed = false;
+      this.skippedFeatures = [];
+
+      for (const card of todoCards) {
+        if (this.aborted) return;
+
+        // Check dependency ordering
+        const deps = graphData.edges
+          .filter((e: any) => e.from === card.id && e.relation === 'depends_on')
+          .map((e: any) => e.to)
+          .filter((depId: string) => graphData.nodes.some((n: any) => n.id === depId && n.type === 'feature'));
+        const blocked = deps.some((depId: string) =>
+          !kanbanData[depId] || kanbanData[depId].column !== 'done'
+        );
+
+        if (blocked) {
+          this.skippedFeatures.push(card.id);
+          continue;
+        }
+
+        // Start pipeline for this card
+        this.currentFeatureId = card.id;
+        this.log('ORCHESTRATOR', `Starting pipeline for ${card.id}`);
+
+        try {
+          const result = await this.pipeline.start(card.id);
+          if (result.error) {
+            this.log('ORCHESTRATOR', `Failed to start pipeline for ${card.id}: ${result.error}`);
+            // Try the next card if this one failed to start
+            continue;
+          }
+        } catch (err: any) {
+          this.log('ORCHESTRATOR', `Failed to start pipeline for ${card.id}: ${err.message}`);
+          continue;
+        }
+
+        // Wait for pipeline to reach a terminal status
+        await this.waitForPipelineCompletion(card.id);
+
+        if (this.aborted) return;
+
+        this.processedCount++;
+        processed = true;
+        break; // Process one card per iteration, then re-fetch data
+      }
+
+      // Deadlock: a full pass with zero features processable
+      if (!processed) {
+        this.log('ORCHESTRATOR', `Deadlock detected — ${this.skippedFeatures.length} features blocked: ${this.skippedFeatures.join(', ')}`);
+        break;
+      }
+    }
+  };
+
+  private waitForPipelineCompletion = async (featureId: string): Promise<void> => {
+    const TERMINAL_STATUSES = ['idle', 'completed', 'blocked', 'failed', 'interrupted'];
+    const POLL_INTERVAL_MS = 5000;
+
+    while (!this.aborted) {
+      try {
+        const status = await this.pipeline.getStatus(featureId);
+        if (TERMINAL_STATUSES.includes(status.status)) {
+          this.log('ORCHESTRATOR', `Pipeline for ${featureId} reached terminal status: ${status.status}`);
+          return;
+        }
+      } catch (err: any) {
+        this.log('ORCHESTRATOR', `Error polling status for ${featureId}: ${err.message}`);
+        return;
+      }
+
+      await new Promise(resolve => setTimeout(resolve, POLL_INTERVAL_MS));
+    }
+  };
+}

package/templates/assistkick-product-system/packages/shared/lib/session.ts

@@ -22,7 +22,7 @@ export const getNextSessionNumber = async (projectId?: string) => {
 /**
  * Create a new session record.
  */
-export const createSession = async (sessionNum, body, projectId?: string) => {
+export const createSession = async (sessionNum, body, projectId: string) => {
   const db = getDb();
   const now = new Date().toISOString();
 
@@ -34,7 +34,7 @@ export const createSession = async (sessionNum, body, projectId?: string) => {
     nodesTouched: '[]',
     questionsResolved: 0,
     body: body || '',
-    projectId: projectId || null,
+    projectId,
   });
 
   return { session: sessionNum, started_at: now };
@@ -55,7 +55,7 @@ export const getLatestSession = async (projectId?: string) => {
 /**
  * Update/end a session with summary and metadata.
  */
-export const endSession = async (sessionNum, updates) => {
+export const endSession = async (sessionNum, updates, projectId: string) => {
   const db = getDb();
 
   const updateFields = {};
@@ -65,15 +65,19 @@ export const endSession = async (sessionNum, updates) => {
   if (updates.questions_resolved !== undefined) updateFields.questionsResolved = updates.questions_resolved;
   if (updates.body !== undefined) updateFields.body = updates.body;
 
-  await db.update(sessions).set(updateFields).where(eq(sessions.sessionNumber, sessionNum));
+  await db.update(sessions).set(updateFields).where(
+    and(eq(sessions.sessionNumber, sessionNum), eq(sessions.projectId, projectId))
+  );
 };
 
 /**
  * Get a session by number.
  */
-export const getSession = async (sessionNum) => {
+export const getSession = async (sessionNum, projectId: string) => {
   const db = getDb();
-  const rows = await db.select().from(sessions).where(eq(sessions.sessionNumber, sessionNum));
+  const rows = await db.select().from(sessions).where(
+    and(eq(sessions.sessionNumber, sessionNum), eq(sessions.projectId, projectId))
+  );
   return rows[0];
 };
 

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

@@ -0,0 +1,275 @@
+#!/usr/bin/env node
+
+/**
+ * db_explorer — Read-only database explorer for AI assistants.
+ * Provides safe, read-only access to inspect database tables, schemas, and data.
+ * Absolutely NO write capabilities — only SELECT, PRAGMA, and EXPLAIN queries allowed.
+ * Sensitive columns (password_hash, token_hash) are automatically redacted.
+ *
+ * Usage:
+ *   npx tsx tools/db_explorer.ts tables
+ *   npx tsx tools/db_explorer.ts describe <table>
+ *   npx tsx tools/db_explorer.ts count <table> [--where "..."]
+ *   npx tsx tools/db_explorer.ts sample <table> [--limit N] [--where "..."] [--order-by <col>]
+ *   npx tsx tools/db_explorer.ts query "SELECT ..."
+ *
+ * Note: --project-id is optional. Use --where "project_id = '...'" to filter by project.
+ */
+
+import { program } from 'commander';
+import chalk from 'chalk';
+import { createClient } from '@libsql/client';
+import { config } from 'dotenv';
+import { dirname, join } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { existsSync } from 'node:fs';
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+let PROJECT_ROOT = join(__dirname, '..');
+while (PROJECT_ROOT !== dirname(PROJECT_ROOT)) {
+  if (existsSync(join(PROJECT_ROOT, 'pnpm-workspace.yaml'))) break;
+  PROJECT_ROOT = dirname(PROJECT_ROOT);
+}
+const ENV_PATH = join(PROJECT_ROOT, '.env');
+
+const SENSITIVE_COLUMNS = ['password_hash', 'token_hash'];
+
+function getClient() {
+  if (existsSync(ENV_PATH)) {
+    config({ path: ENV_PATH, quiet: true });
+  }
+
+  const tursoUrl = process.env.TURSO_DATABASE_URL;
+  const tursoAuthToken = process.env.TURSO_AUTH_TOKEN;
+
+  if (tursoUrl && tursoAuthToken) {
+    return createClient({ url: tursoUrl, authToken: tursoAuthToken });
+  }
+
+  const dataDir = join(PROJECT_ROOT, 'data');
+  return createClient({ url: `file:${join(dataDir, 'local.db')}` });
+}
+
+/**
+ * Validates that a SQL query is strictly read-only.
+ * Returns true only for SELECT, PRAGMA, and EXPLAIN queries.
+ */
+function isReadOnly(query: string): boolean {
+  // Strip SQL comments
+  let cleaned = query
+    .replace(/--[^\n]*/g, '')
+    .replace(/\/\*[\s\S]*?\*\//g, '')
+    .trim();
+
+  // Remove trailing semicolon
+  cleaned = cleaned.replace(/;\s*$/, '');
+
+  // Strip string literals to avoid false positives
+  const noStrings = cleaned.replace(/'[^']*'/g, "''").replace(/"[^"]*"/g, '""');
+
+  // No multiple statements
+  if (noStrings.includes(';')) return false;
+
+  const upper = noStrings.toUpperCase().replace(/\s+/g, ' ');
+
+  // Must start with SELECT, PRAGMA, or EXPLAIN
+  if (!/^(SELECT|PRAGMA|EXPLAIN)\b/.test(upper)) return false;
+
+  // Block write/DDL/dangerous keywords
+  if (/\b(INSERT|UPDATE|DELETE|DROP|ALTER|CREATE|REPLACE|ATTACH|DETACH|VACUUM|REINDEX|GRANT|REVOKE|LOAD_EXTENSION)\b/.test(upper)) {
+    return false;
+  }
+
+  return true;
+}
+
+function redactRows(rows: Record<string, unknown>[], columns: string[]): Record<string, unknown>[] {
+  const hasSensitive = columns.some(c => SENSITIVE_COLUMNS.includes(c.toLowerCase()));
+  if (!hasSensitive) return rows;
+
+  return rows.map(row => {
+    const copy = { ...row };
+    for (const col of SENSITIVE_COLUMNS) {
+      if (col in copy) copy[col] = '[REDACTED]';
+    }
+    return copy;
+  });
+}
+
+function printRows(rows: Record<string, unknown>[], columns: string[]) {
+  if (rows.length === 0) {
+    console.log(chalk.yellow('  (no rows)'));
+    return;
+  }
+  for (const row of rows) {
+    console.log(chalk.gray('  ─────────'));
+    for (const col of columns) {
+      const val = row[col];
+      const display = val === null
+        ? chalk.gray('NULL')
+        : typeof val === 'string' && val.length > 200
+          ? val.substring(0, 200) + '...'
+          : String(val);
+      console.log(`  ${chalk.bold(col)}: ${display}`);
+    }
+  }
+}
+
+function sanitizeTableName(name: string): string {
+  return name.replace(/[^a-zA-Z0-9_]/g, '');
+}
+
+program
+  .argument('<action>', 'Action: tables, describe, count, sample, query')
+  .argument('[target]', 'Table name or SQL query (for query action)')
+  .option('--project-id <id>', 'Project ID (optional — use --where to filter by project)')
+  .option('--limit <n>', 'Row limit for sample action', '10')
+  .option('--where <condition>', 'WHERE clause for count/sample')
+  .option('--order-by <column>', 'ORDER BY clause for sample')
+  .parse();
+
+const [action, target] = program.args;
+const opts = program.opts();
+
+(async () => {
+  const client = getClient();
+
+  try {
+    switch (action) {
+      case 'tables': {
+        const result = await client.execute(
+          "SELECT name FROM sqlite_master WHERE type='table' AND name NOT LIKE 'sqlite_%' AND name NOT LIKE '__drizzle_%' AND name NOT LIKE '_litestream_%' ORDER BY name"
+        );
+        const tableNames = result.rows.map(r => r.name as string);
+
+        console.log(chalk.cyan.bold('Database Tables:\n'));
+        for (const t of tableNames) {
+          const countResult = await client.execute(`SELECT COUNT(*) as cnt FROM "${t}"`);
+          const cnt = countResult.rows[0]?.cnt ?? 0;
+          console.log(`  ${chalk.bold(t)} (${cnt} rows)`);
+        }
+        console.log('\n' + JSON.stringify({ tables: tableNames }));
+        break;
+      }
+
+      case 'describe': {
+        if (!target) throw new Error('Usage: db_explorer describe <table_name>');
+        const table = sanitizeTableName(target);
+
+        const result = await client.execute(`PRAGMA table_info("${table}")`);
+        if (result.rows.length === 0) throw new Error(`Table not found: ${target}`);
+
+        console.log(chalk.cyan.bold(`\nTable: ${table}\n`));
+        console.log(chalk.gray('  #  Name                     Type        Nullable  Default       PK'));
+        console.log(chalk.gray('  ' + '─'.repeat(75)));
+
+        for (const col of result.rows) {
+          const nullable = col.notnull ? 'NOT NULL' : 'NULL    ';
+          const pk = col.pk ? chalk.yellow('PK') : '  ';
+          const def = col.dflt_value !== null ? String(col.dflt_value) : '';
+          console.log(`  ${String(col.cid).padEnd(3)} ${chalk.bold(String(col.name).padEnd(25))} ${String(col.type).padEnd(12)} ${nullable}  ${def.padEnd(14)} ${pk}`);
+        }
+
+        const idxResult = await client.execute(`PRAGMA index_list("${table}")`);
+        if (idxResult.rows.length > 0) {
+          console.log(chalk.cyan.bold('\n  Indexes:'));
+          for (const idx of idxResult.rows) {
+            const unique = idx.unique ? chalk.yellow(' UNIQUE') : '';
+            const idxName = sanitizeTableName(String(idx.name));
+            const idxInfoResult = await client.execute(`PRAGMA index_info("${idxName}")`);
+            const cols = idxInfoResult.rows.map(r => r.name).join(', ');
+            console.log(`    ${idx.name}${unique} (${cols})`);
+          }
+        }
+
+        const fkResult = await client.execute(`PRAGMA foreign_key_list("${table}")`);
+        if (fkResult.rows.length > 0) {
+          console.log(chalk.cyan.bold('\n  Foreign Keys:'));
+          for (const fk of fkResult.rows) {
+            console.log(`    ${fk.from} -> ${fk.table}.${fk.to}`);
+          }
+        }
+
+        console.log('\n' + JSON.stringify({
+          table,
+          columns: result.rows.map(c => ({
+            name: c.name, type: c.type, nullable: !c.notnull,
+            default: c.dflt_value, pk: !!c.pk,
+          })),
+        }));
+        break;
+      }
+
+      case 'count': {
+        if (!target) throw new Error('Usage: db_explorer count <table_name>');
+        const table = sanitizeTableName(target);
+        let query = `SELECT COUNT(*) as cnt FROM "${table}"`;
+        if (opts.where) query += ` WHERE ${opts.where}`;
+
+        if (!isReadOnly(query)) throw new Error('Query validation failed — only read-only queries are allowed');
+
+        const result = await client.execute(query);
+        const count = result.rows[0]?.cnt ?? 0;
+        console.log(chalk.cyan(`Row count for ${chalk.bold(table)}: ${chalk.green(String(count))}`));
+        console.log(JSON.stringify({ table, count }));
+        break;
+      }
+
+      case 'sample': {
+        if (!target) throw new Error('Usage: db_explorer sample <table_name> [--limit N] [--where "..."]');
+        const table = sanitizeTableName(target);
+        const limit = parseInt(opts.limit) || 10;
+
+        let query = `SELECT * FROM "${table}"`;
+        if (opts.where) query += ` WHERE ${opts.where}`;
+        if (opts.orderBy) query += ` ORDER BY ${opts.orderBy}`;
+        query += ` LIMIT ${limit}`;
+
+        if (!isReadOnly(query)) throw new Error('Query validation failed — only read-only queries are allowed');
+
+        const result = await client.execute(query);
+        const columns = result.columns.length > 0
+          ? result.columns
+          : result.rows.length > 0 ? Object.keys(result.rows[0]) : [];
+        const rows = redactRows(result.rows as Record<string, unknown>[], columns);
+
+        console.log(chalk.cyan.bold(`\nSample from ${table} (${rows.length} rows):\n`));
+        printRows(rows, columns);
+        console.log('\n' + JSON.stringify({ table, count: rows.length, columns, rows }));
+        break;
+      }
+
+      case 'query': {
+        if (!target) throw new Error('Usage: db_explorer query "SELECT ..."');
+        if (!isReadOnly(target)) {
+          throw new Error('Only read-only queries are allowed (SELECT, PRAGMA, EXPLAIN). Write operations are blocked.');
+        }
+
+        // Add safety limit if none specified
+        const upper = target.toUpperCase();
+        const query = upper.startsWith('SELECT') && !upper.includes('LIMIT')
+          ? `${target} LIMIT 100`
+          : target;
+
+        const result = await client.execute(query);
+        const columns = result.columns.length > 0
+          ? result.columns
+          : result.rows.length > 0 ? Object.keys(result.rows[0]) : [];
+        const rows = redactRows(result.rows as Record<string, unknown>[], columns);
+
+        console.log(chalk.cyan(`\nQuery returned ${rows.length} row(s):\n`));
+        printRows(rows, columns);
+        console.log('\n' + JSON.stringify({ count: rows.length, columns, rows }));
+        break;
+      }
+
+      default:
+        throw new Error(`Unknown action "${action}". Valid actions: tables, describe, count, sample, query`);
+    }
+  } catch (err) {
+    console.error(chalk.red(`Error: ${(err as Error).message}`));
+    process.exit(1);
+  } finally {
+    client.close();
+  }
+})();

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

@@ -36,7 +36,7 @@ const opts = program.opts();
     }
 
     // Add gap analysis
-    const graph = await readGraph();
+    const graph = await readGraph(opts.projectId);
     const graphNodes = graph.nodes;
     const totalNodes = graphNodes.length;
     const avgCompleteness = totalNodes > 0
@@ -74,7 +74,7 @@ const opts = program.opts();
       nodes_touched: opts.nodesTouched ? opts.nodesTouched.split(',').map(s => s.trim()) : [],
       questions_resolved: opts.questionsResolved,
       body: updatedBody,
-    });
+    }, opts.projectId);
 
     console.log(chalk.green(`✓ Session ${session.sessionNumber} ended`));
     console.log(`Nodes: ${totalNodes} — ${Math.round(avgCompleteness * 100)}% complete`);

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

@@ -14,9 +14,10 @@ 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 VALID_COLUMNS = ['backlog', 'todo', 'in_progress', 'in_review', 'qa', 'done'];
 
 const COLUMN_COLORS = {
+  backlog: chalk.dim,
   todo: chalk.gray,
   in_progress: chalk.blue,
   in_review: chalk.magenta,

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

@@ -25,11 +25,12 @@ 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'];
+const VALID_COLUMNS = ['backlog', 'todo', 'in_progress', 'in_review', 'qa', 'done'];
 
 // AI-allowed transitions (via CLI)
 const ALLOWED_TRANSITIONS = {
-  'todo': ['in_progress'],
+  'backlog': ['todo'],
+  'todo': ['in_progress', 'backlog'],
   'in_progress': ['in_review'],
   'in_review': ['qa', 'todo'],
   'qa': ['todo'],

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

@@ -114,8 +114,8 @@ const opts = program.opts();
     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)`));
+        await saveKanbanEntry(id, { column: 'backlog', rejection_count: 0, notes: [] }, opts.projectId);
+        console.log(chalk.green(`✓ Auto-added ${id} to kanban board (backlog)`));
       }
     }
 

package/templates/assistkick-product-system/tests/kanban.test.ts

@@ -12,7 +12,7 @@ import { randomUUID } from 'node:crypto';
 const __dirname = dirname(fileURLToPath(import.meta.url));
 
 // Valid kanban columns — users can move cards between any columns (mirrors server logic)
-const VALID_COLUMNS = ['todo', 'in_progress', 'in_review', 'qa', 'done'];
+const VALID_COLUMNS = ['backlog', 'todo', 'in_progress', 'in_review', 'qa', 'done'];
 
 // In-memory kanban data used by the test server
 let kanbanData;

package/templates/assistkick-product-system/tests/pipeline_stats_all_cards.test.ts

@@ -96,7 +96,7 @@ describe('Pipeline stats on all kanban cards', () => {
   });
 
   describe('shouldShowStats — stats visibility for all columns', () => {
-    const columns = ['todo', 'in_progress', 'in_review', 'qa', 'done'];
+    const columns = ['backlog', 'todo', 'in_progress', 'in_review', 'qa', 'done'];
 
     for (const column of columns) {
       it(`shows stats for ${column} card with completed pipeline`, () => {