forgesmith 0.0.1 → 0.2.0

package/CHANGELOG.md

@@ -0,0 +1,26 @@
+# Changelog
+
+## 0.2.0 — Architecture Narrative Generators
+
+- `generateArchitectureWalkthrough(blueprint, opts, provider)` — long-form narrative explaining structure, key files, and important relationships. Tones: `technical` | `casual` | `onboarding`
+- `generateChangesSince(current, previous, opts, provider)` — delta narrative: what changed between two Blueprint snapshots (new/removed files, edge changes, stats delta)
+- `generateOnboardingDoc(blueprint, opts, provider)` — new-developer intro to codebase with "Start here", key folders, core shared files. Tones: `friendly` | `formal` | `technical`
+- `generateRefactoringReport(blueprint, opts, provider)` — identifies architecture debt (hot spots, high fan-out, import cycles), suggests refactoring priorities. Tones: `analytical` | `casual` | `executive`
+- `readBlueprintData(targetPath)` — reads `.prism/blueprint/snapshot.json`; returns `BlueprintData | null`
+- New exported types: `BlueprintData`, `BlueprintFile`, `BlueprintEdge`, `ArchitectureWalkthroughOpts`, `ChangesSinceOpts`, `OnboardingDocOpts`, `RefactoringReportOpts`
+- 44 unit tests, all green (+31 new)
+
+## 0.1.1 — /providers sub-entry fix
+
+- Add explicit `./providers` export entry to package.json exports map
+- Add `src/providers.ts` barrel (re-exports `DirectLlmProvider`)
+- Fixes `Module not found: Can't resolve 'forgesmith/providers'` for consumers
+
+## 0.1.0 — Initial real release
+
+- `generateReleaseNotes(data, opts, provider)` — LLM-powered release note generation from prism0x2A data
+- `readPrismDirectory(path)` — reads `.prism/` folder structure into `PrismData`
+- `DirectLlmProvider` — Anthropic SDK-backed LLM provider (import from `forgesmith/providers`)
+- `LlmProvider` interface for custom/mock providers
+- ESM + CJS dual-build via tsup
+- 13 unit tests, all green

package/README.md

@@ -1,15 +1,53 @@
 # forgesmith
 
-> Content & asset-generation engine for code intelligence.
->
-> *The lens observes. The smith forges.*
+Content & asset-generation engine for code intelligence.
 
-**Status:** Reserved — first release follows after prism0x2A v0.3.x ships.
+Forge release notes, blog posts, and social copy from [prism0x2A](https://github.com/dadenjo/prism0x2A) data.
 
-`forgesmith` is the engine library behind [`forge0x2B`](https://github.com/dadenjo/forge0x2B).
-It transforms code intelligence from [`prismlens`](https://github.com/dadenjo/prismlens) /
-[`prism0x2A`](https://github.com/dadenjo/prism0x2A) into communication-ready content:
-release notes, blog posts, social copy, internal updates.
+## Status
+
+**Phase 1** — release-notes generator. More asset-types coming in Phase 2.
+
+## Install
+
+```bash
+npm install forgesmith
+```
+
+## Use
+
+```ts
+import { generateReleaseNotes, readPrismDirectory } from 'forgesmith'
+import { DirectLlmProvider } from 'forgesmith/providers'
+
+const data = await readPrismDirectory('./my-project/.prism')
+const provider = new DirectLlmProvider({ apiKey: process.env.ANTHROPIC_KEY })
+const result = await generateReleaseNotes(data, { tone: 'professional' }, provider)
+console.log(result.text)
+```
+
+## API
+
+### `generateReleaseNotes(data, opts, provider)`
+
+Generates release notes from prism data.
+
+- `data: PrismData` — sessions, recommendations, insights from prism0x2A
+- `opts: ReleaseNotesOpts` — `tone`, `length`, `format`
+- `provider: LlmProvider` — any compatible LLM provider
+
+### `readPrismDirectory(prismPath)`
+
+Reads a `.prism/` folder and returns a `PrismData` object.
+
+### `DirectLlmProvider`
+
+Anthropic SDK-backed provider. Import from `forgesmith/providers`.
+
+```ts
+import { DirectLlmProvider } from 'forgesmith/providers'
+const provider = new DirectLlmProvider({ apiKey: '...', model: 'claude-sonnet-4-6' })
+```
 
 ## Architecture
 
@@ -20,20 +58,10 @@ prism0x2A   (dashboard — persists .prism/ data)
     ↓
 forgesmith  (this — forges assets from data)
     ↓
-forge0x2B   (dashboard product for marketing/comms)
+forge0x2B   (dashboard for marketing/comms)
 ```
 
-## Naming
-
-- **prismlens** *observes* — splits code into spectral analysis
-- **forgesmith** *produces* — takes the analysis and hammers out content
-
-Engines in this family carry **craft-appropriate** suffixes, not a forced uniform suffix.
-
-## Companion repos
+## Related
 
-| Repo | Role |
-|---|---|
-| [`prismlens`](https://github.com/dadenjo/prismlens) | Code-intelligence engine |
-| [`prism0x2A`](https://github.com/dadenjo/prism0x2A) | Code-intelligence dashboard |
-| [`forge0x2B`](https://github.com/dadenjo/forge0x2B) | Content/comms dashboard |
+- [prism0x2A](https://www.npmjs.com/package/prism0x2a) — the intelligence layer
+- [forge0x2B](https://www.npmjs.com/package/forge0x2b) — the dashboard that uses this engine

package/dist/index.cjs

@@ -0,0 +1,392 @@
+'use strict';
+
+var fs = require('fs/promises');
+var path = require('path');
+
+function _interopDefault (e) { return e && e.__esModule ? e : { default: e }; }
+
+var fs__default = /*#__PURE__*/_interopDefault(fs);
+var path__default = /*#__PURE__*/_interopDefault(path);
+
+// src/generators/releaseNotes.ts
+function buildSystemPrompt() {
+  return `You are a technical writer and developer-relations expert. You generate clear, accurate release notes from structured code-intelligence data. Write only the release notes \u2014 no preamble, no meta-commentary.`;
+}
+function buildUserPrompt(data, opts) {
+  const tone = opts.tone ?? "professional";
+  const length = opts.length ?? "medium";
+  const format = opts.format ?? "markdown";
+  const lengthGuide = { short: "2-3 paragraphs or bullet groups", medium: "4-6 sections", long: "comprehensive, 6+ sections with details" }[length];
+  const toneGuide = { professional: "formal, clear, business-appropriate", casual: "friendly, approachable, conversational", technical: "precise, implementation-focused, developer-centric" }[tone];
+  const hasSessions = (data.sessions?.length ?? 0) > 0;
+  const hasRecs = (data.recommendations?.length ?? 0) > 0;
+  const hasInsights = (data.insights?.length ?? 0) > 0;
+  if (!hasSessions && !hasRecs && !hasInsights) {
+    return `Generate a brief release note in ${format} format stating there are no changes to report in this period${data.fromDate ? ` (${data.fromDate} to ${data.toDate ?? "now"})` : ""}.`;
+  }
+  const lines = [];
+  lines.push(`Generate release notes with the following requirements:`);
+  lines.push(`- Tone: ${tone} (${toneGuide})`);
+  lines.push(`- Length: ${length} (${lengthGuide})`);
+  lines.push(`- Format: ${format}`);
+  if (data.fromDate) lines.push(`- Period: ${data.fromDate}${data.toDate ? ` to ${data.toDate}` : " to now"}`);
+  lines.push(``);
+  if (hasSessions) {
+    lines.push(`## Sessions (${data.sessions.length})`);
+    for (const s of data.sessions) {
+      lines.push(`- **${s.title}**${s.summary ? `: ${s.summary}` : ""}${s.conclusion ? ` | Conclusion: ${s.conclusion}` : ""}`);
+    }
+    lines.push(``);
+  }
+  if (hasRecs) {
+    lines.push(`## Recommendations (${data.recommendations.length})`);
+    for (const r of data.recommendations) {
+      const accepted = r.accepted === true ? " [ACCEPTED]" : r.accepted === false ? " [DECLINED]" : "";
+      lines.push(`- [${r.severity?.toUpperCase() ?? "INFO"}${accepted}] **${r.title}**${r.description ? `: ${r.description}` : ""}`);
+    }
+    lines.push(``);
+  }
+  if (hasInsights) {
+    lines.push(`## Insights (${data.insights.length})`);
+    for (const i of data.insights) {
+      lines.push(`- **${i.title}**${i.body ? `: ${i.body}` : ""}`);
+    }
+    lines.push(``);
+  }
+  return lines.join("\n");
+}
+async function generateReleaseNotes(data, opts, provider) {
+  const systemPrompt = buildSystemPrompt();
+  const userPrompt = buildUserPrompt(data, opts);
+  const response = await provider.complete({
+    systemPrompt,
+    messages: [{ role: "user", content: userPrompt }],
+    maxTokens: 2048
+  });
+  return {
+    text: response.content,
+    metadata: {
+      generatedAt: (/* @__PURE__ */ new Date()).toISOString(),
+      usedTokens: response.usedTokens,
+      generator: "forgesmith"
+    }
+  };
+}
+
+// src/generators/architectureWalkthrough.ts
+var NO_DATA_MSG = "No Blueprint data available. Run prism scan first.";
+function buildSystemPrompt2(tone) {
+  const toneMap = {
+    technical: "You are a senior software architect who writes precise, technical documentation for engineering teams.",
+    casual: "You are a friendly developer advocate who explains codebases in an approachable, conversational style.",
+    onboarding: "You are an experienced engineering mentor who helps new developers quickly understand a codebase."
+  };
+  return `${toneMap[tone] ?? toneMap.technical} Write only the requested document \u2014 no preamble, no meta-commentary.`;
+}
+function buildUserPrompt2(blueprint, opts) {
+  const tone = opts.tone ?? "technical";
+  const length = opts.length ?? "long";
+  const format = opts.format ?? "markdown";
+  const lengthGuide = {
+    short: "3-4 sections, concise overview",
+    medium: "5-7 sections with moderate detail",
+    long: "comprehensive, 8+ sections with full detail and examples"
+  }[length];
+  const topFiles = blueprint.files.slice().sort((a, b) => (b.importedByCount ?? 0) - (a.importedByCount ?? 0)).slice(0, 15);
+  const edgeSample = blueprint.edges.slice(0, 20);
+  const lines = [
+    `Generate an architecture walkthrough document in ${format} format for the codebase at "${blueprint.targetPath}".`,
+    `Tone: ${tone}. Length: ${length} (${lengthGuide}).`,
+    ``,
+    `## Codebase Stats`,
+    `- Total files: ${blueprint.stats.totalFiles}`,
+    `- Runtime dependency edges: ${blueprint.stats.runtimeEdges}`,
+    `- Categories: ${JSON.stringify(blueprint.categories)}`,
+    ``,
+    `## Key Files (by incoming dependency count)`,
+    ...topFiles.map((f) => `- ${f.path} [${f.category ?? "unknown"}] \u2014 importedBy: ${f.importedByCount ?? 0}, imports: ${f.importCount ?? 0}, lines: ${f.lineCount ?? "?"}`),
+    ``,
+    `## Dependency Edge Sample`,
+    ...edgeSample.map((e) => `- ${e.from} \u2192 ${e.to}${e.type ? ` (${e.type})` : ""}`),
+    ``,
+    `Cover: architecture overview, key layers/folders, entry points, important relationships, and what a new developer should understand first.`
+  ];
+  return lines.join("\n");
+}
+async function generateArchitectureWalkthrough(blueprint, opts, provider) {
+  if (!blueprint) {
+    return {
+      text: NO_DATA_MSG,
+      metadata: { generatedAt: (/* @__PURE__ */ new Date()).toISOString(), usedTokens: 0, generator: "forgesmith" }
+    };
+  }
+  const response = await provider.complete({
+    systemPrompt: buildSystemPrompt2(opts.tone ?? "technical"),
+    messages: [{ role: "user", content: buildUserPrompt2(blueprint, opts) }],
+    maxTokens: 4096
+  });
+  return {
+    text: response.content,
+    metadata: { generatedAt: (/* @__PURE__ */ new Date()).toISOString(), usedTokens: response.usedTokens, generator: "forgesmith" }
+  };
+}
+
+// src/generators/changesSince.ts
+var NO_DATA_MSG2 = "No Blueprint data available. Run prism scan first.";
+function buildSystemPrompt3() {
+  return `You are a technical writer who produces clear, concise architecture change summaries for development teams. Focus on what changed and why it matters. Write only the document \u2014 no preamble, no meta-commentary.`;
+}
+function computeDelta(current, previous) {
+  const currentPaths = new Set(current.files.map((f) => f.path));
+  const previousPaths = new Set(previous.files.map((f) => f.path));
+  const added = current.files.filter((f) => !previousPaths.has(f.path));
+  const removed = previous.files.filter((f) => !currentPaths.has(f.path));
+  const currentEdgeKeys = new Set(current.edges.map((e) => `${e.from}\u2192${e.to}`));
+  const previousEdgeKeys = new Set(previous.edges.map((e) => `${e.from}\u2192${e.to}`));
+  const addedEdges = current.edges.filter((e) => !previousEdgeKeys.has(`${e.from}\u2192${e.to}`));
+  const removedEdges = previous.edges.filter((e) => !currentEdgeKeys.has(`${e.from}\u2192${e.to}`));
+  return { added, removed, addedEdges, removedEdges };
+}
+function buildUserPrompt3(current, previous, opts) {
+  const tone = opts.tone ?? "professional";
+  const length = opts.length ?? "medium";
+  const format = opts.format ?? "markdown";
+  const delta = computeDelta(current, previous);
+  const prevDate = new Date(previous.scanTimestamp).toISOString().split("T")[0];
+  const currDate = new Date(current.scanTimestamp).toISOString().split("T")[0];
+  const lines = [
+    `Generate an architecture change summary in ${format} format.`,
+    `Tone: ${tone}. Length: ${length}.`,
+    `Period: ${prevDate} \u2192 ${currDate}`,
+    ``,
+    `## File Changes`,
+    `- Added files (${delta.added.length}): ${delta.added.slice(0, 20).map((f) => f.path).join(", ") || "none"}`,
+    `- Removed files (${delta.removed.length}): ${delta.removed.slice(0, 20).map((f) => f.path).join(", ") || "none"}`,
+    ``,
+    `## Dependency Edge Changes`,
+    `- New edges (${delta.addedEdges.length}): ${delta.addedEdges.slice(0, 10).map((e) => `${e.from}\u2192${e.to}`).join(", ") || "none"}`,
+    `- Removed edges (${delta.removedEdges.length}): ${delta.removedEdges.slice(0, 10).map((e) => `${e.from}\u2192${e.to}`).join(", ") || "none"}`,
+    ``,
+    `## Stats Delta`,
+    `- Files: ${previous.stats.totalFiles} \u2192 ${current.stats.totalFiles} (${current.stats.totalFiles - previous.stats.totalFiles >= 0 ? "+" : ""}${current.stats.totalFiles - previous.stats.totalFiles})`,
+    `- Edges: ${previous.stats.runtimeEdges} \u2192 ${current.stats.runtimeEdges} (${current.stats.runtimeEdges - previous.stats.runtimeEdges >= 0 ? "+" : ""}${current.stats.runtimeEdges - previous.stats.runtimeEdges})`,
+    ``,
+    `Summarize what changed architecturally, highlight significant additions or removals, and note any structural shifts.`
+  ];
+  return lines.join("\n");
+}
+async function generateChangesSince(current, previous, opts, provider) {
+  if (!current || !previous) {
+    return {
+      text: NO_DATA_MSG2,
+      metadata: { generatedAt: (/* @__PURE__ */ new Date()).toISOString(), usedTokens: 0, generator: "forgesmith" }
+    };
+  }
+  const response = await provider.complete({
+    systemPrompt: buildSystemPrompt3(),
+    messages: [{ role: "user", content: buildUserPrompt3(current, previous, opts) }],
+    maxTokens: 2048
+  });
+  return {
+    text: response.content,
+    metadata: { generatedAt: (/* @__PURE__ */ new Date()).toISOString(), usedTokens: response.usedTokens, generator: "forgesmith" }
+  };
+}
+
+// src/generators/onboardingDoc.ts
+var NO_DATA_MSG3 = "No Blueprint data available. Run prism scan first.";
+function buildSystemPrompt4(tone) {
+  const toneMap = {
+    friendly: "You are a helpful senior developer writing a welcoming onboarding guide for new team members. Be warm, encouraging, and practical.",
+    formal: "You are a documentation engineer writing a structured onboarding reference for enterprise engineering teams.",
+    technical: "You are a senior engineer writing a technical onboarding document focused on implementation details and system internals."
+  };
+  return `${toneMap[tone] ?? toneMap.friendly} Write only the document \u2014 no preamble, no meta-commentary.`;
+}
+function buildUserPrompt4(blueprint, opts) {
+  const tone = opts.tone ?? "friendly";
+  const length = opts.length ?? "medium";
+  const format = opts.format ?? "markdown";
+  const topEntryPoints = blueprint.files.filter((f) => f.category === "app" || (f.importedByCount ?? 0) === 0).slice(0, 10);
+  const topImported = blueprint.files.slice().sort((a, b) => (b.importedByCount ?? 0) - (a.importedByCount ?? 0)).slice(0, 10);
+  const folderMap = /* @__PURE__ */ new Map();
+  for (const f of blueprint.files) {
+    const parts = f.path.split("/");
+    if (parts.length > 1) {
+      const folder = parts[0];
+      folderMap.set(folder, (folderMap.get(folder) ?? 0) + 1);
+    }
+  }
+  const topFolders = [...folderMap.entries()].sort((a, b) => b[1] - a[1]).slice(0, 8).map(([folder, count]) => `${folder}/ (${count} files)`);
+  const lines = [
+    `Generate an onboarding document in ${format} format for new developers joining this codebase.`,
+    `Project path: "${blueprint.targetPath}"`,
+    `Tone: ${tone}. Length: ${length}.`,
+    ``,
+    `## Codebase Overview`,
+    `- ${blueprint.stats.totalFiles} files across ${Object.keys(blueprint.categories).length} categories`,
+    `- Categories: ${JSON.stringify(blueprint.categories)}`,
+    ``,
+    `## Top-level Folders`,
+    ...topFolders.map((f) => `- ${f}`),
+    ``,
+    `## Entry Points (app-layer files, zero incoming deps)`,
+    ...topEntryPoints.map((f) => `- ${f.path}`),
+    ``,
+    `## Core Shared Files (most imported)`,
+    ...topImported.map((f) => `- ${f.path} \u2014 used by ${f.importedByCount ?? 0} files`),
+    ``,
+    `Include: "Start here" section, key folders tour, important conventions to follow, the 3-5 files to read first, and how to run/test the project.`
+  ];
+  return lines.join("\n");
+}
+async function generateOnboardingDoc(blueprint, opts, provider) {
+  if (!blueprint) {
+    return {
+      text: NO_DATA_MSG3,
+      metadata: { generatedAt: (/* @__PURE__ */ new Date()).toISOString(), usedTokens: 0, generator: "forgesmith" }
+    };
+  }
+  const response = await provider.complete({
+    systemPrompt: buildSystemPrompt4(opts.tone ?? "friendly"),
+    messages: [{ role: "user", content: buildUserPrompt4(blueprint, opts) }],
+    maxTokens: 3072
+  });
+  return {
+    text: response.content,
+    metadata: { generatedAt: (/* @__PURE__ */ new Date()).toISOString(), usedTokens: response.usedTokens, generator: "forgesmith" }
+  };
+}
+
+// src/generators/refactoringReport.ts
+var NO_DATA_MSG4 = "No Blueprint data available. Run prism scan first.";
+function buildSystemPrompt5(tone) {
+  const toneMap = {
+    analytical: "You are a software architecture consultant who produces rigorous, evidence-based refactoring reports with clear prioritization.",
+    casual: "You are a senior developer who gives honest, practical refactoring advice based on code structure data.",
+    executive: "You are a CTO-level advisor who summarizes architectural debt and refactoring priorities for engineering leadership."
+  };
+  return `${toneMap[tone] ?? toneMap.analytical} Write only the report \u2014 no preamble, no meta-commentary.`;
+}
+function detectImportCycles(edges) {
+  const graph = /* @__PURE__ */ new Map();
+  for (const e of edges) {
+    if (!graph.has(e.from)) graph.set(e.from, /* @__PURE__ */ new Set());
+    graph.get(e.from).add(e.to);
+  }
+  const cycles = [];
+  const visited = /* @__PURE__ */ new Set();
+  const stack = /* @__PURE__ */ new Set();
+  function dfs(node, path2) {
+    if (cycles.length >= 5) return;
+    if (stack.has(node)) {
+      const cycleStart = path2.indexOf(node);
+      if (cycleStart !== -1) {
+        cycles.push(path2.slice(cycleStart).join(" \u2192 ") + " \u2192 " + node);
+      }
+      return;
+    }
+    if (visited.has(node)) return;
+    visited.add(node);
+    stack.add(node);
+    for (const neighbor of graph.get(node) ?? []) {
+      dfs(neighbor, [...path2, node]);
+    }
+    stack.delete(node);
+  }
+  for (const node of graph.keys()) {
+    if (!visited.has(node)) dfs(node, []);
+  }
+  return cycles;
+}
+function buildUserPrompt5(blueprint, opts) {
+  const tone = opts.tone ?? "analytical";
+  const length = opts.length ?? "medium";
+  const format = opts.format ?? "markdown";
+  const hotFiles = blueprint.files.slice().sort((a, b) => (b.importedByCount ?? 0) + (b.importCount ?? 0) - ((a.importedByCount ?? 0) + (a.importCount ?? 0))).slice(0, 10);
+  const highFanOut = blueprint.files.slice().sort((a, b) => (b.importCount ?? 0) - (a.importCount ?? 0)).slice(0, 8);
+  const importCycles = detectImportCycles(blueprint.edges);
+  const lines = [
+    `Generate a refactoring report in ${format} format for the codebase at "${blueprint.targetPath}".`,
+    `Tone: ${tone}. Length: ${length}.`,
+    ``,
+    `## Architecture Metrics`,
+    `- Total files: ${blueprint.stats.totalFiles}`,
+    `- Dependency edges: ${blueprint.stats.runtimeEdges}`,
+    `- Categories: ${JSON.stringify(blueprint.categories)}`,
+    ``,
+    `## High-Coupling Hot Spots (high total connections)`,
+    ...hotFiles.map((f) => `- ${f.path} \u2014 in: ${f.importedByCount ?? 0}, out: ${f.importCount ?? 0}, lines: ${f.lineCount ?? "?"}`),
+    ``,
+    `## High Fan-Out Files (many outgoing dependencies)`,
+    ...highFanOut.map((f) => `- ${f.path} \u2014 imports: ${f.importCount ?? 0}`),
+    ``,
+    `## Import Cycles Detected (${importCycles.length})`,
+    ...importCycles.length > 0 ? importCycles.map((c) => `- ${c}`) : ["No cycles detected in sampled edges"],
+    ``,
+    `Identify refactoring priorities: coupling issues, over-large files, circular dependencies, layer violations. Suggest concrete refactoring actions with rationale.`
+  ];
+  return lines.join("\n");
+}
+async function generateRefactoringReport(blueprint, opts, provider) {
+  if (!blueprint) {
+    return {
+      text: NO_DATA_MSG4,
+      metadata: { generatedAt: (/* @__PURE__ */ new Date()).toISOString(), usedTokens: 0, generator: "forgesmith" }
+    };
+  }
+  const response = await provider.complete({
+    systemPrompt: buildSystemPrompt5(opts.tone ?? "analytical"),
+    messages: [{ role: "user", content: buildUserPrompt5(blueprint, opts) }],
+    maxTokens: 3072
+  });
+  return {
+    text: response.content,
+    metadata: { generatedAt: (/* @__PURE__ */ new Date()).toISOString(), usedTokens: response.usedTokens, generator: "forgesmith" }
+  };
+}
+async function readJsonFiles(dir) {
+  try {
+    const entries = await fs__default.default.readdir(dir);
+    const results = [];
+    for (const entry of entries) {
+      if (!entry.endsWith(".json")) continue;
+      try {
+        const raw = await fs__default.default.readFile(path__default.default.join(dir, entry), "utf-8");
+        results.push(JSON.parse(raw));
+      } catch {
+      }
+    }
+    return results;
+  } catch {
+    return [];
+  }
+}
+async function readPrismDirectory(prismPath) {
+  const sessionsDir = path__default.default.join(prismPath, "sessions");
+  const recsDir = path__default.default.join(prismPath, "recommendations");
+  const insightsDir = path__default.default.join(prismPath, "green", "insights", "accepted");
+  const [sessions, recommendations, insights] = await Promise.all([
+    readJsonFiles(sessionsDir),
+    readJsonFiles(recsDir),
+    readJsonFiles(insightsDir)
+  ]);
+  return { sessions, recommendations, insights };
+}
+async function readBlueprintData(targetPath) {
+  const snapshotPath = path__default.default.join(targetPath, ".prism", "blueprint", "snapshot.json");
+  try {
+    const raw = await fs__default.default.readFile(snapshotPath, "utf-8");
+    return JSON.parse(raw);
+  } catch {
+    return null;
+  }
+}
+
+exports.generateArchitectureWalkthrough = generateArchitectureWalkthrough;
+exports.generateChangesSince = generateChangesSince;
+exports.generateOnboardingDoc = generateOnboardingDoc;
+exports.generateRefactoringReport = generateRefactoringReport;
+exports.generateReleaseNotes = generateReleaseNotes;
+exports.readBlueprintData = readBlueprintData;
+exports.readPrismDirectory = readPrismDirectory;

package/dist/index.d.cts

@@ -0,0 +1,122 @@
+interface PrismSession {
+    id: string;
+    title: string;
+    summary?: string;
+    conclusion?: string;
+    createdAt?: string;
+}
+interface PrismRecommendation {
+    id: string;
+    title: string;
+    severity?: "low" | "medium" | "high" | "critical";
+    accepted?: boolean;
+    description?: string;
+}
+interface PrismInsight {
+    id: string;
+    title: string;
+    body?: string;
+}
+interface PrismData {
+    sessions?: PrismSession[];
+    recommendations?: PrismRecommendation[];
+    insights?: PrismInsight[];
+    fromDate?: string;
+    toDate?: string;
+}
+interface ReleaseNotesOpts {
+    tone?: "professional" | "casual" | "technical";
+    length?: "short" | "medium" | "long";
+    format?: "markdown" | "plain";
+}
+interface BlueprintFile {
+    path: string;
+    category?: "app" | "component" | "lib" | "hook" | string;
+    importCount?: number;
+    importedByCount?: number;
+    lineCount?: number;
+}
+interface BlueprintEdge {
+    from: string;
+    to: string;
+    type?: string;
+}
+interface BlueprintData {
+    targetPath: string;
+    scanTimestamp: number;
+    stats: {
+        totalFiles: number;
+        runtimeEdges: number;
+        [key: string]: number;
+    };
+    files: BlueprintFile[];
+    edges: BlueprintEdge[];
+    categories: {
+        app: number;
+        component: number;
+        lib: number;
+        hook: number;
+        [key: string]: number;
+    };
+}
+interface ArchitectureWalkthroughOpts {
+    tone?: "technical" | "casual" | "onboarding";
+    length?: "short" | "medium" | "long";
+    format?: "markdown" | "plain";
+}
+interface ChangesSinceOpts {
+    tone?: "professional" | "casual" | "technical";
+    length?: "short" | "medium" | "long";
+    format?: "markdown" | "plain";
+}
+interface OnboardingDocOpts {
+    tone?: "friendly" | "formal" | "technical";
+    length?: "short" | "medium" | "long";
+    format?: "markdown" | "plain";
+}
+interface RefactoringReportOpts {
+    tone?: "analytical" | "casual" | "executive";
+    length?: "short" | "medium" | "long";
+    format?: "markdown" | "plain";
+}
+interface GenerationResult {
+    text: string;
+    metadata: {
+        generatedAt: string;
+        usedTokens: number;
+        generator: "forgesmith";
+    };
+}
+
+interface LlmMessage {
+    role: "user" | "assistant";
+    content: string;
+}
+interface LlmRequest {
+    model?: string;
+    messages: LlmMessage[];
+    maxTokens?: number;
+    systemPrompt?: string;
+}
+interface LlmResponse {
+    content: string;
+    usedTokens: number;
+}
+interface LlmProvider {
+    complete(request: LlmRequest): Promise<LlmResponse>;
+}
+
+declare function generateReleaseNotes(data: PrismData, opts: ReleaseNotesOpts, provider: LlmProvider): Promise<GenerationResult>;
+
+declare function generateArchitectureWalkthrough(blueprint: BlueprintData | null, opts: ArchitectureWalkthroughOpts, provider: LlmProvider): Promise<GenerationResult>;
+
+declare function generateChangesSince(current: BlueprintData | null, previous: BlueprintData | null, opts: ChangesSinceOpts, provider: LlmProvider): Promise<GenerationResult>;
+
+declare function generateOnboardingDoc(blueprint: BlueprintData | null, opts: OnboardingDocOpts, provider: LlmProvider): Promise<GenerationResult>;
+
+declare function generateRefactoringReport(blueprint: BlueprintData | null, opts: RefactoringReportOpts, provider: LlmProvider): Promise<GenerationResult>;
+
+declare function readPrismDirectory(prismPath: string): Promise<PrismData>;
+declare function readBlueprintData(targetPath: string): Promise<BlueprintData | null>;
+
+export { type ArchitectureWalkthroughOpts, type BlueprintData, type BlueprintEdge, type BlueprintFile, type ChangesSinceOpts, type GenerationResult, type LlmMessage, type LlmProvider, type LlmRequest, type LlmResponse, type OnboardingDocOpts, type PrismData, type PrismInsight, type PrismRecommendation, type PrismSession, type RefactoringReportOpts, type ReleaseNotesOpts, generateArchitectureWalkthrough, generateChangesSince, generateOnboardingDoc, generateRefactoringReport, generateReleaseNotes, readBlueprintData, readPrismDirectory };

package/dist/index.d.ts

@@ -0,0 +1,122 @@
+interface PrismSession {
+    id: string;
+    title: string;
+    summary?: string;
+    conclusion?: string;
+    createdAt?: string;
+}
+interface PrismRecommendation {
+    id: string;
+    title: string;
+    severity?: "low" | "medium" | "high" | "critical";
+    accepted?: boolean;
+    description?: string;
+}
+interface PrismInsight {
+    id: string;
+    title: string;
+    body?: string;
+}
+interface PrismData {
+    sessions?: PrismSession[];
+    recommendations?: PrismRecommendation[];
+    insights?: PrismInsight[];
+    fromDate?: string;
+    toDate?: string;
+}
+interface ReleaseNotesOpts {
+    tone?: "professional" | "casual" | "technical";
+    length?: "short" | "medium" | "long";
+    format?: "markdown" | "plain";
+}
+interface BlueprintFile {
+    path: string;
+    category?: "app" | "component" | "lib" | "hook" | string;
+    importCount?: number;
+    importedByCount?: number;
+    lineCount?: number;
+}
+interface BlueprintEdge {
+    from: string;
+    to: string;
+    type?: string;
+}
+interface BlueprintData {
+    targetPath: string;
+    scanTimestamp: number;
+    stats: {
+        totalFiles: number;
+        runtimeEdges: number;
+        [key: string]: number;
+    };
+    files: BlueprintFile[];
+    edges: BlueprintEdge[];
+    categories: {
+        app: number;
+        component: number;
+        lib: number;
+        hook: number;
+        [key: string]: number;
+    };
+}
+interface ArchitectureWalkthroughOpts {
+    tone?: "technical" | "casual" | "onboarding";
+    length?: "short" | "medium" | "long";
+    format?: "markdown" | "plain";
+}
+interface ChangesSinceOpts {
+    tone?: "professional" | "casual" | "technical";
+    length?: "short" | "medium" | "long";
+    format?: "markdown" | "plain";
+}
+interface OnboardingDocOpts {
+    tone?: "friendly" | "formal" | "technical";
+    length?: "short" | "medium" | "long";
+    format?: "markdown" | "plain";
+}
+interface RefactoringReportOpts {
+    tone?: "analytical" | "casual" | "executive";
+    length?: "short" | "medium" | "long";
+    format?: "markdown" | "plain";
+}
+interface GenerationResult {
+    text: string;
+    metadata: {
+        generatedAt: string;
+        usedTokens: number;
+        generator: "forgesmith";
+    };
+}
+
+interface LlmMessage {
+    role: "user" | "assistant";
+    content: string;
+}
+interface LlmRequest {
+    model?: string;
+    messages: LlmMessage[];
+    maxTokens?: number;
+    systemPrompt?: string;
+}
+interface LlmResponse {
+    content: string;
+    usedTokens: number;
+}
+interface LlmProvider {
+    complete(request: LlmRequest): Promise<LlmResponse>;
+}
+
+declare function generateReleaseNotes(data: PrismData, opts: ReleaseNotesOpts, provider: LlmProvider): Promise<GenerationResult>;
+
+declare function generateArchitectureWalkthrough(blueprint: BlueprintData | null, opts: ArchitectureWalkthroughOpts, provider: LlmProvider): Promise<GenerationResult>;
+
+declare function generateChangesSince(current: BlueprintData | null, previous: BlueprintData | null, opts: ChangesSinceOpts, provider: LlmProvider): Promise<GenerationResult>;
+
+declare function generateOnboardingDoc(blueprint: BlueprintData | null, opts: OnboardingDocOpts, provider: LlmProvider): Promise<GenerationResult>;
+
+declare function generateRefactoringReport(blueprint: BlueprintData | null, opts: RefactoringReportOpts, provider: LlmProvider): Promise<GenerationResult>;
+
+declare function readPrismDirectory(prismPath: string): Promise<PrismData>;
+declare function readBlueprintData(targetPath: string): Promise<BlueprintData | null>;
+
+export { type ArchitectureWalkthroughOpts, type BlueprintData, type BlueprintEdge, type BlueprintFile, type ChangesSinceOpts, type GenerationResult, type LlmMessage, type LlmProvider, type LlmRequest, type LlmResponse, type OnboardingDocOpts, type PrismData, type PrismInsight, type PrismRecommendation, type PrismSession, type RefactoringReportOpts, type ReleaseNotesOpts, generateArchitectureWalkthrough, generateChangesSince, generateOnboardingDoc, generateRefactoringReport, generateReleaseNotes, readBlueprintData, readPrismDirectory };

package/dist/index.mjs

@@ -0,0 +1,379 @@
+import fs from 'fs/promises';
+import path from 'path';
+
+// src/generators/releaseNotes.ts
+function buildSystemPrompt() {
+  return `You are a technical writer and developer-relations expert. You generate clear, accurate release notes from structured code-intelligence data. Write only the release notes \u2014 no preamble, no meta-commentary.`;
+}
+function buildUserPrompt(data, opts) {
+  const tone = opts.tone ?? "professional";
+  const length = opts.length ?? "medium";
+  const format = opts.format ?? "markdown";
+  const lengthGuide = { short: "2-3 paragraphs or bullet groups", medium: "4-6 sections", long: "comprehensive, 6+ sections with details" }[length];
+  const toneGuide = { professional: "formal, clear, business-appropriate", casual: "friendly, approachable, conversational", technical: "precise, implementation-focused, developer-centric" }[tone];
+  const hasSessions = (data.sessions?.length ?? 0) > 0;
+  const hasRecs = (data.recommendations?.length ?? 0) > 0;
+  const hasInsights = (data.insights?.length ?? 0) > 0;
+  if (!hasSessions && !hasRecs && !hasInsights) {
+    return `Generate a brief release note in ${format} format stating there are no changes to report in this period${data.fromDate ? ` (${data.fromDate} to ${data.toDate ?? "now"})` : ""}.`;
+  }
+  const lines = [];
+  lines.push(`Generate release notes with the following requirements:`);
+  lines.push(`- Tone: ${tone} (${toneGuide})`);
+  lines.push(`- Length: ${length} (${lengthGuide})`);
+  lines.push(`- Format: ${format}`);
+  if (data.fromDate) lines.push(`- Period: ${data.fromDate}${data.toDate ? ` to ${data.toDate}` : " to now"}`);
+  lines.push(``);
+  if (hasSessions) {
+    lines.push(`## Sessions (${data.sessions.length})`);
+    for (const s of data.sessions) {
+      lines.push(`- **${s.title}**${s.summary ? `: ${s.summary}` : ""}${s.conclusion ? ` | Conclusion: ${s.conclusion}` : ""}`);
+    }
+    lines.push(``);
+  }
+  if (hasRecs) {
+    lines.push(`## Recommendations (${data.recommendations.length})`);
+    for (const r of data.recommendations) {
+      const accepted = r.accepted === true ? " [ACCEPTED]" : r.accepted === false ? " [DECLINED]" : "";
+      lines.push(`- [${r.severity?.toUpperCase() ?? "INFO"}${accepted}] **${r.title}**${r.description ? `: ${r.description}` : ""}`);
+    }
+    lines.push(``);
+  }
+  if (hasInsights) {
+    lines.push(`## Insights (${data.insights.length})`);
+    for (const i of data.insights) {
+      lines.push(`- **${i.title}**${i.body ? `: ${i.body}` : ""}`);
+    }
+    lines.push(``);
+  }
+  return lines.join("\n");
+}
+async function generateReleaseNotes(data, opts, provider) {
+  const systemPrompt = buildSystemPrompt();
+  const userPrompt = buildUserPrompt(data, opts);
+  const response = await provider.complete({
+    systemPrompt,
+    messages: [{ role: "user", content: userPrompt }],
+    maxTokens: 2048
+  });
+  return {
+    text: response.content,
+    metadata: {
+      generatedAt: (/* @__PURE__ */ new Date()).toISOString(),
+      usedTokens: response.usedTokens,
+      generator: "forgesmith"
+    }
+  };
+}
+
+// src/generators/architectureWalkthrough.ts
+var NO_DATA_MSG = "No Blueprint data available. Run prism scan first.";
+function buildSystemPrompt2(tone) {
+  const toneMap = {
+    technical: "You are a senior software architect who writes precise, technical documentation for engineering teams.",
+    casual: "You are a friendly developer advocate who explains codebases in an approachable, conversational style.",
+    onboarding: "You are an experienced engineering mentor who helps new developers quickly understand a codebase."
+  };
+  return `${toneMap[tone] ?? toneMap.technical} Write only the requested document \u2014 no preamble, no meta-commentary.`;
+}
+function buildUserPrompt2(blueprint, opts) {
+  const tone = opts.tone ?? "technical";
+  const length = opts.length ?? "long";
+  const format = opts.format ?? "markdown";
+  const lengthGuide = {
+    short: "3-4 sections, concise overview",
+    medium: "5-7 sections with moderate detail",
+    long: "comprehensive, 8+ sections with full detail and examples"
+  }[length];
+  const topFiles = blueprint.files.slice().sort((a, b) => (b.importedByCount ?? 0) - (a.importedByCount ?? 0)).slice(0, 15);
+  const edgeSample = blueprint.edges.slice(0, 20);
+  const lines = [
+    `Generate an architecture walkthrough document in ${format} format for the codebase at "${blueprint.targetPath}".`,
+    `Tone: ${tone}. Length: ${length} (${lengthGuide}).`,
+    ``,
+    `## Codebase Stats`,
+    `- Total files: ${blueprint.stats.totalFiles}`,
+    `- Runtime dependency edges: ${blueprint.stats.runtimeEdges}`,
+    `- Categories: ${JSON.stringify(blueprint.categories)}`,
+    ``,
+    `## Key Files (by incoming dependency count)`,
+    ...topFiles.map((f) => `- ${f.path} [${f.category ?? "unknown"}] \u2014 importedBy: ${f.importedByCount ?? 0}, imports: ${f.importCount ?? 0}, lines: ${f.lineCount ?? "?"}`),
+    ``,
+    `## Dependency Edge Sample`,
+    ...edgeSample.map((e) => `- ${e.from} \u2192 ${e.to}${e.type ? ` (${e.type})` : ""}`),
+    ``,
+    `Cover: architecture overview, key layers/folders, entry points, important relationships, and what a new developer should understand first.`
+  ];
+  return lines.join("\n");
+}
+async function generateArchitectureWalkthrough(blueprint, opts, provider) {
+  if (!blueprint) {
+    return {
+      text: NO_DATA_MSG,
+      metadata: { generatedAt: (/* @__PURE__ */ new Date()).toISOString(), usedTokens: 0, generator: "forgesmith" }
+    };
+  }
+  const response = await provider.complete({
+    systemPrompt: buildSystemPrompt2(opts.tone ?? "technical"),
+    messages: [{ role: "user", content: buildUserPrompt2(blueprint, opts) }],
+    maxTokens: 4096
+  });
+  return {
+    text: response.content,
+    metadata: { generatedAt: (/* @__PURE__ */ new Date()).toISOString(), usedTokens: response.usedTokens, generator: "forgesmith" }
+  };
+}
+
+// src/generators/changesSince.ts
+var NO_DATA_MSG2 = "No Blueprint data available. Run prism scan first.";
+function buildSystemPrompt3() {
+  return `You are a technical writer who produces clear, concise architecture change summaries for development teams. Focus on what changed and why it matters. Write only the document \u2014 no preamble, no meta-commentary.`;
+}
+function computeDelta(current, previous) {
+  const currentPaths = new Set(current.files.map((f) => f.path));
+  const previousPaths = new Set(previous.files.map((f) => f.path));
+  const added = current.files.filter((f) => !previousPaths.has(f.path));
+  const removed = previous.files.filter((f) => !currentPaths.has(f.path));
+  const currentEdgeKeys = new Set(current.edges.map((e) => `${e.from}\u2192${e.to}`));
+  const previousEdgeKeys = new Set(previous.edges.map((e) => `${e.from}\u2192${e.to}`));
+  const addedEdges = current.edges.filter((e) => !previousEdgeKeys.has(`${e.from}\u2192${e.to}`));
+  const removedEdges = previous.edges.filter((e) => !currentEdgeKeys.has(`${e.from}\u2192${e.to}`));
+  return { added, removed, addedEdges, removedEdges };
+}
+function buildUserPrompt3(current, previous, opts) {
+  const tone = opts.tone ?? "professional";
+  const length = opts.length ?? "medium";
+  const format = opts.format ?? "markdown";
+  const delta = computeDelta(current, previous);
+  const prevDate = new Date(previous.scanTimestamp).toISOString().split("T")[0];
+  const currDate = new Date(current.scanTimestamp).toISOString().split("T")[0];
+  const lines = [
+    `Generate an architecture change summary in ${format} format.`,
+    `Tone: ${tone}. Length: ${length}.`,
+    `Period: ${prevDate} \u2192 ${currDate}`,
+    ``,
+    `## File Changes`,
+    `- Added files (${delta.added.length}): ${delta.added.slice(0, 20).map((f) => f.path).join(", ") || "none"}`,
+    `- Removed files (${delta.removed.length}): ${delta.removed.slice(0, 20).map((f) => f.path).join(", ") || "none"}`,
+    ``,
+    `## Dependency Edge Changes`,
+    `- New edges (${delta.addedEdges.length}): ${delta.addedEdges.slice(0, 10).map((e) => `${e.from}\u2192${e.to}`).join(", ") || "none"}`,
+    `- Removed edges (${delta.removedEdges.length}): ${delta.removedEdges.slice(0, 10).map((e) => `${e.from}\u2192${e.to}`).join(", ") || "none"}`,
+    ``,
+    `## Stats Delta`,
+    `- Files: ${previous.stats.totalFiles} \u2192 ${current.stats.totalFiles} (${current.stats.totalFiles - previous.stats.totalFiles >= 0 ? "+" : ""}${current.stats.totalFiles - previous.stats.totalFiles})`,
+    `- Edges: ${previous.stats.runtimeEdges} \u2192 ${current.stats.runtimeEdges} (${current.stats.runtimeEdges - previous.stats.runtimeEdges >= 0 ? "+" : ""}${current.stats.runtimeEdges - previous.stats.runtimeEdges})`,
+    ``,
+    `Summarize what changed architecturally, highlight significant additions or removals, and note any structural shifts.`
+  ];
+  return lines.join("\n");
+}
+async function generateChangesSince(current, previous, opts, provider) {
+  if (!current || !previous) {
+    return {
+      text: NO_DATA_MSG2,
+      metadata: { generatedAt: (/* @__PURE__ */ new Date()).toISOString(), usedTokens: 0, generator: "forgesmith" }
+    };
+  }
+  const response = await provider.complete({
+    systemPrompt: buildSystemPrompt3(),
+    messages: [{ role: "user", content: buildUserPrompt3(current, previous, opts) }],
+    maxTokens: 2048
+  });
+  return {
+    text: response.content,
+    metadata: { generatedAt: (/* @__PURE__ */ new Date()).toISOString(), usedTokens: response.usedTokens, generator: "forgesmith" }
+  };
+}
+
+// src/generators/onboardingDoc.ts
+var NO_DATA_MSG3 = "No Blueprint data available. Run prism scan first.";
+function buildSystemPrompt4(tone) {
+  const toneMap = {
+    friendly: "You are a helpful senior developer writing a welcoming onboarding guide for new team members. Be warm, encouraging, and practical.",
+    formal: "You are a documentation engineer writing a structured onboarding reference for enterprise engineering teams.",
+    technical: "You are a senior engineer writing a technical onboarding document focused on implementation details and system internals."
+  };
+  return `${toneMap[tone] ?? toneMap.friendly} Write only the document \u2014 no preamble, no meta-commentary.`;
+}
+function buildUserPrompt4(blueprint, opts) {
+  const tone = opts.tone ?? "friendly";
+  const length = opts.length ?? "medium";
+  const format = opts.format ?? "markdown";
+  const topEntryPoints = blueprint.files.filter((f) => f.category === "app" || (f.importedByCount ?? 0) === 0).slice(0, 10);
+  const topImported = blueprint.files.slice().sort((a, b) => (b.importedByCount ?? 0) - (a.importedByCount ?? 0)).slice(0, 10);
+  const folderMap = /* @__PURE__ */ new Map();
+  for (const f of blueprint.files) {
+    const parts = f.path.split("/");
+    if (parts.length > 1) {
+      const folder = parts[0];
+      folderMap.set(folder, (folderMap.get(folder) ?? 0) + 1);
+    }
+  }
+  const topFolders = [...folderMap.entries()].sort((a, b) => b[1] - a[1]).slice(0, 8).map(([folder, count]) => `${folder}/ (${count} files)`);
+  const lines = [
+    `Generate an onboarding document in ${format} format for new developers joining this codebase.`,
+    `Project path: "${blueprint.targetPath}"`,
+    `Tone: ${tone}. Length: ${length}.`,
+    ``,
+    `## Codebase Overview`,
+    `- ${blueprint.stats.totalFiles} files across ${Object.keys(blueprint.categories).length} categories`,
+    `- Categories: ${JSON.stringify(blueprint.categories)}`,
+    ``,
+    `## Top-level Folders`,
+    ...topFolders.map((f) => `- ${f}`),
+    ``,
+    `## Entry Points (app-layer files, zero incoming deps)`,
+    ...topEntryPoints.map((f) => `- ${f.path}`),
+    ``,
+    `## Core Shared Files (most imported)`,
+    ...topImported.map((f) => `- ${f.path} \u2014 used by ${f.importedByCount ?? 0} files`),
+    ``,
+    `Include: "Start here" section, key folders tour, important conventions to follow, the 3-5 files to read first, and how to run/test the project.`
+  ];
+  return lines.join("\n");
+}
+async function generateOnboardingDoc(blueprint, opts, provider) {
+  if (!blueprint) {
+    return {
+      text: NO_DATA_MSG3,
+      metadata: { generatedAt: (/* @__PURE__ */ new Date()).toISOString(), usedTokens: 0, generator: "forgesmith" }
+    };
+  }
+  const response = await provider.complete({
+    systemPrompt: buildSystemPrompt4(opts.tone ?? "friendly"),
+    messages: [{ role: "user", content: buildUserPrompt4(blueprint, opts) }],
+    maxTokens: 3072
+  });
+  return {
+    text: response.content,
+    metadata: { generatedAt: (/* @__PURE__ */ new Date()).toISOString(), usedTokens: response.usedTokens, generator: "forgesmith" }
+  };
+}
+
+// src/generators/refactoringReport.ts
+var NO_DATA_MSG4 = "No Blueprint data available. Run prism scan first.";
+function buildSystemPrompt5(tone) {
+  const toneMap = {
+    analytical: "You are a software architecture consultant who produces rigorous, evidence-based refactoring reports with clear prioritization.",
+    casual: "You are a senior developer who gives honest, practical refactoring advice based on code structure data.",
+    executive: "You are a CTO-level advisor who summarizes architectural debt and refactoring priorities for engineering leadership."
+  };
+  return `${toneMap[tone] ?? toneMap.analytical} Write only the report \u2014 no preamble, no meta-commentary.`;
+}
+function detectImportCycles(edges) {
+  const graph = /* @__PURE__ */ new Map();
+  for (const e of edges) {
+    if (!graph.has(e.from)) graph.set(e.from, /* @__PURE__ */ new Set());
+    graph.get(e.from).add(e.to);
+  }
+  const cycles = [];
+  const visited = /* @__PURE__ */ new Set();
+  const stack = /* @__PURE__ */ new Set();
+  function dfs(node, path2) {
+    if (cycles.length >= 5) return;
+    if (stack.has(node)) {
+      const cycleStart = path2.indexOf(node);
+      if (cycleStart !== -1) {
+        cycles.push(path2.slice(cycleStart).join(" \u2192 ") + " \u2192 " + node);
+      }
+      return;
+    }
+    if (visited.has(node)) return;
+    visited.add(node);
+    stack.add(node);
+    for (const neighbor of graph.get(node) ?? []) {
+      dfs(neighbor, [...path2, node]);
+    }
+    stack.delete(node);
+  }
+  for (const node of graph.keys()) {
+    if (!visited.has(node)) dfs(node, []);
+  }
+  return cycles;
+}
+function buildUserPrompt5(blueprint, opts) {
+  const tone = opts.tone ?? "analytical";
+  const length = opts.length ?? "medium";
+  const format = opts.format ?? "markdown";
+  const hotFiles = blueprint.files.slice().sort((a, b) => (b.importedByCount ?? 0) + (b.importCount ?? 0) - ((a.importedByCount ?? 0) + (a.importCount ?? 0))).slice(0, 10);
+  const highFanOut = blueprint.files.slice().sort((a, b) => (b.importCount ?? 0) - (a.importCount ?? 0)).slice(0, 8);
+  const importCycles = detectImportCycles(blueprint.edges);
+  const lines = [
+    `Generate a refactoring report in ${format} format for the codebase at "${blueprint.targetPath}".`,
+    `Tone: ${tone}. Length: ${length}.`,
+    ``,
+    `## Architecture Metrics`,
+    `- Total files: ${blueprint.stats.totalFiles}`,
+    `- Dependency edges: ${blueprint.stats.runtimeEdges}`,
+    `- Categories: ${JSON.stringify(blueprint.categories)}`,
+    ``,
+    `## High-Coupling Hot Spots (high total connections)`,
+    ...hotFiles.map((f) => `- ${f.path} \u2014 in: ${f.importedByCount ?? 0}, out: ${f.importCount ?? 0}, lines: ${f.lineCount ?? "?"}`),
+    ``,
+    `## High Fan-Out Files (many outgoing dependencies)`,
+    ...highFanOut.map((f) => `- ${f.path} \u2014 imports: ${f.importCount ?? 0}`),
+    ``,
+    `## Import Cycles Detected (${importCycles.length})`,
+    ...importCycles.length > 0 ? importCycles.map((c) => `- ${c}`) : ["No cycles detected in sampled edges"],
+    ``,
+    `Identify refactoring priorities: coupling issues, over-large files, circular dependencies, layer violations. Suggest concrete refactoring actions with rationale.`
+  ];
+  return lines.join("\n");
+}
+async function generateRefactoringReport(blueprint, opts, provider) {
+  if (!blueprint) {
+    return {
+      text: NO_DATA_MSG4,
+      metadata: { generatedAt: (/* @__PURE__ */ new Date()).toISOString(), usedTokens: 0, generator: "forgesmith" }
+    };
+  }
+  const response = await provider.complete({
+    systemPrompt: buildSystemPrompt5(opts.tone ?? "analytical"),
+    messages: [{ role: "user", content: buildUserPrompt5(blueprint, opts) }],
+    maxTokens: 3072
+  });
+  return {
+    text: response.content,
+    metadata: { generatedAt: (/* @__PURE__ */ new Date()).toISOString(), usedTokens: response.usedTokens, generator: "forgesmith" }
+  };
+}
+async function readJsonFiles(dir) {
+  try {
+    const entries = await fs.readdir(dir);
+    const results = [];
+    for (const entry of entries) {
+      if (!entry.endsWith(".json")) continue;
+      try {
+        const raw = await fs.readFile(path.join(dir, entry), "utf-8");
+        results.push(JSON.parse(raw));
+      } catch {
+      }
+    }
+    return results;
+  } catch {
+    return [];
+  }
+}
+async function readPrismDirectory(prismPath) {
+  const sessionsDir = path.join(prismPath, "sessions");
+  const recsDir = path.join(prismPath, "recommendations");
+  const insightsDir = path.join(prismPath, "green", "insights", "accepted");
+  const [sessions, recommendations, insights] = await Promise.all([
+    readJsonFiles(sessionsDir),
+    readJsonFiles(recsDir),
+    readJsonFiles(insightsDir)
+  ]);
+  return { sessions, recommendations, insights };
+}
+async function readBlueprintData(targetPath) {
+  const snapshotPath = path.join(targetPath, ".prism", "blueprint", "snapshot.json");
+  try {
+    const raw = await fs.readFile(snapshotPath, "utf-8");
+    return JSON.parse(raw);
+  } catch {
+    return null;
+  }
+}
+
+export { generateArchitectureWalkthrough, generateChangesSince, generateOnboardingDoc, generateRefactoringReport, generateReleaseNotes, readBlueprintData, readPrismDirectory };

package/dist/providers.cjs

@@ -0,0 +1,36 @@
+'use strict';
+
+var Anthropic = require('@anthropic-ai/sdk');
+
+function _interopDefault (e) { return e && e.__esModule ? e : { default: e }; }
+
+var Anthropic__default = /*#__PURE__*/_interopDefault(Anthropic);
+
+// src/llm/providers/direct.ts
+var DEFAULT_MODEL = "claude-sonnet-4-6";
+var DirectLlmProvider = class {
+  client;
+  defaultModel;
+  constructor(opts) {
+    this.client = new Anthropic__default.default({ apiKey: opts.apiKey });
+    this.defaultModel = opts.model ?? DEFAULT_MODEL;
+  }
+  async complete(request) {
+    const model = request.model ?? this.defaultModel;
+    const maxTokens = request.maxTokens ?? 4096;
+    const response = await this.client.messages.create({
+      model,
+      max_tokens: maxTokens,
+      system: request.systemPrompt,
+      messages: request.messages.map((m) => ({
+        role: m.role,
+        content: m.content
+      }))
+    });
+    const content = response.content.filter((b) => b.type === "text").map((b) => b.text).join("");
+    const usedTokens = (response.usage?.input_tokens ?? 0) + (response.usage?.output_tokens ?? 0);
+    return { content, usedTokens };
+  }
+};
+
+exports.DirectLlmProvider = DirectLlmProvider;

package/dist/providers.d.cts

@@ -0,0 +1,30 @@
+interface LlmMessage {
+    role: "user" | "assistant";
+    content: string;
+}
+interface LlmRequest {
+    model?: string;
+    messages: LlmMessage[];
+    maxTokens?: number;
+    systemPrompt?: string;
+}
+interface LlmResponse {
+    content: string;
+    usedTokens: number;
+}
+interface LlmProvider {
+    complete(request: LlmRequest): Promise<LlmResponse>;
+}
+
+interface DirectLlmProviderOptions {
+    apiKey: string;
+    model?: string;
+}
+declare class DirectLlmProvider implements LlmProvider {
+    private client;
+    private defaultModel;
+    constructor(opts: DirectLlmProviderOptions);
+    complete(request: LlmRequest): Promise<LlmResponse>;
+}
+
+export { DirectLlmProvider, type DirectLlmProviderOptions };

package/dist/providers.d.ts

@@ -0,0 +1,30 @@
+interface LlmMessage {
+    role: "user" | "assistant";
+    content: string;
+}
+interface LlmRequest {
+    model?: string;
+    messages: LlmMessage[];
+    maxTokens?: number;
+    systemPrompt?: string;
+}
+interface LlmResponse {
+    content: string;
+    usedTokens: number;
+}
+interface LlmProvider {
+    complete(request: LlmRequest): Promise<LlmResponse>;
+}
+
+interface DirectLlmProviderOptions {
+    apiKey: string;
+    model?: string;
+}
+declare class DirectLlmProvider implements LlmProvider {
+    private client;
+    private defaultModel;
+    constructor(opts: DirectLlmProviderOptions);
+    complete(request: LlmRequest): Promise<LlmResponse>;
+}
+
+export { DirectLlmProvider, type DirectLlmProviderOptions };

package/dist/providers.mjs

@@ -0,0 +1,30 @@
+import Anthropic from '@anthropic-ai/sdk';
+
+// src/llm/providers/direct.ts
+var DEFAULT_MODEL = "claude-sonnet-4-6";
+var DirectLlmProvider = class {
+  client;
+  defaultModel;
+  constructor(opts) {
+    this.client = new Anthropic({ apiKey: opts.apiKey });
+    this.defaultModel = opts.model ?? DEFAULT_MODEL;
+  }
+  async complete(request) {
+    const model = request.model ?? this.defaultModel;
+    const maxTokens = request.maxTokens ?? 4096;
+    const response = await this.client.messages.create({
+      model,
+      max_tokens: maxTokens,
+      system: request.systemPrompt,
+      messages: request.messages.map((m) => ({
+        role: m.role,
+        content: m.content
+      }))
+    });
+    const content = response.content.filter((b) => b.type === "text").map((b) => b.text).join("");
+    const usedTokens = (response.usage?.input_tokens ?? 0) + (response.usage?.output_tokens ?? 0);
+    return { content, usedTokens };
+  }
+};
+
+export { DirectLlmProvider };

package/package.json

@@ -1,11 +1,61 @@
 {
   "name": "forgesmith",
-  "version": "0.0.1",
-  "description": "forgesmith — content/asset-generation engine. The lens observes, the smith forges. Sister engine to prismlens. (Reserved package.)",
-  "main": "index.js",
+  "version": "0.2.0",
+  "description": "forgesmith — content & asset-generation engine. Forge release notes, blog posts, social copy from prism0x2A data.",
+  "type": "module",
+  "main": "./dist/index.cjs",
+  "module": "./dist/index.mjs",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.mjs",
+      "require": "./dist/index.cjs",
+      "default": "./dist/index.cjs"
+    },
+    "./providers": {
+      "types": "./dist/providers.d.ts",
+      "import": "./dist/providers.mjs",
+      "require": "./dist/providers.cjs",
+      "default": "./dist/providers.cjs"
+    }
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "CHANGELOG.md"
+  ],
+  "scripts": {
+    "build": "tsup",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "typecheck": "tsc --noEmit",
+    "prepare": "npm run build",
+    "prepublishOnly": "npm run build && npm test"
+  },
+  "dependencies": {
+    "@anthropic-ai/sdk": "^0.37.0"
+  },
+  "devDependencies": {
+    "@types/node": "^22.0.0",
+    "tsup": "^8.3.5",
+    "typescript": "^5.7.2",
+    "vitest": "^2.1.8"
+  },
   "license": "UNLICENSED",
   "private": false,
   "homepage": "https://github.com/dadenjo/forgesmith",
-  "keywords": ["code-intelligence", "content-generation", "release-notes", "marketing", "developer-tools"],
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/dadenjo/forgesmith.git"
+  },
+  "keywords": [
+    "code-intelligence",
+    "content-generation",
+    "release-notes",
+    "marketing",
+    "developer-tools",
+    "prism0x2a"
+  ],
   "author": "dadenjo"
 }

package/index.js

@@ -1,5 +0,0 @@
-// forgesmith — placeholder reservation. Real release follows prism0x2A v0.3.x.
-// The lens observes. The smith forges.
-// See: https://github.com/dadenjo/forgesmith
-console.log("forgesmith — engine for forge0x2B. Reserved.");
-console.log("The lens observes. The smith forges.");