@grainulation/harvest 1.0.0 → 1.0.2

package/CODE_OF_CONDUCT.md

@@ -0,0 +1,25 @@
+# Code of Conduct
+
+## Our standards
+
+We are committed to providing a welcoming and productive environment for everyone. We expect participants to:
+
+- Use welcoming and inclusive language
+- Respect differing viewpoints and experiences
+- Accept constructive criticism gracefully
+- Focus on what is best for the community and the project
+- Show empathy toward other participants
+
+Unacceptable behavior includes harassment, trolling, personal attacks, and publishing others' private information without permission.
+
+## Scope
+
+This code of conduct applies to all project spaces -- issues, pull requests, discussions, and any public channel where someone represents the project.
+
+## Enforcement
+
+Instances of unacceptable behavior may be reported to the project maintainers. All complaints will be reviewed and investigated, and will result in a response deemed necessary and appropriate.
+
+## Attribution
+
+Adapted from the [Contributor Covenant](https://www.contributor-covenant.org/), version 2.1.

package/CONTRIBUTING.md

@@ -0,0 +1,93 @@
+# Contributing to Harvest
+
+Thanks for considering contributing. Harvest is the retrospective and analytics engine for the grainulation ecosystem -- it turns sprint history into insights and calibration data.
+
+## Quick setup
+
+```bash
+git clone https://github.com/grainulation/harvest.git
+cd harvest
+node bin/harvest.js --help
+```
+
+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
+4. Run the tests: `node --test test/basic.test.js`
+5. Commit with a clear message
+6. Open a PR
+
+## Architecture
+
+```
+bin/harvest.js            CLI entrypoint -- dispatches subcommands
+lib/analyzer.js           Sprint data analysis and pattern detection
+lib/calibration.js        Prediction vs outcome scoring
+lib/decay.js              Claim staleness and evidence decay
+lib/patterns.js           Recurring pattern extraction
+lib/report.js             Report generation from analyzed data
+lib/server.js             Local preview server (SSE, zero deps)
+lib/templates.js          Template rendering for HTML output
+lib/velocity.js           Sprint velocity tracking
+templates/                HTML templates (retrospective, etc.)
+public/                   Web UI -- retrospective dashboard
+site/                     Public website (harvest.grainulation.com)
+test/                     Node built-in test runner tests
+```
+
+The key architectural principle: **harvest reads sprint artifacts (claims, compilations, git history) and produces calibrated insights.** It never modifies source data -- read-only analysis, write-only reports.
+
+## Code style
+
+- Zero dependencies. If you need something, write it or use Node built-ins.
+- No transpilation. Ship what you write.
+- ESM imports (`import`/`export`). Node 18+ required.
+- Keep functions small. If a function needs a scroll, split it.
+- No emojis in code, CLI output, or reports.
+
+## Testing
+
+```bash
+node --test test/basic.test.js
+```
+
+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
+harvest: update calibration scoring algorithm
+```
+
+## License
+
+MIT. See LICENSE for details.

package/README.md

@@ -1,10 +1,27 @@
-# @grainulation/harvest
+<p align="center">
+  <img src="site/wordmark.svg" alt="Harvest" width="400">
+</p>
 
-**Are your decisions getting better?**
+<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/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>
 
-Harvest is the analytics and retrospective layer for research sprints. It looks across sprints to find patterns, score predictions, and surface knowledge that's gone stale.
+<p align="center"><strong>Are your decisions getting better?</strong></p>
 
-Learn from every decision you've made.
+Harvest is the analytics layer for research sprints. It looks across sprints to find patterns, score predictions, and surface knowledge that's gone stale.
+
+## Install
+
+```bash
+npm install -g @grainulation/harvest
+```
+
+Or use directly:
+
+```bash
+npx @grainulation/harvest analyze ./sprints/
+```
 
 ## What it does
 
@@ -15,21 +32,9 @@ Learn from every decision you've made.
 - **Sprint velocity** -- how long do sprints take, where do they stall?
 - **Retrospective reports** -- dark-themed HTML reports for the team
 
-## Install
-
-```sh
-npm install @grainulation/harvest
-```
+## Quick start
 
-Or run directly:
-
-```sh
-npx @grainulation/harvest analyze ./sprints/
-```
-
-## Usage
-
-```sh
+```bash
 # Cross-sprint claim analysis
 harvest analyze ./sprints/
 
@@ -50,52 +55,46 @@ harvest report ./sprints/ -o retrospective.html
 
 # All analyses in one pass
 harvest trends ./sprints/ --json
+
+# Start the live dashboard (SSE updates, dark theme)
+harvest serve --root ./sprints/ --port 9096
+
+# Connect to farmer for mobile monitoring
+harvest connect farmer --url http://localhost:9094
 ```
 
 ## Data format
 
 Harvest reads standard wheat sprint data:
 
-- `claims.json` -- array of typed claims with `id`, `type`, `evidence`, `status`, `text`, `created`, etc.
+- `claims.json` -- array of typed claims with `id`, `type`, `evidence`, `status`, `text`, `created`
 - `compilation.json` -- compiled sprint state (optional, enriches analysis)
 - Git history on `claims.json` -- used for velocity and timing analysis
 
-Point harvest at a directory containing sprint subdirectories, or at a single sprint directory:
-
-```
-sprints/
-  sprint-alpha/
-    claims.json
-    compilation.json
-  sprint-beta/
-    claims.json
-```
+Point harvest at a directory containing sprint subdirectories, or at a single sprint directory.
 
 ## Design
 
-- **Zero dependencies** -- Node built-in modules only (fs, path, child_process)
 - **Reads, never writes** -- harvest is a pure analysis tool; it won't modify your sprint data
 - **Git-aware** -- uses git log timestamps for velocity analysis when available
 - **Composable** -- each module (analyzer, calibration, patterns, decay, velocity) works independently
 
-## Claim types it understands
+## Zero dependencies
 
-| Type | What it means |
-|---|---|
-| `constraint` | Hard requirements, non-negotiable |
-| `factual` | Verifiable statements |
-| `estimate` | Predictions, projections, ranges |
-| `risk` | Potential failure modes |
-| `recommendation` | Proposed courses of action |
-| `feedback` | Stakeholder input |
+Node built-in modules only.
 
-## Evidence tiers (lowest to highest)
+## Part of the grainulation ecosystem
 
-1. `stated` -- someone said it
-2. `web` -- found online
-3. `documented` -- in source code or official docs
-4. `tested` -- verified via prototype or benchmark
-5. `production` -- measured from live systems
+| 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;
   }