@shahmarasy/prodo 0.1.0

package/src/providers/mock-provider.ts

@@ -0,0 +1,188 @@
+import type { BriefContractItem } from "../normalized-brief";
+import type { LLMProvider, ProviderSchemaHint } from "../types";
+
+function asStringArray(value: unknown): string[] {
+  if (!Array.isArray(value)) return [];
+  return value.filter((item): item is string => typeof item === "string");
+}
+
+function asContracts(value: unknown): BriefContractItem[] {
+  if (!Array.isArray(value)) return [];
+  return value
+    .map((item) => {
+      if (!item || typeof item !== "object") return null;
+      const record = item as Record<string, unknown>;
+      if (typeof record.id !== "string" || typeof record.text !== "string") return null;
+      return { id: record.id, text: record.text };
+    })
+    .filter((item): item is BriefContractItem => item !== null);
+}
+
+function extractValue(markdown: string, heading: string): string[] {
+  const aliases = heading.split("|").map((item) => item.trim().toLowerCase());
+  const lines = markdown.split(/\r?\n/);
+  let collect = false;
+  const out: string[] = [];
+  for (const raw of lines) {
+    const headingMatch = raw.match(/^#{1,6}\s+(.+?)\s*$/);
+    if (headingMatch) {
+      const current = headingMatch[1].trim().toLowerCase();
+      if (collect && !aliases.includes(current)) break;
+      collect = aliases.includes(current);
+      continue;
+    }
+    if (!collect) continue;
+    const cleaned = raw.replace(/^\s*[-*]\s*/, "").trim();
+    if (cleaned.length > 0) out.push(cleaned);
+  }
+  return out;
+}
+
+function normalizeWithMock(inputContext: Record<string, unknown>): string {
+  const brief = typeof inputContext.briefMarkdown === "string" ? inputContext.briefMarkdown : "";
+  const product = extractValue(brief, "Product Name|Name")[0] ?? "";
+  const problem = extractValue(brief, "Problem|Problem Statement").join(" ");
+  const audience = extractValue(brief, "Audience|Users|Persona");
+  const goals = extractValue(brief, "Goals|Objectives");
+  const features = extractValue(brief, "Core Features|Features|Capabilities");
+  const constraints = extractValue(brief, "Constraints|Limitations|Restrictions");
+  const assumptions = extractValue(brief, "Assumptions|Open Questions");
+
+  const contracts = {
+    goals: goals.map((text, index) => ({ id: `G${index + 1}`, text })),
+    core_features: features.map((text, index) => ({ id: `F${index + 1}`, text })),
+    constraints: constraints.map((text, index) => ({ id: `C${index + 1}`, text }))
+  };
+
+  const confidence = {
+    product_name: product ? 0.95 : 0.25,
+    problem: problem ? 0.95 : 0.25,
+    audience: audience.length > 0 ? 0.95 : 0.25,
+    goals: goals.length > 0 ? 0.95 : 0.25,
+    core_features: features.length > 0 ? 0.95 : 0.25
+  };
+
+  return JSON.stringify(
+    {
+      schema_version: "1.0",
+      product_name: product,
+      problem,
+      audience,
+      goals,
+      core_features: features,
+      constraints,
+      assumptions,
+      contracts,
+      confidence
+    },
+    null,
+    2
+  );
+}
+
+function normalizeSectionItems(inputContext: Record<string, unknown>): string[] {
+  const normalizedBrief = (inputContext.normalizedBrief ?? {}) as Record<string, unknown>;
+  const goals = asStringArray(normalizedBrief.goals);
+  const features = asStringArray(normalizedBrief.core_features);
+  const constraints = asStringArray(normalizedBrief.constraints);
+  return [...goals, ...features, ...constraints];
+}
+
+function coverageItems(
+  schemaHint: ProviderSchemaHint,
+  inputContext: Record<string, unknown>
+): Array<{ id: string; text: string }> {
+  const catalog = (inputContext.contractCatalog ?? {}) as Record<string, unknown>;
+  const values: Array<{ id: string; text: string }> = [];
+  if (schemaHint.requiredContracts.includes("goals")) values.push(...asContracts(catalog.goals));
+  if (schemaHint.requiredContracts.includes("core_features")) values.push(...asContracts(catalog.core_features));
+  if (schemaHint.requiredContracts.includes("constraints")) values.push(...asContracts(catalog.constraints));
+  return values;
+}
+
+function headingBlock(
+  heading: string,
+  items: string[],
+  fallbackText: string,
+  coverage: Array<{ id: string; text: string }>
+): string {
+  const selected = items.slice(0, 2);
+  const contractBullets = coverage.map((item) => `- [${item.id}] ${item.text}`);
+  const bullets = [...contractBullets, ...selected.map((item) => `- ${item}`)];
+  const finalBullets = bullets.length > 0 ? bullets.join("\n") : `- ${fallbackText}`;
+  return `${heading}\n${finalBullets}\n`;
+}
+
+function buildArtifactBody(schemaHint: ProviderSchemaHint, inputContext: Record<string, unknown>): string {
+  const normalizedBrief = (inputContext.normalizedBrief ?? {}) as Record<string, unknown>;
+  const productName =
+    typeof normalizedBrief.product_name === "string" ? normalizedBrief.product_name : "Product";
+  const lang = typeof inputContext.outputLanguage === "string" ? inputContext.outputLanguage.toLowerCase() : "en";
+  const items = normalizeSectionItems(inputContext);
+  const coverage = coverageItems(schemaHint, inputContext);
+  const fallback = lang === "tr" ? "Detay daha sonra netlestirilecek." : "To be refined.";
+  const sections = schemaHint.requiredHeadings.map((heading) => headingBlock(heading, items, fallback, coverage));
+  const title =
+    lang === "tr"
+      ? `# ${productName} icin ${schemaHint.artifactType.toUpperCase()}`
+      : `# ${schemaHint.artifactType.toUpperCase()} for ${productName}`;
+  if (schemaHint.artifactType === "workflow") {
+    return `${title}\n\n${sections.join("\n")}\n\n\`\`\`mermaid
+flowchart TD
+  A[Start] --> B[[F1] User Action]
+  B --> C[System Step]
+  C --> D[Done]
+\`\`\``.trim();
+  }
+  return `${title}\n\n${sections.join("\n")}\n\n${lang === "tr" ? "Not" : "Note"}: ${fallback}`.trim();
+}
+
+function semanticIssuesWithMock(inputContext: Record<string, unknown>): string {
+  const pair = inputContext.pair as Record<string, unknown>;
+  const leftBody = typeof pair?.left_body === "string" ? pair.left_body : "";
+  const rightBody = typeof pair?.right_body === "string" ? pair.right_body : "";
+  const leftFile = typeof pair?.left_file === "string" ? pair.left_file : "";
+  const rightFile = typeof pair?.right_file === "string" ? pair.right_file : "";
+  const issues: Array<Record<string, unknown>> = [];
+
+  const contradiction =
+    /guest checkout/i.test(leftBody) && /(auth required|requires auth|must login)/i.test(rightBody);
+  if (contradiction) {
+    issues.push({
+      level: "error",
+      code: "semantic_contradiction",
+      check: "semantic_consistency",
+      contract_id: "F1",
+      file: rightFile || leftFile,
+      message: "Workflow allows guest checkout but paired artifact requires authentication.",
+      suggestion: "Align auth behavior across both artifacts."
+    });
+  }
+
+  return JSON.stringify({ issues }, null, 2);
+}
+
+function contractRelevanceWithMock(inputContext: Record<string, unknown>): string {
+  const contractText = typeof inputContext.contract_text === "string" ? inputContext.contract_text.toLowerCase() : "";
+  const contextText = typeof inputContext.context_text === "string" ? inputContext.context_text.toLowerCase() : "";
+  const terms = contractText
+    .split(/\W+/)
+    .map((term) => term.trim())
+    .filter((term) => term.length > 3);
+  const overlap = terms.filter((term) => contextText.includes(term)).length;
+  const relevant = terms.length === 0 ? true : overlap / terms.length >= 0.25;
+  return JSON.stringify({ relevant, score: terms.length === 0 ? 1 : overlap / terms.length }, null, 2);
+}
+
+export class MockProvider implements LLMProvider {
+  async generate(
+    _prompt: string,
+    inputContext: Record<string, unknown>,
+    schemaHint: ProviderSchemaHint
+  ): Promise<{ body: string; frontmatter?: Record<string, unknown> }> {
+    if (schemaHint.artifactType === "normalize") return { body: normalizeWithMock(inputContext) };
+    if (schemaHint.artifactType === "semantic_consistency") return { body: semanticIssuesWithMock(inputContext) };
+    if (schemaHint.artifactType === "contract_relevance") return { body: contractRelevanceWithMock(inputContext) };
+    return { body: buildArtifactBody(schemaHint, inputContext) };
+  }
+}

package/src/providers/openai-provider.ts

@@ -0,0 +1,87 @@
+import type { LLMProvider, ProviderSchemaHint } from "../types";
+import { UserError } from "../errors";
+
+type ChatResponse = {
+  choices?: Array<{
+    message?: {
+      content?: string;
+    };
+  }>;
+};
+
+export class OpenAIProvider implements LLMProvider {
+  private readonly apiKey: string;
+  private readonly model: string;
+  private readonly baseUrl: string;
+
+  constructor() {
+    const key = process.env.OPENAI_API_KEY;
+    if (!key) {
+      throw new UserError("OPENAI_API_KEY missing. Set it or use PRODO_LLM_PROVIDER=mock.");
+    }
+    this.apiKey = key;
+    this.model = process.env.PRODO_OPENAI_MODEL ?? "gpt-4o-mini";
+    this.baseUrl = process.env.PRODO_OPENAI_BASE_URL ?? "https://api.openai.com/v1";
+  }
+
+  async generate(
+    prompt: string,
+    inputContext: Record<string, unknown>,
+    schemaHint: ProviderSchemaHint
+  ): Promise<{ body: string; frontmatter?: Record<string, unknown> }> {
+    const outputLanguage =
+      typeof inputContext.outputLanguage === "string" && inputContext.outputLanguage.trim()
+        ? inputContext.outputLanguage.trim()
+        : "en";
+    const mode = schemaHint.artifactType;
+    const system =
+      mode === "normalize"
+        ? `You normalize messy human product briefs into strict JSON.
+Return valid JSON only, no markdown. Include confidence scores (0..1) for critical fields.`
+        : mode === "semantic_consistency"
+          ? `You detect semantic inconsistencies between paired artifacts.
+Return valid JSON only: { "issues": [{level, code, check, contract_id, file, message, suggestion}] }.`
+          : mode === "contract_relevance"
+            ? `You verify whether tagged content actually matches the referenced contract text.
+Return valid JSON only: { "relevant": boolean, "score": number, "reason": string }.`
+            : `You are a product-document generator.
+Return only Markdown body content.
+Headings required:
+${schemaHint.requiredHeadings.join("\n")}
+Required contract tags:
+${schemaHint.requiredContracts.join(", ")}
+Use tags like [G1], [F2], [C1] where relevant.
+Output language: ${outputLanguage}
+Do not translate required headings.`;
+    const user = `${prompt}\n\nContext JSON:\n${JSON.stringify(inputContext, null, 2)}`;
+
+    const response = await fetch(`${this.baseUrl}/chat/completions`, {
+      method: "POST",
+      headers: {
+        "Content-Type": "application/json",
+        Authorization: `Bearer ${this.apiKey}`
+      },
+      body: JSON.stringify({
+        model: this.model,
+        messages: [
+          { role: "system", content: system },
+          { role: "user", content: user }
+        ],
+        temperature: 0.2
+      })
+    });
+
+    if (!response.ok) {
+      const text = await response.text();
+      throw new UserError(`OpenAI request failed (${response.status}): ${text}`);
+    }
+
+    const payload = (await response.json()) as ChatResponse;
+    const content = payload.choices?.[0]?.message?.content?.trim();
+    if (!content) {
+      throw new UserError("OpenAI provider returned an empty response.");
+    }
+
+    return { body: content };
+  }
+}

package/src/registry.ts

@@ -0,0 +1,119 @@
+import fs from "node:fs/promises";
+import path from "node:path";
+import { createHash } from "node:crypto";
+import { registryPath } from "./paths";
+import { ensureDir, fileExists } from "./utils";
+
+export type OverrideRegistryEntry = {
+  artifact_type: string;
+  file: string;
+  sha256: string;
+};
+
+export type ProdoRegistry = {
+  schema_version: "1.0";
+  updated_at: string;
+  installed_presets: string[];
+  installed_overrides: OverrideRegistryEntry[];
+};
+
+const EMPTY_REGISTRY: ProdoRegistry = {
+  schema_version: "1.0",
+  updated_at: new Date(0).toISOString(),
+  installed_presets: [],
+  installed_overrides: []
+};
+
+async function sha256(filePath: string): Promise<string> {
+  const raw = await fs.readFile(filePath);
+  return createHash("sha256").update(raw).digest("hex");
+}
+
+function sanitizeRegistry(input: unknown): ProdoRegistry {
+  if (!input || typeof input !== "object") return { ...EMPTY_REGISTRY };
+  const raw = input as Record<string, unknown>;
+  const installedPresets = Array.isArray(raw.installed_presets)
+    ? raw.installed_presets
+      .filter((value): value is string => typeof value === "string")
+      .map((value) => value.trim())
+      .filter((value) => value.length > 0)
+    : [];
+  const installedOverrides = Array.isArray(raw.installed_overrides)
+    ? raw.installed_overrides
+      .filter((item): item is Record<string, unknown> => !!item && typeof item === "object")
+      .map((item) => ({
+        artifact_type: typeof item.artifact_type === "string" ? item.artifact_type.trim() : "",
+        file: typeof item.file === "string" ? item.file.trim() : "",
+        sha256: typeof item.sha256 === "string" ? item.sha256.trim() : ""
+      }))
+      .filter((item) => item.artifact_type && item.file && item.sha256)
+    : [];
+  return {
+    schema_version: "1.0",
+    updated_at: typeof raw.updated_at === "string" && raw.updated_at.trim() ? raw.updated_at : EMPTY_REGISTRY.updated_at,
+    installed_presets: Array.from(new Set(installedPresets)),
+    installed_overrides: installedOverrides
+  };
+}
+
+export async function readRegistry(cwd: string): Promise<ProdoRegistry> {
+  const file = registryPath(cwd);
+  if (!(await fileExists(file))) return { ...EMPTY_REGISTRY };
+  try {
+    const parsed = JSON.parse(await fs.readFile(file, "utf8")) as unknown;
+    return sanitizeRegistry(parsed);
+  } catch {
+    return { ...EMPTY_REGISTRY };
+  }
+}
+
+async function readInstalledPresetsFromFile(cwd: string): Promise<string[]> {
+  const file = path.join(cwd, ".prodo", "presets", "installed.json");
+  if (!(await fileExists(file))) return [];
+  try {
+    const parsed = JSON.parse(await fs.readFile(file, "utf8")) as unknown;
+    if (!Array.isArray(parsed)) return [];
+    return parsed
+      .filter((value): value is string => typeof value === "string")
+      .map((value) => value.trim())
+      .filter((value) => value.length > 0);
+  } catch {
+    return [];
+  }
+}
+
+async function discoverOverrides(cwd: string): Promise<OverrideRegistryEntry[]> {
+  const overridesDir = path.join(cwd, ".prodo", "templates", "overrides");
+  if (!(await fileExists(overridesDir))) return [];
+  const entries = await fs.readdir(overridesDir, { withFileTypes: true });
+  const out: OverrideRegistryEntry[] = [];
+  for (const entry of entries) {
+    if (!entry.isFile()) continue;
+    if (!entry.name.endsWith(".md")) continue;
+    const fullPath = path.join(overridesDir, entry.name);
+    out.push({
+      artifact_type: entry.name.replace(/\.md$/, ""),
+      file: fullPath,
+      sha256: await sha256(fullPath)
+    });
+  }
+  out.sort((a, b) => a.artifact_type.localeCompare(b.artifact_type));
+  return out;
+}
+
+export async function syncRegistry(cwd: string): Promise<ProdoRegistry> {
+  const existing = await readRegistry(cwd);
+  const discoveredPresets = await readInstalledPresetsFromFile(cwd);
+  const discoveredOverrides = await discoverOverrides(cwd);
+  const mergedPresets = Array.from(new Set([...existing.installed_presets, ...discoveredPresets])).sort();
+  const merged: ProdoRegistry = {
+    schema_version: "1.0",
+    updated_at: new Date().toISOString(),
+    installed_presets: mergedPresets,
+    installed_overrides: discoveredOverrides
+  };
+  const file = registryPath(cwd);
+  await ensureDir(path.dirname(file));
+  await fs.writeFile(file, `${JSON.stringify(merged, null, 2)}\n`, "utf8");
+  return merged;
+}

package/src/settings.ts

@@ -0,0 +1,34 @@
+import fs from "node:fs/promises";
+import { settingsPath } from "./paths";
+import { fileExists } from "./utils";
+
+export type ProdoSettings = {
+  lang: string;
+  ai?: string;
+};
+
+const DEFAULT_SETTINGS: ProdoSettings = {
+  lang: "en"
+};
+
+export async function readSettings(cwd: string): Promise<ProdoSettings> {
+  const path = settingsPath(cwd);
+  if (!(await fileExists(path))) return { ...DEFAULT_SETTINGS };
+  try {
+    const raw = await fs.readFile(path, "utf8");
+    const parsed = JSON.parse(raw) as Partial<ProdoSettings>;
+    return {
+      lang: typeof parsed.lang === "string" && parsed.lang.trim() ? parsed.lang.trim() : "en",
+      ai: typeof parsed.ai === "string" && parsed.ai.trim() ? parsed.ai.trim() : undefined
+    };
+  } catch {
+    return { ...DEFAULT_SETTINGS };
+  }
+}
+
+export async function writeSettings(cwd: string, settings: ProdoSettings): Promise<string> {
+  const path = settingsPath(cwd);
+  await fs.writeFile(path, `${JSON.stringify(settings, null, 2)}\n`, "utf8");
+  return path;
+}
+

package/src/template-resolver.ts

@@ -0,0 +1,33 @@
+import fs from "node:fs/promises";
+import {
+  overrideTemplateCandidatePaths,
+  templateCandidatePaths
+} from "./paths";
+import { extractRequiredHeadings } from "./markdown";
+import type { ArtifactType } from "./types";
+import { fileExists } from "./utils";
+
+type ResolveOptions = {
+  cwd: string;
+  artifactType: ArtifactType;
+};
+
+export async function resolveTemplate(options: ResolveOptions): Promise<{ path: string; content: string } | null> {
+  const { cwd, artifactType } = options;
+  const candidates: string[] = [
+    ...overrideTemplateCandidatePaths(cwd, artifactType),
+    ...templateCandidatePaths(cwd, artifactType)
+  ];
+
+  for (const filePath of candidates) {
+    if (await fileExists(filePath)) {
+      const content = await fs.readFile(filePath, "utf8");
+      return { path: filePath, content };
+    }
+  }
+  return null;
+}
+
+export function extractRequiredHeadingsFromTemplate(content: string): string[] {
+  return extractRequiredHeadings(content);
+}