@grainulation/silo 1.0.0

package/lib/templates.js

@@ -0,0 +1,139 @@
+/**
+ * templates.js — Sprint template management
+ *
+ * Templates are pre-built research questions with seeded claims.
+ * A template contains: question, audience, constraints, and starter claims.
+ */
+
+const fs = require('node:fs');
+const path = require('node:path');
+const { Store } = require('./store.js');
+
+class Templates {
+  constructor(store) {
+    this.store = store || new Store();
+  }
+
+  /**
+   * Save a sprint configuration as a reusable template.
+   *
+   * @param {string} name - Template name
+   * @param {object} template
+   * @param {string} template.question - Research question
+   * @param {string} template.audience - Who this is for
+   * @param {string[]} template.constraints - Hard constraints
+   * @param {object[]} template.seedClaims - Claims to start with
+   * @param {string[]} template.tags - Searchable tags
+   */
+  save(name, template) {
+    this.store.init();
+    const id = this._slugify(name);
+    const entry = {
+      id,
+      name,
+      ...template,
+      savedAt: new Date().toISOString(),
+    };
+    const filePath = path.join(this.store.templatesDir, `${id}.json`);
+    const tmp1 = filePath + '.tmp.' + process.pid;
+    fs.writeFileSync(tmp1, JSON.stringify(entry, null, 2) + '\n', 'utf-8');
+    fs.renameSync(tmp1, filePath);
+
+    this.store._addToIndex({
+      id,
+      name,
+      type: 'template',
+      claimCount: (template.seedClaims || []).length,
+      storedAt: entry.savedAt,
+    });
+
+    return entry;
+  }
+
+  /** Get a template by name/id. */
+  get(nameOrId) {
+    const id = this._slugify(nameOrId);
+    const filePath = path.join(this.store.templatesDir, `${id}.json`);
+    if (!fs.existsSync(filePath)) return null;
+    return JSON.parse(fs.readFileSync(filePath, 'utf-8'));
+  }
+
+  /** List all saved templates. */
+  list() {
+    this.store.init();
+    const dir = this.store.templatesDir;
+    if (!fs.existsSync(dir)) return [];
+
+    return fs
+      .readdirSync(dir)
+      .filter((f) => f.endsWith('.json'))
+      .map((f) => {
+        try {
+          const data = JSON.parse(fs.readFileSync(path.join(dir, f), 'utf-8'));
+          return {
+            id: data.id,
+            name: data.name,
+            question: data.question,
+            seedClaims: (data.seedClaims || []).length,
+            tags: data.tags || [],
+          };
+        } catch {
+          return null;
+        }
+      })
+      .filter(Boolean);
+  }
+
+  /**
+   * Instantiate a template into a sprint directory.
+   * Creates claims.json with seed claims and a sprint config stub.
+   *
+   * @param {string} nameOrId - Template name/id
+   * @param {string} targetDir - Directory to instantiate into
+   */
+  instantiate(nameOrId, targetDir) {
+    const template = this.get(nameOrId);
+    if (!template) {
+      throw new Error(`Template "${nameOrId}" not found`);
+    }
+
+    if (!fs.existsSync(targetDir)) {
+      fs.mkdirSync(targetDir, { recursive: true });
+    }
+
+    // Write seed claims
+    const claimsPath = path.join(targetDir, 'claims.json');
+    const claims = (template.seedClaims || []).map((c, i) => ({
+      ...c,
+      id: c.id || `d${String(i + 1).padStart(3, '0')}`,
+    }));
+    const tmpClaims = claimsPath + '.tmp.' + process.pid;
+    fs.writeFileSync(tmpClaims, JSON.stringify(claims, null, 2) + '\n', 'utf-8');
+    fs.renameSync(tmpClaims, claimsPath);
+
+    // Write sprint config stub
+    const configPath = path.join(targetDir, 'sprint.json');
+    const config = {
+      question: template.question,
+      audience: template.audience,
+      constraints: template.constraints || [],
+      fromTemplate: template.id,
+      createdAt: new Date().toISOString(),
+    };
+    const tmpConfig = configPath + '.tmp.' + process.pid;
+    fs.writeFileSync(tmpConfig, JSON.stringify(config, null, 2) + '\n', 'utf-8');
+    fs.renameSync(tmpConfig, configPath);
+
+    return {
+      claimsFile: claimsPath,
+      configFile: configPath,
+      seedClaims: claims.length,
+    };
+  }
+
+  _slugify(str) {
+    return str.toLowerCase().replace(/[^a-z0-9]+/g, '-').replace(/^-|-$/g, '');
+  }
+}
+
+module.exports = { Templates };

package/package.json

@@ -0,0 +1,48 @@
+{
+  "name": "@grainulation/silo",
+  "version": "1.0.0",
+  "description": "Reusable knowledge for research sprints -- shared claim libraries, templates, and knowledge packs",
+  "main": "lib/index.js",
+  "exports": {
+    ".": "./lib/index.js",
+    "./server": {
+      "import": "./lib/server.js"
+    },
+    "./tokens": "./public/grainulation-tokens.css"
+  },
+  "bin": {
+    "silo": "bin/silo.js"
+  },
+  "scripts": {
+    "test": "node test/basic.test.js",
+    "start": "node bin/silo.js serve",
+    "serve": "node bin/silo.js serve"
+  },
+  "keywords": [
+    "research",
+    "claims",
+    "knowledge",
+    "templates",
+    "sprint"
+  ],
+  "author": "grainulation contributors",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/grainulation/silo.git"
+  },
+  "engines": {
+    "node": ">=18.0.0"
+  },
+  "bugs": {
+    "url": "https://github.com/grainulation/silo/issues"
+  },
+  "homepage": "https://silo.grainulation.com",
+  "files": [
+    "bin/",
+    "lib/",
+    "packs/",
+    "public/",
+    "CHANGELOG.md"
+  ]
+}

package/packs/api-design.json

@@ -0,0 +1,189 @@
+{
+  "name": "API Design",
+  "description": "REST conventions, versioning strategies, pagination, error formats, backwards compatibility, and GraphQL tradeoff analysis for HTTP APIs.",
+  "version": "1.0.0",
+  "claims": [
+    {
+      "id": "api-001",
+      "type": "constraint",
+      "topic": "HTTP method semantics",
+      "content": "GET must be safe and idempotent (no side effects). PUT must be idempotent (same result on repeat). POST is neither safe nor idempotent. DELETE should be idempotent (deleting an already-deleted resource returns 204 or 404, not an error). Violating these semantics breaks caches, retries, and client expectations.",
+      "source": { "origin": "best-practice", "artifact": null, "connector": null },
+      "evidence": "documented",
+      "status": "active",
+      "phase_added": "define",
+      "timestamp": "2025-01-01T00:00:00.000Z",
+      "conflicts_with": [],
+      "resolved_by": null,
+      "tags": ["api", "rest", "http-methods", "idempotency"]
+    },
+    {
+      "id": "api-002",
+      "type": "recommendation",
+      "topic": "error response format",
+      "content": "Use RFC 7807 (Problem Details) for error responses: {type, title, status, detail, instance}. Include a machine-readable error code field for client-side branching. Never expose stack traces, internal paths, or database errors in production responses.",
+      "source": { "origin": "best-practice", "artifact": null, "connector": null },
+      "evidence": "documented",
+      "status": "active",
+      "phase_added": "define",
+      "timestamp": "2025-01-01T00:00:00.000Z",
+      "conflicts_with": [],
+      "resolved_by": null,
+      "tags": ["api", "error-handling", "rfc-7807", "rest"]
+    },
+    {
+      "id": "api-003",
+      "type": "recommendation",
+      "topic": "cursor-based pagination",
+      "content": "Prefer cursor-based pagination over offset-based for datasets that change frequently. Offset pagination becomes inconsistent when rows are inserted or deleted between pages. Cursor pagination uses an opaque token (base64-encoded last-seen ID) and supports consistent forward iteration. Return {data, next_cursor, has_more} in responses.",
+      "source": { "origin": "best-practice", "artifact": null, "connector": null },
+      "evidence": "production",
+      "status": "active",
+      "phase_added": "define",
+      "timestamp": "2025-01-01T00:00:00.000Z",
+      "conflicts_with": [],
+      "resolved_by": null,
+      "tags": ["api", "pagination", "cursor", "rest"]
+    },
+    {
+      "id": "api-004",
+      "type": "risk",
+      "topic": "URL path versioning lock-in",
+      "content": "URL path versioning (/v1/users, /v2/users) is simple but creates permanent routing complexity. Every version doubles the endpoint surface. Prefer header-based versioning (Accept: application/vnd.api+json;version=2) or additive-only changes (no versioning needed if you never remove or rename fields).",
+      "source": { "origin": "best-practice", "artifact": null, "connector": null },
+      "evidence": "web",
+      "status": "active",
+      "phase_added": "define",
+      "timestamp": "2025-01-01T00:00:00.000Z",
+      "conflicts_with": [],
+      "resolved_by": null,
+      "tags": ["api", "versioning", "rest", "backwards-compatibility"]
+    },
+    {
+      "id": "api-005",
+      "type": "constraint",
+      "topic": "backwards compatibility rules",
+      "content": "Breaking changes for public APIs: removing a field, renaming a field, changing a field type, changing a required/optional status, removing an endpoint, changing authentication. Non-breaking: adding optional fields, adding new endpoints, adding new enum values (if clients handle unknown values). Never make breaking changes without a version bump and deprecation period of at least 6 months.",
+      "source": { "origin": "best-practice", "artifact": null, "connector": null },
+      "evidence": "documented",
+      "status": "active",
+      "phase_added": "define",
+      "timestamp": "2025-01-01T00:00:00.000Z",
+      "conflicts_with": [],
+      "resolved_by": null,
+      "tags": ["api", "backwards-compatibility", "deprecation", "breaking-changes"]
+    },
+    {
+      "id": "api-006",
+      "type": "factual",
+      "topic": "GraphQL vs REST tradeoffs",
+      "content": "GraphQL eliminates over-fetching and under-fetching but introduces: query complexity analysis (must limit depth to 7-10 and breadth), N+1 data loader patterns, cache invalidation complexity (no HTTP caching by default), and a steeper client learning curve. REST is simpler for CRUD-heavy APIs with predictable access patterns.",
+      "source": { "origin": "best-practice", "artifact": null, "connector": null },
+      "evidence": "documented",
+      "status": "active",
+      "phase_added": "define",
+      "timestamp": "2025-01-01T00:00:00.000Z",
+      "conflicts_with": [],
+      "resolved_by": null,
+      "tags": ["api", "graphql", "rest", "tradeoffs"]
+    },
+    {
+      "id": "api-007",
+      "type": "recommendation",
+      "topic": "rate limit headers",
+      "content": "Include rate limit headers in every response: X-RateLimit-Limit (max requests per window), X-RateLimit-Remaining (remaining in current window), X-RateLimit-Reset (Unix timestamp when window resets). Return 429 Too Many Requests with a Retry-After header when limit is exceeded. This lets well-behaved clients self-throttle.",
+      "source": { "origin": "best-practice", "artifact": null, "connector": null },
+      "evidence": "documented",
+      "status": "active",
+      "phase_added": "define",
+      "timestamp": "2025-01-01T00:00:00.000Z",
+      "conflicts_with": [],
+      "resolved_by": null,
+      "tags": ["api", "rate-limiting", "headers", "429"]
+    },
+    {
+      "id": "api-008",
+      "type": "constraint",
+      "topic": "request payload size limits",
+      "content": "Set explicit request body size limits: 1 MB for standard JSON APIs, 10 MB for file uploads via multipart, and configurable limits for specific endpoints. Unbounded request bodies enable denial-of-service attacks. Return 413 Payload Too Large with a clear message stating the limit.",
+      "source": { "origin": "best-practice", "artifact": null, "connector": null },
+      "evidence": "documented",
+      "status": "active",
+      "phase_added": "define",
+      "timestamp": "2025-01-01T00:00:00.000Z",
+      "conflicts_with": [],
+      "resolved_by": null,
+      "tags": ["api", "security", "payload-limits", "dos"]
+    },
+    {
+      "id": "api-009",
+      "type": "recommendation",
+      "topic": "idempotency keys for mutations",
+      "content": "POST endpoints that create resources should accept an Idempotency-Key header. Store the key with the response for 24 hours. If a duplicate key arrives, return the stored response without re-executing. This prevents duplicate charges, orders, or records from network retries. Stripe, PayPal, and AWS all use this pattern.",
+      "source": { "origin": "best-practice", "artifact": null, "connector": null },
+      "evidence": "production",
+      "status": "active",
+      "phase_added": "define",
+      "timestamp": "2025-01-01T00:00:00.000Z",
+      "conflicts_with": [],
+      "resolved_by": null,
+      "tags": ["api", "idempotency", "reliability", "payments"]
+    },
+    {
+      "id": "api-010",
+      "type": "risk",
+      "topic": "nested resource depth",
+      "content": "Deeply nested REST routes (/orgs/:id/teams/:id/members/:id/roles) become rigid and hard to evolve. Limit nesting to 2 levels maximum. Use flat routes with query filters for deeper relationships (/roles?member_id=X&team_id=Y). Deep nesting also makes URL construction fragile for API consumers.",
+      "source": { "origin": "best-practice", "artifact": null, "connector": null },
+      "evidence": "web",
+      "status": "active",
+      "phase_added": "define",
+      "timestamp": "2025-01-01T00:00:00.000Z",
+      "conflicts_with": [],
+      "resolved_by": null,
+      "tags": ["api", "rest", "url-design", "nesting"]
+    },
+    {
+      "id": "api-011",
+      "type": "factual",
+      "topic": "HTTP status code semantics",
+      "content": "Use status codes precisely: 200 (success with body), 201 (created, include Location header), 204 (success, no body), 400 (malformed request), 401 (unauthenticated), 403 (authenticated but unauthorized), 404 (not found or hidden), 409 (conflict/duplicate), 422 (valid syntax but semantic error), 429 (rate limited), 500 (server error). Avoid 200-wrapping errors.",
+      "source": { "origin": "best-practice", "artifact": null, "connector": null },
+      "evidence": "documented",
+      "status": "active",
+      "phase_added": "define",
+      "timestamp": "2025-01-01T00:00:00.000Z",
+      "conflicts_with": [],
+      "resolved_by": null,
+      "tags": ["api", "http", "status-codes", "rest"]
+    },
+    {
+      "id": "api-012",
+      "type": "recommendation",
+      "topic": "API documentation contract testing",
+      "content": "Generate API documentation from code (OpenAPI/Swagger) rather than maintaining it manually. Use contract testing (Pact, Dredd, or OpenAPI-diff in CI) to verify that the implementation matches the spec. Manual docs drift within weeks; contract tests catch drift on every PR.",
+      "source": { "origin": "best-practice", "artifact": null, "connector": null },
+      "evidence": "tested",
+      "status": "active",
+      "phase_added": "define",
+      "timestamp": "2025-01-01T00:00:00.000Z",
+      "conflicts_with": [],
+      "resolved_by": null,
+      "tags": ["api", "documentation", "contract-testing", "openapi"]
+    },
+    {
+      "id": "api-013",
+      "type": "estimate",
+      "topic": "API response time targets",
+      "content": "For user-facing APIs: p50 under 100ms, p95 under 500ms, p99 under 1s. For internal service-to-service APIs: p50 under 20ms, p95 under 100ms. These targets assume a CDN for static assets and regional deployment. Every 100ms of API latency reduces conversion by approximately 1% in e-commerce contexts.",
+      "source": { "origin": "industry", "artifact": null, "connector": null },
+      "evidence": "web",
+      "status": "active",
+      "phase_added": "define",
+      "timestamp": "2025-01-01T00:00:00.000Z",
+      "conflicts_with": [],
+      "resolved_by": null,
+      "tags": ["api", "performance", "latency", "sla"]
+    }
+  ]
+}

package/packs/architecture.json

@@ -0,0 +1,175 @@
+{
+  "name": "Architecture Decision Templates",
+  "description": "Constraint and risk claims for common architecture decisions -- monolith vs microservices, build vs buy, sync vs async, SQL vs NoSQL. Drop into any ADR sprint.",
+  "version": "1.0.0",
+  "claims": [
+    {
+      "id": "arch-001",
+      "type": "constraint",
+      "topic": "microservices operational overhead",
+      "content": "Microservices add operational overhead proportional to service count: each service needs its own CI/CD pipeline, monitoring, alerting, and on-call rotation. Below ~10 engineers, this cost often exceeds the benefit.",
+      "source": { "origin": "best-practice", "artifact": null, "connector": null },
+      "evidence": "documented",
+      "status": "active",
+      "phase_added": "define",
+      "timestamp": "2025-01-01T00:00:00.000Z",
+      "conflicts_with": [],
+      "resolved_by": null,
+      "tags": ["architecture", "microservices", "team-size"]
+    },
+    {
+      "id": "arch-002",
+      "type": "risk",
+      "topic": "distributed transaction complexity",
+      "content": "Distributed transactions across microservices require saga patterns or two-phase commit. Both add complexity and failure modes that don't exist in a monolith.",
+      "source": { "origin": "best-practice", "artifact": null, "connector": null },
+      "evidence": "documented",
+      "status": "active",
+      "phase_added": "define",
+      "timestamp": "2025-01-01T00:00:00.000Z",
+      "conflicts_with": [],
+      "resolved_by": null,
+      "tags": ["architecture", "microservices", "transactions"]
+    },
+    {
+      "id": "arch-003",
+      "type": "factual",
+      "topic": "event-driven eventual consistency",
+      "content": "Event-driven architectures decouple producers from consumers but introduce eventual consistency. Any user-facing flow that requires strong consistency must use synchronous calls or compensating transactions.",
+      "source": { "origin": "best-practice", "artifact": null, "connector": null },
+      "evidence": "documented",
+      "status": "active",
+      "phase_added": "define",
+      "timestamp": "2025-01-01T00:00:00.000Z",
+      "conflicts_with": [],
+      "resolved_by": null,
+      "tags": ["architecture", "event-driven", "consistency"]
+    },
+    {
+      "id": "arch-004",
+      "type": "recommendation",
+      "topic": "modular monolith first",
+      "content": "Start with a modular monolith (clear module boundaries, separate data access per module) and extract services only when a module has a distinct scaling, deployment, or team-ownership need.",
+      "source": { "origin": "best-practice", "artifact": null, "connector": null },
+      "evidence": "documented",
+      "status": "active",
+      "phase_added": "define",
+      "timestamp": "2025-01-01T00:00:00.000Z",
+      "conflicts_with": [],
+      "resolved_by": null,
+      "tags": ["architecture", "monolith", "modularity"]
+    },
+    {
+      "id": "arch-005",
+      "type": "risk",
+      "topic": "build vs buy cost analysis",
+      "content": "Build vs buy: custom solutions accumulate maintenance cost of ~15-20% of initial build cost per year. SaaS vendors average 5-10% annual price increases. Break-even is typically 3-5 years.",
+      "source": { "origin": "industry", "artifact": null, "connector": null },
+      "evidence": "web",
+      "status": "active",
+      "phase_added": "define",
+      "timestamp": "2025-01-01T00:00:00.000Z",
+      "conflicts_with": [],
+      "resolved_by": null,
+      "tags": ["architecture", "build-vs-buy", "cost"]
+    },
+    {
+      "id": "arch-006",
+      "type": "constraint",
+      "topic": "SQL vs NoSQL decision criteria",
+      "content": "SQL databases provide ACID transactions and are the correct default for structured data with relationships. NoSQL is justified when: (a) schema is truly unpredictable, (b) horizontal write scaling is required, or (c) access patterns are pure key-value.",
+      "source": { "origin": "best-practice", "artifact": null, "connector": null },
+      "evidence": "documented",
+      "status": "active",
+      "phase_added": "define",
+      "timestamp": "2025-01-01T00:00:00.000Z",
+      "conflicts_with": [],
+      "resolved_by": null,
+      "tags": ["architecture", "database", "sql", "nosql"]
+    },
+    {
+      "id": "arch-007",
+      "type": "factual",
+      "topic": "CAP theorem",
+      "content": "CAP theorem: a distributed system can provide at most two of Consistency, Availability, and Partition tolerance. Since network partitions are inevitable, the real choice is between CP (consistent but may reject requests) and AP (available but may return stale data).",
+      "source": { "origin": "academic", "artifact": null, "connector": null },
+      "evidence": "documented",
+      "status": "active",
+      "phase_added": "define",
+      "timestamp": "2025-01-01T00:00:00.000Z",
+      "conflicts_with": [],
+      "resolved_by": null,
+      "tags": ["architecture", "cap-theorem", "distributed"]
+    },
+    {
+      "id": "arch-008",
+      "type": "risk",
+      "topic": "shared database coupling",
+      "content": "Shared databases between services create hidden coupling. Schema changes in one service break others. Each service should own its data store, exposing data only through APIs.",
+      "source": { "origin": "best-practice", "artifact": null, "connector": null },
+      "evidence": "documented",
+      "status": "active",
+      "phase_added": "define",
+      "timestamp": "2025-01-01T00:00:00.000Z",
+      "conflicts_with": [],
+      "resolved_by": null,
+      "tags": ["architecture", "database", "coupling"]
+    },
+    {
+      "id": "arch-009",
+      "type": "recommendation",
+      "topic": "cache invalidation strategy",
+      "content": "For cache invalidation, prefer short TTLs with stale-while-revalidate over complex invalidation logic. Cache invalidation bugs are the #1 source of data inconsistency in production systems.",
+      "source": { "origin": "industry", "artifact": null, "connector": null },
+      "evidence": "web",
+      "status": "active",
+      "phase_added": "define",
+      "timestamp": "2025-01-01T00:00:00.000Z",
+      "conflicts_with": [],
+      "resolved_by": null,
+      "tags": ["architecture", "caching", "invalidation"]
+    },
+    {
+      "id": "arch-010",
+      "type": "constraint",
+      "topic": "per-client rate limiting",
+      "content": "API gateway rate limiting must be set per client, not globally. Global limits allow a single misbehaving client to consume the entire quota. Use token bucket or sliding window algorithms.",
+      "source": { "origin": "best-practice", "artifact": null, "connector": null },
+      "evidence": "documented",
+      "status": "active",
+      "phase_added": "define",
+      "timestamp": "2025-01-01T00:00:00.000Z",
+      "conflicts_with": [],
+      "resolved_by": null,
+      "tags": ["architecture", "api", "rate-limiting"]
+    },
+    {
+      "id": "arch-011",
+      "type": "recommendation",
+      "topic": "circuit breaker pattern",
+      "content": "Circuit breakers (open after N failures, half-open after timeout, close after success) prevent cascade failures. Every synchronous cross-service call should have a circuit breaker with configurable thresholds.",
+      "source": { "origin": "best-practice", "artifact": null, "connector": null },
+      "evidence": "documented",
+      "status": "active",
+      "phase_added": "define",
+      "timestamp": "2025-01-01T00:00:00.000Z",
+      "conflicts_with": [],
+      "resolved_by": null,
+      "tags": ["architecture", "resilience", "circuit-breaker"]
+    },
+    {
+      "id": "arch-012",
+      "type": "factual",
+      "topic": "p99 latency over average",
+      "content": "Latency at the 99th percentile (p99) matters more than average latency for user experience. A system with 50ms average but 2s p99 feels worse than one with 100ms average and 200ms p99.",
+      "source": { "origin": "best-practice", "artifact": null, "connector": null },
+      "evidence": "documented",
+      "status": "active",
+      "phase_added": "define",
+      "timestamp": "2025-01-01T00:00:00.000Z",
+      "conflicts_with": [],
+      "resolved_by": null,
+      "tags": ["architecture", "latency", "performance"]
+    }
+  ]
+}