@shahmarasy/prodo 0.1.2 → 0.1.4

package/src/init-tui.ts

@@ -1,4 +1,5 @@
 import path from "node:path";
+import os from "node:os";
 import { resolveAi, type SupportedAi } from "./agent-command-installer";
 import { UserError } from "./errors";
 import { fileExists } from "./utils";
@@ -7,6 +8,7 @@ export type InitSelections = {
   ai?: SupportedAi;
   script: "sh" | "ps";
   lang: "tr" | "en";
+  author: string;
   interactive: boolean;
 };
 
@@ -14,6 +16,7 @@ type GatherInitUiOptions = {
   projectRoot: string;
   aiInput?: string;
   langInput?: string;
+  authorInput?: string;
 };
 
 type ClackPrompts = typeof import("@clack/prompts");
@@ -93,17 +96,31 @@ function modelChoiceFromAi(ai?: SupportedAi): "codex" | "gemini" | "auto-detect"
   return "auto-detect";
 }
 
+function defaultAuthorName(authorInput?: string): string {
+  const explicit = (authorInput ?? "").trim();
+  if (explicit.length > 0) return explicit;
+  try {
+    const username = os.userInfo().username.trim();
+    if (username.length > 0) return username;
+  } catch {
+    // ignore lookup errors and continue with fallback
+  }
+  return "Product Author";
+}
+
 export async function gatherInitSelections(options: GatherInitUiOptions): Promise<InitSelections> {
   const clack = await loadClack();
   const defaultLang = normalizeLang(options.langInput);
   const fallbackScript: "sh" | "ps" = process.platform === "win32" ? "ps" : "sh";
   const parsedAi = resolveAi(options.aiInput);
+  const defaultAuthor = defaultAuthorName(options.authorInput);
 
   if (!isInteractiveTerminal()) {
     return {
       ai: parsedAi,
       script: fallbackScript,
       lang: defaultLang,
+      author: defaultAuthor,
       interactive: false
     };
   }
@@ -153,6 +170,16 @@ export async function gatherInitSelections(options: GatherInitUiOptions): Promis
     throw new UserError("Initialization cancelled.");
   }
 
+  const author = await clack.text({
+    message: "Author name",
+    placeholder: "Shahmarasy",
+    defaultValue: defaultAuthor
+  });
+  if (clack.isCancel(author)) {
+    clack.cancel("Initialization cancelled.");
+    throw new UserError("Initialization cancelled.");
+  }
+
   let selectedAi: SupportedAi | undefined;
   if (model === "codex") selectedAi = "codex";
   else if (model === "gemini") selectedAi = "gemini-cli";
@@ -162,6 +189,7 @@ export async function gatherInitSelections(options: GatherInitUiOptions): Promis
     ai: selectedAi,
     script: fallbackScript,
     lang,
+    author: String(author).trim() || defaultAuthor,
     interactive: true
   };
 }
@@ -171,9 +199,10 @@ export function finishInitInteractive(summary: {
   settingsPath: string;
   ai?: SupportedAi;
   lang: "tr" | "en";
+  author: string;
 }): Promise<void> {
   const aiText = summary.ai ?? "none";
   return loadClack().then((clack) => clack.outro(
-    `Scaffold complete.\nAI: ${aiText}\nLanguage: ${summary.lang}\nSettings: ${summary.settingsPath}\nNext: edit brief.md`
+    `Scaffold complete.\nAI: ${aiText}\nLanguage: ${summary.lang}\nAuthor: ${summary.author}\nSettings: ${summary.settingsPath}\nNext: edit brief.md`
   ));
 }

package/src/init.ts

@@ -9,6 +9,7 @@ import { briefPath, outputDirPath, outputIndexPath, prodoPath } from "./paths";
 import { applyConfiguredPresets } from "./preset-loader";
 import { syncRegistry } from "./registry";
 import { writeSettings } from "./settings";
+import { extractRequiredHeadingsFromTemplate } from "./template-resolver";
 import { buildWorkflowCommands } from "./workflow-commands";
 import {
   NORMALIZED_BRIEF_TEMPLATE,
@@ -283,7 +284,7 @@ function summarizeParity(items: AssetManifestItem[]): ScaffoldManifest["parity_s
 
 export async function runInit(
   cwd: string,
-  options?: { ai?: SupportedAi; lang?: string; preset?: string; script?: "sh" | "ps" }
+  options?: { ai?: SupportedAi; lang?: string; author?: string; preset?: string; script?: "sh" | "ps" }
 ): Promise<{ installedAgentFiles: string[]; settingsPath: string }> {
   const root = prodoPath(cwd);
   const artifactDefs = await listArtifactDefinitions(cwd);
@@ -325,15 +326,20 @@ export async function runInit(
   const scriptType = options?.script ?? (process.platform === "win32" ? "ps" : "sh");
   await fs.writeFile(
     path.join(root, "init-options.json"),
-    `${JSON.stringify({ ai: options?.ai ?? null, lang: options?.lang ?? "en", preset: options?.preset ?? null, script: scriptType }, null, 2)}\n`,
+    `${JSON.stringify({ ai: options?.ai ?? null, lang: options?.lang ?? "en", author: options?.author ?? null, preset: options?.preset ?? null, script: scriptType }, null, 2)}\n`,
     "utf8"
   );
 
   await copyDirIfMissing(path.join(projectScaffoldTemplates, "artifacts"), path.join(root, "templates"), copiedAssets);
   for (const artifact of artifactDefs) {
+    const markdownTemplatePath = path.join(root, "templates", `${artifact.name}.md`);
+    const templateHeadings =
+      (await fileExists(markdownTemplatePath))
+        ? extractRequiredHeadingsFromTemplate(await fs.readFile(markdownTemplatePath, "utf8"))
+        : [];
     const schema = {
       ...schemaTemplate(artifact.name),
-      x_required_headings: artifact.required_headings
+      x_required_headings: templateHeadings.length > 0 ? templateHeadings : artifact.required_headings
     };
     await writeFileIfMissing(path.join(root, "schemas", `${artifact.name}.yaml`), yaml.dump(schema));
     await writeFileIfMissing(path.join(root, "prompts", `${artifact.name}.md`), `${promptTemplate(artifact.name, options?.lang ?? "en")}\n`);
@@ -385,7 +391,8 @@ export async function runInit(
   await syncRegistry(cwd);
   const settingsPath = await writeSettings(cwd, {
     lang: (options?.lang ?? "en").trim() || "en",
-    ai: options?.ai
+    ai: options?.ai,
+    author: (options?.author ?? "").trim() || undefined
   });
   return { installedAgentFiles, settingsPath };
 }

package/src/normalize.ts

@@ -17,6 +17,53 @@ type NormalizeOptions = {
   out?: string;
 };
 
+function normalizedKey(value: string): string {
+  return value
+    .normalize("NFD")
+    .replace(/[\u0300-\u036f]/g, "")
+    .replace(/ı/g, "i")
+    .replace(/İ/g, "I")
+    .toLowerCase()
+    .replace(/[^a-z0-9]+/g, " ")
+    .trim();
+}
+
+function extractBriefProductName(rawBrief: string): string | undefined {
+  const lines = rawBrief.split(/\r?\n/);
+  for (let index = 0; index < lines.length; index += 1) {
+    const headingMatch = lines[index].match(/^\s*#{1,6}\s+(.+?)\s*$/);
+    if (!headingMatch) continue;
+    const headingKey = normalizedKey(headingMatch[1]);
+    const isProductHeading =
+      headingKey === "product name" ||
+      headingKey === "project name" ||
+      headingKey === "urun adi" ||
+      headingKey === "urun ismi";
+    if (!isProductHeading) continue;
+
+    for (let cursor = index + 1; cursor < lines.length; cursor += 1) {
+      const rawLine = lines[cursor].trim();
+      if (!rawLine) continue;
+      if (/^\s*#{1,6}\s+/.test(rawLine)) break;
+      const cleaned = rawLine.replace(/^\s*[-*]\s*/, "").trim();
+      if (cleaned.length > 0) return cleaned;
+    }
+  }
+  return undefined;
+}
+
+function preserveOriginalProductName(
+  parsed: Record<string, unknown>,
+  rawBrief: string
+): Record<string, unknown> {
+  const briefProductName = extractBriefProductName(rawBrief);
+  if (!briefProductName) return parsed;
+  const generated = typeof parsed.product_name === "string" ? parsed.product_name : "";
+  if (!generated.trim()) return { ...parsed, product_name: briefProductName };
+  if (normalizedKey(generated) !== normalizedKey(briefProductName)) return parsed;
+  return { ...parsed, product_name: briefProductName };
+}
+
 function extractJsonObject(raw: string): Record<string, unknown> {
   const trimmed = raw.trim();
   const fenced = trimmed.match(/```(?:json)?\s*([\s\S]*?)```/i);
@@ -61,17 +108,18 @@ export async function runNormalize(options: NormalizeOptions): Promise<string> {
   );
 
   const parsed = extractJsonObject(generated.body);
+  const preserved = preserveOriginalProductName(parsed, rawBrief);
   const withContracts = {
-    ...parsed,
+    ...preserved,
     contracts:
-      parsed.contracts ??
+      preserved.contracts ??
       buildContractsFromArrays({
-        goals: Array.isArray(parsed.goals) ? parsed.goals.filter((x): x is string => typeof x === "string") : [],
-        core_features: Array.isArray(parsed.core_features)
-          ? parsed.core_features.filter((x): x is string => typeof x === "string")
+        goals: Array.isArray(preserved.goals) ? preserved.goals.filter((x): x is string => typeof x === "string") : [],
+        core_features: Array.isArray(preserved.core_features)
+          ? preserved.core_features.filter((x): x is string => typeof x === "string")
           : [],
-        constraints: Array.isArray(parsed.constraints)
-          ? parsed.constraints.filter((x): x is string => typeof x === "string")
+        constraints: Array.isArray(preserved.constraints)
+          ? preserved.constraints.filter((x): x is string => typeof x === "string")
           : []
       })
   };

package/src/providers/openai-provider.ts

@@ -37,7 +37,8 @@ export class OpenAIProvider implements LLMProvider {
     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.`
+Return valid JSON only, no markdown. Include confidence scores (0..1) for critical fields.
+Preserve source language and Unicode characters exactly; never transliterate Turkish letters to ASCII.`
         : mode === "semantic_consistency"
           ? `You detect semantic inconsistencies between paired artifacts.
 Return valid JSON only: { "issues": [{level, code, check, contract_id, file, message, suggestion}] }.`

package/src/settings.ts

@@ -5,6 +5,7 @@ import { fileExists } from "./utils";
 export type ProdoSettings = {
   lang: string;
   ai?: string;
+  author?: string;
 };
 
 const DEFAULT_SETTINGS: ProdoSettings = {
@@ -19,7 +20,8 @@ export async function readSettings(cwd: string): Promise<ProdoSettings> {
     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
+      ai: typeof parsed.ai === "string" && parsed.ai.trim() ? parsed.ai.trim() : undefined,
+      author: typeof parsed.author === "string" && parsed.author.trim() ? parsed.author.trim() : undefined
     };
   } catch {
     return { ...DEFAULT_SETTINGS };
@@ -31,4 +33,3 @@ export async function writeSettings(cwd: string, settings: ProdoSettings): Promi
   await fs.writeFile(path, `${JSON.stringify(settings, null, 2)}\n`, "utf8");
   return path;
 }
-

package/src/templates.ts

@@ -347,12 +347,21 @@ Return JSON object with keys:
 Rules:
 - do NOT invent missing critical content
 - keep wording concise and concrete
+- preserve original language and Unicode characters exactly from brief
+- never transliterate Turkish letters (ç, ğ, ı, İ, ö, ş, ü) into ASCII
 - 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 {
+  const normalizeJsonGuard =
+    command.cliSubcommand === "normalize"
+      ? `
+- Normalize output format check:
+  - \`.prodo/briefs/normalized-brief.json\` must be strict JSON object (no markdown fences).
+  - If invalid, rewrite file as pure JSON object only.`
+      : "";
   return `---
 description: ${command.description}
 handoffs:
@@ -375,6 +384,8 @@ Execution policy:
 - Never run \`prodo-${command.cliSubcommand}\`, \`prodo ${command.cliSubcommand}\`, or \`prodo ...\` in shell.
 - Do not inspect hooks or internals unless command execution fails.
 - Input files are read-only; never modify or rewrite \`brief.md\`.
+- Never print full artifact content in chat.
+- Write/update files first, then reply with short status + written file path(s).
 
 ## Execution
 
@@ -392,6 +403,7 @@ Execution policy:
 - Confirm command success state (exit code or validation status).
 - Confirm \`brief.md\` hash/content did not change.
 - Do NOT create manual fallback files under \`.prodo/artifact\` or any ad-hoc folder.
+${normalizeJsonGuard}
 
 4. Diagnose only on failure:
 - Inspect \`.prodo/hooks.yml\` only after execution failure.

package/src/utils.ts

@@ -23,6 +23,20 @@ export function timestampSlug(date = new Date()): string {
   return date.toISOString().replace(/[:.]/g, "-");
 }
 
+function pad2(value: number): string {
+  return String(value).padStart(2, "0");
+}
+
+export function artifactFileStamp(date = new Date()): string {
+  const year = date.getFullYear();
+  const month = pad2(date.getMonth() + 1);
+  const day = pad2(date.getDate());
+  const hour = pad2(date.getHours());
+  const minute = pad2(date.getMinutes());
+  const second = pad2(date.getSeconds());
+  return `${year}${month}${day}-${hour}${minute}${second}`;
+}
+
 export async function listFilesSortedByMtime(dirPath: string): Promise<string[]> {
   const exists = await fileExists(dirPath);
   if (!exists) return [];

package/src/validator.ts

@@ -59,10 +59,6 @@ export async function validateSchema(
   }
 
   const sections = sectionTextMap(doc.body);
-  const trMode = String((doc.frontmatter as Record<string, unknown>).language ?? "").toLowerCase().startsWith("tr");
-  if (trMode) {
-    return { issues, requiredHeadings: [] };
-  }
   for (const heading of requiredHeadings) {
     if (!doc.body.includes(heading)) {
       issues.push({

package/src/workflow-commands.ts

@@ -11,7 +11,8 @@ const BASE_WORKFLOW_COMMANDS: WorkflowCommand[] = [
   { name: "prodo-wireframe", cliSubcommand: "wireframe", description: "Generate wireframe artifact." },
   { name: "prodo-stories", cliSubcommand: "stories", description: "Generate stories artifact." },
   { name: "prodo-techspec", cliSubcommand: "techspec", description: "Generate technical specification artifact." },
-  { name: "prodo-validate", cliSubcommand: "validate", description: "Run schema and cross-artifact consistency validation." }
+  { name: "prodo-validate", cliSubcommand: "validate", description: "Run schema and cross-artifact consistency validation." },
+  { name: "prodo-fix", cliSubcommand: "fix", description: "Auto-fix artifacts based on validation report and brief." }
 ];
 
 export const WORKFLOW_COMMANDS: WorkflowCommand[] = BASE_WORKFLOW_COMMANDS;

package/templates/commands/prodo-fix.md

@@ -0,0 +1,46 @@
+---
+description: Fix failing artifacts using latest validation report and brief-aligned regeneration.
+agent-role: "Recovery Engineer"
+---
+
+## User Input
+
+```text
+$ARGUMENTS
+```
+
+## Execution Policy
+
+- Execute-first, diagnose-second.
+- Do not run shell commands or CLI commands from inside the agent.
+- Never invoke `prodo-fix`, `prodo fix`, or any `prodo ...` command in shell.
+- Input files are read-only; never modify `brief.md`.
+- Write outputs only under `product-docs/` and `.prodo/`.
+- Do not print full artifact bodies in chat.
+
+## Execution
+
+1. Minimum prerequisites only:
+- `.prodo/` exists
+- `brief.md` exists
+- `.prodo/briefs/normalized-brief.json` exists (refresh if stale)
+- Validation report exists in `product-docs/reports/`
+
+2. Execute fix process immediately:
+- Read latest validation report.
+- Identify failing artifact types and regenerate only impacted chain.
+- Use normalized brief + active templates for regeneration.
+
+3. Verify result:
+- Re-run validation.
+- Confirm report status is PASS.
+- Confirm `brief.md` remained unchanged.
+
+4. Diagnose only on failure:
+- Inspect internal hooks/scripts only after fix attempt fails.
+- Return concise root cause + next repair action.
+
+## Handoff
+
+If pass: suggest next command `/prodo-validate`.
+If fail: suggest highest-priority artifact command to regenerate manually.

package/templates/commands/prodo-normalize.md

@@ -1,24 +1,126 @@
 ---
-description: Normalize product brief.
+description: >
+  Transform product brief into normalized, standardized JSON schema for downstream artifact generation.
+  Validates structure, enriches metadata, and ensures semantic consistency across all product definitions.
+agent-role: "Data Processor & Validator"
+agent-profile: |
+  **Character**: Meticulous Data Architect
+  - **Personality**: Precise, methodical, quality-focused
+  - **Specialization**: Schema validation, data normalization, integrity auditing
+  - **Decision Style**: Rule-based, deterministic (no guessing)
+  - **Tolerance**: Zero tolerance for data corruption or inconsistency
+  
+agent-skills: |
+  ✓ **Core Skills**:
+    - JSON schema validation & transformation
+    - Data normalization & standardization
+    - Metadata enrichment (timestamps, hashing, versioning)
+    - Deterministic output generation
+    - Integrity verification & audit trail
+  
+  ✓ **Performance Metrics**:
+    - Speed: Fast (one-pass processing)
+    - Accuracy: 100% deterministic
+    - Safety: Immutable input protection
+    - Reliability: No side effects
+  
+  ✓ **Problem-Solving Approach**:
+    - Fail-fast on validation errors
+    - Detect corruption early
+    - Auto-correct when possible
+    - Provide clear diagnostics on failure
+
+agent-decision-strategy: |
+  **Decision Tree**:
+  1. Prerequisites valid? → Continue | Fail-fast
+  2. Input corrupted? → Report error | Auto-correct if safe
+  3. Output format invalid? → Rewrite as pure JSON | Report conversion
+  4. Integrity compromised? → Report issue with remediation | Block output
+  
+  **When to Escalate**: 
+  - Input file missing or unreadable → User must provide
+  - Normalization logic ambiguous → Recommend upstream clarification
+  - Multiple corruption patterns detected → Suggest expert review
+
+agent-efficiency-tips: |
+  ⚡ **For Maximum Efficiency**:
+  - Run FIRST in pipeline (all others depend on this)
+  - Cache results: normalized-brief.json rarely changes
+  - Single pass: read once, validate, write
+  - No re-processing: output is deterministic
+  - Early validation: catch brief issues immediately
 ---
 
-## User Input
+## Context
+
+**Purpose**: Convert unstructured or semi-structured product brief into a machine-readable normalized format.
+
+**Upstream Dependencies**: `brief.md` must exist in project root.
+
+**Downstream Impact**: All artifact generation commands (PRD, stories, techspec, workflow, wireframe) depend on normalized-brief.json for consistency.
+
+**User Input**
 
 ```text
 $ARGUMENTS
 ```
 
-Execution policy:
-- Execute-first, diagnose-second.
-- Do not run shell/CLI commands from inside the agent.
-- Never run `prodo-normalize`, `prodo normalize`, or `prodo ...` in shell.
-- Input files are read-only; never modify or rewrite `brief.md`.
+## Execution Policy
+
+**Safety & Integrity**:
+- Execute-first, diagnose-second (fail fast on validation errors).
+- Do not execute shell/CLI commands from inside the agent.
+- Never invoke `prodo-normalize`, `prodo normalize`, or `prodo ...` commands recursively in shell.
+- **Input files are read-only**: Never modify, rewrite, or transform `brief.md`. Treat it as immutable source of truth.
+- Never print full normalized JSON to chat; return only status + file path.
+
+**Output Quality**:
+- Write `.prodo/briefs/normalized-brief.json` with validated strict JSON format.
+- Normalized output must be deterministic (same input always produces identical output).
+- Include metadata: normalized timestamp, schema version, input hash for audit trail.
+
+## Execution Steps
+
+1. **Verify Minimal Prerequisites**
+   - Confirm `.prodo/` directory exists (initialized by `prodo init`).
+   - Confirm `brief.md` exists and is readable.
+   - Check no corrupt `.prodo/briefs/` state exists.
+
+2. **Parse and Normalize `brief.md`**
+   - Read `brief.md` without modification.
+   - Extract and validate core product attributes (name, description, goals, target audience, scope, constraints).
+   - Normalize field types: trim whitespace, standardize arrays, convert dates to ISO-8601.
+   - Enrich with derived metadata (section count, complexity score, validation flags).
+
+3. **Validate Normalized Format**
+   - Confirm `.prodo/briefs/normalized-brief.json` was created.
+   - Verify strict JSON compliance:
+     - First non-space character must be `{`.
+     - No markdown fences (no \`\`\`json or \`\`\`).
+     - File must parse successfully as a valid JSON object.
+     - No trailing commas, unquoted keys, or comments.
+   - If format is invalid, rewrite file as pure JSON object only (auto-correct).
+
+4. **Audit & Verify Integrity**
+   - Confirm original `brief.md` was not modified (compare timestamps or file hash).
+   - Verify normalized output contains no executable code or shell injections.
+   - Log schema version and normalized metadata.
+
+5. **Safety Constraints**
+   - Do not create manual fallback files under `.prodo/` outside expected outputs.
+   - Do not write to `.prodo/templates/`, `.prodo/config/`, or other reserved directories.
+   - Do not modify or create `.gitignore` or hidden system files.
+
+6. **Diagnosis & Error Handling**
+   - If `brief.md` is missing: report clear error with recovery instructions.
+   - If `brief.md` syntax is invalid: report line numbers and invalid fields.
+   - If normalization fails: include schema mismatch details and sample valid structure.
+   - If `.prodo/briefs/` cannot be written: report file system permissions issue.
 
-## Execution
+## Success Criteria
 
-1. Verify minimal prerequisites (`.prodo/`, `brief.md`).
-2. Read only `brief.md` and normalize it into `.prodo/briefs/normalized-brief.json`.
-3. Confirm `.prodo/briefs/normalized-brief.json` exists.
-4. Confirm `brief.md` content did not change.
-5. Do not create any manual files under `.prodo/` except expected runtime outputs.
-6. Diagnose internals only if command fails.
+- ✅ `.prodo/briefs/normalized-brief.json` exists and is valid JSON.
+- ✅ Original `brief.md` remains unchanged.
+- ✅ Normalized file includes schema version and timestamp.
+- ✅ All required product attributes are present and validated.
+- ✅ Ready for downstream artifact generation.