@vpxa/aikit 0.1.1

package/scaffold/general/skills/session-handoff/scripts/list_handoffs.js

@@ -0,0 +1,113 @@
+#!/usr/bin/env node
+/**
+ * List available handoff documents in the current project.
+ *
+ * Searches for handoff documents in .handoffs/ and displays:
+ * - Filename with date
+ * - Title extracted from document
+ * - Status (complete / in progress / needs work)
+ *
+ * Usage:
+ *   node list_handoffs.js           # List handoffs in current project
+ *   node list_handoffs.js /path     # List handoffs in specified path
+ */
+
+const fs = require('node:fs');
+const path = require('node:path');
+
+function extractTitle(filepath) {
+  try {
+    const content = fs.readFileSync(filepath, 'utf-8');
+    const m = content.match(/^#\s+(?:Handoff:\s*)?(.+)$/m);
+    if (m) {
+      const title = m[1].trim();
+      if (title.startsWith('[') && title.endsWith(']')) return '[Untitled - needs completion]';
+      return title.length > 50 ? `${title.slice(0, 50)}...` : title;
+    }
+  } catch {
+    /* ignore */
+  }
+  return '[Unable to read title]';
+}
+
+function checkCompletion(filepath) {
+  try {
+    const content = fs.readFileSync(filepath, 'utf-8');
+    const count = (content.match(/\[TODO:/g) || []).length;
+    if (count === 0) return 'Complete';
+    if (count <= 3) return `In Progress (${count} TODOs)`;
+    return `Needs Work (${count} TODOs)`;
+  } catch {
+    return 'Unknown';
+  }
+}
+
+function parseDateFromFilename(filename) {
+  const m = filename.match(/^(\d{4}-\d{2}-\d{2})-(\d{6})/);
+  if (m) {
+    try {
+      return new Date(`${m[1]}T${m[2].slice(0, 2)}:${m[2].slice(2, 4)}:${m[2].slice(4, 6)}`);
+    } catch {
+      /* ignore */
+    }
+  }
+  return null;
+}
+
+function listHandoffs(projectPath) {
+  const dir = path.join(projectPath, '.handoffs');
+  if (!fs.existsSync(dir)) return [];
+
+  const handoffs = [];
+  for (const name of fs.readdirSync(dir)) {
+    if (!name.endsWith('.md')) continue;
+    const fp = path.join(dir, name);
+    const stat = fs.statSync(fp);
+
+    handoffs.push({
+      path: fp,
+      filename: name,
+      title: extractTitle(fp),
+      status: checkCompletion(fp),
+      date: parseDateFromFilename(name),
+      size: stat.size,
+    });
+  }
+
+  handoffs.sort((a, b) => (b.date || 0) - (a.date || 0));
+  return handoffs;
+}
+
+function formatDate(dt) {
+  if (!dt) return 'Unknown date';
+  return dt.toISOString().replace('T', ' ').slice(0, 16);
+}
+
+// --- Main ---
+const args = process.argv.slice(2);
+if (args.includes('--help') || args.includes('-h')) {
+  console.log('Usage: node list_handoffs.js [project-path]');
+  process.exit(0);
+}
+
+const projectPath = args[0] || process.cwd();
+const handoffs = listHandoffs(projectPath);
+
+if (handoffs.length === 0) {
+  console.log('No handoff documents found.');
+  console.log(`Looked in: ${path.join(projectPath, '.handoffs')}`);
+  console.log('\nCreate one with: node scripts/create_handoff.js [task-slug]');
+  process.exit(0);
+}
+
+console.log(`\nFound ${handoffs.length} handoff(s) in ${projectPath}:\n`);
+console.log(`${'Date'.padEnd(18)} ${'Status'.padEnd(25)} Title`);
+console.log(`${'-'.repeat(18)} ${'-'.repeat(25)} ${'-'.repeat(40)}`);
+
+for (const h of handoffs) {
+  console.log(`${formatDate(h.date).padEnd(18)} ${h.status.padEnd(25)} ${h.title}`);
+}
+
+if (args.includes('--json')) {
+  console.log(`\n${JSON.stringify(handoffs, null, 2)}`);
+}

package/scaffold/general/skills/session-handoff/scripts/validate_handoff.js

@@ -0,0 +1,241 @@
+#!/usr/bin/env node
+/**
+ * Validate a handoff document for completeness and quality.
+ *
+ * Checks:
+ * - No TODO placeholders remaining
+ * - Required sections present and populated
+ * - No potential secrets detected
+ * - Referenced files exist
+ * - Quality scoring (0-100)
+ *
+ * Usage:
+ *   node validate_handoff.js <handoff-file>
+ *   node validate_handoff.js .handoffs/2024-01-15-143022-auth.md
+ */
+
+const fs = require('node:fs');
+const path = require('node:path');
+
+// Secret detection patterns
+const SECRET_PATTERNS = [
+  [/["']?[a-zA-Z_]*api[_-]?key["']?\s*[:=]\s*["'][^"']{10,}["']/gi, 'API key'],
+  [/["']?[a-zA-Z_]*password["']?\s*[:=]\s*["'][^"']+["']/gi, 'Password'],
+  [/["']?[a-zA-Z_]*secret["']?\s*[:=]\s*["'][^"']{10,}["']/gi, 'Secret'],
+  [/["']?[a-zA-Z_]*token["']?\s*[:=]\s*["'][^"']{20,}["']/gi, 'Token'],
+  [/["']?[a-zA-Z_]*private[_-]?key["']?\s*[:=]/gi, 'Private key'],
+  [/-----BEGIN [A-Z]+ PRIVATE KEY-----/g, 'PEM private key'],
+  [/mongodb(\+srv)?:\/\/[^/\s]+:[^@\s]+@/gi, 'MongoDB connection string with password'],
+  [/postgres:\/\/[^/\s]+:[^@\s]+@/gi, 'PostgreSQL connection string with password'],
+  [/mysql:\/\/[^/\s]+:[^@\s]+@/gi, 'MySQL connection string with password'],
+  [/Bearer\s+[a-zA-Z0-9_\-.]+/g, 'Bearer token'],
+  [/ghp_[a-zA-Z0-9]{36}/g, 'GitHub personal access token'],
+  [/sk-[a-zA-Z0-9]{48}/g, 'OpenAI API key'],
+  [/xox[baprs]-[a-zA-Z0-9-]+/g, 'Slack token'],
+];
+
+const REQUIRED_SECTIONS = ['Current State Summary', 'Important Context', 'Immediate Next Steps'];
+const RECOMMENDED_SECTIONS = [
+  'Architecture Overview',
+  'Critical Files',
+  'Files Modified',
+  'Decisions Made',
+  'Assumptions Made',
+  'Potential Gotchas',
+];
+
+function checkTodos(content) {
+  const todos = content.match(/\[TODO:[^\]]*\]/g) || [];
+  return { clear: todos.length === 0, todos };
+}
+
+function checkRequiredSections(content) {
+  const missing = [];
+  for (const section of REQUIRED_SECTIONS) {
+    const pattern = new RegExp(
+      `(?:^|\\n)##?\\s*${section.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')}`,
+      'i',
+    );
+    const match = pattern.exec(content);
+    if (!match) {
+      missing.push(`${section} (missing)`);
+    } else {
+      const start = match.index + match[0].length;
+      const nextSection = content.slice(start).search(/\n##?\s+/);
+      const end = nextSection >= 0 ? start + nextSection : content.length;
+      const sectionContent = content.slice(start, end).trim();
+      if (sectionContent.length < 50 || sectionContent.includes('[TODO')) {
+        missing.push(`${section} (incomplete)`);
+      }
+    }
+  }
+  return { complete: missing.length === 0, missing };
+}
+
+function checkRecommendedSections(content) {
+  const missing = [];
+  for (const section of RECOMMENDED_SECTIONS) {
+    const pattern = new RegExp(
+      `(?:^|\\n)##?\\s*${section.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')}`,
+      'i',
+    );
+    if (!pattern.test(content)) missing.push(section);
+  }
+  return missing;
+}
+
+function scanForSecrets(content) {
+  const findings = [];
+  for (const [pattern, description] of SECRET_PATTERNS) {
+    const matches = content.match(pattern);
+    if (matches) findings.push({ description, count: matches.length });
+  }
+  return findings;
+}
+
+function checkFileReferences(content, basePath) {
+  const patterns = [
+    /\|\s*([a-zA-Z0-9_\-./]+\.[a-zA-Z]+)\s*\|/g,
+    /`([a-zA-Z0-9_\-./]+\.[a-zA-Z]+(?::\d+)?)`/g,
+    /(?:^|\s)([a-zA-Z0-9_\-./]+\.[a-zA-Z]+:\d+)/gm,
+  ];
+
+  const foundFiles = new Set();
+  for (const pattern of patterns) {
+    for (const m of content.matchAll(pattern)) {
+      const filepath = m[1].split(':')[0];
+      if (filepath && !filepath.startsWith('http') && filepath.includes('/')) {
+        foundFiles.add(filepath);
+      }
+    }
+  }
+
+  const existing = [];
+  const missing = [];
+  for (const f of foundFiles) {
+    if (fs.existsSync(path.join(basePath, f))) existing.push(f);
+    else missing.push(f);
+  }
+  return { existing, missing };
+}
+
+function calculateScore(todosClear, reqComplete, missingReq, missingRec, secrets, filesMissing) {
+  let score = 100;
+
+  if (!todosClear) score -= 30;
+  if (!reqComplete) score -= 10 * missingReq.length;
+  if (secrets.length > 0) score -= 20;
+  if (filesMissing.length > 0) score -= 5 * Math.min(filesMissing.length, 4);
+  score -= 2 * missingRec.length;
+
+  score = Math.max(0, score);
+
+  let rating;
+  if (score >= 90) rating = 'Excellent - Ready for handoff';
+  else if (score >= 70) rating = 'Good - Minor improvements suggested';
+  else if (score >= 50) rating = 'Fair - Needs attention before handoff';
+  else rating = 'Poor - Significant work needed';
+
+  return { score, rating };
+}
+
+function validateHandoff(filepath) {
+  if (!fs.existsSync(filepath)) return { error: `File not found: ${filepath}` };
+
+  const content = fs.readFileSync(filepath, 'utf-8');
+  const basePath = path.resolve(path.dirname(filepath), '..'); // Up from .handoffs/
+
+  const { clear: todosClear, todos } = checkTodos(content);
+  const { complete: reqComplete, missing: missingReq } = checkRequiredSections(content);
+  const missingRec = checkRecommendedSections(content);
+  const secrets = scanForSecrets(content);
+  const { existing: existingFiles, missing: missingFiles } = checkFileReferences(content, basePath);
+
+  const { score, rating } = calculateScore(
+    todosClear,
+    reqComplete,
+    missingReq,
+    missingRec,
+    secrets,
+    missingFiles,
+  );
+
+  return {
+    filepath,
+    score,
+    rating,
+    todosClear,
+    remainingTodos: todos.slice(0, 5),
+    todoCount: todos.length,
+    requiredComplete: reqComplete,
+    missingRequired: missingReq,
+    missingRecommended: missingRec,
+    secretsFound: secrets,
+    filesVerified: existingFiles.length,
+    filesMissing: missingFiles.slice(0, 5),
+  };
+}
+
+function printReport(result) {
+  if (result.error) {
+    console.log(`Error: ${result.error}`);
+    return;
+  }
+
+  console.log(`\n${'='.repeat(60)}`);
+  console.log('Handoff Validation Report');
+  console.log('='.repeat(60));
+  console.log(`File: ${result.filepath}`);
+  console.log(`\nQuality Score: ${result.score}/100 - ${result.rating}`);
+  console.log('='.repeat(60));
+
+  if (result.todosClear) {
+    console.log('\n[PASS] No TODO placeholders remaining');
+  } else {
+    console.log(`\n[FAIL] ${result.todoCount} TODO placeholders found:`);
+    for (const t of result.remainingTodos) console.log(`       - ${t.slice(0, 50)}...`);
+  }
+
+  if (result.requiredComplete) {
+    console.log('\n[PASS] All required sections complete');
+  } else {
+    console.log('\n[FAIL] Missing/incomplete required sections:');
+    for (const s of result.missingRequired) console.log(`       - ${s}`);
+  }
+
+  if (result.secretsFound.length === 0) {
+    console.log('\n[PASS] No potential secrets detected');
+  } else {
+    console.log('\n[WARN] Potential secrets detected:');
+    for (const s of result.secretsFound)
+      console.log(`       - ${s.description} (${s.count} match(es))`);
+  }
+
+  console.log(
+    `\n[INFO] File references: ${result.filesVerified} verified, ${result.filesMissing.length} missing`,
+  );
+  if (result.filesMissing.length > 0) {
+    for (const f of result.filesMissing) console.log(`       - ${f}`);
+  }
+
+  if (result.missingRecommended.length > 0) {
+    console.log('\n[INFO] Missing recommended sections:');
+    for (const s of result.missingRecommended) console.log(`       - ${s}`);
+  }
+}
+
+// --- Main ---
+const args = process.argv.slice(2);
+if (args.includes('--help') || args.includes('-h') || args.length === 0) {
+  console.log('Usage: node validate_handoff.js <handoff-file>');
+  console.log('       node validate_handoff.js .handoffs/2024-01-15-143022-auth.md');
+  process.exit(args.length === 0 ? 1 : 0);
+}
+
+if (args.includes('--json')) {
+  const result = validateHandoff(args.find((a) => !a.startsWith('-')));
+  console.log(JSON.stringify(result, null, 2));
+} else {
+  const result = validateHandoff(args[0]);
+  printReport(result);
+}

package/scaffold/generate.mjs

@@ -0,0 +1,82 @@
+#!/usr/bin/env node
+/**
+ * Scaffold generator — reads definitions, picks adapter, writes files.
+ *
+ * Usage:
+ *   node scaffold/generate.mjs                  # Default: all adapters
+ *   node scaffold/generate.mjs --ide copilot    # Copilot only
+ *   node scaffold/generate.mjs --ide claude-code # Claude Code only [stub]
+ *
+ * Architecture:
+ *   definitions/  — IDE-agnostic data (agents, models, tools, prompts, hooks, plugins)
+ *   adapters/     — IDE-specific generators (copilot, claude-code)
+ *   general/      — Output directory (agents, prompts, skills) — `aikit init` copies from here
+ *
+ * The copilot adapter writes directly to general/ since all IDEs currently
+ * consume the same VS Code-format .agent.md files. When a future adapter
+ * needs a different format, it gets its own output directory.
+ */
+
+import { existsSync, mkdirSync, rmSync, writeFileSync } from 'node:fs';
+import { dirname, resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { generateClaudeCode } from './adapters/claude-code.mjs';
+import { generateCopilot } from './adapters/copilot.mjs';
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+
+const ADAPTERS = {
+  copilot: { generate: generateCopilot, outDir: 'general' },
+  'claude-code': { generate: generateClaudeCode, outDir: 'claude-code' },
+};
+
+// ─── Parse args ───────────────────────────────────────────────────────────
+
+const args = process.argv.slice(2);
+const ideIdx = args.indexOf('--ide');
+const targetIde = ideIdx >= 0 ? args[ideIdx + 1] : null;
+
+const idesToRun = targetIde ? [targetIde] : Object.keys(ADAPTERS);
+
+// ─── Generate ─────────────────────────────────────────────────────────────
+
+for (const ide of idesToRun) {
+  const adapter = ADAPTERS[ide];
+  if (!adapter) {
+    console.error(`Unknown IDE: ${ide}. Available: ${Object.keys(ADAPTERS).join(', ')}`);
+    process.exit(1);
+  }
+
+  const outDir = resolve(__dirname, adapter.outDir);
+
+  // Clean only the subdirectories the generator manages (agents/, prompts/).
+  // This avoids wiping hand-maintained files if they coexist in general/.
+  for (const subdir of ['agents', 'prompts']) {
+    const sub = resolve(outDir, subdir);
+    if (existsSync(sub)) {
+      rmSync(sub, { recursive: true });
+    }
+  }
+
+  console.log(`\n─── Generating ${ide} scaffold ───`);
+
+  const files = adapter.generate();
+
+  if (files.length === 0) {
+    console.log(`  (stub — no files generated)`);
+    continue;
+  }
+
+  let count = 0;
+  for (const { path, content } of files) {
+    const fullPath = resolve(outDir, path);
+    mkdirSync(dirname(fullPath), { recursive: true });
+    writeFileSync(fullPath, content, 'utf-8');
+    console.log(`  ${path}`);
+    count++;
+  }
+
+  console.log(`  → ${count} files written to scaffold/${adapter.outDir}/`);
+}
+
+console.log('\nDone!');