@shahmarasy/prodo 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Bahman Shahmarasy
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,157 @@
+<div align="center">
+  <h1>Prodo</h1>
+  <h3><em>Product Artifact Toolkit</em></h3>
+</div>
+
+<p align="center">
+  <strong>Build consistent product documentation from a stable brief with a CLI-first workflow.</strong>
+</p>
+
+---
+
+## Table of Contents
+
+- [What is Prodo?](#what-is-prodo)
+- [Install](#install)
+- [Quick Start](#quick-start)
+- [Core Workflow](#core-workflow)
+- [Supported Agents](#supported-agents)
+- [CLI Reference](#cli-reference)
+- [Output Structure](#output-structure)
+- [Validation Model](#validation-model)
+- [Development](#development)
+- [License](#license)
+
+## What is Prodo?
+
+Prodo is a CLI-first toolkit for product-document pipelines.
+
+It helps teams move from a raw brief to structured artifacts such as:
+
+- PRD
+- Workflow (Markdown explanation + Mermaid)
+- Wireframe (Markdown explanation + HTML)
+- Stories
+- Tech Spec
+
+Prodo is designed to keep input stable, outputs deterministic, and cross-artifact consistency measurable.
+
+## Install
+
+```bash
+npm i -g @shahmarasy/prodo
+```
+
+## Quick Start
+
+```bash
+# 1) Initialize in your project
+prodo init . --ai codex --lang tr
+
+# 2) Edit brief
+# brief.md
+
+# 3) Check environment (optional)
+prodo doctor
+```
+
+## Core Workflow
+
+After initialization, Prodo installs agent-native command files.
+
+Recommended flow inside your AI agent:
+
+1. Normalize the brief
+2. Produce artifacts in sequence
+3. Validate consistency
+
+Prodo keeps:
+
+- `brief.md` as input
+- `.prodo/` as internal runtime state
+- `product-docs/` as user-facing outputs
+
+## Supported Agents
+
+`prodo init --ai <name>` supports:
+
+- `codex`
+- `gemini-cli`
+- `claude-cli`
+
+Agent command files are installed to native locations:
+
+- Codex: `.agents/skills/`
+- Gemini CLI: `.gemini/commands/`
+- Claude CLI: `.claude/commands/`
+
+## Agent Commands
+
+Prodo agent command set:
+
+- `/prodo-normalize`
+- `/prodo-prd`
+- `/prodo-workflow`
+- `/prodo-wireframe`
+- `/prodo-stories`
+- `/prodo-techspec`
+- `/prodo-validate`
+
+Codex skills mode equivalents:
+
+- `$prodo-normalize`
+- `$prodo-prd`
+- `$prodo-workflow`
+- `$prodo-wireframe`
+- `$prodo-stories`
+- `$prodo-techspec`
+- `$prodo-validate`
+
+## CLI Reference
+
+Primary commands:
+
+- `prodo init [target] [--ai <name>] [--lang <code>] [--preset <name>]`
+- `prodo doctor` (alias: `prodo check`)
+
+Version:
+
+- `prodo --version`
+- `prodo -v`
+
+## Output Structure
+
+Project-level:
+
+- `brief.md` (input, read-only during execution)
+- `product-docs/` (all generated product documents)
+- `.prodo/` (internal runtime state: prompts, schemas, templates, index, context)
+
+Paired artifact behavior:
+
+- Workflow: `*.md` + `*.mmd`
+- Wireframe: `*.md` + `*.html`
+
+## Validation Model
+
+Validation reports include gate-based checks:
+
+- Schema pass
+- Tag coverage pass
+- Contract relevance pass
+- Semantic consistency pass
+
+All applicable gates must pass for final success.
+
+## Development
+
+```bash
+npm install
+npm run build
+npm test
+npm run verify:release
+```
+
+## License
+
+MIT

package/bin/prodo.cjs

@@ -0,0 +1,6 @@
+#!/usr/bin/env node
+"use strict";
+require("../dist/cli").runCli().then((code) => {
+  process.exitCode = code;
+});
+

package/dist/agent-command-installer.d.ts

@@ -0,0 +1,4 @@
+export declare const AI_ALIASES: Record<string, "codex" | "gemini-cli" | "claude-cli">;
+export type SupportedAi = "codex" | "gemini-cli" | "claude-cli";
+export declare function resolveAi(ai?: string): SupportedAi | undefined;
+export declare function installAgentCommands(projectRoot: string, ai: SupportedAi): Promise<string[]>;

package/dist/agent-command-installer.js

@@ -0,0 +1,158 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.AI_ALIASES = void 0;
+exports.resolveAi = resolveAi;
+exports.installAgentCommands = installAgentCommands;
+const promises_1 = __importDefault(require("node:fs/promises"));
+const node_path_1 = __importDefault(require("node:path"));
+const js_yaml_1 = __importDefault(require("js-yaml"));
+const errors_1 = require("./errors");
+const utils_1 = require("./utils");
+exports.AI_ALIASES = {
+    codex: "codex",
+    gemini: "gemini-cli",
+    "gemmini-cli": "gemini-cli",
+    "gemmini": "gemini-cli",
+    "gemini-cli": "gemini-cli",
+    claude: "claude-cli",
+    "claude-cli": "claude-cli"
+};
+const AGENT_CONFIG = {
+    "claude-cli": {
+        baseDir: ".claude/commands",
+        format: "markdown",
+        extension: ".md",
+        argsPlaceholder: "$ARGUMENTS"
+    },
+    "gemini-cli": {
+        baseDir: ".gemini/commands",
+        format: "toml",
+        extension: ".toml",
+        argsPlaceholder: "{{args}}"
+    },
+    codex: {
+        baseDir: ".agents/skills",
+        format: "skill",
+        extension: "/SKILL.md",
+        argsPlaceholder: "$ARGUMENTS"
+    }
+};
+function parseFrontmatter(content) {
+    if (!content.startsWith("---"))
+        return { frontmatter: {}, body: content };
+    const end = content.indexOf("\n---", 4);
+    if (end === -1)
+        return { frontmatter: {}, body: content };
+    const fmRaw = content.slice(3, end).trim();
+    const body = content.slice(end + 4).trimStart();
+    const frontmatter = js_yaml_1.default.load(fmRaw) ?? {};
+    return { frontmatter, body };
+}
+function renderFrontmatter(frontmatter) {
+    if (Object.keys(frontmatter).length === 0)
+        return "";
+    return `---\n${js_yaml_1.default.dump(frontmatter)}---\n`;
+}
+function resolveScriptBlock(frontmatter, argsPlaceholder) {
+    const run = frontmatter.run;
+    const runAction = typeof run?.action === "string" ? run.action.trim() : "";
+    const runMode = typeof run?.mode === "string" ? run.mode.trim() : "";
+    if (runAction) {
+        const modeSuffix = runMode ? ` (${runMode})` : "";
+        return `- Internal action: ${runAction}${modeSuffix}`;
+    }
+    const runCommand = typeof run?.command === "string" ? run.command.replace("{ARGS}", argsPlaceholder) : "";
+    if (runCommand) {
+        return `- Command: ${runCommand}`;
+    }
+    const scripts = frontmatter.scripts;
+    const sh = typeof scripts?.sh === "string" ? scripts.sh.replace("{ARGS}", argsPlaceholder) : "";
+    const ps = typeof scripts?.ps === "string" ? scripts.ps.replace("{ARGS}", argsPlaceholder) : "";
+    return [`- Bash: ${sh}`, `- PowerShell: ${ps}`].filter((line) => line.length > 8).join("\n");
+}
+function toTomlPrompt(body, frontmatter, argsPlaceholder) {
+    const description = String(frontmatter.description ?? "Prodo command");
+    const scriptsBlock = resolveScriptBlock(frontmatter, argsPlaceholder);
+    const promptBody = body.replaceAll("$ARGUMENTS", argsPlaceholder);
+    return `description = "${description.replace(/"/g, '\\"')}"
+
+prompt = """
+${promptBody}
+
+Script options:
+${scriptsBlock}
+"""`;
+}
+function toSkill(name, body, frontmatter) {
+    const description = String(frontmatter.description ?? "Prodo workflow command");
+    return `---
+name: ${name}
+description: ${description}
+compatibility: Requires Prodo project scaffold (.prodo)
+metadata:
+  author: prodo
+  source: .prodo/commands/${name}.md
+---
+
+${body}`;
+}
+function resolveAi(ai) {
+    if (!ai)
+        return undefined;
+    const normalized = exports.AI_ALIASES[ai.trim().toLowerCase()];
+    if (!normalized) {
+        throw new errors_1.UserError("Unsupported --ai value. Use: codex | gemini-cli | claude-cli");
+    }
+    return normalized;
+}
+async function loadCommandTemplateNames(commandTemplatesDir) {
+    if (!(await (0, utils_1.fileExists)(commandTemplatesDir))) {
+        throw new errors_1.UserError(`Missing command templates directory: ${commandTemplatesDir}`);
+    }
+    const entries = await promises_1.default.readdir(commandTemplatesDir, { withFileTypes: true });
+    return entries
+        .filter((entry) => entry.isFile())
+        .map((entry) => entry.name)
+        .filter((name) => name.endsWith(".md") && name.startsWith("prodo-"))
+        .map((name) => name.replace(/\.md$/, ""))
+        .sort();
+}
+async function installAgentCommands(projectRoot, ai) {
+    const cfg = AGENT_CONFIG[ai];
+    const target = node_path_1.default.join(projectRoot, cfg.baseDir);
+    const commandTemplatesDir = node_path_1.default.join(projectRoot, ".prodo", "commands");
+    const commandNames = await loadCommandTemplateNames(commandTemplatesDir);
+    await (0, utils_1.ensureDir)(target);
+    const written = [];
+    for (const commandName of commandNames) {
+        const templatePath = node_path_1.default.join(commandTemplatesDir, `${commandName}.md`);
+        if (!(await (0, utils_1.fileExists)(templatePath))) {
+            throw new errors_1.UserError(`Missing command template: ${templatePath}`);
+        }
+        const raw = await promises_1.default.readFile(templatePath, "utf8");
+        const parsed = parseFrontmatter(raw);
+        if (cfg.format === "skill") {
+            const skillDir = node_path_1.default.join(target, commandName);
+            await (0, utils_1.ensureDir)(skillDir);
+            const outPath = node_path_1.default.join(skillDir, "SKILL.md");
+            const content = toSkill(commandName, parsed.body.replaceAll("$ARGUMENTS", cfg.argsPlaceholder), parsed.frontmatter);
+            await promises_1.default.writeFile(outPath, content, "utf8");
+            written.push(outPath);
+            continue;
+        }
+        if (cfg.format === "toml") {
+            const outPath = node_path_1.default.join(target, `${commandName}${cfg.extension}`);
+            await promises_1.default.writeFile(outPath, toTomlPrompt(parsed.body, parsed.frontmatter, cfg.argsPlaceholder), "utf8");
+            written.push(outPath);
+            continue;
+        }
+        const outPath = node_path_1.default.join(target, `${commandName}${cfg.extension}`);
+        const replacedBody = parsed.body.replaceAll("$ARGUMENTS", cfg.argsPlaceholder);
+        await promises_1.default.writeFile(outPath, `${renderFrontmatter(parsed.frontmatter)}\n${replacedBody}`, "utf8");
+        written.push(outPath);
+    }
+    return written;
+}

package/dist/agents.d.ts

@@ -0,0 +1,15 @@
+export declare const AGENT_IDS: readonly ["codex", "gemini-cli", "claude-cli"];
+export type AgentId = (typeof AGENT_IDS)[number];
+export declare function isSupportedAgent(agent?: string): agent is AgentId;
+export declare function resolveAgent(agent?: string): AgentId | undefined;
+export type CommandSetItem = {
+    command: string;
+    purpose: string;
+};
+export type AgentCommandSet = {
+    agent: string;
+    description?: string;
+    recommended_sequence?: CommandSetItem[];
+    artifact_shortcuts?: Record<string, string>;
+};
+export declare function loadAgentCommandSet(_cwd: string, agent: AgentId): Promise<AgentCommandSet>;

package/dist/agents.js

@@ -0,0 +1,47 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.AGENT_IDS = void 0;
+exports.isSupportedAgent = isSupportedAgent;
+exports.resolveAgent = resolveAgent;
+exports.loadAgentCommandSet = loadAgentCommandSet;
+const errors_1 = require("./errors");
+exports.AGENT_IDS = ["codex", "gemini-cli", "claude-cli"];
+function isSupportedAgent(agent) {
+    if (!agent)
+        return false;
+    return exports.AGENT_IDS.includes(agent);
+}
+function resolveAgent(agent) {
+    if (!agent)
+        return undefined;
+    if (!isSupportedAgent(agent)) {
+        throw new errors_1.UserError(`Unsupported agent: ${agent}. Supported: ${exports.AGENT_IDS.join(", ")}`);
+    }
+    return agent;
+}
+async function loadAgentCommandSet(_cwd, agent) {
+    const prefix = `prodo-${agent}`;
+    return {
+        agent,
+        description: "Agent-specific command set for Prodo artifact pipeline.",
+        recommended_sequence: [
+            { command: "prodo init . --ai <agent> --lang <en|tr>", purpose: "Initialize Prodo scaffold and agent commands." },
+            { command: `${prefix} normalize`, purpose: "Normalize start brief into normalized brief JSON." },
+            { command: `${prefix} prd`, purpose: "Generate PRD artifact." },
+            { command: `${prefix} workflow`, purpose: "Generate workflow artifact." },
+            { command: `${prefix} wireframe`, purpose: "Generate wireframe artifact." },
+            { command: `${prefix} stories`, purpose: "Generate stories artifact." },
+            { command: `${prefix} techspec`, purpose: "Generate techspec artifact." },
+            { command: `${prefix} validate`, purpose: "Run validation report." }
+        ],
+        artifact_shortcuts: {
+            normalize: `${prefix} normalize`,
+            prd: `${prefix} prd`,
+            workflow: `${prefix} workflow`,
+            wireframe: `${prefix} wireframe`,
+            stories: `${prefix} stories`,
+            techspec: `${prefix} techspec`,
+            validate: `${prefix} validate`
+        }
+    };
+}

package/dist/artifact-registry.d.ts

@@ -0,0 +1,11 @@
+import type { ArtifactType, ContractCoverage } from "./types";
+export type ArtifactDefinition = {
+    name: ArtifactType;
+    output_dir: string;
+    required_headings: string[];
+    upstream: ArtifactType[];
+    required_contracts: Array<keyof ContractCoverage>;
+};
+export declare function listArtifactDefinitions(cwd: string): Promise<ArtifactDefinition[]>;
+export declare function listArtifactTypes(cwd: string): Promise<ArtifactType[]>;
+export declare function getArtifactDefinition(cwd: string, artifactType: string): Promise<ArtifactDefinition>;

package/dist/artifact-registry.js

@@ -0,0 +1,49 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.listArtifactDefinitions = listArtifactDefinitions;
+exports.listArtifactTypes = listArtifactTypes;
+exports.getArtifactDefinition = getArtifactDefinition;
+const constants_1 = require("./constants");
+const project_config_1 = require("./project-config");
+const types_1 = require("./types");
+function normalizeName(name) {
+    return name.trim().toLowerCase().replace(/[^a-z0-9_-]/g, "-");
+}
+function toDefinition(partial) {
+    const name = normalizeName(partial.name);
+    const outputDir = partial.output_dir?.trim() || (0, constants_1.defaultOutputDir)(name);
+    const requiredHeadings = partial.required_headings?.length ? partial.required_headings : (0, constants_1.defaultRequiredHeadings)(name);
+    const upstream = (partial.upstream?.length ? partial.upstream : (0, constants_1.defaultUpstreamByArtifact)(name)).map(normalizeName);
+    const requiredContracts = partial.required_contracts?.length
+        ? partial.required_contracts
+        : (0, constants_1.defaultRequiredContractsByArtifact)(name);
+    return {
+        name,
+        output_dir: outputDir,
+        required_headings: requiredHeadings,
+        upstream,
+        required_contracts: requiredContracts
+    };
+}
+async function listArtifactDefinitions(cwd) {
+    const config = await (0, project_config_1.readProjectConfig)(cwd);
+    const base = types_1.ARTIFACT_TYPES.map((name) => toDefinition({ name }));
+    const byName = new Map(base.map((item) => [item.name, item]));
+    for (const extra of config.artifacts ?? []) {
+        const merged = toDefinition(extra);
+        byName.set(merged.name, merged);
+    }
+    return Array.from(byName.values());
+}
+async function listArtifactTypes(cwd) {
+    const defs = await listArtifactDefinitions(cwd);
+    return defs.map((item) => item.name);
+}
+async function getArtifactDefinition(cwd, artifactType) {
+    const normalized = normalizeName(artifactType);
+    const defs = await listArtifactDefinitions(cwd);
+    const found = defs.find((item) => item.name === normalized);
+    if (found)
+        return found;
+    return toDefinition({ name: normalized });
+}

package/dist/artifacts.d.ts

@@ -0,0 +1,9 @@
+import type { ArtifactType } from "./types";
+export type GenerateOptions = {
+    artifactType: ArtifactType;
+    cwd: string;
+    normalizedBriefOverride?: string;
+    outPath?: string;
+    agent?: string;
+};
+export declare function generateArtifact(options: GenerateOptions): Promise<string>;