@grainulation/grainulation 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 grainulation contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,108 @@
+# grainulation
+
+**Structured research for decisions that satisfice.**
+
+---
+
+## 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.
+
+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
+```
+
+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:
+
+```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
+
+# Or install the unified CLI first
+npm install -g @grainulation/grainulation
+
+# See what's installed
+grainulation doctor
+
+# Interactive setup based on your role
+grainulation setup
+
+# Delegate to any tool
+grainulation wheat init
+grainulation farmer start
+```
+
+## The unified CLI
+
+```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
+```
+
+The CLI is the wayfinder. It doesn't do the work -- it points you to the tool that does.
+
+## Philosophy
+
+**Satisficing over maximizing.** You will never have perfect information. The goal is enough evidence to make a defensible decision, not a perfect one.
+
+**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.
+
+**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`.
+
+## 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.
+
+## License
+
+MIT

package/bin/grainulation.js

@@ -0,0 +1,52 @@
+#!/usr/bin/env node
+
+'use strict';
+
+/**
+ * grainulation
+ *
+ * The unified entry point for the grainulation ecosystem.
+ * Routes to the right tool based on what you need.
+ *
+ * Usage:
+ *   grainulation                  Show ecosystem overview
+ *   grainulation doctor           Check which tools are installed
+ *   grainulation setup            Interactive setup wizard
+ *   grainulation serve            Start the ecosystem control center
+ *   grainulation <tool> [args]    Delegate to a grainulation tool
+ */
+
+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`);
+}
+
+const command = process.argv[2];
+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');
+
+  // Forward remaining args to the server
+  const serverArgs = process.argv.slice(3);
+  const child = spawn(process.execPath, [serverPath, ...serverArgs], {
+    stdio: 'inherit',
+  });
+
+  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');
+  // Strip --json from args before routing (it's handled as a mode flag)
+  const args = process.argv.slice(2).filter((a) => a !== '--json');
+  route(args, { json: jsonMode });
+}

package/lib/doctor.js

@@ -0,0 +1,245 @@
+'use strict';
+
+const { execSync } = require('node:child_process');
+const { existsSync } = require('node:fs');
+const path = require('node:path');
+const { getInstallable } = require('./ecosystem');
+
+/**
+ * Health check.
+ *
+ * Scans the system for installed grainulation tools using multiple
+ * detection methods: global npm, npx cache, local node_modules,
+ * source checkout, and npx --no-install availability.
+ */
+
+/**
+ * Try to detect a package via global npm install.
+ * Returns { version, method } or null.
+ */
+function checkGlobal(packageName) {
+  try {
+    const out = execSync(`npm list -g ${packageName} --depth=0 2>/dev/null`, {
+      stdio: 'pipe',
+      encoding: 'utf-8',
+    });
+    const match = out.match(new RegExp(`${escapeRegex(packageName)}@(\\S+)`));
+    return match ? { version: match[1], method: 'global' } : null;
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Check if the package exists in the npx cache (_npx directories).
+ * Returns { version, method } or null.
+ */
+function checkNpxCache(packageName) {
+  try {
+    const prefix = execSync('npm config get cache', {
+      stdio: 'pipe',
+      encoding: 'utf-8',
+    }).trim();
+    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 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');
+      if (existsSync(pkgJson)) {
+        try {
+          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 null;
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Check if the package exists in local node_modules (project-level install).
+ * Returns { version, method } or null.
+ */
+function checkLocal(packageName) {
+  try {
+    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' };
+    }
+    return null;
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Check if the package is being run from a source/git checkout.
+ * Looks for package.json in common source locations.
+ * Returns { version, method } or null.
+ */
+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'),
+    // Packages dir (monorepo)
+    path.join(process.cwd(), 'packages', packageName.replace(/^@[^/]+\//, '')),
+  ];
+  for (const candidate of candidates) {
+    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'));
+        if (pkg.name === packageName) {
+          return { version: pkg.version || 'installed', method: 'source' };
+        }
+      } catch {
+        // not a match, continue
+      }
+    }
+  }
+  return null;
+}
+
+/**
+ * Try `npx --no-install <package> --version` to check availability
+ * without downloading anything.
+ * Returns { version, method } or null.
+ */
+function checkNpxNoInstall(packageName) {
+  try {
+    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;
+  } catch {
+    return null;
+  }
+}
+
+function escapeRegex(str) {
+  return str.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+}
+
+/**
+ * Detect a package using all available methods, in priority order.
+ * Returns { version, method } or null.
+ */
+function detect(packageName) {
+  return (
+    checkGlobal(packageName) ||
+    checkNpxCache(packageName) ||
+    checkLocal(packageName) ||
+    checkSource(packageName) ||
+    checkNpxNoInstall(packageName)
+  );
+}
+
+/**
+ * Legacy API: returns version string or null.
+ * Kept for backward compatibility with tests.
+ */
+function getVersion(packageName) {
+  const result = detect(packageName);
+  return result ? result.version : null;
+}
+
+function getNodeVersion() {
+  return process.version;
+}
+
+function getNpmVersion() {
+  try {
+    return execSync('npm --version', { stdio: 'pipe', encoding: 'utf-8' }).trim();
+  } catch {
+    return 'not found';
+  }
+}
+
+function run(opts) {
+  const json = opts && opts.json;
+  const tools = getInstallable();
+
+  if (json) {
+    const toolResults = [];
+    for (const tool of tools) {
+      const result = detect(tool.package);
+      toolResults.push({
+        name: tool.name,
+        package: tool.package,
+        installed: !!result,
+        version: result ? result.version : null,
+        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,
+    }));
+    return;
+  }
+
+  let installed = 0;
+  let missing = 0;
+
+  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(`    Node     ${getNodeVersion()}`);
+  console.log(`    npm      v${getNpmVersion()}`);
+  console.log('');
+
+  // Tools
+  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`
+      );
+    } else {
+      missing++;
+      console.log(`    \x1b[2m\u2717 ${tool.name.padEnd(12)} --          (not found)\x1b[0m`);
+    }
+  }
+
+  console.log('');
+
+  // Summary
+  if (missing === tools.length) {
+    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.');
+  } else {
+    console.log('  \x1b[32mAll tools found. Full ecosystem ready.\x1b[0m');
+  }
+
+  console.log('');
+}
+
+module.exports = { run, getVersion, detect };

package/lib/ecosystem.js

@@ -0,0 +1,122 @@
+'use strict';
+
+/**
+ * The grainulation ecosystem registry.
+ *
+ * Eight tools. Each grows from the same soil:
+ * question -> evidence -> decision.
+ */
+
+const TOOLS = [
+  {
+    name: 'wheat',
+    package: '@grainulation/wheat',
+    icon: 'W',
+    role: 'Grows evidence',
+    description: 'Research sprint engine. Ask a question, grow claims, compile a brief.',
+    category: 'core',
+    port: 9091,
+    serveCmd: ['serve'],
+    entryPoint: true,
+  },
+  {
+    name: 'farmer',
+    package: '@grainulation/farmer',
+    icon: 'F',
+    role: 'Permission dashboard',
+    description: 'Permission dashboard. Approve tool calls, review AI actions in real time.',
+    category: 'core',
+    port: 9090,
+    serveCmd: ['start'],
+    entryPoint: false,
+  },
+  {
+    name: 'barn',
+    package: '@grainulation/barn',
+    icon: 'B',
+    role: 'Shared tools',
+    description: 'Public utilities. Claim schemas, HTML templates, shared validators.',
+    category: 'foundation',
+    port: 9093,
+    serveCmd: ['serve'],
+    entryPoint: false,
+  },
+  {
+    name: 'mill',
+    package: '@grainulation/mill',
+    icon: 'M',
+    role: 'Processes output',
+    description: 'Export and publish. Turn compiled research into PDFs, slides, wikis.',
+    category: 'output',
+    port: 9094,
+    serveCmd: ['serve'],
+    entryPoint: false,
+  },
+  {
+    name: 'silo',
+    package: '@grainulation/silo',
+    icon: 'S',
+    role: 'Stores knowledge',
+    description: 'Reusable claim libraries. Share vetted claims across sprints and teams.',
+    category: 'storage',
+    port: 9095,
+    serveCmd: ['serve'],
+    entryPoint: false,
+  },
+  {
+    name: 'harvest',
+    package: '@grainulation/harvest',
+    icon: 'H',
+    role: 'Analytics & retrospectives',
+    description: 'Cross-sprint learning. Track prediction accuracy, find blind spots over time.',
+    category: 'analytics',
+    port: 9096,
+    serveCmd: ['serve'],
+    entryPoint: false,
+  },
+  {
+    name: 'orchard',
+    package: '@grainulation/orchard',
+    icon: 'O',
+    role: 'Orchestration',
+    description: 'Multi-sprint coordination. Run parallel research tracks, merge results.',
+    category: 'orchestration',
+    port: 9097,
+    serveCmd: ['serve'],
+    entryPoint: false,
+  },
+  {
+    name: 'grainulation',
+    package: '@grainulation/grainulation',
+    icon: 'G',
+    role: 'The machine',
+    description: 'Process manager and ecosystem hub. Start, stop, and monitor all tools.',
+    category: 'meta',
+    port: 9098,
+    serveCmd: ['serve'],
+    entryPoint: false,
+  },
+];
+
+function getAll() {
+  return TOOLS;
+}
+
+function getByName(name) {
+  return TOOLS.find((t) => t.name === name);
+}
+
+function getInstallable() {
+  return TOOLS.filter((t) => t.name !== 'grainulation');
+}
+
+function getCategories() {
+  const cats = {};
+  for (const tool of TOOLS) {
+    if (!cats[tool.category]) cats[tool.category] = [];
+    cats[tool.category].push(tool);
+  }
+  return cats;
+}
+
+module.exports = { TOOLS, getAll, getByName, getInstallable, getCategories };