@grainulation/harvest 1.0.1 → 1.0.2

package/CONTRIBUTING.md

@@ -15,16 +15,20 @@ No `npm install` needed -- harvest has zero dependencies.
 ## How to contribute
 
 ### Report a bug
+
 Open an issue with:
+
 - What you expected
 - What happened instead
 - Your Node version (`node --version`)
 - Steps to reproduce
 
 ### Suggest a feature
+
 Open an issue describing the use case, not just the solution. "I need X because Y" is more useful than "add X."
 
 ### Submit a PR
+
 1. Fork the repo
 2. Create a branch (`git checkout -b fix/description`)
 3. Make your changes
@@ -71,11 +75,13 @@ Tests use Node's built-in test runner. No test framework dependencies.
 ## Commit messages
 
 Follow the existing pattern:
+
 ```
 harvest: <what changed>
 ```
 
 Examples:
+
 ```
 harvest: add velocity trend chart
 harvest: fix decay calculation for stale claims

package/README.md

@@ -3,7 +3,8 @@
 </p>
 
 <p align="center">
-  <a href="https://www.npmjs.com/package/@grainulation/harvest"><img src="https://img.shields.io/npm/v/@grainulation/harvest" alt="npm version"></a> <a href="https://www.npmjs.com/package/@grainulation/harvest"><img src="https://img.shields.io/npm/dm/@grainulation/harvest" alt="npm downloads"></a> <a href="https://github.com/grainulation/harvest/blob/main/LICENSE"><img src="https://img.shields.io/npm/l/@grainulation/harvest" alt="license"></a> <a href="https://nodejs.org"><img src="https://img.shields.io/node/v/@grainulation/harvest" alt="node"></a> <a href="https://github.com/grainulation/harvest/actions"><img src="https://github.com/grainulation/harvest/actions/workflows/ci.yml/badge.svg" alt="CI"></a>
+  <a href="https://www.npmjs.com/package/@grainulation/harvest"><img src="https://img.shields.io/npm/v/@grainulation/harvest" alt="npm version"></a> <a href="https://www.npmjs.com/package/@grainulation/harvest"><img src="https://img.shields.io/npm/dm/@grainulation/harvest" alt="npm downloads"></a> <a href="https://github.com/grainulation/harvest/blob/main/LICENSE"><img src="https://img.shields.io/badge/license-MIT-green" alt="license"></a> <a href="https://nodejs.org"><img src="https://img.shields.io/node/v/@grainulation/harvest" alt="node"></a> <a href="https://github.com/grainulation/harvest/actions"><img src="https://github.com/grainulation/harvest/actions/workflows/ci.yml/badge.svg" alt="CI"></a>
+  <a href="https://deepwiki.com/grainulation/harvest"><img src="https://deepwiki.com/badge.svg" alt="Explore on DeepWiki"></a>
 </p>
 
 <p align="center"><strong>Are your decisions getting better?</strong></p>
@@ -84,16 +85,16 @@ Node built-in modules only.
 
 ## Part of the grainulation ecosystem
 
-| Tool | Role |
-|------|------|
-| [wheat](https://github.com/grainulation/wheat) | Research engine -- grow structured evidence |
-| [farmer](https://github.com/grainulation/farmer) | Permission dashboard -- approve AI actions in real time |
-| [barn](https://github.com/grainulation/barn) | Shared tools -- templates, validators, sprint detection |
-| [mill](https://github.com/grainulation/mill) | Format conversion -- export to PDF, CSV, slides, 24 formats |
-| [silo](https://github.com/grainulation/silo) | Knowledge storage -- reusable claim libraries and packs |
-| **harvest** | Analytics -- cross-sprint patterns and prediction scoring |
-| [orchard](https://github.com/grainulation/orchard) | Orchestration -- multi-sprint coordination and dependencies |
-| [grainulation](https://github.com/grainulation/grainulation) | Unified CLI -- single entry point to the ecosystem |
+| Tool                                                         | Role                                                        |
+| ------------------------------------------------------------ | ----------------------------------------------------------- |
+| [wheat](https://github.com/grainulation/wheat)               | Research engine -- grow structured evidence                 |
+| [farmer](https://github.com/grainulation/farmer)             | Permission dashboard -- approve AI actions in real time     |
+| [barn](https://github.com/grainulation/barn)                 | Shared tools -- templates, validators, sprint detection     |
+| [mill](https://github.com/grainulation/mill)                 | Format conversion -- export to PDF, CSV, slides, 24 formats |
+| [silo](https://github.com/grainulation/silo)                 | Knowledge storage -- reusable claim libraries and packs     |
+| **harvest**                                                  | Analytics -- cross-sprint patterns and prediction scoring   |
+| [orchard](https://github.com/grainulation/orchard)           | Orchestration -- multi-sprint coordination and dependencies |
+| [grainulation](https://github.com/grainulation/grainulation) | Unified CLI -- single entry point to the ecosystem          |
 
 ## License
 

package/bin/harvest.js

@@ -1,23 +1,31 @@
 #!/usr/bin/env node
 
-'use strict';
-
-const path = require('node:path');
-const fs = require('node:fs');
-
-const { analyze } = require('../lib/analyzer.js');
-const { calibrate } = require('../lib/calibration.js');
-const { detectPatterns } = require('../lib/patterns.js');
-const { checkDecay } = require('../lib/decay.js');
-const { measureVelocity } = require('../lib/velocity.js');
-const { generateReport } = require('../lib/report.js');
-const { connect: farmerConnect } = require('../lib/farmer.js');
-
-const verbose = process.argv.includes('--verbose') || process.argv.includes('-v');
+"use strict";
+
+const path = require("node:path");
+const fs = require("node:fs");
+
+const { analyze } = require("../lib/analyzer.js");
+const { calibrate } = require("../lib/calibration.js");
+const { detectPatterns } = require("../lib/patterns.js");
+const { checkDecay, decayAlerts } = require("../lib/decay.js");
+const { measureVelocity } = require("../lib/velocity.js");
+const { generateReport } = require("../lib/report.js");
+const { connect: farmerConnect } = require("../lib/farmer.js");
+const { analyzeTokens } = require("../lib/tokens.js");
+const { trackCosts } = require("../lib/token-tracker.js");
+const { generateWrapped } = require("../lib/wrapped.js");
+const {
+  generateCard,
+  generateEmbedSnippet,
+} = require("../lib/harvest-card.js");
+
+const verbose =
+  process.argv.includes("--verbose") || process.argv.includes("-v");
 function vlog(...a) {
   if (!verbose) return;
   const ts = new Date().toISOString();
-  process.stderr.write(`[${ts}] harvest: ${a.join(' ')}\n`);
+  process.stderr.write(`[${ts}] harvest: ${a.join(" ")}\n`);
 }
 
 const USAGE = `
@@ -29,8 +37,11 @@ Usage:
   harvest patterns <sprints-dir>      Detect decision patterns
   harvest decay <sprints-dir>         Find claims that need refreshing
   harvest velocity <sprints-dir>      Sprint timing and phase analysis
+  harvest tokens <sprints-dir>        Token cost tracking and efficiency
+  harvest card <sprints-dir> [-o <output>]  Generate Harvest Report SVG card
   harvest report <sprints-dir> [-o <output>]  Generate retrospective HTML
   harvest trends <sprints-dir>        All analyses in one pass
+  harvest intelligence <sprints-dir>  Full intelligence report (all features)
   harvest serve [--port 9096] [--root <sprints-dir>]  Start the dashboard UI
   harvest connect farmer [--url <url>]               Configure farmer integration
 
@@ -43,22 +54,29 @@ Options:
 
 function parseArgs(argv) {
   const args = argv.slice(2);
-  const parsed = { command: null, dir: null, output: null, json: false, days: 90 };
+  const parsed = {
+    command: null,
+    dir: null,
+    output: null,
+    json: false,
+    days: 90,
+  };
 
-  if (args.length === 0 || args.includes('-h') || args.includes('--help')) {
+  if (args.length === 0 || args.includes("-h") || args.includes("--help")) {
     console.log(USAGE);
     process.exit(0);
   }
 
   parsed.command = args[0];
-  parsed.dir = (args[1] && !args[1].startsWith('-')) ? path.resolve(args[1]) : null;
+  parsed.dir =
+    args[1] && !args[1].startsWith("-") ? path.resolve(args[1]) : null;
 
   for (let i = 2; i < args.length; i++) {
-    if ((args[i] === '-o' || args[i] === '--output') && args[i + 1]) {
+    if ((args[i] === "-o" || args[i] === "--output") && args[i + 1]) {
       parsed.output = path.resolve(args[++i]);
-    } else if (args[i] === '--json') {
+    } else if (args[i] === "--json") {
       parsed.json = true;
-    } else if (args[i] === '--days' && args[i + 1]) {
+    } else if (args[i] === "--days" && args[i + 1]) {
       parsed.days = parseInt(args[++i], 10);
     }
   }
@@ -75,7 +93,7 @@ function loadSprintData(dir) {
   const sprints = [];
 
   // Include root if it has claims.json
-  const directClaims = path.join(dir, 'claims.json');
+  const directClaims = path.join(dir, "claims.json");
   if (fs.existsSync(directClaims)) {
     sprints.push(loadSingleSprint(dir));
   }
@@ -85,9 +103,9 @@ function loadSprintData(dir) {
     const entries = fs.readdirSync(dir, { withFileTypes: true });
     for (const entry of entries) {
       if (!entry.isDirectory()) continue;
-      if (entry.name.startsWith('.')) continue;
+      if (entry.name.startsWith(".")) continue;
       const childDir = path.join(dir, entry.name);
-      const childClaims = path.join(childDir, 'claims.json');
+      const childClaims = path.join(childDir, "claims.json");
       if (fs.existsSync(childClaims)) {
         sprints.push(loadSingleSprint(childDir));
       }
@@ -96,20 +114,26 @@ function loadSprintData(dir) {
         const subEntries = fs.readdirSync(childDir, { withFileTypes: true });
         for (const sub of subEntries) {
           if (!sub.isDirectory()) continue;
-          if (sub.name.startsWith('.')) continue;
+          if (sub.name.startsWith(".")) continue;
           const subDir = path.join(childDir, sub.name);
-          const subClaims = path.join(subDir, 'claims.json');
+          const subClaims = path.join(subDir, "claims.json");
           if (fs.existsSync(subClaims)) {
             sprints.push(loadSingleSprint(subDir));
           }
         }
-      } catch { /* skip */ }
+      } catch {
+        /* skip */
+      }
     }
-  } catch { /* skip */ }
+  } catch {
+    /* skip */
+  }
 
   if (sprints.length === 0) {
     console.error(`harvest: no sprint data found in ${dir}`);
-    console.error('Expected claims.json in the directory or its subdirectories.');
+    console.error(
+      "Expected claims.json in the directory or its subdirectories.",
+    );
     process.exit(1);
   }
 
@@ -125,9 +149,9 @@ function loadSingleSprint(dir) {
     gitLog: null,
   };
 
-  const claimsPath = path.join(dir, 'claims.json');
+  const claimsPath = path.join(dir, "claims.json");
   try {
-    sprint.claims = JSON.parse(fs.readFileSync(claimsPath, 'utf8'));
+    sprint.claims = JSON.parse(fs.readFileSync(claimsPath, "utf8"));
     if (!Array.isArray(sprint.claims)) {
       // Handle { claims: [...] } wrapper
       sprint.claims = sprint.claims.claims || [];
@@ -136,10 +160,10 @@ function loadSingleSprint(dir) {
     console.error(`harvest: could not parse ${claimsPath}: ${e.message}`);
   }
 
-  const compilationPath = path.join(dir, 'compilation.json');
+  const compilationPath = path.join(dir, "compilation.json");
   if (fs.existsSync(compilationPath)) {
     try {
-      sprint.compilation = JSON.parse(fs.readFileSync(compilationPath, 'utf8'));
+      sprint.compilation = JSON.parse(fs.readFileSync(compilationPath, "utf8"));
     } catch (e) {
       // skip
     }
@@ -147,14 +171,23 @@ function loadSingleSprint(dir) {
 
   // Try to read git log for the sprint directory
   try {
-    const { execSync } = require('node:child_process');
+    const { execSync } = require("node:child_process");
     sprint.gitLog = execSync(
       `git log --oneline --format="%H|%ai|%s" -- claims.json`,
-      { cwd: dir, encoding: 'utf8', timeout: 5000, stdio: ['pipe', 'pipe', 'pipe'] }
-    ).trim().split('\n').filter(Boolean).map(line => {
-      const [hash, date, ...msg] = line.split('|');
-      return { hash, date, message: msg.join('|') };
-    });
+      {
+        cwd: dir,
+        encoding: "utf8",
+        timeout: 5000,
+        stdio: ["pipe", "pipe", "pipe"],
+      },
+    )
+      .trim()
+      .split("\n")
+      .filter(Boolean)
+      .map((line) => {
+        const [hash, date, ...msg] = line.split("|");
+        return { hash, date, message: msg.join("|") };
+      });
   } catch (e) {
     sprint.gitLog = [];
   }
@@ -165,7 +198,7 @@ function loadSingleSprint(dir) {
 function output(result, opts) {
   if (opts.json) {
     console.log(JSON.stringify(result, null, 2));
-  } else if (typeof result === 'string') {
+  } else if (typeof result === "string") {
     console.log(result);
   } else {
     console.log(JSON.stringify(result, null, 2));
@@ -174,7 +207,11 @@ function output(result, opts) {
 
 async function main() {
   const opts = parseArgs(process.argv);
-  vlog('startup', `command=${opts.command || '(none)'}`, `dir=${opts.dir || 'none'}`);
+  vlog(
+    "startup",
+    `command=${opts.command || "(none)"}`,
+    `dir=${opts.dir || "none"}`,
+  );
 
   const commands = {
     analyze() {
@@ -210,11 +247,49 @@ async function main() {
         patternsFn: detectPatterns,
         decayFn: checkDecay,
         velocityFn: measureVelocity,
+        tokensFn: analyzeTokens,
+        wrappedFn: generateWrapped,
       });
-      const outPath = opts.output || path.join(process.cwd(), 'retrospective.html');
-      fs.writeFileSync(outPath, html, 'utf8');
+      const outPath =
+        opts.output || path.join(process.cwd(), "retrospective.html");
+      fs.writeFileSync(outPath, html, "utf8");
       console.log(`Retrospective written to ${outPath}`);
     },
+    tokens() {
+      const sprints = loadSprintData(opts.dir);
+      const result = analyzeTokens(sprints);
+      output(result, opts);
+    },
+    card() {
+      const sprints = loadSprintData(opts.dir);
+      const { svg, stats } = generateCard(sprints);
+
+      if (opts.json) {
+        output(stats, opts);
+        return;
+      }
+
+      const outPath =
+        opts.output || path.join(process.cwd(), "harvest-card.svg");
+      fs.writeFileSync(outPath, svg, "utf8");
+      const embed = generateEmbedSnippet(path.basename(outPath));
+      console.log(`Harvest card written to ${outPath}`);
+      console.log(`\nEmbed in README:\n  ${embed.markdown}`);
+      console.log(`\nHTML:\n  ${embed.html}`);
+    },
+    intelligence() {
+      const sprints = loadSprintData(opts.dir);
+      const result = {
+        analysis: analyze(sprints),
+        calibration: calibrate(sprints),
+        patterns: detectPatterns(sprints),
+        decay: checkDecay(sprints, { thresholdDays: opts.days }),
+        decayAlerts: decayAlerts(sprints),
+        velocity: measureVelocity(sprints),
+        tokens: analyzeTokens(sprints),
+      };
+      output(result, opts);
+    },
     trends() {
       const sprints = loadSprintData(opts.dir);
       const result = {
@@ -228,47 +303,47 @@ async function main() {
     },
   };
 
-  if (opts.command === 'help') {
+  if (opts.command === "help") {
     console.log(USAGE);
     process.exit(0);
   }
 
-  if (opts.command === 'connect') {
+  if (opts.command === "connect") {
     // Forward remaining args to farmer connect handler
-    const connectArgs = process.argv.slice(process.argv.indexOf('connect') + 1);
+    const connectArgs = process.argv.slice(process.argv.indexOf("connect") + 1);
     await farmerConnect(opts.dir || process.cwd(), connectArgs);
     return;
   }
 
-  if (opts.command === 'serve') {
+  if (opts.command === "serve") {
     // Launch the ESM server module
-    const { execFile } = require('node:child_process');
-    const serverPath = path.join(__dirname, '..', 'lib', 'server.js');
+    const { execFile } = require("node:child_process");
+    const serverPath = path.join(__dirname, "..", "lib", "server.js");
     const serverArgs = [];
     // Forward --port and --root
-    const portIdx = process.argv.indexOf('--port');
+    const portIdx = process.argv.indexOf("--port");
     if (portIdx !== -1 && process.argv[portIdx + 1]) {
-      serverArgs.push('--port', process.argv[portIdx + 1]);
+      serverArgs.push("--port", process.argv[portIdx + 1]);
     }
-    const rootIdx = process.argv.indexOf('--root');
+    const rootIdx = process.argv.indexOf("--root");
     if (rootIdx !== -1 && process.argv[rootIdx + 1]) {
-      serverArgs.push('--root', process.argv[rootIdx + 1]);
+      serverArgs.push("--root", process.argv[rootIdx + 1]);
     } else if (opts.dir) {
-      serverArgs.push('--root', opts.dir);
+      serverArgs.push("--root", opts.dir);
     }
-    const child = execFile('node', [serverPath, ...serverArgs], {
-      stdio: 'inherit',
+    const child = execFile("node", [serverPath, ...serverArgs], {
+      stdio: "inherit",
       env: process.env,
     });
     child.stdout && child.stdout.pipe(process.stdout);
     child.stderr && child.stderr.pipe(process.stderr);
-    child.on('error', (err) => {
+    child.on("error", (err) => {
       console.error(`harvest: error starting server: ${err.message}`);
       process.exit(1);
     });
-    child.on('exit', (code) => process.exit(code || 0));
-    process.on('SIGTERM', () => child.kill('SIGTERM'));
-    process.on('SIGINT', () => child.kill('SIGINT'));
+    child.on("exit", (code) => process.exit(code || 0));
+    process.on("SIGTERM", () => child.kill("SIGTERM"));
+    process.on("SIGINT", () => child.kill("SIGINT"));
     return;
   }
 

package/lib/analyzer.js

@@ -1,4 +1,4 @@
-'use strict';
+"use strict";
 
 /**
  * Cross-sprint claim analysis.
@@ -11,19 +11,21 @@
  */
 
 function analyze(sprints) {
-  const allClaims = sprints.flatMap(s => s.claims.map(c => ({ ...c, _sprint: s.name })));
+  const allClaims = sprints.flatMap((s) =>
+    s.claims.map((c) => ({ ...c, _sprint: s.name })),
+  );
 
-  const typeDistribution = countBy(allClaims, 'type');
-  const evidenceDistribution = countBy(allClaims, 'evidence');
-  const statusDistribution = countBy(allClaims, 'status');
+  const typeDistribution = countBy(allClaims, "type");
+  const evidenceDistribution = countBy(allClaims, "evidence");
+  const statusDistribution = countBy(allClaims, "status");
 
   // Per-sprint density
-  const perSprint = sprints.map(s => ({
+  const perSprint = sprints.map((s) => ({
     name: s.name,
     claimCount: s.claims.length,
-    types: countBy(s.claims, 'type'),
-    evidence: countBy(s.claims, 'evidence'),
-    statuses: countBy(s.claims, 'status'),
+    types: countBy(s.claims, "type"),
+    evidence: countBy(s.claims, "evidence"),
+    statuses: countBy(s.claims, "status"),
   }));
 
   // Find cross-sprint themes by looking at tags
@@ -36,35 +38,40 @@ function analyze(sprints) {
   }
 
   // Identify weak spots: claims with low evidence tiers
-  const weakClaims = allClaims.filter(c =>
-    c.evidence === 'stated' || c.evidence === 'web'
+  const weakClaims = allClaims.filter(
+    (c) => c.evidence === "stated" || c.evidence === "web",
   );
 
   // Type monoculture detection: sprints dominated by a single claim type
-  const monocultures = perSprint.filter(s => {
-    const types = Object.entries(s.types);
-    if (types.length === 0) return false;
-    const max = Math.max(...types.map(([, v]) => v));
-    return max / s.claimCount > 0.7 && s.claimCount > 3;
-  }).map(s => ({
-    sprint: s.name,
-    dominantType: Object.entries(s.types).sort((a, b) => b[1] - a[1])[0][0],
-    ratio: Math.round(Math.max(...Object.values(s.types)) / s.claimCount * 100),
-  }));
+  const monocultures = perSprint
+    .filter((s) => {
+      const types = Object.entries(s.types);
+      if (types.length === 0) return false;
+      const max = Math.max(...types.map(([, v]) => v));
+      return max / s.claimCount > 0.7 && s.claimCount > 3;
+    })
+    .map((s) => ({
+      sprint: s.name,
+      dominantType: Object.entries(s.types).sort((a, b) => b[1] - a[1])[0][0],
+      ratio: Math.round(
+        (Math.max(...Object.values(s.types)) / s.claimCount) * 100,
+      ),
+    }));
 
   return {
     summary: {
       totalSprints: sprints.length,
       totalClaims: allClaims.length,
-      averageClaimsPerSprint: sprints.length > 0
-        ? Math.round(allClaims.length / sprints.length * 10) / 10
-        : 0,
+      averageClaimsPerSprint:
+        sprints.length > 0
+          ? Math.round((allClaims.length / sprints.length) * 10) / 10
+          : 0,
     },
     typeDistribution,
     evidenceDistribution,
     statusDistribution,
     tagFrequency,
-    weakClaims: weakClaims.map(c => ({
+    weakClaims: weakClaims.map((c) => ({
       id: c.id,
       sprint: c._sprint,
       type: c.type,
@@ -79,7 +86,7 @@ function analyze(sprints) {
 function countBy(items, key) {
   const counts = {};
   for (const item of items) {
-    const val = item[key] || 'unknown';
+    const val = item[key] || "unknown";
     counts[val] = (counts[val] || 0) + 1;
   }
   return counts;