@shahmarasy/prodo 0.1.0

package/src/templates.ts

@@ -0,0 +1,440 @@
+import { defaultRequiredHeadings } from "./constants";
+import type { ArtifactType } from "./types";
+import type { WorkflowCommand } from "./workflow-commands";
+
+const BASE_SCHEMA = {
+  $schema: "https://json-schema.org/draft/2020-12/schema",
+  type: "object",
+  required: ["frontmatter", "body"],
+  properties: {
+    frontmatter: {
+      type: "object",
+      required: ["artifact_type", "version", "source_brief", "generated_at", "status"],
+      properties: {
+        artifact_type: { type: "string" },
+        version: { type: "string", minLength: 1 },
+        source_brief: { type: "string", minLength: 1 },
+        generated_at: { type: "string", format: "date-time" },
+        status: { type: "string", enum: ["draft", "reviewed", "approved"] },
+        title: { type: "string" },
+        upstream_artifacts: {
+          type: "array",
+          items: { type: "string" }
+        },
+        contract_coverage: {
+          type: "object",
+          required: ["goals", "core_features", "constraints"],
+          properties: {
+            goals: { type: "array", items: { type: "string", pattern: "^G[0-9]+$" } },
+            core_features: { type: "array", items: { type: "string", pattern: "^F[0-9]+$" } },
+            constraints: { type: "array", items: { type: "string", pattern: "^C[0-9]+$" } }
+          },
+          additionalProperties: false
+        }
+      },
+      additionalProperties: true
+    },
+    body: {
+      type: "string",
+      minLength: 40
+    }
+  },
+  additionalProperties: false
+};
+
+export function schemaTemplate(artifactType: ArtifactType): Record<string, unknown> {
+  return {
+    ...BASE_SCHEMA,
+    properties: {
+      ...(BASE_SCHEMA.properties as Record<string, unknown>),
+      frontmatter: {
+        ...((BASE_SCHEMA.properties as Record<string, unknown>).frontmatter as Record<string, unknown>),
+        properties: {
+          ...((((BASE_SCHEMA.properties as Record<string, unknown>).frontmatter as Record<string, unknown>)
+            .properties as Record<string, unknown>)),
+          artifact_type: { const: artifactType }
+        }
+      }
+    },
+    x_required_headings: defaultRequiredHeadings(artifactType)
+  };
+}
+
+export function promptTemplate(artifactType: ArtifactType, lang = "en"): string {
+  const tr = lang.toLowerCase().startsWith("tr");
+  if (artifactType === "workflow") {
+    return `You are Prodo's artifact generator for WORKFLOW.
+
+Goal:
+- Produce paired workflow outputs for the same flow.
+
+Output contract (STRICT):
+- Return Markdown explanation first (no frontmatter), following required headings exactly.
+- Include actionable flow details and contract tags like [F1].
+- Then append a mandatory Mermaid block for the same flow:
+\`\`\`mermaid
+flowchart TD
+  A --> B
+\`\`\`
+- Do not return prose-only markdown without Mermaid.
+
+Input immutability:
+- Input files are read-only.
+- Do not modify, rewrite, summarize, or optimize \`brief.md\`.
+
+Language contract:
+- Output text in requested language from inputContext.outputLanguage.
+- If outputLanguage is "tr", every sentence and heading MUST be Turkish.
+- Never mix Turkish and English in the same artifact.
+
+Quality bar:
+- Main flow must be implementation-ready.
+- Edge cases and postconditions must be explicit.`;
+  }
+  if (artifactType === "wireframe") {
+    return `You are Prodo's artifact generator for WIREFRAME.
+
+Goal:
+- Produce a human-readable wireframe explanation in Markdown.
+
+Output contract (STRICT):
+- Return Markdown body only (no frontmatter).
+- Include all required headings exactly as provided.
+- Describe one concrete screen at a time with actionable details.
+- HTML wireframe is generated by Prodo as a companion .html file; do not output raw HTML as primary markdown body.
+
+Input immutability:
+- Input files are read-only.
+- Do not modify, rewrite, summarize, or optimize \`brief.md\`.
+
+Language contract:
+- Output text in requested language from inputContext.outputLanguage.
+- If outputLanguage is "tr", every sentence and heading MUST be Turkish.
+- Never mix Turkish and English in the same artifact.
+
+Quality bar:
+- Keep sections concise but specific.
+- Ensure actions/states/messages are testable and implementation-relevant.`;
+  }
+  return `You are Prodo's artifact generator for ${artifactType.toUpperCase()}.
+
+Goal:
+- Produce a decision-ready product artifact from normalized brief and upstream artifacts.
+
+Output contract:
+- Return only Markdown body (NO YAML frontmatter).
+- Keep all required section headings exactly as provided.
+- When referencing brief contracts, use explicit tags like [G1], [F2], [C1].
+- Use concrete statements, avoid placeholders like "TBD" unless unavoidable.
+- Reference upstream constraints and tradeoffs explicitly.
+
+Input immutability:
+- Input files are read-only.
+- Do not modify, rewrite, summarize, or optimize \`brief.md\`.
+
+Language contract:
+- Output text in requested language from inputContext.outputLanguage.
+- If outputLanguage is "tr", every sentence and heading MUST be Turkish.
+- Never mix Turkish and English in the same artifact.
+- Do not translate or change required headings unless outputLanguage is "tr" and Turkish headings are provided.
+
+Quality bar:
+- Every section must contain actionable content.
+- Include assumptions and risks where relevant.
+- Keep content concise but implementation-ready.
+
+Required headings:
+${defaultRequiredHeadings(artifactType).map((heading) => `- ${heading}`).join("\n")}
+
+When data is missing:
+${tr ? "- varsayim yaparken Turkce yaz\n- varsayimi ilgili bolumde acikca belirt" : "- infer a sensible default\n- state the assumption clearly in the relevant section"}`;
+}
+
+export function artifactTemplateTemplate(artifactType: ArtifactType, lang = "en"): string {
+  const tr = lang.toLowerCase().startsWith("tr");
+  const base = [`# ${artifactType.toUpperCase()} Template`, ""];
+
+  if (artifactType === "prd") {
+    return [
+      ...base,
+      "## Problem",
+      "- User pain and why now",
+      "- Existing workaround and gap",
+      "",
+      "## Goals",
+      "- Business goals (measurable)",
+      "- User outcomes",
+      "",
+      "## Scope",
+      "- In scope",
+      "- Out of scope",
+      "",
+      "## Requirements",
+      "- Functional requirements",
+      "- Non-functional requirements",
+      "- Compliance/security requirements",
+      "",
+      "## Risks",
+      "- Top risks and mitigations",
+      "",
+      "## Assumptions",
+      "- Key assumptions"
+    ].join("\n");
+  }
+
+  if (artifactType === "workflow") {
+    return [
+      "flowchart TD",
+      `  A[${tr ? "Baslangic" : "Start"}] --> B[[F1] ${tr ? "Kullanici islemi" : "User action"}]`,
+      `  B --> C[${tr ? "Sistem islemi" : "System process"}]`,
+      `  C --> D[${tr ? "Basari" : "Success"}]`,
+      `  C --> E[${tr ? "Hata" : "Error"}]`
+    ].join("\n");
+  }
+
+  if (artifactType === "wireframe") {
+    return `<!doctype html>
+<html lang="${tr ? "tr" : "en"}">
+<head>
+  <meta charset="utf-8" />
+  <meta name="viewport" content="width=device-width, initial-scale=1" />
+  <title>${tr ? "Wireframe Ekrani" : "Wireframe Screen"}</title>
+</head>
+<body>
+  <header>
+    <h1>${tr ? "Ekran Basligi" : "Screen Title"}</h1>
+    <nav>
+      <button type="button">${tr ? "Geri" : "Back"}</button>
+      <button type="button">${tr ? "Devam" : "Next"}</button>
+    </nav>
+  </header>
+  <main>
+    <section>
+      <h2>${tr ? "Birincil Icerik" : "Primary Content"}</h2>
+      <ul>
+        <li>${tr ? "Durum ozeti" : "Status summary"}</li>
+        <li>${tr ? "Aksiyon alani" : "Action area"}</li>
+      </ul>
+    </section>
+    <section>
+      <h2>${tr ? "Form" : "Form"}</h2>
+      <form>
+        <label>${tr ? "Alan" : "Field"} <input type="text" /></label>
+        <button type="submit">${tr ? "Kaydet" : "Save"}</button>
+      </form>
+    </section>
+  </main>
+</body>
+</html>`;
+  }
+
+  if (artifactType === "stories") {
+    return [
+      ...base,
+      "## User Stories",
+      "- As a <user>, I want <goal>, so that <benefit>",
+      "",
+      "## Acceptance Criteria",
+      "- Given / When / Then criteria",
+      "- Negative and edge scenarios",
+      "",
+      "## Traceability",
+      "- Map each story to PRD requirement"
+    ].join("\n");
+  }
+
+  if (artifactType === "techspec") {
+    return [
+      ...base,
+      "## Architecture",
+      "- High-level components and boundaries",
+      "",
+      "## Data Model",
+      "- Entities, fields, relations",
+      "",
+      "## APIs",
+      "- Endpoints/interfaces and contracts",
+      "",
+      "## Risks",
+      "- Technical risks and mitigation",
+      "",
+      "## Observability",
+      "- Logs, metrics, alerts"
+    ].join("\n");
+  }
+
+  const fallbackTemplate = [
+    ...base,
+    tr ? "## Ozet" : "## Summary",
+    tr ? "- Ana amac ve beklenen cikti" : "- Core intent and outcomes",
+    "",
+    tr ? "## Detaylar" : "## Details",
+    tr ? "- Kararlar, varsayimlar ve riskler" : "- Key decisions, assumptions, and risks",
+    "",
+    tr ? "## Izlenebilirlik" : "## Traceability",
+    tr ? "- Kararlari kontrat etiketleri ile eslestir" : "- Link decisions to contract tags"
+  ].join("\n");
+
+  return fallbackTemplate;
+}
+
+export const START_BRIEF_TEMPLATE = `# Product Brief
+
+## Product Name
+Example Product
+
+## Problem
+Describe the user problem.
+
+## Audience
+Who this product is for.
+
+## Core Features
+- Feature A
+- Feature B
+
+## Goals
+- Goal 1
+- Goal 2
+
+## Constraints
+- Budget or timeline constraints
+- Compliance or technical constraints
+`;
+
+export const NORMALIZED_BRIEF_TEMPLATE = {
+  schema_version: "1.0",
+  product_name: "Example Product",
+  problem: "Describe the user problem clearly.",
+  audience: ["Primary users"],
+  goals: ["Goal 1", "Goal 2"],
+  core_features: ["Feature A", "Feature B"],
+  constraints: ["Constraint 1"],
+  assumptions: ["Assumption 1"],
+  contracts: {
+    goals: [
+      { id: "G1", text: "Goal 1" },
+      { id: "G2", text: "Goal 2" }
+    ],
+    core_features: [
+      { id: "F1", text: "Feature A" },
+      { id: "F2", text: "Feature B" }
+    ],
+    constraints: [{ id: "C1", text: "Constraint 1" }]
+  }
+};
+
+export const NORMALIZE_PROMPT_TEMPLATE = `Normalize start-brief content into JSON.
+
+Return JSON object with keys:
+- schema_version (string)
+- product_name (string)
+- problem (string)
+- audience (string[])
+- goals (string[])
+- core_features (string[])
+- constraints (string[])
+- assumptions (string[])
+- contracts.goals[] ({id,text})
+- contracts.core_features[] ({id,text})
+- contracts.constraints[] ({id,text})
+- confidence.product_name (0..1)
+- confidence.problem (0..1)
+- confidence.audience (0..1)
+- confidence.goals (0..1)
+- confidence.core_features (0..1)
+
+Rules:
+- do NOT invent missing critical content
+- keep wording concise and concrete
+- if critical field is missing, return empty and low confidence (<0.7)
+- assign deterministic IDs: goals => G1..Gn, features => F1..Fn, constraints => C1..Cn
+- input files are read-only; never modify, summarize, or rewrite \`brief.md\` in-place
+- write normalized output as a new JSON object only`;
+
+export function commandTemplate(command: WorkflowCommand): string {
+  return `---
+description: ${command.description}
+handoffs:
+  - label: Continue Workflow
+    agent: prodo-next
+    prompt: Continue with the next Prodo command in sequence.
+    send: true
+run:
+  action: ${command.cliSubcommand}
+  mode: internal-runtime
+---
+
+## User Input
+
+\`\`\`text
+$ARGUMENTS
+\`\`\`
+
+Execution policy:
+- Execute-first, diagnose-second.
+- Perform only minimal prerequisite checks before execution.
+- Do not inspect hooks or internals unless command execution fails.
+- Input files are read-only; never modify or rewrite \`brief.md\`.
+
+## Execution
+
+1. Minimal prerequisites only:
+- Confirm project is initialized (\`.prodo/\` exists).
+- Confirm required input files for \`${command.cliSubcommand}\` exist.
+- Confirm output location is writable.
+
+2. Execute immediately:
+- Execute the \`${command.cliSubcommand}\` process through Prodo internal runtime.
+- Keep narration short and action-oriented.
+
+3. Verify result:
+- Confirm expected output file(s) were created/updated.
+- Confirm command success state (exit code or validation status).
+
+4. Diagnose only on failure:
+- Inspect \`.prodo/hooks.yml\` only after execution failure.
+- Explain root cause and next fix steps briefly.
+
+## Handoff
+
+Suggest the next slash command explicitly (for example: \`/prodo-prd\`, \`/prodo-workflow\`).`;
+}
+
+export const HOOKS_TEMPLATE = `# Hook item fields:
+# - command: string (required)
+# - optional: boolean (default false)
+# - enabled: boolean (default true)
+# - condition: shell command; run hook only if condition exits 0
+# - timeout_ms: per-attempt timeout in milliseconds (default 30000)
+# - retry: extra retry count after first attempt (default 0)
+# - retry_delay_ms: delay between retries (default 500)
+#
+# Example:
+# hooks:
+#   before_prd:
+#     - command: "node -e \\"console.log('lint ok')\\""
+#       optional: false
+#       enabled: true
+#       condition: "node -e \\"process.exit(0)\\""
+#       timeout_ms: 15000
+#       retry: 1
+#       retry_delay_ms: 300
+
+hooks:
+  before_normalize: []
+  after_normalize: []
+  before_prd: []
+  after_prd: []
+  before_workflow: []
+  after_workflow: []
+  before_wireframe: []
+  after_wireframe: []
+  before_stories: []
+  after_stories: []
+  before_techspec: []
+  after_techspec: []
+  before_validate: []
+  after_validate: []
+`;
+

package/src/types.ts

@@ -0,0 +1,46 @@
+export const CORE_ARTIFACT_TYPES = ["prd", "workflow", "wireframe", "stories", "techspec"] as const;
+export const ARTIFACT_TYPES = CORE_ARTIFACT_TYPES;
+
+export type CoreArtifactType = (typeof CORE_ARTIFACT_TYPES)[number];
+export type ArtifactType = CoreArtifactType | string;
+
+export type ArtifactDoc = {
+  frontmatter: Record<string, unknown>;
+  body: string;
+};
+
+export type ContractCoverage = {
+  goals: string[];
+  core_features: string[];
+  constraints: string[];
+};
+
+export type ValidationIssue = {
+  level: "error" | "warning";
+  code: string;
+  check?: "schema" | "tag_coverage" | "semantic_consistency" | "contract_relevance";
+  artifactType?: ArtifactType;
+  file?: string;
+  field?: string;
+  message: string;
+  suggestion?: string;
+};
+
+export type GenerateResult = {
+  body: string;
+  frontmatter?: Record<string, unknown>;
+};
+
+export type ProviderSchemaHint = {
+  artifactType: ArtifactType | "normalize" | "semantic_consistency" | "contract_relevance";
+  requiredHeadings: string[];
+  requiredContracts: Array<keyof ContractCoverage>;
+};
+
+export type LLMProvider = {
+  generate: (
+    prompt: string,
+    inputContext: Record<string, unknown>,
+    schemaHint: ProviderSchemaHint
+  ) => Promise<GenerateResult>;
+};

package/src/utils.ts

@@ -0,0 +1,50 @@
+import fs from "node:fs/promises";
+import path from "node:path";
+
+export async function ensureDir(dirPath: string): Promise<void> {
+  await fs.mkdir(dirPath, { recursive: true });
+}
+
+export async function fileExists(filePath: string): Promise<boolean> {
+  try {
+    await fs.access(filePath);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+export async function readJsonFile<T>(filePath: string): Promise<T> {
+  const raw = await fs.readFile(filePath, "utf8");
+  return JSON.parse(raw) as T;
+}
+
+export function timestampSlug(date = new Date()): string {
+  return date.toISOString().replace(/[:.]/g, "-");
+}
+
+export async function listFilesSortedByMtime(dirPath: string): Promise<string[]> {
+  const exists = await fileExists(dirPath);
+  if (!exists) return [];
+
+  const entries = await fs.readdir(dirPath);
+  const withStats = await Promise.all(
+    entries.map(async (name) => {
+      const fullPath = path.join(dirPath, name);
+      const stat = await fs.stat(fullPath);
+      return { fullPath, mtimeMs: stat.mtimeMs, isFile: stat.isFile() };
+    })
+  );
+
+  return withStats
+    .filter((entry) => entry.isFile)
+    .sort((a, b) => b.mtimeMs - a.mtimeMs)
+    .map((entry) => entry.fullPath);
+}
+
+export function isPathInside(parentDir: string, candidatePath: string): boolean {
+  const parent = path.resolve(parentDir);
+  const child = path.resolve(candidatePath);
+  const relative = path.relative(parent, child);
+  return relative === "" || (!relative.startsWith("..") && !path.isAbsolute(relative));
+}