@grainulation/grainulation 1.0.0 → 1.1.0

package/README.md

@@ -1,85 +1,71 @@
-# grainulation
+<p align="center">
+  <img src="site/wordmark.svg" alt="grainulation" width="400">
+</p>
 
-**Structured research for decisions that satisfice.**
+<p align="center">
+  <a href="https://www.npmjs.com/package/@grainulation/grainulation"><img src="https://img.shields.io/npm/v/@grainulation/grainulation?label=%40grainulation%2Fgrainulation" alt="npm version"></a>
+  <a href="https://www.npmjs.com/package/@grainulation/grainulation"><img src="https://img.shields.io/npm/dm/@grainulation/grainulation" alt="npm downloads"></a>
+  <a href="https://github.com/grainulation/grainulation/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/grainulation" alt="node"></a>
+  <a href="https://github.com/grainulation/grainulation/actions"><img src="https://github.com/grainulation/grainulation/actions/workflows/ci.yml/badge.svg" alt="CI"></a>
+  <a href="https://deepwiki.com/grainulation/grainulation"><img src="https://deepwiki.com/badge.svg" alt="Explore on DeepWiki"></a>
+</p>
 
----
+<p align="center"><strong>Structured research for decisions that satisfice.</strong></p>
 
-## Slow down and trust the process
+Most decisions fail not because the team lacked data, but because they lacked a process for turning data into evidence and evidence into conviction. Grainulation is that process.
 
-Most decisions fail not because the team lacked data, but because they lacked a process for turning data into evidence and evidence into conviction.
+You start with a question. You grow evidence: claims with types, confidence levels, and evidence tiers. You challenge what you find. You look for blind spots. And only when the evidence compiles -- when conflicts are resolved and gaps are acknowledged -- do you write the brief.
 
-Grainulation is that process.
+## Install
 
-You start with a question. Not an answer, not a hypothesis -- a question. Then you grow evidence: claims with types, confidence levels, and evidence tiers. You challenge what you find. You look for blind spots. You corroborate with external sources. And only when the evidence compiles -- when conflicts are resolved and gaps are acknowledged -- do you write the brief.
-
-The brief is not the goal. The brief is the receipt. The goal is the thinking that got you there.
-
-## The journey
-
-```mermaid
-flowchart LR
-    Q["Question"] -->|"/init"| S["Seed Claims"]
-    S -->|"/research"| C["Grow Evidence"]
-    C -->|"/compile"| B["Compile Brief"]
-    C -->|"/challenge /blind-spot"| A["Adversarial Pressure"]
-    A -->|"/witness /feedback"| C
+```bash
+npm install -g @grainulation/grainulation
 ```
 
-Every step is tracked. Every claim has provenance. Every decision is reproducible.
-
-## The ecosystem
-
-Eight tools. Each does one thing. Use what you need.
-
-| Tool | What it does | Install |
-|------|-------------|---------|
-| **wheat** | Grows evidence. Research sprint engine. | `npx @grainulation/wheat init` |
-| **farmer** | Permission dashboard. Approve AI actions in real time. | `npm i -g @grainulation/farmer` |
-| **barn** | Shared tools. Claim schemas, templates, validators. | `npm i -g @grainulation/barn` |
-| **mill** | Processes output. Export to PDF, slides, wiki. | `npm i -g @grainulation/mill` |
-| **silo** | Stores knowledge. Reusable claim libraries. | `npm i -g @grainulation/silo` |
-| **harvest** | Analytics. Cross-sprint learning and prediction scoring. | `npm i -g @grainulation/harvest` |
-| **orchard** | Orchestration. Multi-sprint coordination. | `npm i -g @grainulation/orchard` |
-| **grainulation** | The machine. Unified CLI and brand. | `npm i -g grainulation` |
-
-**You don't need all eight.** Start with wheat. That's it. One command:
+Or start a research sprint directly:
 
 ```bash
 npx @grainulation/wheat init
 ```
 
-Everything else is optional. Add tools when you feel the friction.
-
 ## Quick start
 
 ```bash
-# Start a research sprint
-npx @grainulation/wheat init
+grainulation              # Ecosystem overview
+grainulation doctor       # Health check: which tools, which versions
+grainulation setup        # Install the right tools for your role
+grainulation wheat init   # Delegate to any tool
+grainulation farmer start
+```
 
-# Or install the unified CLI first
-npm install -g @grainulation/grainulation
+## The ecosystem
 
-# See what's installed
-grainulation doctor
+Eight tools. Each does one thing. Use what you need.
 
-# Interactive setup based on your role
-grainulation setup
+| Tool                                                         | What it does                                                                  | Install                               |
+| ------------------------------------------------------------ | ----------------------------------------------------------------------------- | ------------------------------------- |
+| [wheat](https://github.com/grainulation/wheat)               | Research engine. Grow structured evidence.                                    | `npx @grainulation/wheat init`        |
+| [farmer](https://github.com/grainulation/farmer)             | Permission dashboard. Approve AI actions in real time (admin + viewer roles). | `npm i -g @grainulation/farmer`       |
+| [barn](https://github.com/grainulation/barn)                 | Shared tools. Templates, validators, sprint detection.                        | `npm i -g @grainulation/barn`         |
+| [mill](https://github.com/grainulation/mill)                 | Format conversion. Export to PDF, CSV, slides, 24 formats.                    | `npm i -g @grainulation/mill`         |
+| [silo](https://github.com/grainulation/silo)                 | Knowledge storage. Reusable claim libraries and packs.                        | `npm i -g @grainulation/silo`         |
+| [harvest](https://github.com/grainulation/harvest)           | Analytics. Cross-sprint patterns and prediction scoring.                      | `npm i -g @grainulation/harvest`      |
+| [orchard](https://github.com/grainulation/orchard)           | Orchestration. Multi-sprint coordination and dependencies.                    | `npm i -g @grainulation/orchard`      |
+| [grainulation](https://github.com/grainulation/grainulation) | Unified CLI. Single entry point to the ecosystem.                             | `npm i -g @grainulation/grainulation` |
 
-# Delegate to any tool
-grainulation wheat init
-grainulation farmer start
-```
+**You don't need all eight.** Start with wheat. That's it. One command. Everything else is optional -- add tools when you feel the friction.
 
-## The unified CLI
+## The journey
 
-```bash
-grainulation              # Ecosystem overview
-grainulation doctor       # Health check: which tools, which versions
-grainulation setup        # Install the right tools for your role
-grainulation <tool> ...   # Delegate to any grainulation tool
+```
+Question --> Seed Claims --> Grow Evidence --> Compile Brief
+  /init       /research       /challenge        /brief
+                              /blind-spot
+                              /witness
 ```
 
-The CLI is the wayfinder. It doesn't do the work -- it points you to the tool that does.
+Every step is tracked. Every claim has provenance. Every decision is reproducible.
 
 ## Philosophy
 
@@ -87,18 +73,16 @@ The CLI is the wayfinder. It doesn't do the work -- it points you to the tool th
 
 **Claims over opinions.** Every finding is a typed claim with an evidence tier. "I think" becomes "r003: factual, tested -- measured 340ms p95 latency under load."
 
-**Adversarial pressure over consensus.** The `/challenge` command exists because comfortable agreement is the enemy of good decisions. If nobody is stress-testing the claims, the research isn't done.
+**Adversarial pressure over consensus.** The `/challenge` command exists because comfortable agreement is the enemy of good decisions.
 
 **Process over heroics.** A reproducible sprint that anyone can pick up beats a brilliant analysis that lives in one person's head.
 
 ## Zero dependencies
 
-Every grainulation tool runs on Node built-ins only. No npm install waterfall. No left-pad. No supply chain anxiety. Just `node`, `fs`, `http`, and `crypto`.
+Every grainulation tool runs on Node built-ins only. No npm install waterfall. No left-pad. No supply chain anxiety.
 
 ## The name
 
-The name comes last.
-
 You build the crop (wheat), the steward (farmer), the barn, the mill, the silo, the harvest, the orchard -- and only then do you name the machine that connects them all.
 
 Grainulation: the machine that processes the grain.

package/bin/grainulation.js

@@ -1,7 +1,5 @@
 #!/usr/bin/env node
 
-'use strict';
-
 /**
  * grainulation
  *

package/lib/doctor.js

@@ -1,5 +1,3 @@
-'use strict';
-
 const { execSync } = require('node:child_process');
 const { existsSync } = require('node:fs');
 const path = require('node:path');
@@ -22,6 +20,7 @@ function checkGlobal(packageName) {
     const out = execSync(`npm list -g ${packageName} --depth=0 2>/dev/null`, {
       stdio: 'pipe',
       encoding: 'utf-8',
+      timeout: 5000,
     });
     const match = out.match(new RegExp(`${escapeRegex(packageName)}@(\\S+)`));
     return match ? { version: match[1], method: 'global' } : null;
@@ -39,6 +38,7 @@ function checkNpxCache(packageName) {
     const prefix = execSync('npm config get cache', {
       stdio: 'pipe',
       encoding: 'utf-8',
+      timeout: 5000,
     }).trim();
     const npxDir = path.join(prefix, '_npx');
     if (!existsSync(npxDir)) return null;
@@ -95,9 +95,7 @@ function checkSource(packageName) {
     path.join(process.cwd(), 'packages', packageName.replace(/^@[^/]+\//, '')),
   ];
   for (const candidate of candidates) {
-    const pkgJson = candidate.endsWith('package.json')
-      ? candidate
-      : path.join(candidate, 'package.json');
+    const pkgJson = candidate.endsWith('package.json') ? candidate : path.join(candidate, 'package.json');
     if (existsSync(pkgJson)) {
       try {
         const pkg = JSON.parse(require('node:fs').readFileSync(pkgJson, 'utf-8'));
@@ -165,16 +163,62 @@ function getNodeVersion() {
 
 function getNpmVersion() {
   try {
-    return execSync('npm --version', { stdio: 'pipe', encoding: 'utf-8' }).trim();
+    return execSync('npm --version', {
+      stdio: 'pipe',
+      encoding: 'utf-8',
+      timeout: 5000,
+    }).trim();
   } catch {
     return 'not found';
   }
 }
 
+function getPnpmVersion() {
+  try {
+    return execSync('pnpm --version', {
+      stdio: 'pipe',
+      encoding: 'utf-8',
+      timeout: 5000,
+    }).trim();
+  } catch {
+    return null;
+  }
+}
+
+function getBiomeVersion() {
+  try {
+    const out = execSync('npx biome --version', {
+      stdio: 'pipe',
+      encoding: 'utf-8',
+      timeout: 5000,
+    }).trim();
+    const match = out.match(/(\d+\.\d+\.\d+\S*)/);
+    return match ? match[1] : out;
+  } catch {
+    return null;
+  }
+}
+
+function getHooksPath() {
+  try {
+    return execSync('git config core.hooksPath', {
+      stdio: 'pipe',
+      encoding: 'utf-8',
+      timeout: 5000,
+    }).trim();
+  } catch {
+    return null;
+  }
+}
+
 function run(opts) {
-  const json = opts && opts.json;
+  const json = opts?.json;
   const tools = getInstallable();
 
+  const pnpmVersion = getPnpmVersion();
+  const biomeVersion = getBiomeVersion();
+  const hooksPath = getHooksPath();
+
   if (json) {
     const toolResults = [];
     for (const tool of tools) {
@@ -187,12 +231,20 @@ function run(opts) {
         method: result ? result.method : null,
       });
     }
-    console.log(JSON.stringify({
-      environment: { node: getNodeVersion(), npm: getNpmVersion() },
-      tools: toolResults,
-      installed: toolResults.filter((t) => t.installed).length,
-      missing: toolResults.filter((t) => !t.installed).length,
-    }));
+    console.log(
+      JSON.stringify({
+        environment: {
+          node: getNodeVersion(),
+          npm: getNpmVersion(),
+          pnpm: pnpmVersion,
+          biome: biomeVersion,
+          hooksPath: hooksPath,
+        },
+        tools: toolResults,
+        installed: toolResults.filter((t) => t.installed).length,
+        missing: toolResults.filter((t) => !t.installed).length,
+      }),
+    );
     return;
   }
 
@@ -208,6 +260,25 @@ function run(opts) {
   console.log('  \x1b[2mEnvironment:\x1b[0m');
   console.log(`    Node     ${getNodeVersion()}`);
   console.log(`    npm      v${getNpmVersion()}`);
+  if (pnpmVersion) {
+    console.log(`    pnpm     v${pnpmVersion}`);
+  } else {
+    console.log('    pnpm     \x1b[2mnot found\x1b[0m');
+  }
+  console.log('');
+
+  // DX tooling
+  console.log('  \x1b[2mDX tooling:\x1b[0m');
+  if (biomeVersion) {
+    console.log(`    \x1b[32m\u2713\x1b[0m Biome     v${biomeVersion}`);
+  } else {
+    console.log('    \x1b[2m\u2717 Biome     not found (pnpm install to set up)\x1b[0m');
+  }
+  if (hooksPath) {
+    console.log(`    \x1b[32m\u2713\x1b[0m Git hooks  ${hooksPath}`);
+  } else {
+    console.log('    \x1b[2m\u2717 Git hooks  not configured (run: git config core.hooksPath .githooks)\x1b[0m');
+  }
   console.log('');
 
   // Tools
@@ -217,9 +288,7 @@ function run(opts) {
     if (result) {
       installed++;
       const ver = `v${result.version}`.padEnd(10);
-      console.log(
-        `    \x1b[32m\u2713\x1b[0m ${tool.name.padEnd(12)} ${ver} \x1b[2m(${result.method})\x1b[0m`
-      );
+      console.log(`    \x1b[32m\u2713\x1b[0m ${tool.name.padEnd(12)} ${ver} \x1b[2m(${result.method})\x1b[0m`);
     } else {
       missing++;
       console.log(`    \x1b[2m\u2717 ${tool.name.padEnd(12)} --          (not found)\x1b[0m`);
@@ -242,4 +311,11 @@ function run(opts) {
   console.log('');
 }
 
-module.exports = { run, getVersion, detect };
+module.exports = {
+  run,
+  getVersion,
+  detect,
+  getPnpmVersion,
+  getBiomeVersion,
+  getHooksPath,
+};

package/lib/ecosystem.js

@@ -1,5 +1,3 @@
-'use strict';
-
 /**
  * The grainulation ecosystem registry.
  *

package/lib/pm.js

@@ -1,5 +1,3 @@
-'use strict';
-
 /**
  * Process Manager — start, stop, and monitor grainulation tools.
  *
@@ -7,7 +5,7 @@
  * This module spawns/kills them and probes ports for health.
  */
 
-const { spawn, execSync } = require('node:child_process');
+const { spawn, execFileSync } = require('node:child_process');
 const { existsSync, readFileSync, writeFileSync, mkdirSync } = require('node:fs');
 const { join } = require('node:path');
 const http = require('node:http');
@@ -19,7 +17,11 @@ const PID_DIR = join(PM_DIR, 'pids');
 const CONFIG_FILE = join(PM_DIR, 'config.json');
 
 function loadConfig() {
-  try { return JSON.parse(readFileSync(CONFIG_FILE, 'utf8')); } catch { return {}; }
+  try {
+    return JSON.parse(readFileSync(CONFIG_FILE, 'utf8'));
+  } catch {
+    return {};
+  }
 }
 
 function ensureDirs() {
@@ -36,7 +38,7 @@ function readPid(toolName) {
   if (!existsSync(f)) return null;
   try {
     const pid = parseInt(readFileSync(f, 'utf8').trim(), 10);
-    if (isNaN(pid)) return null;
+    if (Number.isNaN(pid)) return null;
     // Check if process is alive
     process.kill(pid, 0);
     return pid;
@@ -52,7 +54,9 @@ function writePid(toolName, pid) {
 
 function removePid(toolName) {
   const f = pidFile(toolName);
-  try { require('node:fs').unlinkSync(f); } catch {}
+  try {
+    require('node:fs').unlinkSync(f);
+  } catch {}
 }
 
 /**
@@ -69,7 +73,10 @@ function probe(port, timeoutMs = 2000) {
       resolve({ alive: true, statusCode: res.statusCode, latencyMs });
     });
     req.on('error', () => resolve({ alive: false }));
-    req.on('timeout', () => { req.destroy(); resolve({ alive: false }); });
+    req.on('timeout', () => {
+      req.destroy();
+      resolve({ alive: false });
+    });
   });
 }
 
@@ -78,10 +85,7 @@ function probe(port, timeoutMs = 2000) {
  */
 function findBin(tool) {
   const shortName = tool.package.replace(/^@[^/]+\//, '');
-  const candidates = [
-    join(__dirname, '..', '..', shortName),
-    join(process.cwd(), '..', shortName),
-  ];
+  const candidates = [join(__dirname, '..', '..', shortName), join(process.cwd(), '..', shortName)];
   for (const dir of candidates) {
     try {
       const pkgPath = join(dir, 'package.json');
@@ -97,7 +101,7 @@ function findBin(tool) {
       }
     } catch {}
   }
-  return { cmd: 'npx', args: [tool.package], shell: true };
+  return { cmd: 'npx', args: [tool.package] };
 }
 
 /**
@@ -128,7 +132,7 @@ function startTool(toolName, extraArgs = []) {
   const child = spawn(bin.cmd, args, {
     stdio: 'ignore',
     detached: true,
-    shell: bin.shell || false,
+    shell: false,
   });
 
   child.unref();
@@ -143,10 +147,18 @@ function startTool(toolName, extraArgs = []) {
  */
 function findPidByPort(port) {
   try {
-    const out = execSync(`lsof -ti :${port}`, { timeout: 3000, stdio: ['ignore', 'pipe', 'pipe'] });
-    const pids = out.toString().trim().split('\n').map(s => parseInt(s, 10)).filter(n => !isNaN(n) && n > 0);
+    const out = execFileSync('lsof', ['-ti', `:${port}`], {
+      timeout: 3000,
+      stdio: ['ignore', 'pipe', 'pipe'],
+    });
+    const pids = out
+      .toString()
+      .trim()
+      .split('\n')
+      .map((s) => parseInt(s, 10))
+      .filter((n) => !Number.isNaN(n) && n > 0);
     // Return the first PID that isn't our own process
-    return pids.find(p => p !== process.pid) || null;
+    return pids.find((p) => p !== process.pid) || null;
   } catch {
     return null;
   }
@@ -181,19 +193,21 @@ function stopTool(toolName) {
  */
 async function ps() {
   const tools = getInstallable();
-  const results = await Promise.all(tools.map(async (tool) => {
-    const pid = readPid(tool.name);
-    const health = await probe(tool.port);
-    return {
-      name: tool.name,
-      port: tool.port,
-      role: tool.role,
-      pid: pid || null,
-      alive: health.alive,
-      latencyMs: health.latencyMs || null,
-      statusCode: health.statusCode || null,
-    };
-  }));
+  const results = await Promise.all(
+    tools.map(async (tool) => {
+      const pid = readPid(tool.name);
+      const health = await probe(tool.port);
+      return {
+        name: tool.name,
+        port: tool.port,
+        role: tool.role,
+        pid: pid || null,
+        alive: health.alive,
+        latencyMs: health.latencyMs || null,
+        statusCode: health.statusCode || null,
+      };
+    }),
+  );
   return results;
 }
 
@@ -203,8 +217,12 @@ async function ps() {
  */
 function up(toolNames, extraArgs = []) {
   const defaults = ['farmer', 'wheat'];
-  const names = (!toolNames || toolNames.length === 0) ? defaults :
-    (toolNames[0] === 'all' ? getInstallable().map(t => t.name) : toolNames);
+  const names =
+    !toolNames || toolNames.length === 0
+      ? defaults
+      : toolNames[0] === 'all'
+        ? getInstallable().map((t) => t.name)
+        : toolNames;
 
   const results = [];
   for (const name of names) {
@@ -222,9 +240,7 @@ function up(toolNames, extraArgs = []) {
  * Stop multiple tools. Default: stop all running.
  */
 function down(toolNames) {
-  const names = (!toolNames || toolNames.length === 0)
-    ? getInstallable().map(t => t.name)
-    : toolNames;
+  const names = !toolNames || toolNames.length === 0 ? getInstallable().map((t) => t.name) : toolNames;
 
   const results = [];
   for (const name of names) {