@grainulation/orchard 1.0.0

package/lib/dashboard.js

@@ -0,0 +1,291 @@
+'use strict';
+
+const fs = require('node:fs');
+const path = require('node:path');
+
+/**
+ * Scan for claims.json files in target directory.
+ * Two levels deep to handle structures like root/sprints/<name>/claims.json.
+ */
+function findSprintFiles(targetDir) {
+  const found = [];
+
+  // Direct claims.json in target dir
+  const direct = path.join(targetDir, 'claims.json');
+  if (fs.existsSync(direct)) {
+    found.push({ file: direct, dir: targetDir, name: path.basename(targetDir), cat: 'root' });
+  }
+
+  // Archive subdir (flat JSON files)
+  const archiveDir = path.join(targetDir, 'archive');
+  if (fs.existsSync(archiveDir) && fs.statSync(archiveDir).isDirectory()) {
+    for (const f of fs.readdirSync(archiveDir)) {
+      if (f.endsWith('.json') && f.includes('claims')) {
+        found.push({ file: path.join(archiveDir, f), dir: archiveDir, name: f.replace('.json', '').replace(/-/g, ' '), cat: 'archive' });
+      }
+    }
+  }
+
+  // Scan subdirectories (two levels: sprints/<name>/claims.json, etc.)
+  try {
+    const entries = fs.readdirSync(targetDir, { withFileTypes: true });
+    for (const entry of entries) {
+      if (!entry.isDirectory()) continue;
+      if (entry.name.startsWith('.') || entry.name === 'archive' || entry.name === 'node_modules') continue;
+      const childDir = path.join(targetDir, entry.name);
+      const childClaims = path.join(childDir, 'claims.json');
+      if (fs.existsSync(childClaims)) {
+        found.push({ file: childClaims, dir: childDir, name: entry.name, cat: 'active' });
+      }
+      // Second level
+      try {
+        const subEntries = fs.readdirSync(childDir, { withFileTypes: true });
+        for (const sub of subEntries) {
+          if (!sub.isDirectory()) continue;
+          if (sub.name.startsWith('.')) continue;
+          const subDir = path.join(childDir, sub.name);
+          const subClaims = path.join(subDir, 'claims.json');
+          if (fs.existsSync(subClaims)) {
+            found.push({ file: subClaims, dir: subDir, name: sub.name, cat: 'active' });
+          }
+        }
+      } catch { /* skip */ }
+    }
+  } catch { /* skip */ }
+
+  return found;
+}
+
+/**
+ * Parse a claims.json file into sprint metadata and claims array.
+ */
+function parseClaims(filePath) {
+  try {
+    const raw = JSON.parse(fs.readFileSync(filePath, 'utf8'));
+    const meta = raw.meta || {};
+    const claims = Array.isArray(raw) ? raw : (raw.claims || []);
+    return { meta, claims };
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Load all sprint data from a target directory.
+ * Returns the graph data structure: { sprints, edges, cycles, status }
+ * suitable for template injection.
+ */
+function loadSprints(targetDir) {
+  const sources = findSprintFiles(targetDir);
+  const sprints = [];
+
+  for (const src of sources) {
+    const parsed = parseClaims(src.file);
+    if (!parsed) continue;
+    const { meta, claims } = parsed;
+    if (claims.length === 0) continue;
+
+    const topicSet = new Set();
+    for (const c of claims) {
+      if (c.topic) topicSet.add(c.topic);
+    }
+
+    sprints.push({
+      path: src.dir,
+      question: meta.question || '(no question)',
+      phase: meta.phase || 'unknown',
+      claimCount: claims.length,
+      topics: [...topicSet],
+      initiated: meta.initiated || null,
+      _claims: claims,
+    });
+  }
+
+  // Build edges from cross-references
+  const edges = [];
+  for (const sprint of sprints) {
+    for (const claim of sprint._claims) {
+      // Check resolved_by for cross-sprint references
+      if (claim.resolved_by && typeof claim.resolved_by === 'string') {
+        for (const other of sprints) {
+          if (other.path === sprint.path) continue;
+          const dirName = path.basename(other.path);
+          if (claim.resolved_by.includes(dirName)) {
+            addEdge(edges, sprint.path, other.path, 'resolved_by');
+            break;
+          }
+        }
+      }
+
+      // Check conflicts_with
+      if (Array.isArray(claim.conflicts_with)) {
+        for (const ref of claim.conflicts_with) {
+          if (typeof ref !== 'string') continue;
+          for (const other of sprints) {
+            if (other.path === sprint.path) continue;
+            const dirName = path.basename(other.path);
+            if (ref.includes(dirName)) {
+              addEdge(edges, sprint.path, other.path, 'conflict');
+              break;
+            }
+          }
+        }
+      }
+
+      // Check content for sprint name references
+      const content = claim.content || claim.text || '';
+      if (typeof content === 'string') {
+        for (const other of sprints) {
+          if (other.path === sprint.path) continue;
+          const sprintName = path.basename(other.path);
+          if (sprintName.length > 3 && content.includes(sprintName)) {
+            addEdge(edges, sprint.path, other.path, 'reference');
+          }
+        }
+      }
+    }
+  }
+
+  // Detect cycles via DFS
+  const cycles = detectCycles(sprints, edges);
+
+  // Build status array
+  const status = sprints.map(s => {
+    let active = 0, resolved = 0, superseded = 0, other = 0;
+    let latestTimestamp = null;
+    const topicCounts = {};
+
+    for (const c of s._claims) {
+      const st = (c.status || '').toLowerCase();
+      if (st === 'active') active++;
+      else if (st === 'resolved') resolved++;
+      else if (st === 'superseded') superseded++;
+      else other++;
+
+      if (c.timestamp) {
+        if (!latestTimestamp || c.timestamp > latestTimestamp) latestTimestamp = c.timestamp;
+      }
+      if (c.topic) {
+        topicCounts[c.topic] = (topicCounts[c.topic] || 0) + 1;
+      }
+    }
+
+    let daysSinceUpdate = null;
+    if (latestTimestamp) {
+      const lastDate = new Date(latestTimestamp);
+      const now = new Date();
+      daysSinceUpdate = Math.floor((now - lastDate) / (1000 * 60 * 60 * 24));
+    }
+
+    const topTopics = Object.entries(topicCounts)
+      .sort((a, b) => b[1] - a[1])
+      .slice(0, 5)
+      .map(([topic, count]) => ({ topic, count }));
+
+    return {
+      path: s.path,
+      question: s.question,
+      phase: s.phase,
+      initiated: s.initiated,
+      total: s._claims.length,
+      active,
+      resolved,
+      superseded,
+      other,
+      daysSinceUpdate,
+      topTopics,
+    };
+  });
+
+  // Strip _claims from sprint objects before returning
+  const cleanSprints = sprints.map(s => {
+    const { _claims, ...rest } = s;
+    return rest;
+  });
+
+  return { sprints: cleanSprints, edges, cycles, status };
+}
+
+function addEdge(edges, from, to, type) {
+  const existing = edges.find(e => e.from === from && e.to === to && e.type === type);
+  if (existing) {
+    existing.count++;
+  } else {
+    edges.push({ from, to, type, count: 1 });
+  }
+}
+
+function detectCycles(sprints, edges) {
+  const cycles = [];
+  const adj = {};
+  for (const s of sprints) adj[s.path] = [];
+  for (const e of edges) {
+    if (!adj[e.from]) adj[e.from] = [];
+    adj[e.from].push(e.to);
+  }
+
+  const WHITE = 0, GRAY = 1, BLACK = 2;
+  const color = {};
+  for (const s of sprints) color[s.path] = WHITE;
+
+  function dfs(u, pathStack) {
+    color[u] = GRAY;
+    pathStack.push(u);
+    for (const v of (adj[u] || [])) {
+      if (color[v] === GRAY) {
+        const cycleStart = pathStack.indexOf(v);
+        if (cycleStart !== -1) {
+          cycles.push(pathStack.slice(cycleStart).map(p => path.basename(p)));
+        }
+      } else if (color[v] === WHITE) {
+        dfs(v, pathStack);
+      }
+    }
+    pathStack.pop();
+    color[u] = BLACK;
+  }
+
+  for (const s of sprints) {
+    if (color[s.path] === WHITE) dfs(s.path, []);
+  }
+
+  return cycles;
+}
+
+/**
+ * Build the dashboard HTML string from sprint graph data.
+ * @param {object} graphData - { sprints, edges, cycles, status }
+ * @returns {string} Complete HTML string
+ */
+function buildHtml(graphData) {
+  const templatePath = path.join(__dirname, '..', 'templates', 'dashboard.html');
+  const template = fs.readFileSync(templatePath, 'utf8');
+  const jsonData = JSON.stringify(graphData).replace(/<\/script/gi, '<\\/script');
+  return template.replace('__SPRINT_DATA__', jsonData);
+}
+
+/**
+ * Return paths to all claims.json files for watching.
+ */
+function claimsPaths(targetDir) {
+  return findSprintFiles(targetDir).map(s => s.file);
+}
+
+/**
+ * Generate a self-contained HTML dashboard file (for `orchard dashboard` CLI command).
+ */
+function generateDashboard(config, root, outPath) {
+  const graphData = loadSprints(root);
+
+  if (graphData.sprints.length === 0) {
+    console.error('No sprints found (no claims.json files detected).');
+    process.exit(1);
+  }
+
+  const html = buildHtml(graphData);
+  fs.writeFileSync(outPath, html);
+  console.log(`Dashboard written to ${outPath}`);
+  console.log(`  ${graphData.sprints.length} sprints, ${graphData.edges.length} edges, ${graphData.cycles.length} cycles`);
+}
+
+module.exports = { loadSprints, buildHtml, claimsPaths, findSprintFiles, generateDashboard };

package/lib/doctor.js

@@ -0,0 +1,137 @@
+'use strict';
+
+const fs = require('node:fs');
+const path = require('node:path');
+
+/**
+ * Run all doctor checks against the orchard root directory.
+ * Returns { checks: [...], ok: boolean }
+ */
+function runChecks(root) {
+  const checks = [];
+
+  // 1. orchard.json present and parseable
+  const configPath = path.join(root, 'orchard.json');
+  const configExists = fs.existsSync(configPath);
+  checks.push({
+    name: 'orchard.json exists',
+    ok: configExists,
+    detail: configExists ? configPath : 'Not found. Run "orchard init" to create one.',
+  });
+
+  if (!configExists) {
+    return { checks, ok: false };
+  }
+
+  let config;
+  try {
+    config = JSON.parse(fs.readFileSync(configPath, 'utf8'));
+    checks.push({ name: 'orchard.json is valid JSON', ok: true, detail: '' });
+  } catch (err) {
+    checks.push({ name: 'orchard.json is valid JSON', ok: false, detail: err.message });
+    return { checks, ok: false };
+  }
+
+  const sprints = config.sprints || [];
+  checks.push({
+    name: 'sprints defined',
+    ok: sprints.length > 0,
+    detail: sprints.length > 0
+      ? `${sprints.length} sprint(s) configured`
+      : 'No sprints in orchard.json',
+  });
+
+  // 2. Sprint directories reachable
+  let allReachable = true;
+  for (const sprint of sprints) {
+    const sprintDir = sprint.path === '.'
+      ? root
+      : path.isAbsolute(sprint.path)
+        ? sprint.path
+        : path.join(root, sprint.path);
+    const exists = fs.existsSync(sprintDir);
+    if (!exists) allReachable = false;
+    checks.push({
+      name: `sprint dir: ${sprint.name || sprint.path}`,
+      ok: exists,
+      detail: exists ? sprintDir : `Missing: ${sprintDir}`,
+    });
+  }
+
+  // 3. Dependencies resolve (all depends_on targets exist in sprint list)
+  const sprintPaths = new Set(sprints.map((s) => s.path));
+  const sprintNames = new Set(sprints.map((s) => s.name).filter(Boolean));
+  let allDepsResolved = true;
+
+  for (const sprint of sprints) {
+    for (const dep of sprint.depends_on || []) {
+      // Match by path or by name
+      const resolved = sprintPaths.has(dep) || sprintNames.has(dep);
+      if (!resolved) {
+        allDepsResolved = false;
+        checks.push({
+          name: `dependency: ${sprint.name || sprint.path} -> ${dep}`,
+          ok: false,
+          detail: `"${dep}" not found in sprint list`,
+        });
+      }
+    }
+  }
+  if (allDepsResolved && sprints.length > 0) {
+    const totalDeps = sprints.reduce((n, s) => n + (s.depends_on || []).length, 0);
+    checks.push({
+      name: 'all dependencies resolve',
+      ok: true,
+      detail: `${totalDeps} dependency link(s) verified`,
+    });
+  }
+
+  // 4. Cycle detection
+  let hasCycles = false;
+  try {
+    const { detectCycles } = require('./planner.js');
+    const cycles = detectCycles(config);
+    hasCycles = cycles.length > 0;
+    checks.push({
+      name: 'no dependency cycles',
+      ok: !hasCycles,
+      detail: hasCycles ? `Cycle involving: ${cycles.join(', ')}` : 'Dependency graph is acyclic',
+    });
+  } catch (err) {
+    checks.push({
+      name: 'no dependency cycles',
+      ok: false,
+      detail: `Cycle check failed: ${err.message}`,
+    });
+  }
+
+  const ok = checks.every((c) => c.ok);
+  return { checks, ok };
+}
+
+/**
+ * Print doctor results to stdout.
+ */
+function printReport(result) {
+  console.log('');
+  console.log('  orchard doctor');
+  console.log('  ' + '='.repeat(40));
+  console.log('');
+
+  for (const check of result.checks) {
+    const icon = check.ok ? 'ok' : 'FAIL';
+    const line = `  [${icon.padEnd(4)}] ${check.name}`;
+    console.log(line);
+    if (check.detail && !check.ok) {
+      console.log(`         ${check.detail}`);
+    }
+  }
+
+  console.log('');
+  const passed = result.checks.filter((c) => c.ok).length;
+  const total = result.checks.length;
+  console.log(`  ${passed}/${total} checks passed` + (result.ok ? ' -- all healthy' : ' -- issues found'));
+  console.log('');
+}
+
+module.exports = { runChecks, printReport };

package/lib/export.js

@@ -0,0 +1,98 @@
+'use strict';
+
+/**
+ * orchard -> mill edge: export trigger for completed sprints.
+ *
+ * When orchard detects a sprint is "done", it can trigger mill's
+ * export API to produce formatted output. Probes mill via localhost
+ * or filesystem. Graceful fallback if mill is not available.
+ */
+
+const fs = require('node:fs');
+const path = require('node:path');
+const http = require('node:http');
+
+const MILL_PORT = 9094;
+const MILL_SIBLINGS = [
+  path.join(__dirname, '..', '..', 'mill'),
+  path.join(__dirname, '..', '..', '..', 'mill'),
+];
+
+/**
+ * Check if mill is reachable (HTTP or filesystem).
+ * Returns { available: true, method, formats? } or { available: false }.
+ */
+function detectMill() {
+  for (const dir of MILL_SIBLINGS) {
+    const pkg = path.join(dir, 'package.json');
+    if (fs.existsSync(pkg)) {
+      try {
+        const meta = JSON.parse(fs.readFileSync(pkg, 'utf8'));
+        if (meta.name === '@grainulation/mill') {
+          return { available: true, method: 'filesystem', path: dir };
+        }
+      } catch { continue; }
+    }
+  }
+  return { available: false };
+}
+
+/**
+ * Trigger an export via mill's HTTP API.
+ * @param {string} sprintPath — absolute path to the sprint directory
+ * @param {string} format — export format name (e.g. "markdown", "csv", "json-ld")
+ * @returns {Promise<{ok: boolean, job?, error?}>}
+ */
+function exportSprint(sprintPath, format) {
+  return new Promise((resolve) => {
+    const body = JSON.stringify({ format, options: { source: sprintPath } });
+    const req = http.request({
+      hostname: '127.0.0.1',
+      port: MILL_PORT,
+      path: '/api/export',
+      method: 'POST',
+      headers: { 'Content-Type': 'application/json', 'Content-Length': Buffer.byteLength(body) },
+      timeout: 5000,
+    }, (res) => {
+      let data = '';
+      res.on('data', (chunk) => { data += chunk; });
+      res.on('end', () => {
+        try {
+          const result = JSON.parse(data);
+          resolve(result.error ? { ok: false, error: result.error } : { ok: true, job: result.job });
+        } catch {
+          resolve({ ok: false, error: 'Invalid response from mill' });
+        }
+      });
+    });
+    req.on('error', () => resolve({ ok: false, error: 'mill not reachable on port ' + MILL_PORT }));
+    req.on('timeout', () => { req.destroy(); resolve({ ok: false, error: 'mill request timed out' }); });
+    req.write(body);
+    req.end();
+  });
+}
+
+/**
+ * List available export formats from mill's API.
+ * @returns {Promise<{available: boolean, formats?: Array}>}
+ */
+function listFormats() {
+  return new Promise((resolve) => {
+    const req = http.get(`http://127.0.0.1:${MILL_PORT}/api/formats`, { timeout: 2000 }, (res) => {
+      let body = '';
+      res.on('data', (chunk) => { body += chunk; });
+      res.on('end', () => {
+        try {
+          const data = JSON.parse(body);
+          resolve({ available: true, formats: data.formats || [] });
+        } catch {
+          resolve({ available: false });
+        }
+      });
+    });
+    req.on('error', () => resolve({ available: false }));
+    req.on('timeout', () => { req.destroy(); resolve({ available: false }); });
+  });
+}
+
+module.exports = { detectMill, exportSprint, listFormats, MILL_PORT };

package/lib/farmer.js

@@ -0,0 +1,107 @@
+'use strict';
+
+const fs = require('node:fs');
+const path = require('node:path');
+const http = require('node:http');
+const https = require('node:https');
+
+/**
+ * POST an activity event to farmer.
+ * Graceful failure -- catch and warn, never crash.
+ * @param {string} farmerUrl - Base URL of farmer (e.g. http://localhost:9090)
+ * @param {object} event - Event object (e.g. { type: "scan", data: {...} })
+ */
+function notify(farmerUrl, event) {
+  return new Promise((resolve) => {
+    try {
+      const payload = JSON.stringify({
+        tool: 'orchard',
+        event,
+        timestamp: new Date().toISOString()
+      });
+
+      const url = new URL(`${farmerUrl}/hooks/activity`);
+      const transport = url.protocol === 'https:' ? https : http;
+
+      const req = transport.request({
+        hostname: url.hostname,
+        port: url.port,
+        path: url.pathname,
+        method: 'POST',
+        headers: {
+          'Content-Type': 'application/json',
+          'Content-Length': Buffer.byteLength(payload)
+        },
+        timeout: 5000
+      }, (res) => {
+        let body = '';
+        res.on('data', chunk => { body += chunk; });
+        res.on('end', () => resolve({ ok: res.statusCode < 400, status: res.statusCode, body }));
+      });
+
+      req.on('error', (err) => {
+        console.error(`[orchard] farmer notify failed: ${err.message}`);
+        resolve({ ok: false, error: err.message });
+      });
+
+      req.on('timeout', () => {
+        req.destroy();
+        console.error('[orchard] farmer notify timed out');
+        resolve({ ok: false, error: 'timeout' });
+      });
+
+      req.write(payload);
+      req.end();
+    } catch (err) {
+      console.error(`[orchard] farmer notify failed: ${err.message}`);
+      resolve({ ok: false, error: err.message });
+    }
+  });
+}
+
+/**
+ * CLI handler for `orchard connect farmer`.
+ * Reads/writes .farmer.json in targetDir.
+ * @param {string} targetDir - Working directory
+ * @param {string[]} args - CLI arguments (e.g. ["farmer", "--url", "http://..."])
+ */
+async function connect(targetDir, args) {
+  const subcommand = args[0];
+  if (subcommand !== 'farmer') {
+    console.error('Usage: orchard connect farmer [--url http://localhost:9090]');
+    process.exit(1);
+  }
+
+  const configPath = path.join(targetDir, '.farmer.json');
+
+  const urlIdx = args.indexOf('--url');
+  if (urlIdx !== -1 && args[urlIdx + 1]) {
+    const url = args[urlIdx + 1];
+    const config = { url };
+    fs.writeFileSync(configPath, JSON.stringify(config, null, 2), 'utf8');
+    console.log(`Farmer connection saved to ${configPath}`);
+    console.log(`  URL: ${url}`);
+
+    // Test the connection
+    const result = await notify(url, { type: 'connect', data: { tool: 'orchard' } });
+    if (result.ok) {
+      console.log('  Connection test: OK');
+    } else {
+      console.log(`  Connection test: failed (${result.error || 'status ' + result.status})`);
+      console.log('  Farmer may not be running. The URL is saved and will be used when farmer is available.');
+    }
+    return;
+  }
+
+  // Show current config
+  if (fs.existsSync(configPath)) {
+    const config = JSON.parse(fs.readFileSync(configPath, 'utf8'));
+    console.log(`Farmer connection: ${config.url}`);
+    console.log(`Config: ${configPath}`);
+  } else {
+    console.log('No farmer connection configured.');
+    console.log('Usage: orchard connect farmer --url http://localhost:9090');
+  }
+}
+
+module.exports = { connect, notify };