@grainulation/grainulation 1.0.0 → 1.0.1

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" 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
  *
@@ -16,37 +14,38 @@
  *   grainulation <tool> [args]    Delegate to a grainulation tool
  */
 
-const verbose = process.argv.includes('--verbose') || process.argv.includes('-v');
-const jsonMode = process.argv.includes('--json');
+const verbose =
+  process.argv.includes("--verbose") || process.argv.includes("-v");
+const jsonMode = process.argv.includes("--json");
 function vlog(...a) {
   if (!verbose) return;
   const ts = new Date().toISOString();
-  process.stderr.write(`[${ts}] grainulation: ${a.join(' ')}\n`);
+  process.stderr.write(`[${ts}] grainulation: ${a.join(" ")}\n`);
 }
 
 const command = process.argv[2];
-vlog('startup', `command=${command || '(none)'}`, `cwd=${process.cwd()}`);
+vlog("startup", `command=${command || "(none)"}`, `cwd=${process.cwd()}`);
 
 // Serve command — start the HTTP server (ESM module)
-if (command === 'serve') {
-  const path = require('node:path');
-  const { spawn } = require('node:child_process');
-  const serverPath = path.join(__dirname, '..', 'lib', 'server.mjs');
+if (command === "serve") {
+  const path = require("node:path");
+  const { spawn } = require("node:child_process");
+  const serverPath = path.join(__dirname, "..", "lib", "server.mjs");
 
   // Forward remaining args to the server
   const serverArgs = process.argv.slice(3);
   const child = spawn(process.execPath, [serverPath, ...serverArgs], {
-    stdio: 'inherit',
+    stdio: "inherit",
   });
 
-  child.on('close', (code) => process.exit(code ?? 0));
-  child.on('error', (err) => {
+  child.on("close", (code) => process.exit(code ?? 0));
+  child.on("error", (err) => {
     console.error(`grainulation: failed to start server: ${err.message}`);
     process.exit(1);
   });
 } else {
-  const { route } = require('../lib/router');
+  const { route } = require("../lib/router");
   // Strip --json from args before routing (it's handled as a mode flag)
-  const args = process.argv.slice(2).filter((a) => a !== '--json');
+  const args = process.argv.slice(2).filter((a) => a !== "--json");
   route(args, { json: jsonMode });
 }

package/lib/doctor.js

@@ -1,9 +1,7 @@
-'use strict';
-
-const { execSync } = require('node:child_process');
-const { existsSync } = require('node:fs');
-const path = require('node:path');
-const { getInstallable } = require('./ecosystem');
+const { execSync } = require("node:child_process");
+const { existsSync } = require("node:fs");
+const path = require("node:path");
+const { getInstallable } = require("./ecosystem");
 
 /**
  * Health check.
@@ -20,11 +18,12 @@ const { getInstallable } = require('./ecosystem');
 function checkGlobal(packageName) {
   try {
     const out = execSync(`npm list -g ${packageName} --depth=0 2>/dev/null`, {
-      stdio: 'pipe',
-      encoding: 'utf-8',
+      stdio: "pipe",
+      encoding: "utf-8",
+      timeout: 5000,
     });
     const match = out.match(new RegExp(`${escapeRegex(packageName)}@(\\S+)`));
-    return match ? { version: match[1], method: 'global' } : null;
+    return match ? { version: match[1], method: "global" } : null;
   } catch {
     return null;
   }
@@ -36,25 +35,34 @@ function checkGlobal(packageName) {
  */
 function checkNpxCache(packageName) {
   try {
-    const prefix = execSync('npm config get cache', {
-      stdio: 'pipe',
-      encoding: 'utf-8',
+    const prefix = execSync("npm config get cache", {
+      stdio: "pipe",
+      encoding: "utf-8",
+      timeout: 5000,
     }).trim();
-    const npxDir = path.join(prefix, '_npx');
+    const npxDir = path.join(prefix, "_npx");
     if (!existsSync(npxDir)) return null;
 
     // npx cache has hash-named directories, each with node_modules
-    const { readdirSync } = require('node:fs');
+    const { readdirSync } = require("node:fs");
     const entries = readdirSync(npxDir, { withFileTypes: true });
     for (const entry of entries) {
       if (!entry.isDirectory()) continue;
-      const pkgJson = path.join(npxDir, entry.name, 'node_modules', packageName, 'package.json');
+      const pkgJson = path.join(
+        npxDir,
+        entry.name,
+        "node_modules",
+        packageName,
+        "package.json",
+      );
       if (existsSync(pkgJson)) {
         try {
-          const pkg = JSON.parse(require('node:fs').readFileSync(pkgJson, 'utf-8'));
-          return { version: pkg.version || 'installed', method: 'npx cache' };
+          const pkg = JSON.parse(
+            require("node:fs").readFileSync(pkgJson, "utf-8"),
+          );
+          return { version: pkg.version || "installed", method: "npx cache" };
         } catch {
-          return { version: 'installed', method: 'npx cache' };
+          return { version: "installed", method: "npx cache" };
         }
       }
     }
@@ -70,10 +78,15 @@ function checkNpxCache(packageName) {
  */
 function checkLocal(packageName) {
   try {
-    const pkgJson = path.join(process.cwd(), 'node_modules', packageName, 'package.json');
+    const pkgJson = path.join(
+      process.cwd(),
+      "node_modules",
+      packageName,
+      "package.json",
+    );
     if (existsSync(pkgJson)) {
-      const pkg = JSON.parse(require('node:fs').readFileSync(pkgJson, 'utf-8'));
-      return { version: pkg.version || 'installed', method: 'local' };
+      const pkg = JSON.parse(require("node:fs").readFileSync(pkgJson, "utf-8"));
+      return { version: pkg.version || "installed", method: "local" };
     }
     return null;
   } catch {
@@ -89,20 +102,27 @@ function checkLocal(packageName) {
 function checkSource(packageName) {
   const candidates = [
     // Sibling directory (monorepo or co-located checkouts)
-    path.join(process.cwd(), '..', packageName.replace(/^@[^/]+\//, '')),
-    path.join(process.cwd(), '..', packageName.replace(/^@[^/]+\//, ''), 'package.json'),
+    path.join(process.cwd(), "..", packageName.replace(/^@[^/]+\//, "")),
+    path.join(
+      process.cwd(),
+      "..",
+      packageName.replace(/^@[^/]+\//, ""),
+      "package.json",
+    ),
     // Packages dir (monorepo)
-    path.join(process.cwd(), 'packages', packageName.replace(/^@[^/]+\//, '')),
+    path.join(process.cwd(), "packages", packageName.replace(/^@[^/]+\//, "")),
   ];
   for (const candidate of candidates) {
-    const pkgJson = candidate.endsWith('package.json')
+    const pkgJson = candidate.endsWith("package.json")
       ? candidate
-      : path.join(candidate, 'package.json');
+      : path.join(candidate, "package.json");
     if (existsSync(pkgJson)) {
       try {
-        const pkg = JSON.parse(require('node:fs').readFileSync(pkgJson, 'utf-8'));
+        const pkg = JSON.parse(
+          require("node:fs").readFileSync(pkgJson, "utf-8"),
+        );
         if (pkg.name === packageName) {
-          return { version: pkg.version || 'installed', method: 'source' };
+          return { version: pkg.version || "installed", method: "source" };
         }
       } catch {
         // not a match, continue
@@ -119,21 +139,24 @@ function checkSource(packageName) {
  */
 function checkNpxNoInstall(packageName) {
   try {
-    const out = execSync(`npx --no-install ${packageName} --version 2>/dev/null`, {
-      stdio: 'pipe',
-      encoding: 'utf-8',
-      timeout: 5000,
-    }).trim();
+    const out = execSync(
+      `npx --no-install ${packageName} --version 2>/dev/null`,
+      {
+        stdio: "pipe",
+        encoding: "utf-8",
+        timeout: 5000,
+      },
+    ).trim();
     // Expect a version-like string
     const match = out.match(/v?(\d+\.\d+\.\d+\S*)/);
-    return match ? { version: match[1], method: 'npx' } : null;
+    return match ? { version: match[1], method: "npx" } : null;
   } catch {
     return null;
   }
 }
 
 function escapeRegex(str) {
-  return str.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+  return str.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
 }
 
 /**
@@ -165,9 +188,51 @@ 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 'not found';
+    return null;
+  }
+}
+
+function getHooksPath() {
+  try {
+    return execSync("git config core.hooksPath", {
+      stdio: "pipe",
+      encoding: "utf-8",
+      timeout: 5000,
+    }).trim();
+  } catch {
+    return null;
   }
 }
 
@@ -175,6 +240,10 @@ function run(opts) {
   const json = opts && opts.json;
   const tools = getInstallable();
 
+  const pnpmVersion = getPnpmVersion();
+  const biomeVersion = getBiomeVersion();
+  const hooksPath = getHooksPath();
+
   if (json) {
     const toolResults = [];
     for (const tool of tools) {
@@ -187,59 +256,103 @@ 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;
   }
 
   let installed = 0;
   let missing = 0;
 
-  console.log('');
-  console.log('  \x1b[1;33mgrainulation doctor\x1b[0m');
-  console.log('  Checking ecosystem health...');
-  console.log('');
+  console.log("");
+  console.log("  \x1b[1;33mgrainulation doctor\x1b[0m");
+  console.log("  Checking ecosystem health...");
+  console.log("");
 
   // Environment
-  console.log('  \x1b[2mEnvironment:\x1b[0m');
+  console.log("  \x1b[2mEnvironment:\x1b[0m");
   console.log(`    Node     ${getNodeVersion()}`);
   console.log(`    npm      v${getNpmVersion()}`);
-  console.log('');
+  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
-  console.log('  \x1b[2mTools:\x1b[0m');
+  console.log("  \x1b[2mTools:\x1b[0m");
   for (const tool of tools) {
     const result = detect(tool.package);
     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`
+        `    \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`);
+      console.log(
+        `    \x1b[2m\u2717 ${tool.name.padEnd(12)} --          (not found)\x1b[0m`,
+      );
     }
   }
 
-  console.log('');
+  console.log("");
 
   // Summary
   if (missing === tools.length) {
-    console.log('  \x1b[33mNo grainulation tools found.\x1b[0m');
-    console.log('  Start with: npx @grainulation/wheat init');
+    console.log("  \x1b[33mNo grainulation tools found.\x1b[0m");
+    console.log("  Start with: npx @grainulation/wheat init");
   } else if (missing > 0) {
-    console.log(`  \x1b[32m${installed} found\x1b[0m, \x1b[2m${missing} not found\x1b[0m`);
-    console.log('  Run \x1b[1mgrainulation setup\x1b[0m to install what you need.');
+    console.log(
+      `  \x1b[32m${installed} found\x1b[0m, \x1b[2m${missing} not found\x1b[0m`,
+    );
+    console.log(
+      "  Run \x1b[1mgrainulation setup\x1b[0m to install what you need.",
+    );
   } else {
-    console.log('  \x1b[32mAll tools found. Full ecosystem ready.\x1b[0m');
+    console.log("  \x1b[32mAll tools found. Full ecosystem ready.\x1b[0m");
   }
 
-  console.log('');
+  console.log("");
 }
 
-module.exports = { run, getVersion, detect };
+module.exports = {
+  run,
+  getVersion,
+  detect,
+  getPnpmVersion,
+  getBiomeVersion,
+  getHooksPath,
+};