prdforge-cli 0.1.0

package/.env.example

@@ -0,0 +1,9 @@
+# PRDForge CLI — Environment Variables
+# Copy to .env and fill in your values.
+# Alternatively, run 'prdforge auth login' to store your key interactively.
+
+# Your PRDForge API key (get this from Dashboard → Settings → API Keys)
+PRDFORGE_API_KEY=
+
+# Override the default API base URL (optional — only for self-hosted or staging)
+# PRDFORGE_API_URL=https://jnlkzcmeiksqljnbtfhb.supabase.co/functions/v1

package/README.md

@@ -0,0 +1,129 @@
+# PRDForge CLI
+
+The official command-line interface for [PRDForge](https://prdforge.dev) — generate, manage, and export AI-powered Product Requirements Documents from your terminal, CI pipeline, or AI agents.
+
+**PRDForge** turns a product idea into a full blueprint in minutes: structured PRD, architecture, guardrails, and task breakdowns—ready for Cursor, Claude Code, Lovable, or any tool that speaks MCP. This CLI gives you the same power from the command line.
+
+**[→ prdforge.dev](https://prdforge.dev)** · [Web app](https://prdforge.dev) (dashboard, API keys, export)
+
+---
+
+## Installation
+
+```bash
+npm install -g prdforge-cli
+# or run directly
+npx prdforge-cli
+```
+
+## Quick Start
+
+```bash
+# 1. Authenticate with your API key
+prdforge auth login
+
+# 2. Create a new PRD from a prompt
+prdforge prd create --name "My App" --prompt "A task manager for remote teams"
+
+# 3. Export to Markdown for Claude Code / Cursor
+prdforge export <projectId> --format markdown
+```
+
+## Authentication
+
+Get your API key from the PRDForge dashboard: **Dashboard → Settings → API Keys**
+
+Requires an active **Pro** or **Starter** subscription.
+
+```bash
+prdforge auth login          # Set your API key interactively
+prdforge auth status         # Check authentication status
+prdforge auth logout         # Remove stored key
+```
+
+You can also set `PRDFORGE_API_KEY` as an environment variable (useful for CI/CD and agents).
+
+## Commands
+
+### `prdforge prd`
+
+```bash
+prdforge prd list                          # List all projects
+prdforge prd get <id>                      # Show all PRD sections
+prdforge prd get <id> --section feature_list  # Show a specific section
+prdforge prd create --name "App" --prompt "..."  # Generate a new PRD
+prdforge prd update <id> --prompt "..."    # Smart-merge an update
+prdforge prd refresh <id>                  # Regenerate stale stages
+```
+
+### `prdforge export`
+
+```bash
+prdforge export <id>                       # Export as Markdown (default)
+prdforge export <id> --format json         # Export as JSON
+prdforge export <id> --output ./CLAUDE.md  # Custom output path
+prdforge export <id> --stdout              # Print to stdout (pipe to files/agents)
+```
+
+### `prdforge watch`
+
+```bash
+prdforge watch <projectId>                 # Poll project and re-export PRD.md when it changes
+prdforge watch <id> -o ./PRD.md -i 60      # Custom output path and 60s interval
+```
+
+### `prdforge mcp`
+
+```bash
+prdforge mcp serve                         # Run MCP server on stdio (for Cursor / MCP clients)
+```
+
+Exposes tools: `prdforge_list_projects`, `prdforge_get_prd`, `prdforge_get_sections`.
+
+### `prdforge bulk`
+
+```bash
+prdforge bulk ideas.csv                    # Generate PRDs from CSV (name, prompt columns)
+prdforge bulk ideas.json --dry-run        # JSON array of { name, prompt }; --dry-run to preview
+prdforge bulk ideas.csv --delay 5000      # Delay between each generation (ms)
+```
+
+### `prdforge config`
+
+```bash
+prdforge config list                       # Show all config values
+prdforge config set outputDir ./exports    # Change export directory
+prdforge config set defaultFormat json     # Change default export format
+prdforge config get outputDir
+```
+
+## Agent / MCP Usage
+
+The CLI is designed to work with AI agents and automation workflows:
+
+```bash
+# Example: Agent generates a PRD, pipes markdown to Claude Code
+prdforge prd create --name "Scheduler" --prompt "$PROMPT" --json | \
+  jq -r '.project.id' | \
+  xargs -I{} prdforge export {} --stdout > CLAUDE.md
+
+# Example: Bulk PRD generation from a list of ideas
+cat ideas.txt | while read idea; do
+  prdforge prd create --name "$(echo $idea | cut -c1-30)" --prompt "$idea"
+done
+```
+
+## Environment Variables
+
+| Variable | Description |
+|----------|-------------|
+| `PRDFORGE_API_KEY` | Your API key (overrides stored key) |
+| `PRDFORGE_API_URL` | Custom API base URL (for self-hosted) |
+
+## Sync with Main App
+
+See [`SYNC.md`](./SYNC.md) for notes on how this CLI stays in sync with the PRDForge web app and API.
+
+## License
+
+MIT

package/bin/prdforge

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+import "../src/index.js";

package/package.json

@@ -0,0 +1,57 @@
+{
+  "name": "prdforge-cli",
+  "version": "0.1.0",
+  "description": "Official CLI for PRDForge — generate and manage PRDs from your terminal or AI agents",
+  "main": "src/index.js",
+  "bin": {
+    "prdforge": "bin/prdforge"
+  },
+  "type": "module",
+  "scripts": {
+    "start": "node src/index.js",
+    "dev": "node --watch src/index.js",
+    "test": "node --test src/**/*.test.js",
+    "link": "npm link"
+  },
+  "keywords": [
+    "prdforge",
+    "prd",
+    "product",
+    "requirements",
+    "ai",
+    "cli",
+    "agent",
+    "mcp"
+  ],
+  "license": "MIT",
+  "engines": {
+    "node": ">=18.0.0"
+  },
+  "files": [
+    "bin",
+    "src",
+    "README.md",
+    ".env.example"
+  ],
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.27.1",
+    "chalk": "^5.3.0",
+    "cli-table3": "^0.6.5",
+    "commander": "^12.1.0",
+    "conf": "^13.0.0",
+    "dotenv": "^16.4.5",
+    "ink": "^5.2.1",
+    "ink-spinner": "^5.0.0",
+    "ink-text-input": "^6.0.0",
+    "inquirer": "^10.2.2",
+    "marked": "^14.1.2",
+    "marked-terminal": "^7.1.0",
+    "node-fetch": "^3.3.2",
+    "ora": "^8.1.1",
+    "react": "^18.3.1"
+  },
+  "devDependencies": {
+    "@types/node": "^22.0.0",
+    "@types/react": "^18.3.0"
+  }
+}

package/src/api/client.js

@@ -0,0 +1,164 @@
+import { getApiUrl, requireApiKey } from "../utils/config.js";
+
+/** User-facing messages for HTTP status codes (centralized for CLI and agents). */
+function messageForStatus(status, bodyMessage) {
+  if (bodyMessage && typeof bodyMessage === "string") return bodyMessage;
+  switch (status) {
+    case 401:
+      return "Invalid or expired API key. Run `prdforge auth login` or check your key at https://prdforge.app (Settings → CLI Keys).";
+    case 402:
+      return "Credits exhausted. Upgrade your plan or wait until next month. See https://prdforge.app/subscription";
+    case 403:
+      return "Access denied. This action requires a paid plan (Starter or Pro).";
+    case 404:
+      return "Project or resource not found.";
+    case 429:
+      return "Rate limit exceeded. Try again in a moment.";
+    default:
+      if (status >= 500) return "PRDForge service error. Try again later.";
+      return `Request failed (HTTP ${status}).`;
+  }
+}
+
+/**
+ * Make an authenticated request to the PRDForge API (Supabase Edge Functions).
+ * Throws an Error with user-facing message and .httpStatus for exit code handling.
+ */
+async function request(path, { method = "GET", body } = {}) {
+  const apiKey = requireApiKey();
+  const baseUrl = getApiUrl();
+  const url = `${baseUrl}${path}`;
+
+  const headers = {
+    "Content-Type": "application/json",
+    "Authorization": `Bearer ${apiKey}`,
+    "x-prdforge-cli": "1",
+  };
+
+  let res;
+  try {
+    res = await fetch(url, {
+      method,
+      headers,
+      body: body ? JSON.stringify(body) : undefined,
+    });
+  } catch (e) {
+    const err = new Error("Could not reach PRDForge. Check your connection and API URL.");
+    err.httpStatus = 0;
+    throw err;
+  }
+
+  if (!res.ok) {
+    let bodyMessage;
+    try {
+      const errJson = await res.json();
+      bodyMessage = errJson.error || errJson.message;
+    } catch {
+      bodyMessage = null;
+    }
+    const err = new Error(messageForStatus(res.status, bodyMessage));
+    err.httpStatus = res.status;
+    throw err;
+  }
+
+  return res.json();
+}
+
+/** Use for exit code: 2 = auth error, 1 = other. */
+export function isAuthError(err) {
+  return err?.httpStatus === 401 || err?.httpStatus === 403;
+}
+
+// ─── Projects ────────────────────────────────────────────────────────────────
+
+export const projects = {
+  list: () => request("/prdforge-api/projects"),
+  get: (id) => request(`/prdforge-api/projects/${id}`),
+  create: (name, description) =>
+    request("/prdforge-api/projects", {
+      method: "POST",
+      body: { name, description },
+    }),
+  delete: (id) => request(`/prdforge-api/projects/${id}`, { method: "DELETE" }),
+};
+
+// ─── PRD Generation ───────────────────────────────────────────────────────────
+
+export const prd = {
+  generate: (projectId, prompt, modelId) =>
+    request("/prdforge-ai", {
+      method: "POST",
+      body: {
+        action: "generate_from_prompt",
+        payload: { project_id: projectId, prompt },
+        ...(modelId ? { model_id: modelId } : {}),
+      },
+    }),
+
+  update: (projectId, prompt, modelId) =>
+    request("/prdforge-ai", {
+      method: "POST",
+      body: {
+        action: "smart_update",
+        payload: { project_id: projectId, prompt },
+        ...(modelId ? { model_id: modelId } : {}),
+      },
+    }),
+
+  getSections: (projectId) => request(`/prdforge-api/projects/${projectId}/sections`),
+
+  regenerateStale: (projectId, modelId) =>
+    request("/prdforge-ai", {
+      method: "POST",
+      body: {
+        action: "regenerate_stale",
+        payload: { project_id: projectId },
+        ...(modelId ? { model_id: modelId } : {}),
+      },
+    }),
+};
+
+// ─── Export ───────────────────────────────────────────────────────────────────
+
+export const exports_ = {
+  export: (projectId, format) =>
+    request(`/prdforge-api/projects/${projectId}/export`, {
+      method: "POST",
+      body: { format },
+    }),
+};
+
+// ─── Auth ────────────────────────────────────────────────────────────────────
+
+export const auth = {
+  validate: (apiKey) =>
+    fetch(`${getApiUrl()}/prdforge-api/auth/validate`, {
+      headers: { Authorization: `Bearer ${apiKey}` },
+    }).then((r) => r.json()),
+};
+
+// ─── User ────────────────────────────────────────────────────────────────────
+
+export const user = {
+  validate: () => request("/prdforge-api/auth/validate"),
+};
+
+// ─── Models ──────────────────────────────────────────────────────────────────
+
+const FALLBACK_MODELS = [
+  { model_id: null,        name: "Default",   is_free_tier: true,  credit_cost: 4 },
+  { model_id: "standard",  name: "Standard",  is_free_tier: true,  credit_cost: 4 },
+  { model_id: "premium",   name: "Premium",   is_free_tier: false, credit_cost: 8 },
+  { model_id: "advanced",  name: "Advanced",  is_free_tier: false, credit_cost: 16 },
+];
+
+export const models = {
+  list: async () => {
+    try {
+      const data = await request("/prdforge-api/models");
+      return Array.isArray(data) && data.length > 0 ? data : FALLBACK_MODELS;
+    } catch {
+      return FALLBACK_MODELS;
+    }
+  },
+};

package/src/api/client.test.js

@@ -0,0 +1,34 @@
+import { describe, it } from "node:test";
+import assert from "node:assert";
+import { isAuthError } from "./client.js";
+
+describe("client", () => {
+  describe("isAuthError", () => {
+    it("returns true for 401", () => {
+      const err = new Error("Unauthorized");
+      err.httpStatus = 401;
+      assert.strictEqual(isAuthError(err), true);
+    });
+
+    it("returns true for 403", () => {
+      const err = new Error("Forbidden");
+      err.httpStatus = 403;
+      assert.strictEqual(isAuthError(err), true);
+    });
+
+    it("returns false for 404", () => {
+      const err = new Error("Not found");
+      err.httpStatus = 404;
+      assert.strictEqual(isAuthError(err), false);
+    });
+
+    it("returns false when httpStatus is missing", () => {
+      assert.strictEqual(isAuthError(new Error("Network")), false);
+    });
+
+    it("returns false for null/undefined", () => {
+      assert.strictEqual(isAuthError(null), false);
+      assert.strictEqual(isAuthError(undefined), false);
+    });
+  });
+});

package/src/commands/auth.js

@@ -0,0 +1,160 @@
+import { Command } from "commander";
+import { config, getApiKey, getEmail, setEmail, getAuthBase } from "../utils/config.js";
+import { success, error, info, dim, header } from "../utils/output.js";
+
+export function authCommand() {
+  const cmd = new Command("auth").description("Manage authentication and API keys");
+
+  cmd
+    .command("login")
+    .description("Authenticate with PRDForge (email OTP or API key)")
+    .option("-k, --key <key>", "Paste an API key directly (or set PRDFORGE_API_KEY env var)")
+    .action(async (opts) => {
+      const { default: inquirer } = await import("inquirer");
+
+      // If -k key was provided, skip the menu and save directly
+      if (opts.key) {
+        config.set("apiKey", opts.key);
+        success("API key saved. You are now authenticated.");
+        dim("  Key stored in: " + config.path);
+        info("Run 'prdforge prd list' to see your projects.");
+        return;
+      }
+
+      // Show auth method menu
+      const { method } = await inquirer.prompt([
+        {
+          type: "list",
+          name: "method",
+          message: "How do you want to authenticate?",
+          choices: [
+            { name: "Email + verification code (recommended)", value: "otp" },
+            { name: "Paste an API key directly", value: "key" },
+          ],
+        },
+      ]);
+
+      if (method === "key") {
+        const { apiKey } = await inquirer.prompt([
+          {
+            type: "password",
+            name: "apiKey",
+            message: "Enter your PRDForge API key:",
+            validate: (v) => v.length > 10 || "Key too short",
+          },
+        ]);
+        config.set("apiKey", apiKey);
+        success("API key saved. You are now authenticated.");
+        dim("  Key stored in: " + config.path);
+        info("Run 'prdforge prd list' to see your projects.");
+        return;
+      }
+
+      // OTP email flow
+      const { email } = await inquirer.prompt([
+        {
+          type: "input",
+          name: "email",
+          message: "Email address:",
+          validate: (v) => v.includes("@") || "Please enter a valid email",
+        },
+      ]);
+
+      const authBase = getAuthBase();
+      process.stdout.write("\n");
+      const { default: ora } = await import("ora");
+      const spinner = ora("Sending verification code…").start();
+
+      let sendRes;
+      try {
+        sendRes = await fetch(authBase, {
+          method: "POST",
+          headers: { "Content-Type": "application/json" },
+          body: JSON.stringify({ action: "request", email }),
+        });
+      } catch {
+        spinner.fail("Network error — could not reach PRDForge.");
+        process.exit(1);
+      }
+
+      const sendData = await sendRes.json().catch(() => ({}));
+      if (!sendRes.ok || !sendData.success) {
+        spinner.fail(sendData.error ?? "Failed to send verification code.");
+        process.exit(1);
+      }
+      spinner.succeed("Verification code sent — check your email.");
+
+      const { code } = await inquirer.prompt([
+        {
+          type: "input",
+          name: "code",
+          message: "Enter the 6-digit code:",
+          validate: (v) => /^\d{6}$/.test(v.trim()) || "Must be a 6-digit number",
+        },
+      ]);
+
+      const verSpinner = ora("Verifying code…").start();
+      let verRes;
+      try {
+        verRes = await fetch(authBase, {
+          method: "POST",
+          headers: { "Content-Type": "application/json" },
+          body: JSON.stringify({ action: "verify", email, code: code.trim() }),
+        });
+      } catch {
+        verSpinner.fail("Network error — could not reach PRDForge.");
+        process.exit(1);
+      }
+
+      const verData = await verRes.json().catch(() => ({}));
+      if (!verRes.ok || !verData.success) {
+        verSpinner.fail(verData.error ?? "Invalid or expired code.");
+        process.exit(1);
+      }
+
+      config.set("apiKey", verData.api_key);
+      setEmail(verData.email ?? email);
+      verSpinner.succeed(`Authenticated as ${verData.email ?? email}`);
+      dim(`  Key prefix: ${verData.key_prefix ?? "(unknown)"}`);
+      dim("  Config: " + config.path);
+      info("Run 'prdforge prd list' to see your projects.");
+    });
+
+  cmd
+    .command("logout")
+    .description("Remove stored API key")
+    .action(() => {
+      config.delete("apiKey");
+      success("Logged out — API key removed.");
+    });
+
+  cmd
+    .command("status")
+    .description("Show current authentication status")
+    .action(async () => {
+      header("Auth Status");
+      const key = getApiKey();
+      if (!key) {
+        error("Not authenticated");
+        info("Run 'prdforge auth login' to set your API key.");
+        info("Get your key at: https://prdforge.netlify.app/dashboard (Settings → API Keys)");
+        return;
+      }
+      success("Authenticated");
+      const email = getEmail();
+      if (email) dim(`  Email:  ${email}`);
+      dim(`  Key:    ${key.slice(0, 8)}${"*".repeat(Math.max(0, key.length - 8))}`);
+      dim(`  Config: ${config.path}`);
+      // Show live subscription/credits if possible
+      try {
+        const { user } = await import("../api/client.js");
+        const data = await user.validate();
+        dim(`  Plan:   ${data.subscription}`);
+        dim(`  Credits used: ${data.credits_used_this_month} this month`);
+      } catch {
+        // Non-fatal — key might work but network unavailable
+      }
+    });
+
+  return cmd;
+}

package/src/commands/bulk.js

@@ -0,0 +1,126 @@
+import { Command } from "commander";
+import { readFileSync } from "fs";
+import { projects, prd, isAuthError } from "../api/client.js";
+import { success, error, info, dim } from "../utils/output.js";
+
+function parseCSV(content) {
+  const lines = content.trim().split(/\r?\n/).filter(Boolean);
+  if (lines.length === 0) return [];
+  const header = lines[0].split(",").map((h) => h.trim().toLowerCase());
+  const nameIdx = header.indexOf("name");
+  const promptIdx = header.indexOf("prompt");
+  const descIdx = header.indexOf("description");
+  if (nameIdx === -1 || (promptIdx === -1 && descIdx === -1)) {
+    throw new Error("CSV must have columns: name, and prompt or description");
+  }
+  const promptCol = promptIdx >= 0 ? promptIdx : descIdx;
+  const rows = [];
+  for (let i = 1; i < lines.length; i++) {
+    const values = lines[i].split(",").map((v) => v.trim());
+    const name = values[nameIdx] ?? "";
+    const prompt = values[promptCol] ?? "";
+    if (name) rows.push({ name, prompt });
+  }
+  return rows;
+}
+
+function parseJSON(content) {
+  const data = JSON.parse(content);
+  const arr = Array.isArray(data) ? data : [data];
+  return arr.map((row) => {
+    const name = row.name ?? row.title ?? "";
+    const prompt = row.prompt ?? row.description ?? "";
+    return { name, prompt };
+  });
+}
+
+export function bulkCommand() {
+  const cmd = new Command("bulk")
+    .description("Generate many PRDs from a CSV or JSON file (one PRD per row/item)")
+    .argument("<file>", "Path to .csv or .json file")
+    .option("--delay <ms>", "Delay in ms between each PRD generation (default: 2000)", "2000")
+    .option("--dry-run", "Only parse the file and show what would be created")
+    .option("-m, --model <modelId>", "AI model ID to use for generation")
+    .action(async (file, opts) => {
+      const { default: ora } = await import("ora");
+      let raw;
+      try {
+        raw = readFileSync(file, "utf8");
+      } catch (e) {
+        error(`Cannot read file: ${file}`);
+        process.exit(1);
+      }
+
+      const ext = file.replace(/^.*\./, "").toLowerCase();
+      let rows;
+      try {
+        if (ext === "csv") {
+          rows = parseCSV(raw);
+        } else if (ext === "json") {
+          rows = parseJSON(raw);
+        } else {
+          error("File must be .csv or .json");
+          process.exit(1);
+        }
+      } catch (e) {
+        error(e.message);
+        process.exit(1);
+      }
+
+      if (rows.length === 0) {
+        info("No rows to process.");
+        return;
+      }
+
+      if (opts.dryRun) {
+        info(`Dry run: would create ${rows.length} PRD(s):`);
+        rows.forEach((r, i) => dim(`  ${i + 1}. ${r.name}: ${(r.prompt || "").slice(0, 50)}…`));
+        return;
+      }
+
+      const delayMs = Math.max(0, parseInt(opts.delay, 10) || 2000);
+      const results = [];
+      for (let i = 0; i < rows.length; i++) {
+        const { name, prompt } = rows[i];
+        const spinner = ora(`[${i + 1}/${rows.length}] Creating "${name}"…`).start();
+        try {
+          const project = await projects.create(name, prompt || "");
+          spinner.text = `[${i + 1}/${rows.length}] Generating PRD for "${name}"…`;
+          await prd.generate(project.id, prompt || "", opts.model);
+          spinner.succeed(`"${name}" created (${project.id.slice(0, 8)}…)`);
+          results.push({ name, id: project.id });
+        } catch (err) {
+          spinner.fail(`"${name}" failed`);
+          error(err.message);
+          if (isAuthError(err)) {
+            process.exit(2);
+          }
+          results.push({ name, error: err.message });
+        }
+        if (i < rows.length - 1 && delayMs > 0) {
+          await new Promise((r) => setTimeout(r, delayMs));
+        }
+      }
+
+      success(`Bulk run complete: ${results.filter((r) => !r.error).length} created, ${results.filter((r) => r.error).length} failed.`);
+    });
+
+  cmd.addHelpText(
+    "after",
+    `
+File formats:
+  CSV: header row with "name" and "prompt" (or "description"). Example:
+    name,prompt
+    My App,A task manager for remote teams
+    API,REST API for payments
+
+  JSON: array of objects with "name" and "prompt" (or "description"). Example:
+    [{"name":"My App","prompt":"A task manager"},{"name":"API","prompt":"REST API"}]
+
+Examples:
+  prdforge bulk ideas.csv
+  prdforge bulk ideas.json --delay 5000 --dry-run
+`
+  );
+  return cmd;
+}