@grainulation/barn 1.0.0 → 1.0.1

package/CODE_OF_CONDUCT.md

@@ -0,0 +1,25 @@
+# Code of Conduct
+
+## Our standards
+
+We are committed to providing a welcoming and productive environment for everyone. We expect participants to:
+
+- Use welcoming and inclusive language
+- Respect differing viewpoints and experiences
+- Accept constructive criticism gracefully
+- Focus on what is best for the community and the project
+- Show empathy toward other participants
+
+Unacceptable behavior includes harassment, trolling, personal attacks, and publishing others' private information without permission.
+
+## Scope
+
+This code of conduct applies to all project spaces -- issues, pull requests, discussions, and any public channel where someone represents the project.
+
+## Enforcement
+
+Instances of unacceptable behavior may be reported to the project maintainers. All complaints will be reviewed and investigated, and will result in a response deemed necessary and appropriate.
+
+## Attribution
+
+Adapted from the [Contributor Covenant](https://www.contributor-covenant.org/), version 2.1.

package/CONTRIBUTING.md

@@ -0,0 +1,97 @@
+# Contributing to Barn
+
+Thanks for considering contributing. Barn is the template engine for the grainulation ecosystem -- it turns structured data into polished HTML artifacts.
+
+## Quick setup
+
+```bash
+git clone https://github.com/grainulation/barn.git
+cd barn
+node bin/barn.js --help
+```
+
+No `npm install` needed -- barn 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
+4. Run the tests: `node test/basic.test.js`
+5. Commit with a clear message
+6. Open a PR
+
+### Add a template
+
+Templates live in `templates/`. Each template is a pair: an HTML file and a JSON schema file. To add one:
+
+1. Create `templates/your-template.html` and `templates/your-template.json`
+2. Follow the pattern of existing templates (use `template.schema.json` as the base schema)
+3. Ensure the HTML is self-contained (inline CSS/JS, no external dependencies)
+4. Add it to the README templates table
+
+## Architecture
+
+```
+bin/barn.js           CLI entrypoint -- dispatches subcommands
+lib/index.js          Core library -- template resolution and rendering
+lib/server.js         Local preview server (SSE, zero deps)
+templates/            HTML + JSON schema pairs for each artifact type
+public/               Web UI -- two-column template nav + preview
+site/                 Public website (barn.grainulation.com)
+tools/                Utility scripts
+test/                 Node built-in test runner tests
+```
+
+The key architectural principle: **templates are self-contained HTML with inline CSS/JS.** No external dependencies, no build step, no CDN links.
+
+## Code style
+
+- Zero dependencies. If you need something, write it or use Node built-ins.
+- No transpilation. Ship what you write.
+- ESM imports (`import`/`export`). Node 18+ required.
+- Keep functions small. If a function needs a scroll, split it.
+- No emojis in code, CLI output, or templates.
+
+## Testing
+
+```bash
+node test/basic.test.js
+```
+
+Tests use Node's built-in test runner. No test framework dependencies.
+
+## Commit messages
+
+Follow the existing pattern:
+
+```
+barn: <what changed>
+```
+
+Examples:
+
+```
+barn: add postmortem template
+barn: fix server SSE reconnection
+barn: update schema validation for nested fields
+```
+
+## License
+
+MIT. See LICENSE for details.

package/README.md

@@ -1,8 +1,15 @@
-# barn
+<p align="center">
+  <img src="site/wordmark.svg" alt="Barn" width="400">
+</p>
 
-Open tools for structured research. Use with wheat, or use standalone.
+<p align="center">
+  <a href="https://www.npmjs.com/package/@grainulation/barn"><img src="https://img.shields.io/npm/v/@grainulation/barn" alt="npm version"></a> <a href="https://www.npmjs.com/package/@grainulation/barn"><img src="https://img.shields.io/npm/dm/@grainulation/barn" alt="npm downloads"></a> <a href="https://github.com/grainulation/barn/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/barn" alt="node"></a> <a href="https://github.com/grainulation/barn/actions"><img src="https://github.com/grainulation/barn/actions/workflows/ci.yml/badge.svg" alt="CI"></a>
+  <a href="https://deepwiki.com/grainulation/barn"><img src="https://deepwiki.com/badge.svg" alt="Explore on DeepWiki"></a>
+</p>
 
-Barn extracts the reusable utilities from the [wheat](https://github.com/grainulation/wheat) research sprint system into a standalone package. Zero npm dependencies -- Node built-in only.
+<p align="center"><strong>Shared tools for the grainulation ecosystem.</strong></p>
+
+Barn extracts the reusable utilities from [wheat](https://github.com/grainulation/wheat) into a standalone package. Sprint detection, manifest generation, PDF builds, and 17 HTML templates for research artifacts.
 
 ## Install
 
@@ -49,38 +56,48 @@ barn build-pdf output/brief.md
 
 ## Templates
 
-HTML templates for sprint artifacts. Self-contained (inline CSS/JS, no external deps), dark theme, mobile responsive.
-
-- **adr.html** -- Architecture Decision Record
-- **brief.html** -- Sprint brief / recommendation document
-- **certificate.html** -- Compilation certificate
-- **changelog.html** -- Sprint changelog
-- **comparison.html** -- Side-by-side comparison dashboard
-- **conflict-map.html** -- Claim conflict visualization
-- **dashboard.html** -- Sprint status dashboard
-- **email-digest.html** -- Email digest summary
-- **evidence-matrix.html** -- Evidence tier matrix
-- **explainer.html** -- Full-screen scroll-snap presentation
-- **handoff.html** -- Knowledge transfer document
-- **one-pager.html** -- Single-page executive summary
-- **postmortem.html** -- Sprint postmortem
-- **rfc.html** -- Request for Comments
-- **risk-register.html** -- Risk tracking register
-- **slide-deck.html** -- Slide deck presentation
-- **wiki-page.html** -- Wiki-style documentation page
-
-Copy templates into your project:
+17 self-contained HTML templates for sprint artifacts. Dark theme, inline CSS/JS, no external deps, mobile responsive.
+
+| Template               | Purpose                                |
+| ---------------------- | -------------------------------------- |
+| `adr.html`             | Architecture Decision Record           |
+| `brief.html`           | Sprint brief / recommendation document |
+| `certificate.html`     | Compilation certificate                |
+| `changelog.html`       | Sprint changelog                       |
+| `comparison.html`      | Side-by-side comparison dashboard      |
+| `conflict-map.html`    | Claim conflict visualization           |
+| `dashboard.html`       | Sprint status dashboard                |
+| `email-digest.html`    | Email digest summary                   |
+| `evidence-matrix.html` | Evidence tier matrix                   |
+| `explainer.html`       | Full-screen scroll-snap presentation   |
+| `handoff.html`         | Knowledge transfer document            |
+| `one-pager.html`       | Single-page executive summary          |
+| `postmortem.html`      | Sprint postmortem                      |
+| `rfc.html`             | Request for Comments                   |
+| `risk-register.html`   | Risk tracking register                 |
+| `slide-deck.html`      | Slide deck presentation                |
+| `wiki-page.html`       | Wiki-style documentation page          |
 
 ```bash
 cp node_modules/@grainulation/barn/templates/explainer.html ./output/
 ```
 
-## Philosophy
+## Zero dependencies
+
+Node built-in modules only. No npm install waterfall.
+
+## Part of the grainulation ecosystem
 
-- Zero npm dependencies. Node built-in modules only.
-- Git as the source of truth. No config files for state that git already knows.
-- Self-describing structures. New sessions understand the repo without full scans.
-- Works with AI search tools (Glob, Grep, Read) out of the box.
+| 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**                                                     | 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](https://github.com/grainulation/orchard)           | Orchestration -- multi-sprint coordination and dependencies |
+| [grainulation](https://github.com/grainulation/grainulation) | Unified CLI -- single entry point to the ecosystem          |
 
 ## License
 

package/bin/barn.js

@@ -14,44 +14,51 @@
  * Zero npm dependencies (Node built-in only).
  */
 
-import { fileURLToPath } from 'node:url';
-import { dirname, join } from 'node:path';
-import { fork } from 'node:child_process';
+import { fileURLToPath } from "node:url";
+import { dirname, join } from "node:path";
+import { fork } from "node:child_process";
 
 const __dirname = dirname(fileURLToPath(import.meta.url));
-const TOOLS_DIR = join(__dirname, '..', 'tools');
+const TOOLS_DIR = join(__dirname, "..", "tools");
 
-const LIB_DIR = join(__dirname, '..', 'lib');
+const LIB_DIR = join(__dirname, "..", "lib");
 
 // ── --version / -v ───────────────────────────────────────────────────────────
-import { readFileSync } from 'node:fs';
+import { readFileSync } from "node:fs";
 
 const args = process.argv.slice(2);
 const command = args[0];
 
-if (command === '--version' || command === '-v') {
-  const pkg = JSON.parse(readFileSync(join(__dirname, '..', 'package.json'), 'utf8'));
+if (command === "--version" || command === "-v") {
+  const pkg = JSON.parse(
+    readFileSync(join(__dirname, "..", "package.json"), "utf8"),
+  );
   console.log(pkg.version);
   process.exit(0);
 }
 
-const verbose = process.argv.includes('--verbose');
+const verbose = process.argv.includes("--verbose");
 function vlog(...a) {
   if (!verbose) return;
   const ts = new Date().toISOString();
-  process.stderr.write(`[${ts}] barn: ${a.join(' ')}\n`);
+  process.stderr.write(`[${ts}] barn: ${a.join(" ")}\n`);
 }
 export { vlog, verbose };
 
 const commands = {
-  'detect-sprints': 'detect-sprints.js',
-  'generate-manifest': 'generate-manifest.js',
-  'build-pdf': 'build-pdf.js',
+  "detect-sprints": "detect-sprints.js",
+  "generate-manifest": "generate-manifest.js",
+  "build-pdf": "build-pdf.js",
 };
 
-vlog('startup', `command=${command || '(none)'}`, `cwd=${process.cwd()}`);
+vlog("startup", `command=${command || "(none)"}`, `cwd=${process.cwd()}`);
 
-if (!command || command === 'help' || command === '--help' || command === '-h') {
+if (
+  !command ||
+  command === "help" ||
+  command === "--help" ||
+  command === "-h"
+) {
   console.log(`barn — open tools for structured research
 
 Usage:
@@ -81,16 +88,16 @@ https://github.com/grainulation/barn`);
 }
 
 // ── serve command (lib/server.js) ──
-if (command === 'serve') {
-  const serverPath = join(LIB_DIR, 'server.js');
-  const child = fork(serverPath, args.slice(1), { stdio: 'inherit' });
-  child.on('exit', (code) => process.exit(code ?? 0));
-  process.on('SIGTERM', () => child.kill('SIGTERM'));
-  process.on('SIGINT', () => child.kill('SIGINT'));
+if (command === "serve") {
+  const serverPath = join(LIB_DIR, "server.js");
+  const child = fork(serverPath, args.slice(1), { stdio: "inherit" });
+  child.on("exit", (code) => process.exit(code ?? 0));
+  process.on("SIGTERM", () => child.kill("SIGTERM"));
+  process.on("SIGINT", () => child.kill("SIGINT"));
 } else if (commands[command]) {
   const toolPath = join(TOOLS_DIR, commands[command]);
-  const child = fork(toolPath, args.slice(1), { stdio: 'inherit' });
-  child.on('exit', (code) => process.exit(code ?? 0));
+  const child = fork(toolPath, args.slice(1), { stdio: "inherit" });
+  child.on("exit", (code) => process.exit(code ?? 0));
 } else {
   console.error(`barn: unknown command: ${command}`);
   console.error(`Run "barn help" for available commands.`);

package/lib/index.js

@@ -8,12 +8,14 @@
  *   generateManifest(opts) — build wheat-manifest.json topic map (re-export)
  */
 
-import { readFileSync, existsSync, readdirSync, statSync } from 'node:fs';
-import { join, dirname } from 'node:path';
-import { fileURLToPath } from 'node:url';
+import { readFileSync, existsSync, readdirSync, statSync } from "node:fs";
+import { join, dirname } from "node:path";
+import { fileURLToPath } from "node:url";
 
 const __dirname = dirname(fileURLToPath(import.meta.url));
-const pkg = JSON.parse(readFileSync(join(__dirname, '..', 'package.json'), 'utf8'));
+const pkg = JSON.parse(
+  readFileSync(join(__dirname, "..", "package.json"), "utf8"),
+);
 
 export const name = pkg.name;
 export const version = pkg.version;
@@ -30,64 +32,78 @@ export function loadTemplates(templatesDir) {
   if (!existsSync(templatesDir)) return templates;
 
   for (const file of readdirSync(templatesDir)) {
-    if (!file.endsWith('.html')) continue;
+    if (!file.endsWith(".html")) continue;
     const filePath = join(templatesDir, file);
-    const content = readFileSync(filePath, 'utf8');
-    const tplName = file.replace('.html', '');
+    const content = readFileSync(filePath, "utf8");
+    const tplName = file.replace(".html", "");
 
     // Extract placeholders
     const placeholders = [...new Set(content.match(/\{\{[A-Z_]+\}\}/g) || [])];
 
     // Extract description from first comment
     const commentMatch = content.match(/<!--\s*(.*?)\s*-->/);
-    let description = commentMatch ? commentMatch[1] : '';
+    let description = commentMatch ? commentMatch[1] : "";
 
     // Count lines and size
-    const lines = content.split('\n').length;
+    const lines = content.split("\n").length;
     const size = statSync(filePath).size;
 
     // Detect features
     const features = [];
-    if (content.includes('scroll-snap')) features.push('scroll-snap');
-    if (content.includes('@media')) features.push('responsive');
-    if (content.includes('var(--')) features.push('css-variables');
-    if (content.includes('<table')) features.push('tables');
-    if (content.includes('.card')) features.push('cards');
-    if (content.includes('.slide')) features.push('slides');
+    if (content.includes("scroll-snap")) features.push("scroll-snap");
+    if (content.includes("@media")) features.push("responsive");
+    if (content.includes("var(--")) features.push("css-variables");
+    if (content.includes("<table")) features.push("tables");
+    if (content.includes(".card")) features.push("cards");
+    if (content.includes(".slide")) features.push("slides");
 
     // Merge optional template.json metadata
-    const metaPath = join(templatesDir, tplName + '.json');
+    const metaPath = join(templatesDir, tplName + ".json");
     let title = tplName;
     let tags = [];
-    let author = '';
-    let tplVersion = '';
+    let author = "";
+    let tplVersion = "";
     let exportPresets = [];
     let seedPacks = [];
     let scaffoldConfig = null;
     if (existsSync(metaPath)) {
       try {
-        const meta = JSON.parse(readFileSync(metaPath, 'utf8'));
+        const meta = JSON.parse(readFileSync(metaPath, "utf8"));
         if (meta.title) title = meta.title;
         if (meta.description) description = meta.description;
         if (Array.isArray(meta.tags)) tags = meta.tags;
         if (meta.author) author = meta.author;
         if (meta.version) tplVersion = meta.version;
-        if (Array.isArray(meta.exportPresets)) exportPresets = meta.exportPresets;
+        if (Array.isArray(meta.exportPresets))
+          exportPresets = meta.exportPresets;
         if (Array.isArray(meta.seedPacks)) seedPacks = meta.seedPacks;
-        if (meta.scaffoldConfig && typeof meta.scaffoldConfig === 'object') scaffoldConfig = meta.scaffoldConfig;
+        if (meta.scaffoldConfig && typeof meta.scaffoldConfig === "object")
+          scaffoldConfig = meta.scaffoldConfig;
       } catch {
         // skip malformed sidecar
       }
     }
 
     templates.push({
-      name: tplName, file, title, placeholders, description, lines, size,
-      features, tags, author, version: tplVersion, exportPresets, seedPacks, scaffoldConfig,
+      name: tplName,
+      file,
+      title,
+      placeholders,
+      description,
+      lines,
+      size,
+      features,
+      tags,
+      author,
+      version: tplVersion,
+      exportPresets,
+      seedPacks,
+      scaffoldConfig,
     });
   }
   return templates;
 }
 
 // Re-export tools
-export { detectSprints } from '../tools/detect-sprints.js';
-export { generateManifest } from '../tools/generate-manifest.js';
+export { detectSprints } from "../tools/detect-sprints.js";
+export { generateManifest } from "../tools/generate-manifest.js";