@grainulation/silo 1.0.0

package/lib/import-export.js

@@ -0,0 +1,174 @@
+/**
+ * import-export.js — Pull claims between sprints and silos
+ *
+ * Handles the core workflow: take claims from a silo collection
+ * (or built-in pack) and merge them into a sprint's claims.json.
+ */
+
+const fs = require('node:fs');
+const path = require('node:path');
+const { Store } = require('./store.js');
+
+/**
+ * Normalize a claim to wheat's canonical schema.
+ * Handles legacy fields: tier -> evidence, text -> content.
+ * Fills in missing required fields with sensible defaults.
+ */
+function normalizeClaim(claim) {
+  const normalized = { ...claim };
+
+  // Map legacy field names to wheat-canonical names
+  if ('tier' in normalized && !('evidence' in normalized)) {
+    normalized.evidence = normalized.tier;
+  }
+  delete normalized.tier;
+
+  if ('text' in normalized && !('content' in normalized)) {
+    normalized.content = normalized.text;
+  }
+  delete normalized.text;
+
+  // Ensure all required wheat fields exist
+  normalized.id = normalized.id || null;
+  normalized.type = normalized.type || 'factual';
+  normalized.topic = normalized.topic || '';
+  normalized.content = normalized.content || '';
+  normalized.evidence = normalized.evidence || 'stated';
+  normalized.status = normalized.status || 'active';
+  normalized.phase_added = normalized.phase_added || 'import';
+  normalized.timestamp = normalized.timestamp || new Date().toISOString();
+  normalized.conflicts_with = normalized.conflicts_with || [];
+  normalized.resolved_by = normalized.resolved_by || null;
+  normalized.tags = normalized.tags || [];
+
+  // Normalize source to object form
+  if (!normalized.source || typeof normalized.source === 'string') {
+    normalized.source = {
+      origin: typeof normalized.source === 'string' ? normalized.source : 'silo-import',
+      artifact: null,
+      connector: null,
+    };
+  }
+
+  return normalized;
+}
+
+class ImportExport {
+  constructor(store) {
+    this.store = store || new Store();
+  }
+
+  /**
+   * Pull claims from a silo collection into a target claims file.
+   * New claims get re-prefixed to avoid ID collisions.
+   *
+   * @param {string} source - Collection name/id or built-in pack name
+   * @param {string} targetPath - Path to claims.json to merge into
+   * @param {object} opts
+   * @param {string} opts.prefix - Claim ID prefix for imported claims (default: 'imp')
+   * @param {string[]} opts.types - Only import these claim types
+   * @param {string[]} opts.ids - Only import claims with these original IDs
+   * @param {boolean} opts.dryRun - If true, return what would be imported without writing
+   */
+  pull(source, targetPath, opts = {}) {
+    const { prefix = 'imp', types, ids, dryRun = false } = opts;
+
+    // Resolve source: try silo store first, then built-in packs
+    let sourceClaims = this._resolveSource(source);
+    if (!sourceClaims) {
+      throw new Error(`Collection or pack "${source}" not found`);
+    }
+
+    // Normalize all claims to wheat schema
+    sourceClaims = sourceClaims.map(normalizeClaim);
+
+    // Filter by specific claim IDs if requested
+    if (ids && ids.length > 0) {
+      const idSet = new Set(ids);
+      sourceClaims = sourceClaims.filter((c) => idSet.has(c.id));
+    }
+
+    // Filter by type if requested
+    if (types && types.length > 0) {
+      sourceClaims = sourceClaims.filter((c) => types.includes(c.type));
+    }
+
+    // Re-prefix claim IDs
+    const imported = sourceClaims.map((claim, i) => ({
+      ...claim,
+      id: `${prefix}${String(i + 1).padStart(3, '0')}`,
+      importedFrom: source,
+      importedAt: new Date().toISOString(),
+    }));
+
+    if (dryRun) {
+      return { wouldImport: imported.length, claims: imported };
+    }
+
+    // Read existing target or create empty
+    let existing = [];
+    if (fs.existsSync(targetPath)) {
+      const raw = JSON.parse(fs.readFileSync(targetPath, 'utf-8'));
+      existing = Array.isArray(raw) ? raw : raw.claims || [];
+    }
+
+    // Deduplicate by content (wheat-canonical field)
+    const existingTexts = new Set(
+      existing.map((c) => (c.content || c.text || '').toLowerCase()),
+    );
+    const deduped = imported.filter(
+      (c) => !existingTexts.has((c.content || '').toLowerCase()),
+    );
+
+    const merged = [...existing, ...deduped];
+    const output = Array.isArray(JSON.parse(fs.readFileSync(targetPath, 'utf-8') || '[]'))
+      ? merged
+      : { claims: merged };
+
+    const tmp = targetPath + '.tmp.' + process.pid;
+    fs.writeFileSync(tmp, JSON.stringify(output, null, 2) + '\n', 'utf-8');
+    fs.renameSync(tmp, targetPath);
+
+    return {
+      imported: deduped.length,
+      skippedDuplicates: imported.length - deduped.length,
+      totalClaims: merged.length,
+    };
+  }
+
+  /**
+   * Export claims from a sprint's claims.json into the silo.
+   *
+   * @param {string} sourcePath - Path to claims.json
+   * @param {string} name - Name for the stored collection
+   * @param {object} meta - Additional metadata
+   */
+  push(sourcePath, name, meta = {}) {
+    if (!fs.existsSync(sourcePath)) {
+      throw new Error(`Claims file not found: ${sourcePath}`);
+    }
+
+    const raw = JSON.parse(fs.readFileSync(sourcePath, 'utf-8'));
+    const claims = Array.isArray(raw) ? raw : raw.claims || [];
+
+    return this.store.storeClaims(name, claims, meta);
+  }
+
+  /** Resolve a source name to an array of claims. */
+  _resolveSource(source) {
+    // Try silo store
+    const stored = this.store.getClaims(source);
+    if (stored) return stored.claims;
+
+    // Try built-in packs
+    const packPath = path.join(__dirname, '..', 'packs', `${source}.json`);
+    if (fs.existsSync(packPath)) {
+      const pack = JSON.parse(fs.readFileSync(packPath, 'utf-8'));
+      return pack.claims || [];
+    }
+
+    return null;
+  }
+}
+
+module.exports = { ImportExport, normalizeClaim };

package/lib/index.js

@@ -0,0 +1,28 @@
+/**
+ * index.js — Unified entry point for @grainulation/silo
+ *
+ * Re-exports all public modules so consumers can import from a single path.
+ */
+
+const { readFileSync } = require('node:fs');
+const { join } = require('node:path');
+const { Store, DEFAULT_SILO_DIR } = require('./store.js');
+const { Search } = require('./search.js');
+const { Packs } = require('./packs.js');
+const { ImportExport } = require('./import-export.js');
+const { Templates } = require('./templates.js');
+
+const pkg = JSON.parse(readFileSync(join(__dirname, '..', 'package.json'), 'utf-8'));
+
+module.exports = {
+  name: 'silo',
+  version: pkg.version,
+  description: pkg.description,
+
+  Store,
+  DEFAULT_SILO_DIR,
+  Search,
+  Packs,
+  ImportExport,
+  Templates,
+};

package/lib/packs.js

@@ -0,0 +1,184 @@
+/**
+ * packs.js — Knowledge pack bundling
+ *
+ * Packs are versioned bundles of claims + templates that teams can
+ * publish and subscribe to. A pack is a directory or JSON file with
+ * a manifest, claims, and optional templates.
+ */
+
+const fs = require('node:fs');
+const path = require('node:path');
+const crypto = require('node:crypto');
+const { Store } = require('./store.js');
+
+const BUILT_IN_PACKS_DIR = path.join(__dirname, '..', 'packs');
+
+class Packs {
+  constructor(store) {
+    this.store = store || new Store();
+  }
+
+  /** List all available packs (built-in + locally installed). */
+  list() {
+    const packs = [];
+
+    // Built-in packs
+    if (fs.existsSync(BUILT_IN_PACKS_DIR)) {
+      for (const file of fs.readdirSync(BUILT_IN_PACKS_DIR)) {
+        if (!file.endsWith('.json')) continue;
+        try {
+          const data = JSON.parse(
+            fs.readFileSync(path.join(BUILT_IN_PACKS_DIR, file), 'utf-8'),
+          );
+          packs.push({
+            id: file.replace('.json', ''),
+            name: data.name,
+            description: data.description,
+            claimCount: (data.claims || []).length,
+            version: data.version || '1.0.0',
+            source: 'built-in',
+          });
+        } catch {
+          // skip malformed
+        }
+      }
+    }
+
+    // Locally installed packs
+    const localDir = this.store.packsDir;
+    if (fs.existsSync(localDir)) {
+      for (const file of fs.readdirSync(localDir)) {
+        if (!file.endsWith('.json')) continue;
+        try {
+          const data = JSON.parse(
+            fs.readFileSync(path.join(localDir, file), 'utf-8'),
+          );
+          packs.push({
+            id: file.replace('.json', ''),
+            name: data.name,
+            description: data.description,
+            claimCount: (data.claims || []).length,
+            version: data.version || '1.0.0',
+            source: 'local',
+          });
+        } catch {
+          // skip malformed
+        }
+      }
+    }
+
+    return packs;
+  }
+
+  /** Get a pack by ID (checks built-in first, then local). */
+  get(id) {
+    const builtIn = path.join(BUILT_IN_PACKS_DIR, `${id}.json`);
+    if (fs.existsSync(builtIn)) {
+      return JSON.parse(fs.readFileSync(builtIn, 'utf-8'));
+    }
+
+    const local = path.join(this.store.packsDir, `${id}.json`);
+    if (fs.existsSync(local)) {
+      return JSON.parse(fs.readFileSync(local, 'utf-8'));
+    }
+
+    return null;
+  }
+
+  /**
+   * Bundle claims from the silo into a publishable pack.
+   *
+   * @param {string} name - Pack name
+   * @param {string[]} collectionIds - Claim collection IDs to include
+   * @param {object} meta - Pack metadata (description, version, author)
+   */
+  bundle(name, collectionIds, meta = {}) {
+    this.store.init();
+    const allClaims = [];
+
+    for (const id of collectionIds) {
+      const data = this.store.getClaims(id);
+      if (data) {
+        allClaims.push(...(data.claims || []));
+      }
+    }
+
+    const pack = {
+      name,
+      description: meta.description || '',
+      version: meta.version || '1.0.0',
+      author: meta.author || '',
+      createdAt: new Date().toISOString(),
+      hash: crypto.createHash('sha256').update(JSON.stringify(allClaims)).digest('hex'),
+      sources: collectionIds,
+      claims: allClaims,
+    };
+
+    const slug = name.toLowerCase().replace(/[^a-z0-9]+/g, '-').replace(/^-|-$/g, '');
+    const packPath = path.join(this.store.packsDir, `${slug}.json`);
+    const tmp = packPath + '.tmp.' + process.pid;
+    fs.writeFileSync(tmp, JSON.stringify(pack, null, 2) + '\n', 'utf-8');
+    fs.renameSync(tmp, packPath);
+
+    return { id: slug, path: packPath, claimCount: allClaims.length };
+  }
+
+  /**
+   * Install a pack from a file path into the local silo.
+   *
+   * @param {string} filePath - Path to the pack JSON file
+   */
+  install(filePath, options = {}) {
+    if (!fs.existsSync(filePath)) {
+      throw new Error(`Pack file not found: ${filePath}`);
+    }
+
+    const pack = JSON.parse(fs.readFileSync(filePath, 'utf-8'));
+    const slug = (pack.name || path.basename(filePath, '.json'))
+      .toLowerCase()
+      .replace(/[^a-z0-9]+/g, '-')
+      .replace(/^-|-$/g, '');
+
+    // Verify pack integrity if hash present
+    if (pack.hash && pack.claims) {
+      const actual = crypto.createHash('sha256').update(JSON.stringify(pack.claims)).digest('hex');
+      // Support both old 12-char and new 64-char hashes
+      if (pack.hash !== actual && !actual.startsWith(pack.hash)) {
+        if (!options.force) {
+          throw new Error(`Pack integrity check failed: hash mismatch. Use --force to install anyway.`);
+        }
+      }
+    }
+
+    this.store.init();
+    const dest = path.join(this.store.packsDir, `${slug}.json`);
+
+    // Version comparison if pack already exists
+    if (fs.existsSync(dest) && !options.force) {
+      const existing = JSON.parse(fs.readFileSync(dest, 'utf-8'));
+      const cmp = _compareSemver(pack.version || '0.0.0', existing.version || '0.0.0');
+      if (cmp === 0) {
+        return { id: slug, claimCount: (pack.claims || []).length, skipped: true, reason: 'same version' };
+      }
+      if (cmp < 0) {
+        return { id: slug, claimCount: (pack.claims || []).length, skipped: true, reason: `downgrade (${existing.version} → ${pack.version}). Use --force to override.` };
+      }
+    }
+
+    fs.copyFileSync(filePath, dest);
+    return { id: slug, claimCount: (pack.claims || []).length };
+  }
+}
+
+/** Compare two semver strings. Returns -1, 0, or 1. */
+function _compareSemver(a, b) {
+  const pa = (a || '0.0.0').split('.').map(Number);
+  const pb = (b || '0.0.0').split('.').map(Number);
+  for (let i = 0; i < 3; i++) {
+    if ((pa[i] || 0) > (pb[i] || 0)) return 1;
+    if ((pa[i] || 0) < (pb[i] || 0)) return -1;
+  }
+  return 0;
+}
+
+module.exports = { Packs, _compareSemver };

package/lib/search.js

@@ -0,0 +1,128 @@
+/**
+ * search.js — Full-text search across stored claims
+ *
+ * Simple but effective: tokenize query, scan all claim files,
+ * rank by term frequency. No external deps.
+ */
+
+const fs = require('node:fs');
+const path = require('node:path');
+const { Store } = require('./store.js');
+
+class Search {
+  constructor(store) {
+    this.store = store || new Store();
+  }
+
+  /**
+   * Search across all stored claims.
+   * Returns matches sorted by relevance (highest first).
+   *
+   * @param {string} query - Search terms (space-separated, OR logic)
+   * @param {object} opts
+   * @param {string} opts.type - Filter by claim type (constraint, risk, etc.)
+   * @param {string} opts.evidence - Filter by evidence tier (also accepts legacy 'tier')
+   * @param {number} opts.limit - Max results (default 20)
+   */
+  query(query, opts = {}) {
+    const { type, evidence, tier, limit = 20 } = opts;
+    const evidenceFilter = evidence || tier; // support legacy 'tier' option
+    const tokens = this._tokenize(query);
+    if (tokens.length === 0) return [];
+
+    const results = [];
+    const claimsDir = this.store.claimsDir;
+
+    if (!fs.existsSync(claimsDir)) return [];
+
+    const files = fs.readdirSync(claimsDir).filter((f) => f.endsWith('.json'));
+
+    for (const file of files) {
+      const filePath = path.join(claimsDir, file);
+      let data;
+      try {
+        data = JSON.parse(fs.readFileSync(filePath, 'utf-8'));
+      } catch {
+        continue;
+      }
+
+      const collectionName = data.meta?.name || file.replace('.json', '');
+      const claims = data.claims || [];
+
+      for (const claim of claims) {
+        // Apply filters
+        if (type && claim.type !== type) continue;
+        const claimEvidence = claim.evidence || claim.tier;
+        if (evidenceFilter && claimEvidence !== evidenceFilter) continue;
+
+        // Score by token matches across searchable fields (support both content and legacy text)
+        const sourceStr = typeof claim.source === 'object'
+          ? [claim.source?.origin, claim.source?.artifact].filter(Boolean).join(' ')
+          : (claim.source || '');
+        const searchable = [
+          claim.content || claim.text || '',
+          claim.type || '',
+          claim.tags?.join(' ') || '',
+          sourceStr,
+          collectionName,
+        ]
+          .join(' ')
+          .toLowerCase();
+
+        let score = 0;
+        for (const token of tokens) {
+          const idx = searchable.indexOf(token);
+          if (idx !== -1) {
+            score += 1;
+            // Bonus for exact word match
+            if (searchable.includes(` ${token} `) || searchable.startsWith(`${token} `)) {
+              score += 0.5;
+            }
+          }
+        }
+
+        if (score > 0) {
+          results.push({
+            claim,
+            collection: collectionName,
+            score,
+          });
+        }
+      }
+    }
+
+    results.sort((a, b) => b.score - a.score);
+    return results.slice(0, limit);
+  }
+
+  /** List all unique tags across stored claims. */
+  tags() {
+    const tagSet = new Set();
+    const claimsDir = this.store.claimsDir;
+    if (!fs.existsSync(claimsDir)) return [];
+
+    const files = fs.readdirSync(claimsDir).filter((f) => f.endsWith('.json'));
+    for (const file of files) {
+      try {
+        const data = JSON.parse(fs.readFileSync(path.join(claimsDir, file), 'utf-8'));
+        for (const claim of data.claims || []) {
+          for (const tag of claim.tags || []) {
+            tagSet.add(tag);
+          }
+        }
+      } catch {
+        // skip malformed files
+      }
+    }
+    return [...tagSet].sort();
+  }
+
+  _tokenize(str) {
+    return str
+      .toLowerCase()
+      .split(/\s+/)
+      .filter((t) => t.length > 1);
+  }
+}
+
+module.exports = { Search };