@grainulation/orchard 1.0.1 → 1.0.2

package/CONTRIBUTING.md

@@ -15,16 +15,20 @@ No `npm install` needed -- orchard 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
@@ -74,11 +78,13 @@ Tests use Node's built-in test runner. No test framework dependencies.
 ## Commit messages
 
 Follow the existing pattern:
+
 ```
 orchard: <what changed>
 ```
 
 Examples:
+
 ```
 orchard: add cross-sprint dependency graph
 orchard: fix timeline calculation for overlapping sprints

package/README.md

@@ -3,7 +3,8 @@
 </p>
 
 <p align="center">
-  <a href="https://www.npmjs.com/package/@grainulation/orchard"><img src="https://img.shields.io/npm/v/@grainulation/orchard" alt="npm version"></a> <a href="https://www.npmjs.com/package/@grainulation/orchard"><img src="https://img.shields.io/npm/dm/@grainulation/orchard" alt="npm downloads"></a> <a href="https://github.com/grainulation/orchard/blob/main/LICENSE"><img src="https://img.shields.io/npm/l/@grainulation/orchard" alt="license"></a> <a href="https://nodejs.org"><img src="https://img.shields.io/node/v/@grainulation/orchard" alt="node"></a> <a href="https://github.com/grainulation/orchard/actions"><img src="https://github.com/grainulation/orchard/actions/workflows/ci.yml/badge.svg" alt="CI"></a>
+  <a href="https://www.npmjs.com/package/@grainulation/orchard"><img src="https://img.shields.io/npm/v/@grainulation/orchard" alt="npm version"></a> <a href="https://www.npmjs.com/package/@grainulation/orchard"><img src="https://img.shields.io/npm/dm/@grainulation/orchard" alt="npm downloads"></a> <a href="https://github.com/grainulation/orchard/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/orchard" alt="node"></a> <a href="https://github.com/grainulation/orchard/actions"><img src="https://github.com/grainulation/orchard/actions/workflows/ci.yml/badge.svg" alt="CI"></a>
+  <a href="https://deepwiki.com/grainulation/orchard"><img src="https://deepwiki.com/badge.svg" alt="Explore on DeepWiki"></a>
 </p>
 
 <p align="center"><strong>Multi-sprint orchestration and dependency tracking.</strong></p>
@@ -69,15 +70,15 @@ orchard dashboard   # Generate unified HTML dashboard
 
 ## CLI
 
-| Command | Description |
-|---------|-------------|
-| `orchard plan` | Show sprint dependency graph |
-| `orchard status` | Show status of all tracked sprints |
-| `orchard assign <path> <person>` | Assign a person to a sprint |
-| `orchard sync` | Sync sprint states from directories |
-| `orchard dashboard [outfile]` | Generate unified HTML dashboard |
-| `orchard init` | Initialize orchard.json |
-| `orchard serve` | Start the portfolio dashboard web server |
+| Command                          | Description                              |
+| -------------------------------- | ---------------------------------------- |
+| `orchard plan`                   | Show sprint dependency graph             |
+| `orchard status`                 | Show status of all tracked sprints       |
+| `orchard assign <path> <person>` | Assign a person to a sprint              |
+| `orchard sync`                   | Sync sprint states from directories      |
+| `orchard dashboard [outfile]`    | Generate unified HTML dashboard          |
+| `orchard init`                   | Initialize orchard.json                  |
+| `orchard serve`                  | Start the portfolio dashboard web server |
 
 ## Conflict detection
 
@@ -92,16 +93,16 @@ Node built-in modules only.
 
 ## Part of the grainulation ecosystem
 
-| 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](https://github.com/grainulation/harvest) | Analytics -- cross-sprint patterns and prediction scoring |
-| **orchard** | Orchestration -- multi-sprint coordination and dependencies |
-| [grainulation](https://github.com/grainulation/grainulation) | Unified CLI -- single entry point to the ecosystem |
+| 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](https://github.com/grainulation/harvest)           | Analytics -- cross-sprint patterns and prediction scoring   |
+| **orchard**                                                  | Orchestration -- multi-sprint coordination and dependencies |
+| [grainulation](https://github.com/grainulation/grainulation) | Unified CLI -- single entry point to the ecosystem          |
 
 ## License
 

package/bin/orchard.js

@@ -1,74 +1,78 @@
 #!/usr/bin/env node
-'use strict';
+"use strict";
 
-const path = require('node:path');
-const fs = require('node:fs');
+const path = require("node:path");
+const fs = require("node:fs");
 
-const verbose = process.argv.includes('--verbose') || process.argv.includes('-v');
+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}] orchard: ${a.join(' ')}\n`);
+  process.stderr.write(`[${ts}] orchard: ${a.join(" ")}\n`);
 }
 
 const COMMANDS = {
-  init: 'Initialize orchard.json in the current directory',
-  plan: 'Show sprint dependency graph as ASCII',
-  status: 'Show status of all tracked sprints',
-  assign: 'Assign a person to a sprint',
-  sync: 'Sync sprint states from their directories',
-  dashboard: 'Generate unified HTML dashboard',
-  serve: 'Start the portfolio dashboard web server',
-  connect: 'Connect to a farmer instance',
-  doctor: 'Check health of orchard setup',
-  help: 'Show this help message',
+  init: "Initialize orchard.json in the current directory",
+  plan: "Show sprint dependency graph (--format mermaid|ascii, --mermaid)",
+  status: "Show status of all tracked sprints",
+  conflicts: "Show cross-sprint conflicts (--severity critical|warning|info)",
+  assign: "Assign a person to a sprint",
+  sync: "Sync sprint states from their directories",
+  decompose: "Auto-decompose a question into sub-sprints",
+  hackathon: "Hackathon coordinator (init|team|status|end)",
+  dashboard: "Generate unified HTML dashboard",
+  serve: "Start the portfolio dashboard web server",
+  connect: "Connect to a farmer instance",
+  doctor: "Check health of orchard setup",
+  help: "Show this help message",
 };
 
 function loadConfig(dir) {
-  const configPath = path.join(dir, 'orchard.json');
+  const configPath = path.join(dir, "orchard.json");
   if (!fs.existsSync(configPath)) {
     return null;
   }
-  return JSON.parse(fs.readFileSync(configPath, 'utf8'));
+  return JSON.parse(fs.readFileSync(configPath, "utf8"));
 }
 
 function findOrchardRoot() {
   let dir = process.cwd();
   while (dir !== path.dirname(dir)) {
-    if (fs.existsSync(path.join(dir, 'orchard.json'))) return dir;
+    if (fs.existsSync(path.join(dir, "orchard.json"))) return dir;
     dir = path.dirname(dir);
   }
   return null;
 }
 
 function printHelp() {
-  console.log('');
-  console.log('  orchard - Multi-sprint research orchestrator');
-  console.log('');
-  console.log('  Usage: orchard <command> [options]');
-  console.log('');
-  console.log('  Commands:');
+  console.log("");
+  console.log("  orchard - Multi-sprint research orchestrator");
+  console.log("");
+  console.log("  Usage: orchard <command> [options]");
+  console.log("");
+  console.log("  Commands:");
   for (const [cmd, desc] of Object.entries(COMMANDS)) {
     console.log(`    ${cmd.padEnd(12)} ${desc}`);
   }
-  console.log('');
-  console.log('  Serve options:');
-  console.log('    --port 9097    Port for the web server (default: 9097)');
-  console.log('    --root <dir>   Root directory to scan for sprints');
-  console.log('');
-  console.log('  Connect:');
-  console.log('    orchard connect farmer --url http://localhost:9090');
-  console.log('');
-  console.log('  Config: orchard.json in project root');
-  console.log('');
+  console.log("");
+  console.log("  Serve options:");
+  console.log("    --port 9097    Port for the web server (default: 9097)");
+  console.log("    --root <dir>   Root directory to scan for sprints");
+  console.log("");
+  console.log("  Connect:");
+  console.log("    orchard connect farmer --url http://localhost:9090");
+  console.log("");
+  console.log("  Config: orchard.json in project root");
+  console.log("");
 }
 
 async function main() {
   const args = process.argv.slice(2);
-  const command = args[0] || 'help';
-  vlog('startup', `command=${command}`, `cwd=${process.cwd()}`);
+  const command = args[0] || "help";
+  vlog("startup", `command=${command}`, `cwd=${process.cwd()}`);
 
-  if (command === 'help' || command === '--help' || command === '-h') {
+  if (command === "help" || command === "--help" || command === "-h") {
     printHelp();
     process.exit(0);
   }
@@ -80,30 +84,30 @@ async function main() {
   }
 
   // Serve command — start the HTTP server (ESM module)
-  if (command === 'serve') {
-    const serverPath = path.join(__dirname, '..', 'lib', 'server.js');
-    const { spawn } = require('node:child_process');
+  if (command === "serve") {
+    const serverPath = path.join(__dirname, "..", "lib", "server.js");
+    const { spawn } = require("node:child_process");
 
     // Forward remaining args to the server
     const serverArgs = args.slice(1);
     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(`orchard: failed to start server: ${err.message}`);
       process.exit(1);
     });
-    process.on('SIGTERM', () => child.kill('SIGTERM'));
-    process.on('SIGINT', () => child.kill('SIGINT'));
+    process.on("SIGTERM", () => child.kill("SIGTERM"));
+    process.on("SIGINT", () => child.kill("SIGINT"));
     return;
   }
 
-  if (command === 'connect') {
-    const { connect: farmerConnect } = require('../lib/farmer.js');
-    const connectArgs = process.argv.slice(process.argv.indexOf('connect') + 1);
-    const rootIdx = connectArgs.indexOf('--root');
+  if (command === "connect") {
+    const { connect: farmerConnect } = require("../lib/farmer.js");
+    const connectArgs = process.argv.slice(process.argv.indexOf("connect") + 1);
+    const rootIdx = connectArgs.indexOf("--root");
     let targetDir = process.cwd();
     if (rootIdx !== -1 && connectArgs[rootIdx + 1]) {
       targetDir = path.resolve(connectArgs[rootIdx + 1]);
@@ -112,85 +116,228 @@ async function main() {
     return;
   }
 
-  if (command === 'init') {
-    const { parseArgs } = require('node:util');
+  if (command === "init") {
+    const { parseArgs } = require("node:util");
     let rootDir = process.cwd();
     try {
-      const { values } = parseArgs({ args: process.argv.slice(3), options: { root: { type: 'string' } }, allowPositionals: true });
+      const { values } = parseArgs({
+        args: process.argv.slice(3),
+        options: { root: { type: "string" } },
+        allowPositionals: true,
+      });
       if (values.root) rootDir = path.resolve(values.root);
-    } catch (_) { /* ignore parse errors for init */ }
-    const configPath = path.join(rootDir, 'orchard.json');
+    } catch (_) {
+      /* ignore parse errors for init */
+    }
+    const configPath = path.join(rootDir, "orchard.json");
     if (fs.existsSync(configPath)) {
-      console.error('orchard: orchard.json already exists');
+      console.error("orchard: orchard.json already exists");
       process.exit(1);
     }
-    const defaultConfig = { sprints: [], settings: { sync_interval: 'manual' } };
-    fs.writeFileSync(configPath, JSON.stringify(defaultConfig, null, 2) + '\n', 'utf8');
-    console.log('Initialized orchard.json — add sprints with `orchard plan`');
+    const defaultConfig = {
+      sprints: [],
+      settings: { sync_interval: "manual" },
+    };
+    fs.writeFileSync(
+      configPath,
+      JSON.stringify(defaultConfig, null, 2) + "\n",
+      "utf8",
+    );
+    console.log("Initialized orchard.json — add sprints with `orchard plan`");
     process.exit(0);
   }
 
   const root = findOrchardRoot();
-  if (!root && command !== 'help' && command !== 'doctor') {
-    console.error('orchard: no orchard.json found. Run from a directory with orchard.json or a subdirectory.');
-    console.error('');
-    console.error('Create one:');
+  if (!root && command !== "help" && command !== "doctor") {
+    console.error(
+      "orchard: no orchard.json found. Run from a directory with orchard.json or a subdirectory.",
+    );
+    console.error("");
+    console.error("Create one:");
     console.error('  { "sprints": [] }');
     process.exit(1);
   }
 
   const config = root ? loadConfig(root) : { sprints: [] };
-  const jsonMode = args.includes('--json');
+  const jsonMode = args.includes("--json");
 
   switch (command) {
-    case 'plan': {
+    case "plan": {
       if (jsonMode) {
-        const { buildGraph, topoSort, detectCycles } = require('../lib/planner.js');
+        const {
+          buildGraph,
+          topoSort,
+          detectCycles,
+        } = require("../lib/planner.js");
         const graph = buildGraph(config);
         const order = topoSort(config);
         const cycles = detectCycles(config);
         console.log(JSON.stringify({ graph, order, cycles }, null, 2));
         break;
       }
-      const { printDependencyGraph } = require('../lib/planner.js');
-      printDependencyGraph(config, root);
+      const fmtIdx = args.indexOf("--format");
+      const planFormat =
+        fmtIdx !== -1 && args[fmtIdx + 1] ? args[fmtIdx + 1] : null;
+      if (args.includes("--mermaid") || planFormat === "mermaid") {
+        const { generateMermaid } = require("../lib/planner.js");
+        console.log(generateMermaid(config));
+        break;
+      }
+      if (planFormat === "ascii" || !planFormat) {
+        const { printDependencyGraph } = require("../lib/planner.js");
+        printDependencyGraph(config, root);
+        break;
+      }
+      console.error(
+        `orchard: unknown plan format: ${planFormat}. Supported: ascii, mermaid`,
+      );
+      process.exit(1);
       break;
     }
-    case 'status': {
+    case "status": {
       if (jsonMode) {
-        const { getStatusData } = require('../lib/tracker.js');
+        const { getStatusData } = require("../lib/tracker.js");
         const data = getStatusData(config, root);
         console.log(JSON.stringify(data, null, 2));
         break;
       }
-      const { printStatus } = require('../lib/tracker.js');
+      const { printStatus } = require("../lib/tracker.js");
       printStatus(config, root);
       break;
     }
-    case 'assign': {
+    case "assign": {
       const sprintPath = args[1];
       const person = args[2];
       if (!sprintPath || !person) {
-        console.error('orchard: usage: orchard assign <sprint-path> <person>');
+        console.error("orchard: usage: orchard assign <sprint-path> <person>");
         process.exit(1);
       }
-      const { assignSprint } = require('../lib/assignments.js');
+      const { assignSprint } = require("../lib/assignments.js");
       assignSprint(config, root, sprintPath, person);
       break;
     }
-    case 'sync': {
-      const { syncAll } = require('../lib/sync.js');
+    case "sync": {
+      const { syncAll } = require("../lib/sync.js");
       syncAll(config, root);
       break;
     }
-    case 'dashboard': {
-      const { generateDashboard } = require('../lib/dashboard.js');
-      const outPath = args[1] || path.join(root, 'orchard-dashboard.html');
+    case "dashboard": {
+      const { generateDashboard } = require("../lib/dashboard.js");
+      const outPath = args[1] || path.join(root, "orchard-dashboard.html");
       generateDashboard(config, root, outPath);
       break;
     }
-    case 'doctor': {
-      const { runChecks, printReport } = require('../lib/doctor.js');
+    case "conflicts": {
+      const {
+        detectConflicts,
+        filterBySeverity,
+        printConflicts,
+      } = require("../lib/conflicts.js");
+      const sevIdx = args.indexOf("--severity");
+      const severity =
+        sevIdx !== -1 && args[sevIdx + 1] ? args[sevIdx + 1] : "info";
+      if (jsonMode) {
+        const all = detectConflicts(config, root);
+        const filtered = filterBySeverity(all, severity);
+        console.log(
+          JSON.stringify(
+            { conflicts: filtered, count: filtered.length },
+            null,
+            2,
+          ),
+        );
+        break;
+      }
+      printConflicts(config, root, { severity });
+      break;
+    }
+    case "decompose": {
+      const question = args
+        .filter((a) => !a.startsWith("--"))
+        .slice(1)
+        .join(" ");
+      if (!question) {
+        console.error(
+          'orchard: usage: orchard decompose "<question>" [--apply] [--max <n>]',
+        );
+        process.exit(1);
+      }
+      const maxIdx = args.indexOf("--max");
+      const maxSprints =
+        maxIdx !== -1 && args[maxIdx + 1] ? parseInt(args[maxIdx + 1], 10) : 5;
+      if (args.includes("--apply")) {
+        const { applyDecomposition } = require("../lib/decompose.js");
+        const sprints = applyDecomposition(root, question, { maxSprints });
+        console.log(`Created ${sprints.length} sub-sprints for: "${question}"`);
+        for (const s of sprints) {
+          console.log(`  ${s.path}`);
+        }
+      } else {
+        const { printDecomposition } = require("../lib/decompose.js");
+        printDecomposition(question, { maxSprints });
+      }
+      break;
+    }
+    case "hackathon": {
+      const sub = args[1];
+      const hack = require("../lib/hackathon.js");
+      switch (sub) {
+        case "init": {
+          const nameIdx = args.indexOf("--name");
+          const durIdx = args.indexOf("--duration");
+          const name =
+            nameIdx !== -1 && args[nameIdx + 1] ? args[nameIdx + 1] : undefined;
+          const duration =
+            durIdx !== -1 && args[durIdx + 1]
+              ? parseInt(args[durIdx + 1], 10)
+              : undefined;
+          const h = hack.initHackathon(root, { name, duration });
+          console.log(`Hackathon "${h.name}" started — ends at ${h.endTime}`);
+          break;
+        }
+        case "team": {
+          const teamName = args[2];
+          const qIdx = args.indexOf("--question");
+          const question =
+            qIdx !== -1 ? args.slice(qIdx + 1).join(" ") : undefined;
+          if (!teamName) {
+            console.error(
+              'orchard: usage: orchard hackathon team <name> [--question "..."]',
+            );
+            process.exit(1);
+          }
+          const result = hack.addTeam(root, teamName, question);
+          console.log(
+            `Team "${result.teamName}" added — sprint: ${result.sprintPath}`,
+          );
+          break;
+        }
+        case "end": {
+          const board = hack.endHackathon(root);
+          console.log("Hackathon ended! Final leaderboard:");
+          for (let i = 0; i < board.length; i++) {
+            const t = board[i];
+            console.log(
+              `  ${i + 1}. ${t.team} — ${t.score}pts (${t.claimCount} claims)`,
+            );
+          }
+          break;
+        }
+        default: {
+          if (jsonMode) {
+            const timer = hack.timerStatus(root);
+            const board = hack.leaderboard(root);
+            console.log(JSON.stringify({ timer, leaderboard: board }, null, 2));
+          } else {
+            hack.printHackathon(root);
+          }
+          break;
+        }
+      }
+      break;
+    }
+    case "doctor": {
+      const { runChecks, printReport } = require("../lib/doctor.js");
       const result = runChecks(root || process.cwd());
       if (jsonMode) {
         console.log(JSON.stringify(result, null, 2));

package/lib/assignments.js

@@ -1,7 +1,7 @@
-'use strict';
+"use strict";
 
-const fs = require('node:fs');
-const path = require('node:path');
+const fs = require("node:fs");
+const path = require("node:path");
 
 /**
  * Assign a person to a sprint. Updates orchard.json.
@@ -11,7 +11,7 @@ function assignSprint(config, root, sprintPath, person) {
 
   if (!sprint) {
     console.error(`Sprint not found: ${sprintPath}`);
-    console.error('Available sprints:');
+    console.error("Available sprints:");
     for (const s of config.sprints || []) {
       console.error(`  ${s.path}`);
     }
@@ -21,13 +21,15 @@ function assignSprint(config, root, sprintPath, person) {
   const prev = sprint.assigned_to;
   sprint.assigned_to = person;
 
-  const configPath = path.join(root, 'orchard.json');
-  const tmp = configPath + '.tmp.' + process.pid;
-  fs.writeFileSync(tmp, JSON.stringify(config, null, 2) + '\n');
+  const configPath = path.join(root, "orchard.json");
+  const tmp = configPath + ".tmp." + process.pid;
+  fs.writeFileSync(tmp, JSON.stringify(config, null, 2) + "\n");
   fs.renameSync(tmp, configPath);
 
   if (prev) {
-    console.log(`Reassigned ${path.basename(sprintPath)}: ${prev} -> ${person}`);
+    console.log(
+      `Reassigned ${path.basename(sprintPath)}: ${prev} -> ${person}`,
+    );
   } else {
     console.log(`Assigned ${path.basename(sprintPath)} to ${person}`);
   }
@@ -40,7 +42,7 @@ function getWorkload(config) {
   const workload = new Map();
 
   for (const sprint of config.sprints || []) {
-    const person = sprint.assigned_to || 'unassigned';
+    const person = sprint.assigned_to || "unassigned";
     if (!workload.has(person)) {
       workload.set(person, []);
     }
@@ -56,20 +58,20 @@ function getWorkload(config) {
 function printWorkload(config) {
   const workload = getWorkload(config);
 
-  console.log('');
-  console.log('  Workload Distribution');
-  console.log('  ' + '-'.repeat(40));
+  console.log("");
+  console.log("  Workload Distribution");
+  console.log("  " + "-".repeat(40));
 
   for (const [person, sprints] of workload) {
-    const active = sprints.filter((s) => s.status !== 'done').length;
+    const active = sprints.filter((s) => s.status !== "done").length;
     console.log(`  ${person}: ${sprints.length} sprints (${active} active)`);
     for (const s of sprints) {
-      const status = s.status || 'unknown';
+      const status = s.status || "unknown";
       console.log(`    - ${path.basename(s.path)} [${status}]`);
     }
   }
 
-  console.log('');
+  console.log("");
 }
 
 /**
@@ -80,8 +82,8 @@ function findOverloaded(config, maxLoad = 3) {
   const overloaded = [];
 
   for (const [person, sprints] of workload) {
-    if (person === 'unassigned') continue;
-    const active = sprints.filter((s) => s.status !== 'done').length;
+    if (person === "unassigned") continue;
+    const active = sprints.filter((s) => s.status !== "done").length;
     if (active > maxLoad) {
       overloaded.push({ person, active, sprints });
     }