@grainulation/harvest 1.0.0 → 1.0.1

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,87 @@
+# 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,26 @@
-# @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/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>
+</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 +31,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 +54,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/lib/server.js

@@ -81,7 +81,7 @@ const { analyze } = require('./analyzer.js');
 const { measureVelocity } = require('./velocity.js');
 const { checkDecay } = require('./decay.js');
 const { calibrate } = require('./calibration.js');
-const { loadSprints: loadDashboardSprints, buildHtml, claimsPaths } = require('./dashboard.js');
+const { claimsPaths } = require('./dashboard.js');
 
 // ── Sprint discovery ─────────────────────────────────────────────────────────
 
@@ -204,38 +204,6 @@ function jsonResponse(res, code, data) {
   res.end(JSON.stringify(data));
 }
 
-// ── SSE live-reload injection ────────────────────────────────────────────────
-
-const SSE_SCRIPT = `
-<script>
-(function() {
-  var es, retryCount = 0;
-  var dot = document.getElementById('statusDot');
-  function connect() {
-    es = new EventSource('/events');
-    es.addEventListener('update', function() { location.reload(); });
-    es.onopen = function() {
-      retryCount = 0;
-      if (dot) dot.className = 'status-dot ok';
-      if (window._grainSetState) window._grainSetState('idle');
-    };
-    es.onerror = function() {
-      es.close();
-      if (dot) dot.className = 'status-dot';
-      if (window._grainSetState) window._grainSetState('orbit');
-      var delay = Math.min(30000, 1000 * Math.pow(2, retryCount)) + Math.random() * 1000;
-      retryCount++;
-      setTimeout(connect, delay);
-    };
-  }
-  connect();
-})();
-</script>`;
-
-function injectSSE(html) {
-  return html.replace('</body>', SSE_SCRIPT + '\n</body>');
-}
-
 // ── HTTP server ───────────────────────────────────────────────────────────────
 
 const server = createServer(async (req, res) => {
@@ -375,21 +343,16 @@ ${ROUTES.map(r => '<tr><td><code>'+r.method+'</code></td><td><code>'+r.path+'</c
     return;
   }
 
-  // ── Dashboard UI (template-injected) ──
+  // ── Dashboard UI (web app from public/) ──
   if (req.method === 'GET' && (url.pathname === '/' || url.pathname === '/index.html')) {
+    const indexPath = join(PUBLIC_DIR, 'index.html');
     try {
-      const sprints = loadDashboardSprints(ROOT);
-      if (sprints.length === 0) {
-        res.writeHead(200, { 'Content-Type': 'text/html; charset=utf-8' });
-        res.end('<html><body style="background:#0a0e1a;color:#e2e8f0;font-family:monospace;padding:40px"><h1>No claims.json files found</h1><p>Watching for changes...</p>' + SSE_SCRIPT + '</body></html>');
-        return;
-      }
-      const html = injectSSE(buildHtml(sprints));
+      const html = readFileSync(indexPath, 'utf8');
       res.writeHead(200, { 'Content-Type': 'text/html; charset=utf-8' });
       res.end(html);
     } catch (err) {
       res.writeHead(500, { 'Content-Type': 'text/plain' });
-      res.end('Error building dashboard: ' + err.message);
+      res.end('Error reading dashboard: ' + err.message);
     }
     return;
   }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@grainulation/harvest",
-  "version": "1.0.0",
+  "version": "1.0.1",
   "description": "Analytics and retrospective layer for research sprints -- learn from every decision you've made",
   "main": "lib/analyzer.js",
   "exports": {
@@ -35,7 +35,9 @@
     "public/",
     "templates/",
     "README.md",
-    "LICENSE"
+    "LICENSE",
+    "CODE_OF_CONDUCT.md",
+    "CONTRIBUTING.md"
   ],
   "engines": {
     "node": ">=18.0.0"