@shahmarasy/prodo 0.1.0

package/dist/templates.js

@@ -0,0 +1,428 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.HOOKS_TEMPLATE = exports.NORMALIZE_PROMPT_TEMPLATE = exports.NORMALIZED_BRIEF_TEMPLATE = exports.START_BRIEF_TEMPLATE = void 0;
+exports.schemaTemplate = schemaTemplate;
+exports.promptTemplate = promptTemplate;
+exports.artifactTemplateTemplate = artifactTemplateTemplate;
+exports.commandTemplate = commandTemplate;
+const constants_1 = require("./constants");
+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
+};
+function schemaTemplate(artifactType) {
+    return {
+        ...BASE_SCHEMA,
+        properties: {
+            ...BASE_SCHEMA.properties,
+            frontmatter: {
+                ...BASE_SCHEMA.properties.frontmatter,
+                properties: {
+                    ...BASE_SCHEMA.properties.frontmatter
+                        .properties,
+                    artifact_type: { const: artifactType }
+                }
+            }
+        },
+        x_required_headings: (0, constants_1.defaultRequiredHeadings)(artifactType)
+    };
+}
+function promptTemplate(artifactType, lang = "en") {
+    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:
+${(0, constants_1.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"}`;
+}
+function artifactTemplateTemplate(artifactType, lang = "en") {
+    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;
+}
+exports.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
+`;
+exports.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" }]
+    }
+};
+exports.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`;
+function commandTemplate(command) {
+    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\`).`;
+}
+exports.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/dist/types.d.ts

@@ -0,0 +1,35 @@
+export declare const CORE_ARTIFACT_TYPES: readonly ["prd", "workflow", "wireframe", "stories", "techspec"];
+export declare const ARTIFACT_TYPES: readonly ["prd", "workflow", "wireframe", "stories", "techspec"];
+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/dist/types.js

@@ -0,0 +1,5 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ARTIFACT_TYPES = exports.CORE_ARTIFACT_TYPES = void 0;
+exports.CORE_ARTIFACT_TYPES = ["prd", "workflow", "wireframe", "stories", "techspec"];
+exports.ARTIFACT_TYPES = exports.CORE_ARTIFACT_TYPES;

package/dist/utils.d.ts

@@ -0,0 +1,6 @@
+export declare function ensureDir(dirPath: string): Promise<void>;
+export declare function fileExists(filePath: string): Promise<boolean>;
+export declare function readJsonFile<T>(filePath: string): Promise<T>;
+export declare function timestampSlug(date?: Date): string;
+export declare function listFilesSortedByMtime(dirPath: string): Promise<string[]>;
+export declare function isPathInside(parentDir: string, candidatePath: string): boolean;

package/dist/utils.js

@@ -0,0 +1,53 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ensureDir = ensureDir;
+exports.fileExists = fileExists;
+exports.readJsonFile = readJsonFile;
+exports.timestampSlug = timestampSlug;
+exports.listFilesSortedByMtime = listFilesSortedByMtime;
+exports.isPathInside = isPathInside;
+const promises_1 = __importDefault(require("node:fs/promises"));
+const node_path_1 = __importDefault(require("node:path"));
+async function ensureDir(dirPath) {
+    await promises_1.default.mkdir(dirPath, { recursive: true });
+}
+async function fileExists(filePath) {
+    try {
+        await promises_1.default.access(filePath);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+async function readJsonFile(filePath) {
+    const raw = await promises_1.default.readFile(filePath, "utf8");
+    return JSON.parse(raw);
+}
+function timestampSlug(date = new Date()) {
+    return date.toISOString().replace(/[:.]/g, "-");
+}
+async function listFilesSortedByMtime(dirPath) {
+    const exists = await fileExists(dirPath);
+    if (!exists)
+        return [];
+    const entries = await promises_1.default.readdir(dirPath);
+    const withStats = await Promise.all(entries.map(async (name) => {
+        const fullPath = node_path_1.default.join(dirPath, name);
+        const stat = await promises_1.default.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);
+}
+function isPathInside(parentDir, candidatePath) {
+    const parent = node_path_1.default.resolve(parentDir);
+    const child = node_path_1.default.resolve(candidatePath);
+    const relative = node_path_1.default.relative(parent, child);
+    return relative === "" || (!relative.startsWith("..") && !node_path_1.default.isAbsolute(relative));
+}

package/dist/validate.d.ts

@@ -0,0 +1,9 @@
+import type { ValidationIssue } from "./types";
+export declare function runValidate(cwd: string, options: {
+    strict?: boolean;
+    report?: string;
+}): Promise<{
+    pass: boolean;
+    reportPath: string;
+    issues: ValidationIssue[];
+}>;