@vpxa/aikit 0.1.73 → 0.1.75

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

@@ -1,299 +0,0 @@
-#!/usr/bin/env node
-/**
- * Smart scaffold generator for handoff documents.
- *
- * Creates a new handoff document with auto-detected metadata:
- * - Current timestamp
- * - Project path
- * - Git branch (if available)
- * - Recent git log
- * - Modified/staged files
- * - Handoff chain linking
- *
- * Usage:
- *   node create_handoff.js [task-slug]
- *   node create_handoff.js "implementing-auth"
- *   node create_handoff.js "auth-part-2" --continues-from 2024-01-15-auth.md
- *   node create_handoff.js  # auto-generates slug from timestamp
- */
-
-const fs = require('node:fs');
-const path = require('node:path');
-const { execSync } = require('node:child_process');
-
-function _die(msg) {
-  process.stderr.write(`${msg}\n`);
-  process.exit(1);
-}
-
-function runCmd(cmd, cwd) {
-  try {
-    return { ok: true, out: execSync(cmd, { cwd, timeout: 10_000, encoding: 'utf-8' }).trim() };
-  } catch {
-    return { ok: false, out: '' };
-  }
-}
-
-function getGitInfo(projectPath) {
-  const info = {
-    isGitRepo: false,
-    branch: null,
-    recentCommits: [],
-    modifiedFiles: [],
-    stagedFiles: [],
-  };
-
-  if (!runCmd('git rev-parse --git-dir', projectPath).ok) return info;
-  info.isGitRepo = true;
-
-  const { ok: bOk, out: branch } = runCmd('git branch --show-current', projectPath);
-  if (bOk && branch) info.branch = branch;
-
-  const { ok: lOk, out: log } = runCmd('git log --oneline -5 --no-decorate', projectPath);
-  if (lOk && log) info.recentCommits = log.split('\n');
-
-  const { ok: mOk, out: modified } = runCmd('git diff --name-only', projectPath);
-  if (mOk && modified) info.modifiedFiles = modified.split('\n');
-
-  const { ok: sOk, out: staged } = runCmd('git diff --name-only --cached', projectPath);
-  if (sOk && staged) info.stagedFiles = staged.split('\n');
-
-  return info;
-}
-
-function findPreviousHandoffs(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);
-
-    let title = name;
-    try {
-      const content = fs.readFileSync(fp, 'utf-8');
-      const m = content.match(/^#\s+(?:Handoff:\s*)?(.+)$/m);
-      if (m) title = m[1].trim();
-    } catch {
-      /* ignore */
-    }
-
-    let date = null;
-    const dm = name.match(/^(\d{4}-\d{2}-\d{2})-(\d{6})/);
-    if (dm) {
-      try {
-        date = new Date(`${dm[1]}T${dm[2].slice(0, 2)}:${dm[2].slice(2, 4)}:${dm[2].slice(4, 6)}`);
-      } catch {
-        /* ignore */
-      }
-    }
-
-    handoffs.push({ filename: name, path: fp, title, date });
-  }
-
-  handoffs.sort((a, b) => (b.date || 0) - (a.date || 0));
-  return handoffs;
-}
-
-function getPreviousHandoffInfo(projectPath, continuesFrom) {
-  const handoffs = findPreviousHandoffs(projectPath);
-
-  if (continuesFrom) {
-    const found = handoffs.find((h) => h.filename.includes(continuesFrom));
-    return found
-      ? { exists: true, filename: found.filename, title: found.title }
-      : { exists: false, filename: continuesFrom, title: 'Not found' };
-  }
-
-  if (handoffs.length > 0) {
-    return {
-      exists: true,
-      filename: handoffs[0].filename,
-      title: handoffs[0].title,
-      suggested: true,
-    };
-  }
-
-  return { exists: false };
-}
-
-function sanitizeSlug(slug) {
-  return slug
-    .toLowerCase()
-    .replace(/[\s_]/g, '-')
-    .replace(/[^a-z0-9-]/g, '');
-}
-
-function generateHandoff(projectPath, slug, continuesFrom) {
-  const now = new Date();
-  const timestamp = now.toISOString().replace('T', ' ').slice(0, 19);
-  const fileTs = `${now.toISOString().slice(0, 10)}-${String(now.getHours()).padStart(2, '0')}${String(now.getMinutes()).padStart(2, '0')}${String(now.getSeconds()).padStart(2, '0')}`;
-
-  if (!slug) slug = 'handoff';
-  slug = sanitizeSlug(slug);
-  const filename = `${fileTs}-${slug}.md`;
-
-  const handoffsDir = path.join(projectPath, '.handoffs');
-  fs.mkdirSync(handoffsDir, { recursive: true });
-  const filepath = path.join(handoffsDir, filename);
-
-  const git = getGitInfo(projectPath);
-  const prev = getPreviousHandoffInfo(projectPath, continuesFrom);
-
-  const branchLine = git.branch || '[not a git repo or detached HEAD]';
-
-  const commitsSection =
-    git.recentCommits.length > 0
-      ? git.recentCommits.map((c) => `  - ${c}`).join('\n')
-      : '  - [no recent commits or not a git repo]';
-
-  const allModified = [...new Set([...git.modifiedFiles, ...git.stagedFiles])];
-  let modifiedSection;
-  if (allModified.length > 0) {
-    modifiedSection = allModified
-      .slice(0, 10)
-      .map((f) => `| ${f} | [describe changes] | [why changed] |`)
-      .join('\n');
-    if (allModified.length > 10)
-      modifiedSection += `\n| ... and ${allModified.length - 10} more files | | |`;
-  } else {
-    modifiedSection = '| [no modified files detected] | | |';
-  }
-
-  let chainSection;
-  if (prev.exists) {
-    chainSection = `## Handoff Chain
-
-- **Continues from**: [${prev.filename}](./${prev.filename})
-  - Previous title: ${prev.title || 'Unknown'}
-- **Supersedes**: [list any older handoffs this replaces, or "None"]
-
-> Review the previous handoff for full context before filling this one.`;
-  } else {
-    chainSection = `## Handoff Chain
-
-- **Continues from**: None (fresh start)
-- **Supersedes**: None
-
-> This is the first handoff for this task.`;
-  }
-
-  const content = `# Handoff: [TASK_TITLE - replace this]
-
-## Session Metadata
-- Created: ${timestamp}
-- Project: ${projectPath}
-- Branch: ${branchLine}
-- Session duration: [estimate how long you worked]
-
-### Recent Commits (for context)
-${commitsSection}
-
-${chainSection}
-
-## Current State Summary
-
-[TODO: Write one paragraph describing what was being worked on, current status, and where things left off]
-
-## Codebase Understanding
-
-### Architecture Overview
-
-[TODO: Document key architectural insights discovered during this session]
-
-### Critical Files
-
-| File | Purpose | Relevance |
-|------|---------|-----------|
-| [TODO: Add critical files] | | |
-
-### Key Patterns Discovered
-
-[TODO: Document important patterns, conventions, or idioms found in this codebase]
-
-## Work Completed
-
-### Tasks Finished
-
-- [ ] [TODO: List completed tasks]
-
-### Files Modified
-
-| File | Changes | Rationale |
-|------|---------|-----------|
-${modifiedSection}
-
-### Decisions Made
-
-| Decision | Options Considered | Rationale |
-|----------|-------------------|-----------|
-| [TODO: Document key decisions] | | |
-
-## Pending Work
-
-### Immediate Next Steps
-
-1. [TODO: Most critical next action]
-2. [TODO: Second priority]
-3. [TODO: Third priority]
-
-### Blockers/Open Questions
-
-- [ ] [TODO: List blockers or open questions]
-
-### Deferred Items
-
-- [TODO: Items deferred and why]
-
-## Context for Resuming Agent
-
-### Important Context
-
-[TODO: Critical information the next agent MUST know]
-
-### Assumptions Made
-
-[TODO: List assumptions that might not be obvious]
-
-### Potential Gotchas
-
-[TODO: Things that could trip up the next agent]
-
-## Environment State
-
-[TODO: Required env vars, running processes, DB state]
-
-## Related Resources
-
-[TODO: Links to docs, PRs, issues, Slack threads]
-`;
-
-  fs.writeFileSync(filepath, content, 'utf-8');
-  return { filepath, filename };
-}
-
-// --- Main ---
-const args = process.argv.slice(2);
-if (args.includes('--help') || args.includes('-h')) {
-  console.log('Usage: node create_handoff.js [task-slug] [--continues-from <previous>]');
-  console.log('       node create_handoff.js "implementing-auth"');
-  console.log('       node create_handoff.js "auth-part-2" --continues-from 2024-01-15-auth.md');
-  process.exit(0);
-}
-
-let slug = null;
-let continuesFrom = null;
-for (let i = 0; i < args.length; i++) {
-  if (args[i] === '--continues-from' && i + 1 < args.length) {
-    continuesFrom = args[++i];
-  } else if (!args[i].startsWith('-')) {
-    slug = args[i];
-  }
-}
-
-const cwd = process.cwd();
-const { filepath } = generateHandoff(cwd, slug, continuesFrom);
-console.log(`Created handoff: ${filepath}`);
-console.log(`\nNext: Open the file and fill in all [TODO: ...] sections.`);
-console.log(`Then validate: node scripts/validate_handoff.js ${filepath}`);

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

@@ -1,113 +0,0 @@
-#!/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

@@ -1,241 +0,0 @@
-#!/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);
-}