forgesmith 0.2.0 → 0.3.0

package/CHANGELOG.md

@@ -1,5 +1,16 @@
 # Changelog
 
+## 0.3.0 — Ask-Driven Asset Generation
+
+- `generateAskDrivenAsset(blueprint, question, opts, provider)` — generate any content format from a natural-language question about your codebase architecture
+  - Formats: `markdown` | `blog` | `social` | `email` | `slack` | `slide`
+  - Tones: `professional` | `casual` | `technical` | `executive`
+  - Grounded in Blueprint dependency graph (top files by usage, edge sample, category breakdown)
+  - Format-aware token budgets (512 for social/slack, 3072 for blog/markdown, 2048 for slides)
+  - Use-cases: blog posts, tweets, investor-update bullets, Slack status, slide decks
+- New exported types: `AskDrivenAssetOpts`, `AskDrivenAssetFormat`
+- 52 unit tests, all green (+8 new)
+
 ## 0.2.0 — Architecture Narrative Generators
 
 - `generateArchitectureWalkthrough(blueprint, opts, provider)` — long-form narrative explaining structure, key files, and important relationships. Tones: `technical` | `casual` | `onboarding`

package/dist/index.cjs

@@ -383,7 +383,90 @@ async function readBlueprintData(targetPath) {
   }
 }
 
+// src/generators/askDrivenAsset.ts
+var NO_DATA_MSG5 = "No Blueprint data available. Run prism scan first.";
+var FORMAT_GUIDES = {
+  markdown: { name: "Markdown document", structure: "Use headers, bullet lists, and code blocks where appropriate.", maxTokens: 3072 },
+  blog: { name: "blog post", structure: "Write with an engaging intro, clear sections, a conclusion, and a call-to-action.", maxTokens: 3072 },
+  social: { name: "social media post", structure: "Write concise, punchy content suitable for Twitter/LinkedIn. Max 280 characters for Twitter mode.", maxTokens: 512 },
+  email: { name: "email", structure: "Use Subject:, greeting, body paragraphs, and a sign-off.", maxTokens: 1024 },
+  slack: { name: "Slack message", structure: "Keep it conversational, use *bold* for emphasis, bullet points for lists. Max 3 paragraphs.", maxTokens: 512 },
+  slide: { name: "presentation outline", structure: "Structure as slide titles with 3-5 bullet points each. Include a title slide and summary slide.", maxTokens: 2048 }
+};
+function buildSystemPrompt6(format, tone) {
+  const toneMap = {
+    professional: "You are a professional technical writer and developer advocate.",
+    casual: "You are a friendly engineering blogger who writes in an approachable, conversational style.",
+    technical: "You are a senior software engineer writing precise, implementation-focused content.",
+    executive: "You are a VP of Engineering writing high-level, business-value-focused content for leadership."
+  };
+  const guide = FORMAT_GUIDES[format];
+  return `${toneMap[tone] ?? toneMap.professional} Generate a ${guide.name} based on the user's question and the provided codebase architecture context. ${guide.structure} Write only the requested content \u2014 no preamble, no meta-commentary.`;
+}
+function buildUserPrompt6(blueprint, question, opts) {
+  const format = opts.format ?? "markdown";
+  const tone = opts.tone ?? "professional";
+  const length = opts.length ?? "medium";
+  const guide = FORMAT_GUIDES[format];
+  const lengthGuide = {
+    short: "Keep it concise \u2014 1-2 paragraphs or equivalent.",
+    medium: "Medium length \u2014 3-5 paragraphs or equivalent.",
+    long: "Detailed and comprehensive \u2014 cover the topic thoroughly."
+  }[length];
+  const topFiles = blueprint.files.slice().sort((a, b) => (b.importedByCount ?? 0) - (a.importedByCount ?? 0)).slice(0, 12);
+  const lines = [
+    `## User's Question`,
+    question,
+    ``,
+    `## Output Requirements`,
+    `- Format: ${guide.name}`,
+    `- Tone: ${tone}`,
+    `- Length: ${length} (${lengthGuide})`,
+    ``,
+    `## Codebase Architecture Context`,
+    `Target: ${blueprint.targetPath}`,
+    `Total files: ${blueprint.stats.totalFiles} | Dependency edges: ${blueprint.stats.runtimeEdges}`,
+    `Categories: app=${blueprint.categories.app ?? 0}, components=${blueprint.categories.component ?? 0}, lib=${blueprint.categories.lib ?? 0}, hooks=${blueprint.categories.hook ?? 0}`,
+    ``,
+    `Key files (by usage):`,
+    ...topFiles.map((f) => `- ${f.path} [${f.category ?? "?"}] \u2014 imported by ${f.importedByCount ?? 0} files, ${f.lineCount ?? "?"} lines`)
+  ];
+  if (blueprint.edges.length > 0) {
+    const edgeSample = blueprint.edges.slice(0, 15);
+    lines.push(``, `Dependency edges (sample):`, ...edgeSample.map((e) => `- ${e.from} \u2192 ${e.to}`));
+  }
+  lines.push(``, `Answer the user's question using the architecture context above. Generate the ${guide.name} now.`);
+  return lines.join("\n");
+}
+async function generateAskDrivenAsset(blueprint, question, opts, provider) {
+  if (!blueprint) {
+    return {
+      text: NO_DATA_MSG5,
+      metadata: { generatedAt: (/* @__PURE__ */ new Date()).toISOString(), usedTokens: 0, generator: "forgesmith" }
+    };
+  }
+  if (!question || !question.trim()) {
+    return {
+      text: "No question provided. Please ask something about your codebase.",
+      metadata: { generatedAt: (/* @__PURE__ */ new Date()).toISOString(), usedTokens: 0, generator: "forgesmith" }
+    };
+  }
+  const format = opts.format ?? "markdown";
+  const tone = opts.tone ?? "professional";
+  const maxTokens = FORMAT_GUIDES[format].maxTokens;
+  const response = await provider.complete({
+    systemPrompt: buildSystemPrompt6(format, tone),
+    messages: [{ role: "user", content: buildUserPrompt6(blueprint, question, opts) }],
+    maxTokens
+  });
+  return {
+    text: response.content,
+    metadata: { generatedAt: (/* @__PURE__ */ new Date()).toISOString(), usedTokens: response.usedTokens, generator: "forgesmith" }
+  };
+}
+
 exports.generateArchitectureWalkthrough = generateArchitectureWalkthrough;
+exports.generateAskDrivenAsset = generateAskDrivenAsset;
 exports.generateChangesSince = generateChangesSince;
 exports.generateOnboardingDoc = generateOnboardingDoc;
 exports.generateRefactoringReport = generateRefactoringReport;

package/dist/index.d.cts

@@ -79,6 +79,12 @@ interface RefactoringReportOpts {
     length?: "short" | "medium" | "long";
     format?: "markdown" | "plain";
 }
+type AskDrivenAssetFormat = "markdown" | "blog" | "social" | "email" | "slack" | "slide";
+interface AskDrivenAssetOpts {
+    format?: AskDrivenAssetFormat;
+    tone?: "professional" | "casual" | "technical" | "executive";
+    length?: "short" | "medium" | "long";
+}
 interface GenerationResult {
     text: string;
     metadata: {
@@ -119,4 +125,6 @@ declare function generateRefactoringReport(blueprint: BlueprintData | null, opts
 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 };
+declare function generateAskDrivenAsset(blueprint: BlueprintData | null, question: string, opts: AskDrivenAssetOpts, provider: LlmProvider): Promise<GenerationResult>;
+
+export { type ArchitectureWalkthroughOpts, type AskDrivenAssetFormat, type AskDrivenAssetOpts, 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, generateAskDrivenAsset, generateChangesSince, generateOnboardingDoc, generateRefactoringReport, generateReleaseNotes, readBlueprintData, readPrismDirectory };

package/dist/index.d.ts

@@ -79,6 +79,12 @@ interface RefactoringReportOpts {
     length?: "short" | "medium" | "long";
     format?: "markdown" | "plain";
 }
+type AskDrivenAssetFormat = "markdown" | "blog" | "social" | "email" | "slack" | "slide";
+interface AskDrivenAssetOpts {
+    format?: AskDrivenAssetFormat;
+    tone?: "professional" | "casual" | "technical" | "executive";
+    length?: "short" | "medium" | "long";
+}
 interface GenerationResult {
     text: string;
     metadata: {
@@ -119,4 +125,6 @@ declare function generateRefactoringReport(blueprint: BlueprintData | null, opts
 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 };
+declare function generateAskDrivenAsset(blueprint: BlueprintData | null, question: string, opts: AskDrivenAssetOpts, provider: LlmProvider): Promise<GenerationResult>;
+
+export { type ArchitectureWalkthroughOpts, type AskDrivenAssetFormat, type AskDrivenAssetOpts, 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, generateAskDrivenAsset, generateChangesSince, generateOnboardingDoc, generateRefactoringReport, generateReleaseNotes, readBlueprintData, readPrismDirectory };

package/dist/index.mjs

@@ -376,4 +376,86 @@ async function readBlueprintData(targetPath) {
   }
 }
 
-export { generateArchitectureWalkthrough, generateChangesSince, generateOnboardingDoc, generateRefactoringReport, generateReleaseNotes, readBlueprintData, readPrismDirectory };
+// src/generators/askDrivenAsset.ts
+var NO_DATA_MSG5 = "No Blueprint data available. Run prism scan first.";
+var FORMAT_GUIDES = {
+  markdown: { name: "Markdown document", structure: "Use headers, bullet lists, and code blocks where appropriate.", maxTokens: 3072 },
+  blog: { name: "blog post", structure: "Write with an engaging intro, clear sections, a conclusion, and a call-to-action.", maxTokens: 3072 },
+  social: { name: "social media post", structure: "Write concise, punchy content suitable for Twitter/LinkedIn. Max 280 characters for Twitter mode.", maxTokens: 512 },
+  email: { name: "email", structure: "Use Subject:, greeting, body paragraphs, and a sign-off.", maxTokens: 1024 },
+  slack: { name: "Slack message", structure: "Keep it conversational, use *bold* for emphasis, bullet points for lists. Max 3 paragraphs.", maxTokens: 512 },
+  slide: { name: "presentation outline", structure: "Structure as slide titles with 3-5 bullet points each. Include a title slide and summary slide.", maxTokens: 2048 }
+};
+function buildSystemPrompt6(format, tone) {
+  const toneMap = {
+    professional: "You are a professional technical writer and developer advocate.",
+    casual: "You are a friendly engineering blogger who writes in an approachable, conversational style.",
+    technical: "You are a senior software engineer writing precise, implementation-focused content.",
+    executive: "You are a VP of Engineering writing high-level, business-value-focused content for leadership."
+  };
+  const guide = FORMAT_GUIDES[format];
+  return `${toneMap[tone] ?? toneMap.professional} Generate a ${guide.name} based on the user's question and the provided codebase architecture context. ${guide.structure} Write only the requested content \u2014 no preamble, no meta-commentary.`;
+}
+function buildUserPrompt6(blueprint, question, opts) {
+  const format = opts.format ?? "markdown";
+  const tone = opts.tone ?? "professional";
+  const length = opts.length ?? "medium";
+  const guide = FORMAT_GUIDES[format];
+  const lengthGuide = {
+    short: "Keep it concise \u2014 1-2 paragraphs or equivalent.",
+    medium: "Medium length \u2014 3-5 paragraphs or equivalent.",
+    long: "Detailed and comprehensive \u2014 cover the topic thoroughly."
+  }[length];
+  const topFiles = blueprint.files.slice().sort((a, b) => (b.importedByCount ?? 0) - (a.importedByCount ?? 0)).slice(0, 12);
+  const lines = [
+    `## User's Question`,
+    question,
+    ``,
+    `## Output Requirements`,
+    `- Format: ${guide.name}`,
+    `- Tone: ${tone}`,
+    `- Length: ${length} (${lengthGuide})`,
+    ``,
+    `## Codebase Architecture Context`,
+    `Target: ${blueprint.targetPath}`,
+    `Total files: ${blueprint.stats.totalFiles} | Dependency edges: ${blueprint.stats.runtimeEdges}`,
+    `Categories: app=${blueprint.categories.app ?? 0}, components=${blueprint.categories.component ?? 0}, lib=${blueprint.categories.lib ?? 0}, hooks=${blueprint.categories.hook ?? 0}`,
+    ``,
+    `Key files (by usage):`,
+    ...topFiles.map((f) => `- ${f.path} [${f.category ?? "?"}] \u2014 imported by ${f.importedByCount ?? 0} files, ${f.lineCount ?? "?"} lines`)
+  ];
+  if (blueprint.edges.length > 0) {
+    const edgeSample = blueprint.edges.slice(0, 15);
+    lines.push(``, `Dependency edges (sample):`, ...edgeSample.map((e) => `- ${e.from} \u2192 ${e.to}`));
+  }
+  lines.push(``, `Answer the user's question using the architecture context above. Generate the ${guide.name} now.`);
+  return lines.join("\n");
+}
+async function generateAskDrivenAsset(blueprint, question, opts, provider) {
+  if (!blueprint) {
+    return {
+      text: NO_DATA_MSG5,
+      metadata: { generatedAt: (/* @__PURE__ */ new Date()).toISOString(), usedTokens: 0, generator: "forgesmith" }
+    };
+  }
+  if (!question || !question.trim()) {
+    return {
+      text: "No question provided. Please ask something about your codebase.",
+      metadata: { generatedAt: (/* @__PURE__ */ new Date()).toISOString(), usedTokens: 0, generator: "forgesmith" }
+    };
+  }
+  const format = opts.format ?? "markdown";
+  const tone = opts.tone ?? "professional";
+  const maxTokens = FORMAT_GUIDES[format].maxTokens;
+  const response = await provider.complete({
+    systemPrompt: buildSystemPrompt6(format, tone),
+    messages: [{ role: "user", content: buildUserPrompt6(blueprint, question, opts) }],
+    maxTokens
+  });
+  return {
+    text: response.content,
+    metadata: { generatedAt: (/* @__PURE__ */ new Date()).toISOString(), usedTokens: response.usedTokens, generator: "forgesmith" }
+  };
+}
+
+export { generateArchitectureWalkthrough, generateAskDrivenAsset, generateChangesSince, generateOnboardingDoc, generateRefactoringReport, generateReleaseNotes, readBlueprintData, readPrismDirectory };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "forgesmith",
-  "version": "0.2.0",
+  "version": "0.3.0",
   "description": "forgesmith — content & asset-generation engine. Forge release notes, blog posts, social copy from prism0x2A data.",
   "type": "module",
   "main": "./dist/index.cjs",