@grainulation/barn 1.0.0

package/tools/detect-sprints.js

@@ -0,0 +1,292 @@
+#!/usr/bin/env node
+/**
+ * detect-sprints.js — Git-based sprint detection
+ *
+ * Scans a repo for sprint indicators (claims.json files) and determines
+ * which sprint is "active" using filesystem + git heuristics:
+ *
+ *   1. Find all claims.json files (root + examples/ subdirs)
+ *   2. Read meta.phase — "archived" sprints are inactive
+ *   3. Query git log for most recent commit touching each claims.json
+ *   4. Rank by: non-archived > most recent git activity > initiated date
+ *
+ * Returns a list of sprints with status (active/archived/example).
+ * Works without any config file — pure filesystem + git.
+ *
+ * Usage:
+ *   node detect-sprints.js                    # Human-readable output
+ *   node detect-sprints.js --json             # Machine-readable JSON
+ *   node detect-sprints.js --active           # Print only the active sprint path
+ *   node detect-sprints.js --root /path       # Scan a specific directory
+ *
+ * Zero npm dependencies (Node built-in only).
+ */
+
+import { readFileSync, existsSync, readdirSync } from 'node:fs';
+import { join, basename } from 'node:path';
+import { execFileSync } from 'node:child_process';
+import { fileURLToPath } from 'node:url';
+
+const __filename = fileURLToPath(import.meta.url);
+
+// ─── CLI args (only parsed when run directly) ────────────────────────────────
+
+let ROOT = process.cwd();
+
+/** Parse CLI args — only called when this file is the entry point. */
+function parseCLIArgs() {
+  const args = process.argv.slice(2);
+  const i = args.indexOf('--root');
+  if (i !== -1 && args[i + 1]) ROOT = args[i + 1];
+  return args;
+}
+
+// ─── Helpers ─────────────────────────────────────────────────────────────────
+
+/** Safely parse JSON from a file path; returns null on failure. */
+function loadJSON(filePath) {
+  try {
+    return JSON.parse(readFileSync(filePath, 'utf8'));
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Get the ISO timestamp of the most recent git commit touching a file.
+ * Returns null if file is untracked or git is unavailable.
+ */
+function lastGitCommitDate(filePath) {
+  try {
+    const result = execFileSync('git', [
+      'log', '-1', '--format=%aI', '--', filePath
+    ], { cwd: ROOT, timeout: 5000, stdio: ['ignore', 'pipe', 'pipe'] });
+    const dateStr = result.toString().trim();
+    return dateStr || null;
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Count git commits touching a file (proxy for activity level).
+ */
+function gitCommitCount(filePath) {
+  try {
+    const result = execFileSync('git', [
+      'rev-list', '--count', 'HEAD', '--', filePath
+    ], { cwd: ROOT, timeout: 5000, stdio: ['ignore', 'pipe', 'pipe'] });
+    return parseInt(result.toString().trim(), 10) || 0;
+  } catch {
+    return 0;
+  }
+}
+
+/**
+ * Derive a slug from the sprint's path or question.
+ */
+function deriveName(sprintPath, meta) {
+  if (sprintPath !== '.') {
+    return basename(sprintPath);
+  }
+  if (meta?.question) {
+    return meta.question
+      .toLowerCase()
+      .replace(/[^a-z0-9\s]/g, '')
+      .split(/\s+/)
+      .slice(0, 4)
+      .join('-');
+  }
+  return 'current';
+}
+
+// ─── Scanner ─────────────────────────────────────────────────────────────────
+
+/** Find all sprint roots (directories containing claims.json). */
+function findSprintRoots() {
+  const roots = [];
+
+  const rootClaims = join(ROOT, 'claims.json');
+  if (existsSync(rootClaims)) {
+    roots.push({ claimsPath: rootClaims, sprintPath: '.' });
+  }
+
+  const examplesDir = join(ROOT, 'examples');
+  if (existsSync(examplesDir)) {
+    try {
+      for (const entry of readdirSync(examplesDir, { withFileTypes: true })) {
+        if (!entry.isDirectory()) continue;
+        const claimsPath = join(examplesDir, entry.name, 'claims.json');
+        if (existsSync(claimsPath)) {
+          roots.push({
+            claimsPath,
+            sprintPath: join('examples', entry.name),
+          });
+        }
+      }
+    } catch { /* skip if unreadable */ }
+  }
+
+  return roots;
+}
+
+// ─── Sprint Analysis ─────────────────────────────────────────────────────────
+
+function analyzeSprint(root) {
+  const claims = loadJSON(root.claimsPath);
+  if (!claims) return null;
+
+  const meta = claims.meta || {};
+  const claimsList = claims.claims || [];
+
+  const lastCommit = lastGitCommitDate(root.claimsPath);
+  const commitCount = gitCommitCount(root.claimsPath);
+
+  const phase = meta.phase || 'unknown';
+  const isArchived = phase === 'archived' || phase === 'complete';
+  const isExample = root.sprintPath.startsWith('examples/') || root.sprintPath.startsWith('examples\\');
+
+  let status;
+  if (isArchived) {
+    status = 'archived';
+  } else if (isExample) {
+    status = 'example';
+  } else {
+    status = 'candidate';
+  }
+
+  return {
+    name: deriveName(root.sprintPath, meta),
+    path: root.sprintPath,
+    question: meta.question || '',
+    phase,
+    initiated: meta.initiated || null,
+    last_git_activity: lastCommit,
+    git_commit_count: commitCount,
+    claims_count: claimsList.length,
+    active_claims: claimsList.filter(c => c.status === 'active').length,
+    status,
+  };
+}
+
+/**
+ * Detect all sprints and determine which is active.
+ *
+ * Ranking (highest to lowest priority):
+ *   1. Non-archived, non-example sprints (root-level candidates)
+ *   2. Most recent git commit touching claims.json
+ *   3. Most recent meta.initiated date
+ *   4. Highest claim count (tiebreaker)
+ */
+export function detectSprints(rootDir) {
+  if (rootDir) ROOT = rootDir;
+  const roots = findSprintRoots();
+  const sprints = roots.map(analyzeSprint).filter(Boolean);
+
+  const candidates = sprints.filter(s => s.status === 'candidate');
+  const others = sprints.filter(s => s.status !== 'candidate');
+
+  candidates.sort((a, b) => {
+    const dateA = a.last_git_activity ? new Date(a.last_git_activity).getTime() : 0;
+    const dateB = b.last_git_activity ? new Date(b.last_git_activity).getTime() : 0;
+    if (dateB !== dateA) return dateB - dateA;
+
+    const initA = a.initiated ? new Date(a.initiated).getTime() : 0;
+    const initB = b.initiated ? new Date(b.initiated).getTime() : 0;
+    if (initB !== initA) return initB - initA;
+
+    return b.claims_count - a.claims_count;
+  });
+
+  let active = null;
+  if (candidates.length > 0) {
+    candidates[0].status = 'active';
+    active = candidates[0];
+  }
+
+  if (!active && others.length > 0) {
+    const nonArchived = others.filter(s => s.status !== 'archived');
+    if (nonArchived.length > 0) {
+      nonArchived.sort((a, b) => {
+        const dateA = a.last_git_activity ? new Date(a.last_git_activity).getTime() : 0;
+        const dateB = b.last_git_activity ? new Date(b.last_git_activity).getTime() : 0;
+        return dateB - dateA;
+      });
+      nonArchived[0].status = 'active';
+      active = nonArchived[0];
+    }
+  }
+
+  const allSprints = [...candidates, ...others].sort((a, b) => {
+    if (a.status === 'active' && b.status !== 'active') return -1;
+    if (b.status === 'active' && a.status !== 'active') return 1;
+    const dateA = a.last_git_activity ? new Date(a.last_git_activity).getTime() : 0;
+    const dateB = b.last_git_activity ? new Date(b.last_git_activity).getTime() : 0;
+    return dateB - dateA;
+  });
+
+  return { active, sprints: allSprints };
+}
+
+// ─── CLI ─────────────────────────────────────────────────────────────────────
+
+if (process.argv[1] === __filename) {
+  const args = parseCLIArgs();
+  if (args.includes('--help') || args.includes('-h')) {
+    console.log(`detect-sprints — git-based sprint detection (no config required)
+
+Usage:
+  barn detect-sprints              Human-readable sprint list
+  barn detect-sprints --json       Machine-readable JSON output
+  barn detect-sprints --active     Print only the active sprint path
+  barn detect-sprints --root PATH  Scan a specific directory
+
+Detects sprints from claims.json files in a repo. Determines the active
+sprint using git commit history and metadata — no config pointer needed.`);
+    process.exit(0);
+  }
+
+  const t0 = performance.now();
+  const result = detectSprints();
+  const elapsed = (performance.now() - t0).toFixed(1);
+
+  if (args.includes('--json')) {
+    console.log(JSON.stringify(result, null, 2));
+    process.exit(0);
+  }
+
+  if (args.includes('--active')) {
+    if (result.active) {
+      console.log(result.active.path);
+    } else {
+      console.error('No active sprint detected.');
+      process.exit(1);
+    }
+    process.exit(0);
+  }
+
+  // Human-readable output
+  console.log(`Sprint Detection (${elapsed}ms)`);
+  console.log('='.repeat(50));
+  console.log(`Found ${result.sprints.length} sprint(s)\n`);
+
+  for (const sprint of result.sprints) {
+    const icon = sprint.status === 'active' ? '>>>' : '   ';
+    const statusTag = sprint.status.toUpperCase().padEnd(8);
+    console.log(`${icon} [${statusTag}] ${sprint.name}`);
+    console.log(`    Path:     ${sprint.path}`);
+    console.log(`    Phase:    ${sprint.phase}`);
+    console.log(`    Claims:   ${sprint.claims_count} total, ${sprint.active_claims} active`);
+    console.log(`    Initiated: ${sprint.initiated || 'unknown'}`);
+    console.log(`    Last git:  ${sprint.last_git_activity || 'untracked'}`);
+    console.log(`    Commits:   ${sprint.git_commit_count}`);
+    console.log(`    Question:  ${sprint.question.slice(0, 80)}${sprint.question.length > 80 ? '...' : ''}`);
+    console.log();
+  }
+
+  if (result.active) {
+    console.log(`Active sprint: ${result.active.path} (${result.active.name})`);
+  } else {
+    console.log('No active sprint detected.');
+  }
+}

package/tools/generate-manifest.js

@@ -0,0 +1,237 @@
+#!/usr/bin/env node
+/**
+ * generate-manifest.js — Build wheat-manifest.json topic map
+ *
+ * Reads claims.json, compilation.json, and scans the repo directory structure
+ * to produce a topic-map manifest. Zero npm dependencies.
+ *
+ * Usage:
+ *   barn generate-manifest                        # Write wheat-manifest.json
+ *   barn generate-manifest --root /path            # Target a specific repo
+ *   barn generate-manifest --out custom-name.json  # Custom output path
+ */
+
+import { readFileSync, writeFileSync, readdirSync, statSync, existsSync } from 'node:fs';
+import { join, relative, resolve, basename, sep } from 'node:path';
+import { execFileSync } from 'node:child_process';
+import { fileURLToPath } from 'node:url';
+import { detectSprints } from './detect-sprints.js';
+
+// ─── CLI args ────────────────────────────────────────────────────────────────
+
+const args = process.argv.slice(2);
+
+function arg(name, fallback) {
+  const i = args.indexOf(`--${name}`);
+  return i !== -1 && args[i + 1] ? args[i + 1] : fallback;
+}
+
+const ROOT = arg('root', process.cwd());
+const OUT_PATH = join(ROOT, arg('out', 'wheat-manifest.json'));
+
+// ─── Helpers ─────────────────────────────────────────────────────────────────
+
+function loadJSON(path) {
+  try {
+    return JSON.parse(readFileSync(path, 'utf8'));
+  } catch {
+    return null;
+  }
+}
+
+/** Recursively list files under dir, returning paths relative to rootDir. */
+function walk(dir, filter, rootDir) {
+  const results = [];
+  if (!existsSync(dir)) return results;
+  const base = rootDir || dir;
+  for (const entry of readdirSync(dir, { withFileTypes: true })) {
+    const full = join(dir, entry.name);
+    if (entry.isDirectory()) {
+      if (entry.name.startsWith('.') || entry.name === 'node_modules') continue;
+      results.push(...walk(full, filter, base));
+    } else {
+      const rel = relative(base, full).split(sep).join('/');
+      if (!filter || filter(rel, entry.name)) results.push(rel);
+    }
+  }
+  return results;
+}
+
+/** Determine file type from its path. */
+function classifyFile(relPath) {
+  if (relPath.startsWith('prototypes/')) return 'prototype';
+  if (relPath.startsWith('research/')) return 'research';
+  if (relPath.startsWith('output/')) return 'output';
+  if (relPath.startsWith('evidence/')) return 'evidence';
+  if (relPath.startsWith('templates/')) return 'template';
+  if (relPath.startsWith('examples/')) return 'example';
+  if (relPath.startsWith('test/')) return 'test';
+  if (relPath.startsWith('docs/')) return 'docs';
+  if (relPath.endsWith('.json')) return 'config';
+  if (relPath.endsWith('.js') || relPath.endsWith('.mjs')) return 'script';
+  if (relPath.endsWith('.md')) return 'docs';
+  return 'other';
+}
+
+/** Compute highest evidence tier from a list of claims. */
+function highestEvidence(claims) {
+  const tiers = ['stated', 'web', 'documented', 'tested', 'production'];
+  let max = 0;
+  for (const c of claims) {
+    const idx = tiers.indexOf(c.evidence);
+    if (idx > max) max = idx;
+  }
+  return tiers[max];
+}
+
+// ─── Exported function ───────────────────────────────────────────────────────
+
+/**
+ * Generate a wheat-manifest object from a claims.json path.
+ *
+ * @param {string} claimsPath — absolute path to claims.json
+ * @param {object} [opts] — optional overrides
+ * @param {string} [opts.root] — repo root directory (defaults to dirname of claimsPath)
+ * @returns {object} — the manifest object (not written to disk)
+ */
+export function generateManifest(claimsPath, opts = {}) {
+  const root = opts.root || join(claimsPath, '..');
+  const claims = loadJSON(claimsPath);
+  if (!claims) {
+    throw new Error(`claims.json not found or invalid at ${claimsPath}`);
+  }
+
+  const compilationPath = join(root, 'compilation.json');
+  const compilation = loadJSON(compilationPath);
+
+  // 1. Build topic map from claims
+  const topicMap = {};
+  for (const claim of claims.claims) {
+    const topic = claim.topic;
+    if (!topicMap[topic]) {
+      topicMap[topic] = { claims: [], files: new Set(), sprint: 'current', evidence_level: 'stated' };
+    }
+    topicMap[topic].claims.push(claim.id);
+  }
+
+  for (const topic of Object.keys(topicMap)) {
+    const topicClaims = claims.claims.filter(c => c.topic === topic);
+    topicMap[topic].evidence_level = highestEvidence(topicClaims);
+  }
+
+  // 2. Scan directories for files
+  const scanDirs = ['research', 'prototypes', 'output', 'evidence', 'templates', 'test', 'docs'];
+  const allFiles = {};
+
+  for (const dir of scanDirs) {
+    const files = walk(join(root, dir), null, root);
+    for (const f of files) {
+      allFiles[f] = { topics: [], type: classifyFile(f) };
+    }
+  }
+
+  // Root-level scripts/configs
+  try {
+    for (const entry of readdirSync(root)) {
+      if (entry.startsWith('.') || entry === 'node_modules') continue;
+      const full = join(root, entry);
+      try {
+        if (statSync(full).isFile()) {
+          const type = classifyFile(entry);
+          if (type !== 'other') {
+            allFiles[entry] = { topics: [], type };
+          }
+        }
+      } catch { /* skip */ }
+    }
+  } catch { /* skip */ }
+
+  // 3. Map files to topics via claim artifacts
+  for (const [filePath, fileInfo] of Object.entries(allFiles)) {
+    for (const claim of claims.claims) {
+      if (claim.source?.artifact && filePath.includes(claim.source.artifact.replace(/^.*[/\\]prototypes[/\\]/, 'prototypes/'))) {
+        if (!fileInfo.topics.includes(claim.topic)) {
+          fileInfo.topics.push(claim.topic);
+        }
+      }
+    }
+
+    for (const topic of fileInfo.topics) {
+      if (topicMap[topic]) {
+        topicMap[topic].files.add(filePath);
+      }
+    }
+  }
+
+  // 4. Convert Sets to arrays
+  for (const topic of Object.keys(topicMap)) {
+    topicMap[topic].files = [...topicMap[topic].files].sort();
+  }
+
+  // 5. Detect sprints
+  const sprintResult = detectSprints(root);
+  const sprints = {};
+  for (const s of (sprintResult.sprints || [])) {
+    sprints[s.name] = {
+      question: s.question || '',
+      phase: s.phase || 'unknown',
+      claims_count: s.claims_count || 0,
+      active_claims: s.active_claims || 0,
+      path: s.path,
+      status: s.status,
+      last_git_activity: s.last_git_activity,
+      git_commit_count: s.git_commit_count,
+    };
+  }
+
+  // 6. Build manifest
+  const topicFiles = {};
+  for (const [path, info] of Object.entries(allFiles)) {
+    if (info.topics.length > 0) {
+      topicFiles[path] = info;
+    }
+  }
+
+  return {
+    schema_version: '1.0',
+    generated: new Date().toISOString(),
+    generator: '@grainulation/barn generate-manifest',
+    claims_hash: compilation?.claims_hash || null,
+    topics: topicMap,
+    sprints,
+    files: topicFiles,
+  };
+}
+
+// ─── CLI ─────────────────────────────────────────────────────────────────────
+
+// Only run CLI logic when executed directly (not imported)
+const isMain = process.argv[1] && resolve(process.argv[1]) === fileURLToPath(import.meta.url);
+if (isMain) {
+  if (args.includes('--help') || args.includes('-h')) {
+    console.log(`generate-manifest — build wheat-manifest.json topic map
+
+Usage:
+  barn generate-manifest                         Write wheat-manifest.json
+  barn generate-manifest --root /path             Target a specific repo
+  barn generate-manifest --out custom-name.json   Custom output path
+
+Reads claims.json and scans the repo to produce a topic map manifest
+that gives AI tools a single file describing the sprint state.`);
+    process.exit(0);
+  }
+
+  const t0 = performance.now();
+  const manifest = generateManifest(join(ROOT, 'claims.json'), { root: ROOT });
+
+  writeFileSync(OUT_PATH, JSON.stringify(manifest, null, 2) + '\n');
+  const elapsed = (performance.now() - t0).toFixed(1);
+
+  const topicCount = Object.keys(manifest.topics).length;
+  const fileCount = Object.keys(manifest.files).length;
+  const sprintCount = Object.keys(manifest.sprints).length;
+  const sizeBytes = Buffer.byteLength(JSON.stringify(manifest, null, 2));
+
+  console.log(`wheat-manifest.json generated in ${elapsed}ms`);
+  console.log(`  Topics: ${topicCount}  |  Files: ${fileCount}  |  Sprints: ${sprintCount}  |  Size: ${(sizeBytes / 1024).toFixed(1)}KB`);
+}