@smartmemory/compose 0.1.0

package/server/artifact-manager.js

@@ -0,0 +1,247 @@
+/**
+ * artifact-manager.js — Artifact schema definitions, quality assessment,
+ * scaffolding, and template loading.
+ *
+ * Stateless — reads files and schemas, computes signals, returns data.
+ * No persistence beyond what the lifecycle manager already stores.
+ */
+
+import fs from 'node:fs';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+/** Phases that produce named artifacts (derived from contracts/lifecycle.json). */
+const PHASE_ARTIFACTS = {
+  explore_design: 'design.md',
+  prd: 'prd.md',
+  architecture: 'architecture.md',
+  blueprint: 'blueprint.md',
+  plan: 'plan.md',
+  report: 'report.md',
+};
+
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+const TEMPLATES_DIR = path.join(__dirname, 'artifact-templates');
+
+// ---------------------------------------------------------------------------
+// Artifact schemas
+// ---------------------------------------------------------------------------
+
+export const ARTIFACT_SCHEMAS = {
+  'design.md': {
+    requiredSections: ['Problem', 'Goal'],
+    optionalSections: ['Related Documents', 'Decision \\d+', 'Files', 'Open Questions', 'Resolved Questions'],
+    minWordCount: 200,
+  },
+  'prd.md': {
+    requiredSections: ['Problem Statement', 'Goals & Non-Goals', 'Requirements'],
+    optionalSections: ['Success Criteria', 'User Stories', 'Constraints', 'Open Questions'],
+    minWordCount: 300,
+  },
+  'architecture.md': {
+    requiredSections: ['Problem', 'Proposals'],
+    optionalSections: ['Trade-offs', 'Decision', 'Component Diagram'],
+    minWordCount: 200,
+  },
+  'blueprint.md': {
+    requiredSections: ['File Plan'],
+    optionalSections: ['Corrections Table'],
+    minWordCount: 300,
+  },
+  'plan.md': {
+    requiredSections: ['Task Order', 'Task 1'],
+    optionalSections: ['Files Summary'],
+    minWordCount: 150,
+  },
+  'report.md': {
+    requiredSections: ['Summary', 'Files Changed'],
+    optionalSections: ['Delivered vs Planned', 'Architecture Deviations', 'Key Decisions', 'Test Coverage', 'Known Issues', 'Lessons Learned'],
+    minWordCount: 200,
+  },
+};
+
+// ---------------------------------------------------------------------------
+// Startup invariant: schema keys must match PHASE_ARTIFACTS values
+// ---------------------------------------------------------------------------
+
+const schemaKeys = new Set(Object.keys(ARTIFACT_SCHEMAS));
+const artifactValues = new Set(Object.values(PHASE_ARTIFACTS));
+if (schemaKeys.size !== artifactValues.size || [...schemaKeys].some(k => !artifactValues.has(k))) {
+  throw new Error('ARTIFACT_SCHEMAS keys and PHASE_ARTIFACTS values are out of sync');
+}
+
+// ---------------------------------------------------------------------------
+// Private helpers
+// ---------------------------------------------------------------------------
+
+function _validateFeatureCode(featureCode) {
+  if (!featureCode || !/^[A-Za-z0-9_-]+$/.test(featureCode)) {
+    throw new Error(`Invalid featureCode: ${featureCode}`);
+  }
+}
+
+function _featurePath(featureRoot, featureCode) {
+  _validateFeatureCode(featureCode);
+  const realRoot = fs.realpathSync(featureRoot);
+  const candidate = path.resolve(realRoot, featureCode);
+  if (!candidate.startsWith(realRoot + path.sep) && candidate !== realRoot) {
+    throw new Error(`Path escapes feature root: ${featureCode}`);
+  }
+  // Tier 2: if candidate exists, verify real path
+  if (fs.existsSync(candidate)) {
+    const realCandidate = fs.realpathSync(candidate);
+    if (!realCandidate.startsWith(realRoot + path.sep) && realCandidate !== realRoot) {
+      throw new Error(`Symlink escapes feature root: ${featureCode}`);
+    }
+  }
+  return candidate;
+}
+
+function _extractSections(markdown) {
+  const headings = [];
+  for (const line of markdown.split('\n')) {
+    const m = line.match(/^#{1,4}\s+(.+)$/);
+    if (m) {
+      let text = m[1].trim();
+      // Strip trailing punctuation (with optional leading/trailing whitespace)
+      text = text.replace(/\s*[:—–]+\s*$/, '');
+      headings.push(text);
+    }
+  }
+  return headings;
+}
+
+function _matchPattern(heading, pattern) {
+  if (pattern.includes('\\d+')) {
+    const re = new RegExp(`^${pattern}$`, 'i');
+    return re.test(heading);
+  }
+  return heading.toLowerCase() === pattern.toLowerCase();
+}
+
+function _matchSections(foundHeadings, schema) {
+  const found = [];
+  const missing = [];
+  for (const pattern of schema.requiredSections) {
+    if (foundHeadings.some(h => _matchPattern(h, pattern))) {
+      found.push(pattern);
+    } else {
+      missing.push(pattern);
+    }
+  }
+
+  const optional = [];
+  for (const pattern of schema.optionalSections) {
+    if (foundHeadings.some(h => _matchPattern(h, pattern))) {
+      optional.push(pattern);
+    }
+  }
+
+  return { found, missing, optional };
+}
+
+// ---------------------------------------------------------------------------
+// ArtifactManager
+// ---------------------------------------------------------------------------
+
+export class ArtifactManager {
+  #featureRoot;
+
+  constructor(featureRoot) {
+    this.#featureRoot = featureRoot;
+  }
+
+  assess(featureCode) {
+    const artifacts = {};
+    for (const filename of Object.keys(ARTIFACT_SCHEMAS)) {
+      artifacts[filename] = this.assessOne(featureCode, filename);
+    }
+    return { artifacts };
+  }
+
+  assessOne(featureCode, filename) {
+    if (!ARTIFACT_SCHEMAS[filename]) {
+      throw new Error(`Unknown artifact: ${filename}`);
+    }
+    const dir = _featurePath(this.#featureRoot, featureCode);
+    const filePath = path.join(dir, filename);
+    const schema = ARTIFACT_SCHEMAS[filename];
+
+    // Check file-level symlink escape
+    if (fs.existsSync(filePath)) {
+      const realFile = fs.realpathSync(filePath);
+      const realRoot = fs.realpathSync(this.#featureRoot);
+      if (!realFile.startsWith(realRoot + path.sep)) {
+        throw new Error(`Symlink escapes feature root: ${filename}`);
+      }
+    }
+
+    if (!fs.existsSync(filePath)) {
+      return {
+        exists: false,
+        wordCount: 0,
+        meetsMinWordCount: false,
+        sections: { found: [], missing: [...schema.requiredSections], optional: [] },
+        completeness: 0,
+        lastModified: null,
+      };
+    }
+
+    const content = fs.readFileSync(filePath, 'utf-8');
+    const wordCount = content.split(/\s+/).filter(Boolean).length;
+    const headings = _extractSections(content);
+    const sections = _matchSections(headings, schema);
+    const completeness = schema.requiredSections.length > 0
+      ? sections.found.length / schema.requiredSections.length
+      : 1.0;
+    const lastModified = fs.statSync(filePath).mtime.toISOString();
+
+    return {
+      exists: true,
+      wordCount,
+      meetsMinWordCount: wordCount >= schema.minWordCount,
+      sections,
+      completeness,
+      lastModified,
+    };
+  }
+
+  scaffold(featureCode, options) {
+    const dir = _featurePath(this.#featureRoot, featureCode);
+    const created = [];
+    const skipped = [];
+
+    // Create directories
+    fs.mkdirSync(dir, { recursive: true });
+    fs.mkdirSync(path.join(dir, 'sessions'), { recursive: true });
+
+    for (const filename of Object.keys(ARTIFACT_SCHEMAS)) {
+      if (options?.only && !options.only.includes(filename)) continue;
+
+      const filePath = path.join(dir, filename);
+      if (fs.existsSync(filePath)) {
+        skipped.push(filename);
+      } else {
+        const template = this.getTemplate(filename);
+        fs.writeFileSync(filePath, template, 'utf-8');
+        created.push(filename);
+      }
+    }
+
+    return { created, skipped };
+  }
+
+  getTemplate(artifactName) {
+    if (!ARTIFACT_SCHEMAS[artifactName]) {
+      throw new Error(`Unknown artifact: ${artifactName}`);
+    }
+    const filePath = path.join(TEMPLATES_DIR, artifactName);
+    if (!fs.existsSync(filePath)) {
+      throw new Error(`Template not found: ${artifactName}`);
+    }
+    return fs.readFileSync(filePath, 'utf-8');
+  }
+
+  getSchema(artifactName) {
+    return ARTIFACT_SCHEMAS[artifactName] || null;
+  }
+}

package/server/artifact-templates/architecture.md

@@ -0,0 +1,28 @@
+# <Feature Name>: Architecture
+
+**Status:** ARCHITECTURE
+**Date:** <date>
+
+## Problem
+
+<!-- Technical problem statement -->
+
+## Proposals
+
+### Proposal A: <Name>
+
+<!-- Description, trade-offs, diagram if helpful -->
+
+### Proposal B: <Name>
+
+<!-- Description, trade-offs, diagram if helpful -->
+
+## Trade-offs
+
+| Dimension | Proposal A | Proposal B |
+|-----------|-----------|-----------|
+| | | |
+
+## Decision
+
+<!-- Which proposal was chosen and why -->

package/server/artifact-templates/blueprint.md

@@ -0,0 +1,21 @@
+# <Feature Name>: Implementation Blueprint
+
+**Status:** BLUEPRINT
+**Date:** <date>
+**Design:** [design.md](design.md)
+
+---
+
+## File Plan
+
+| File | Action | Purpose |
+|------|--------|---------|
+| | | |
+
+---
+
+## Corrections Table
+
+| Spec Assumption | Reality | Resolution |
+|----------------|---------|------------|
+| | | |

package/server/artifact-templates/design.md

@@ -0,0 +1,36 @@
+# <Feature Name>: Design
+
+**Status:** DESIGN
+**Date:** <date>
+
+## Related Documents
+
+<!-- Link to roadmap, dependencies, and related features -->
+
+---
+
+## Problem
+
+<!-- Describe the problem this feature solves -->
+
+## Goal
+
+<!-- What does success look like? Scope and non-scope. -->
+
+---
+
+## Decision 1: <Title>
+
+<!-- Describe the decision, options considered, and rationale -->
+
+---
+
+## Files
+
+| File | Action | Purpose |
+|------|--------|---------|
+| | | |
+
+## Open Questions
+
+<!-- List unresolved questions -->

package/server/artifact-templates/plan.md

@@ -0,0 +1,25 @@
+# <Feature Name>: Implementation Plan
+
+**Status:** PLAN
+**Date:** <date>
+**Blueprint:** [blueprint.md](blueprint.md)
+
+---
+
+## Task Order
+
+<!-- List tasks in dependency order -->
+
+## Task 1: <Title>
+
+- **File:** `<path>` (new/existing)
+- **What:** <!-- What to implement -->
+- **Pattern:** <!-- Existing pattern to follow -->
+- **Test:** <!-- What test to write -->
+- **Depends on:** <!-- Task dependencies -->
+
+## Files Summary
+
+| File | Tasks |
+|------|-------|
+| | |

package/server/artifact-templates/prd.md

@@ -0,0 +1,43 @@
+# <Feature Name>: PRD
+
+**Status:** PRD
+**Date:** <date>
+
+## Problem Statement
+
+<!-- What problem are we solving and for whom? -->
+
+## Goals & Non-Goals
+
+### Goals
+<!-- What this feature WILL do -->
+
+### Non-Goals
+<!-- What this feature will NOT do -->
+
+## Requirements
+
+### MUST
+<!-- Non-negotiable requirements -->
+
+### SHOULD
+<!-- Important but not blocking -->
+
+### MAY
+<!-- Nice-to-have -->
+
+## Success Criteria
+
+<!-- How do we know this feature succeeded? -->
+
+## User Stories
+
+<!-- As a <role>, I want <goal> so that <benefit> -->
+
+## Constraints
+
+<!-- Technical, time, or resource constraints -->
+
+## Open Questions
+
+<!-- Unresolved questions -->

package/server/artifact-templates/report.md

@@ -0,0 +1,40 @@
+# <Feature Name>: Implementation Report
+
+**Status:** REPORT
+**Date:** <date>
+
+## Summary
+
+<!-- 2-3 sentence overview of what was delivered -->
+
+## Delivered vs Planned
+
+| Planned | Delivered | Notes |
+|---------|-----------|-------|
+| | | |
+
+## Architecture Deviations
+
+<!-- Any deviations from the architecture/blueprint -->
+
+## Key Decisions
+
+<!-- Decisions made during implementation -->
+
+## Test Coverage
+
+<!-- What's tested, what's not, and why -->
+
+## Files Changed
+
+| File | Action | Purpose |
+|------|--------|---------|
+| | | |
+
+## Known Issues
+
+<!-- Known bugs, tech debt, or incomplete work -->
+
+## Lessons Learned
+
+<!-- What went well, what didn't, what to do differently -->

package/server/block-tracker.js

@@ -0,0 +1,90 @@
+/**
+ * block-tracker.js — Work block detection and classification.
+ *
+ * These functions operate on a session object passed by reference,
+ * extracted from SessionManager to keep it under the line limit.
+ */
+
+// ---------------------------------------------------------------------------
+// Block detection
+// ---------------------------------------------------------------------------
+
+/**
+ * Detect block boundaries: a new block starts when the set of resolved items changes.
+ *
+ * @param {object} session — the current session object (mutated in place)
+ * @param {string[]} itemIds — current resolved item IDs
+ * @param {string} now — ISO timestamp
+ * @param {string} category — tool category string
+ */
+export function updateBlock(session, itemIds, now, category) {
+  const currentSet = session.currentBlock?.itemIds;
+
+  const sameBlock = currentSet
+    && itemIds.length === currentSet.size
+    && itemIds.every(id => currentSet.has(id));
+
+  if (sameBlock) {
+    session.currentBlock.toolCount++;
+    if (category) session.currentBlock.categories.add(category);
+    return;
+  }
+
+  // Different set → close current block, start new one
+  closeCurrentBlock(session);
+
+  session.currentBlock = {
+    itemIds: new Set(itemIds),
+    startedAt: now,
+    toolCount: 1,
+    categories: new Set(category ? [category] : []),
+  };
+}
+
+// ---------------------------------------------------------------------------
+// Block closing
+// ---------------------------------------------------------------------------
+
+/**
+ * Close the current block and push it to session.blocks.
+ *
+ * @param {object} session — the current session object (mutated in place)
+ */
+export function closeCurrentBlock(session) {
+  if (!session?.currentBlock) return;
+
+  const block = session.currentBlock;
+  session.blocks.push({
+    itemIds: Array.from(block.itemIds),
+    startedAt: block.startedAt,
+    endedAt: new Date().toISOString(),
+    toolCount: block.toolCount,
+    categories: Array.from(block.categories || []),
+    intent: classifyBlockIntent(block),
+  });
+
+  session.currentBlock = null;
+}
+
+// ---------------------------------------------------------------------------
+// Block classification
+// ---------------------------------------------------------------------------
+
+/**
+ * Classify a work block's intent from the categories of tools used.
+ *
+ * @param {object} block — block with a categories Set
+ * @returns {'building'|'debugging'|'testing'|'exploring'|'thinking'|'mixed'}
+ */
+export function classifyBlockIntent(block) {
+  const cats = block.categories || new Set();
+  const hasWriting = cats.has('writing');
+  const hasExecuting = cats.has('executing');
+  const hasReading = cats.has('reading') || cats.has('searching');
+  if (hasWriting && !hasExecuting) return 'building';
+  if (hasWriting && hasExecuting) return 'debugging';
+  if (hasExecuting && !hasWriting) return 'testing';
+  if (hasReading && !hasWriting && !hasExecuting) return 'exploring';
+  if (cats.size === 0) return 'thinking';
+  return 'mixed';
+}