forgesmith 0.0.1 → 0.1.0

package/CHANGELOG.md

@@ -0,0 +1,10 @@
+# Changelog
+
+## 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,105 @@
+'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"
+    }
+  };
+}
+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 };
+}
+
+exports.generateReleaseNotes = generateReleaseNotes;
+exports.readPrismDirectory = readPrismDirectory;

package/dist/index.d.cts

@@ -0,0 +1,63 @@
+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 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 readPrismDirectory(prismPath: string): Promise<PrismData>;
+
+export { type GenerationResult, type LlmMessage, type LlmProvider, type LlmRequest, type LlmResponse, type PrismData, type PrismInsight, type PrismRecommendation, type PrismSession, type ReleaseNotesOpts, generateReleaseNotes, readPrismDirectory };

package/dist/index.d.ts

@@ -0,0 +1,63 @@
+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 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 readPrismDirectory(prismPath: string): Promise<PrismData>;
+
+export { type GenerationResult, type LlmMessage, type LlmProvider, type LlmRequest, type LlmResponse, type PrismData, type PrismInsight, type PrismRecommendation, type PrismSession, type ReleaseNotesOpts, generateReleaseNotes, readPrismDirectory };

package/dist/index.mjs

@@ -0,0 +1,97 @@
+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"
+    }
+  };
+}
+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 };
+}
+
+export { generateReleaseNotes, 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.1.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.");