prototype-prd-vite-plugin 0.1.0

package/examples/basic/package.json

@@ -0,0 +1,12 @@
+{
+  "name": "prototype-prd-vite-plugin-basic-example",
+  "private": true,
+  "type": "module",
+  "scripts": {
+    "dev": "vite"
+  },
+  "devDependencies": {
+    "prototype-prd-vite-plugin": "file:../..",
+    "vite": ">=5.0.0"
+  }
+}

package/examples/basic/src/main.js

@@ -0,0 +1 @@
+import "./style.css";

package/examples/basic/src/style.css

@@ -0,0 +1,45 @@
+body {
+  margin: 0;
+  min-height: 100vh;
+  background:
+    radial-gradient(circle at 20% 10%, rgba(219, 143, 62, 0.26), transparent 28%),
+    linear-gradient(135deg, #f7ead7, #dbe7dd);
+  color: #1f1c17;
+  display: grid;
+  place-items: center;
+  font-family: Georgia, "Times New Roman", serif;
+}
+
+.hero {
+  width: min(720px, calc(100vw - 40px));
+  background: rgba(255, 250, 240, 0.78);
+  border: 1px solid rgba(91, 65, 33, 0.18);
+  border-radius: 28px;
+  box-shadow: 0 30px 90px rgba(48, 35, 18, 0.18);
+  padding: 56px;
+}
+
+.eyebrow {
+  font-family: "Avenir Next", "Gill Sans", sans-serif;
+  font-size: 12px;
+  font-weight: 800;
+  letter-spacing: 0.16em;
+  text-transform: uppercase;
+}
+
+h1 {
+  font-size: clamp(42px, 8vw, 84px);
+  line-height: 0.92;
+  margin: 0;
+}
+
+button {
+  background: #1f1c17;
+  border: 0;
+  border-radius: 999px;
+  color: #fff7e7;
+  cursor: pointer;
+  font-weight: 800;
+  margin-top: 24px;
+  padding: 14px 18px;
+}

package/examples/basic/vite.config.js

@@ -0,0 +1,10 @@
+import { defineConfig } from "vite";
+import prototypePrd from "prototype-prd-vite-plugin";
+
+export default defineConfig({
+  plugins: [
+    prototypePrd({
+      defaultTitle: "Checkout Flow PRD"
+    })
+  ]
+});

package/index.js

@@ -0,0 +1,83 @@
+import { readFile } from "node:fs/promises";
+import { fileURLToPath } from "node:url";
+import path from "node:path";
+
+import { normalizeOptions } from "./src/config.js";
+import { createPrototypePrdMiddleware } from "./src/middleware.js";
+
+const PACKAGE_ROOT = path.dirname(fileURLToPath(import.meta.url));
+const CLIENT_PREFIX = "/__prototype_prd__/client/";
+
+export default function prototypePrd(userOptions = {}) {
+  let resolvedConfig = {
+    command: "serve",
+    root: process.cwd()
+  };
+  let options = normalizeOptions(userOptions, "serve");
+
+  return {
+    name: "prototype-prd-vite-plugin",
+    apply: "serve",
+
+    configResolved(config) {
+      resolvedConfig = config;
+      options = normalizeOptions(userOptions, config.command);
+    },
+
+    configureServer(server) {
+      if (!options.enabled) {
+        return;
+      }
+
+      server.middlewares.use(createClientAssetMiddleware());
+      server.middlewares.use(
+        createPrototypePrdMiddleware({
+          root: resolvedConfig.root,
+          options
+        })
+      );
+    },
+
+    transformIndexHtml(html) {
+      if (!options.enabled) {
+        return html;
+      }
+
+      const script = `<script type="module" src="${CLIENT_PREFIX}overlay.js"></script>`;
+      return html.includes("</body>")
+        ? html.replace("</body>", `${script}</body>`)
+        : `${html}${script}`;
+    }
+  };
+}
+
+export { prototypePrd };
+
+function createClientAssetMiddleware() {
+  return async function clientAssetMiddleware(req, res, next) {
+    const url = new URL(req.url ?? "/", "http://localhost");
+
+    if (!url.pathname.startsWith(CLIENT_PREFIX)) {
+      next();
+      return;
+    }
+
+    const assetName = path.basename(url.pathname);
+    if (!["overlay.js", "overlay.css"].includes(assetName)) {
+      res.statusCode = 404;
+      res.end("Not found");
+      return;
+    }
+
+    const filePath = path.join(PACKAGE_ROOT, "client", assetName);
+    const content = await readFile(filePath, "utf8");
+
+    res.setHeader(
+      "content-type",
+      assetName.endsWith(".css")
+        ? "text/css; charset=utf-8"
+        : "text/javascript; charset=utf-8"
+    );
+    res.end(content);
+  };
+}

package/package.json

@@ -0,0 +1,50 @@
+{
+  "name": "prototype-prd-vite-plugin",
+  "version": "0.1.0",
+  "description": "Local-first PRD workbench overlay for Vite prototype projects.",
+  "type": "module",
+  "main": "./index.js",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/dzye/prototype-prd-vite-plugin.git"
+  },
+  "bugs": {
+    "url": "https://github.com/dzye/prototype-prd-vite-plugin/issues"
+  },
+  "homepage": "https://github.com/dzye/prototype-prd-vite-plugin#readme",
+  "exports": {
+    ".": "./index.js"
+  },
+  "files": [
+    "index.js",
+    "src",
+    "client",
+    "examples/basic/index.html",
+    "examples/basic/package.json",
+    "examples/basic/package-lock.json",
+    "examples/basic/src",
+    "examples/basic/vite.config.js",
+    "README.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "test": "node --test",
+    "pack:dry": "npm pack --dry-run"
+  },
+  "keywords": [
+    "vite",
+    "plugin",
+    "prd",
+    "prototype",
+    "markdown",
+    "openai"
+  ],
+  "author": "",
+  "license": "MIT",
+  "peerDependencies": {
+    "vite": ">=5.0.0"
+  },
+  "engines": {
+    "node": ">=18.18.0"
+  }
+}

package/src/config.js

@@ -0,0 +1,27 @@
+const DEFAULT_OPTIONS = {
+  draftDir: ".prototype-prd",
+  draftFile: "current.md",
+  exportDir: "docs/prd",
+  defaultTitle: "Product Requirements Document",
+  ai: {
+    enabled: true,
+    trigger: "manual",
+    model: "gpt-4.1-mini",
+    baseURL: "https://api.openai.com/v1"
+  }
+};
+
+export function normalizeOptions(userOptions = {}, command = "serve") {
+  const ai = {
+    ...DEFAULT_OPTIONS.ai,
+    ...(userOptions.ai ?? {}),
+    trigger: "manual"
+  };
+
+  return {
+    ...DEFAULT_OPTIONS,
+    ...userOptions,
+    enabled: userOptions.enabled ?? command === "serve",
+    ai
+  };
+}

package/src/files.js

@@ -0,0 +1,74 @@
+import { constants as fsConstants } from "node:fs";
+import { access, mkdir, readFile, writeFile } from "node:fs/promises";
+import path from "node:path";
+
+import { slugify } from "./paths.js";
+
+const STARTER_SECTIONS = [
+  "Background",
+  "Goals",
+  "Non-Goals",
+  "Users",
+  "User Stories",
+  "Functional Requirements",
+  "UX Notes",
+  "Data And State",
+  "Edge Cases",
+  "Acceptance Criteria"
+];
+
+export function getStarterMarkdown(title = "Product Requirements Document") {
+  const safeTitle = String(title || "Product Requirements Document").trim();
+  const sections = STARTER_SECTIONS.map((section) => `## ${section}\n`).join("\n");
+
+  return `# ${safeTitle}\n\n${sections}`;
+}
+
+export async function readDraft(storagePaths, title) {
+  try {
+    const markdown = await readFile(storagePaths.draftPath, "utf8");
+    return { exists: true, markdown, path: storagePaths.draftPath };
+  } catch (error) {
+    if (error?.code !== "ENOENT") {
+      throw error;
+    }
+
+    return {
+      exists: false,
+      markdown: getStarterMarkdown(title),
+      path: storagePaths.draftPath
+    };
+  }
+}
+
+export async function saveDraft(storagePaths, markdown) {
+  await mkdir(path.dirname(storagePaths.draftPath), { recursive: true });
+  await writeFile(storagePaths.draftPath, String(markdown ?? ""), "utf8");
+
+  return { path: storagePaths.draftPath };
+}
+
+export async function exportPrd(
+  storagePaths,
+  { markdown, title, date = new Date().toISOString().slice(0, 10), overwrite = false }
+) {
+  await mkdir(storagePaths.exportDirPath, { recursive: true });
+
+  const fileName = `${date}-${slugify(title)}.md`;
+  const targetPath = path.join(storagePaths.exportDirPath, fileName);
+
+  if (!overwrite) {
+    try {
+      await access(targetPath, fsConstants.F_OK);
+      throw new Error(`Export file "${fileName}" already exists.`);
+    } catch (error) {
+      if (error?.code !== "ENOENT") {
+        throw error;
+      }
+    }
+  }
+
+  await writeFile(targetPath, String(markdown ?? ""), "utf8");
+
+  return { fileName, path: targetPath };
+}

package/src/http.js

@@ -0,0 +1,25 @@
+export async function readJson(req) {
+  const chunks = [];
+
+  for await (const chunk of req) {
+    chunks.push(Buffer.from(chunk));
+  }
+
+  const raw = Buffer.concat(chunks).toString("utf8");
+  return raw ? JSON.parse(raw) : {};
+}
+
+export function sendJson(res, statusCode, payload) {
+  res.statusCode = statusCode;
+  res.setHeader("content-type", "application/json; charset=utf-8");
+  res.end(JSON.stringify(payload));
+}
+
+export function sendError(res, statusCode, code, message) {
+  sendJson(res, statusCode, {
+    error: {
+      code,
+      message
+    }
+  });
+}

package/src/middleware.js

@@ -0,0 +1,112 @@
+import { normalizeOptions } from "./config.js";
+import { exportPrd, readDraft, saveDraft } from "./files.js";
+import { readJson, sendError, sendJson } from "./http.js";
+import { generatePrdMarkdown } from "./openai.js";
+import { resolveStoragePaths } from "./paths.js";
+
+const PREFIX = "/__prototype_prd__";
+
+export function createPrototypePrdMiddleware({
+  root,
+  options = {},
+  env = process.env,
+  generate = generatePrdMarkdown
+}) {
+  const normalized = normalizeOptions(options, "serve");
+  const storagePaths = resolveStoragePaths(root, normalized);
+
+  return async function prototypePrdMiddleware(req, res, next) {
+    const url = new URL(req.url ?? "/", "http://localhost");
+
+    if (!url.pathname.startsWith(PREFIX)) {
+      next();
+      return;
+    }
+
+    try {
+      if (req.method === "GET" && url.pathname === `${PREFIX}/state`) {
+        sendJson(res, 200, {
+          title: normalized.defaultTitle,
+          draftPath: relativeForClient(storagePaths.root, storagePaths.draftPath),
+          exportDir: relativeForClient(storagePaths.root, storagePaths.exportDirPath),
+          ai: {
+            enabled: normalized.ai.enabled,
+            trigger: "manual",
+            configured: Boolean(env.OPENAI_API_KEY)
+          }
+        });
+        return;
+      }
+
+      if (req.method === "GET" && url.pathname === `${PREFIX}/draft`) {
+        sendJson(res, 200, await readDraft(storagePaths, normalized.defaultTitle));
+        return;
+      }
+
+      if (req.method === "PUT" && url.pathname === `${PREFIX}/draft`) {
+        const body = await readJson(req);
+        sendJson(res, 200, await saveDraft(storagePaths, body.markdown));
+        return;
+      }
+
+      if (req.method === "POST" && url.pathname === `${PREFIX}/export`) {
+        const body = await readJson(req);
+        sendJson(
+          res,
+          200,
+          await exportPrd(storagePaths, {
+            markdown: body.markdown,
+            title: body.title || normalized.defaultTitle,
+            date: body.date,
+            overwrite: Boolean(body.overwrite)
+          })
+        );
+        return;
+      }
+
+      if (req.method === "POST" && url.pathname === `${PREFIX}/ai/generate`) {
+        if (!normalized.ai.enabled) {
+          sendError(res, 400, "AI_DISABLED", "AI generation is disabled.");
+          return;
+        }
+
+        if (!env.OPENAI_API_KEY) {
+          sendError(
+            res,
+            400,
+            "OPENAI_API_KEY_MISSING",
+            "Set OPENAI_API_KEY in your local environment to use AI generation."
+          );
+          return;
+        }
+
+        const body = await readJson(req);
+        const markdown = await generate({
+          apiKey: env.OPENAI_API_KEY,
+          baseURL: normalized.ai.baseURL,
+          model: normalized.ai.model,
+          markdown: body.markdown,
+          instruction: body.instruction,
+          pageUrl: body.pageUrl,
+          notes: body.notes
+        });
+
+        sendJson(res, 200, { markdown });
+        return;
+      }
+
+      sendError(res, 404, "NOT_FOUND", "Prototype PRD endpoint not found.");
+    } catch (error) {
+      sendError(
+        res,
+        error?.message?.includes("already exists") ? 409 : 500,
+        "PROTOTYPE_PRD_ERROR",
+        error?.message || "Prototype PRD request failed."
+      );
+    }
+  };
+}
+
+function relativeForClient(root, targetPath) {
+  return targetPath.replace(`${root}/`, "");
+}

package/src/openai.js

@@ -0,0 +1,78 @@
+const INSTRUCTIONS = `You are a senior product manager helping write a concise product requirements document.
+Return only Markdown. Preserve useful existing sections and improve the PRD structure when needed.
+Use these sections when applicable: Background, Goals, Non-Goals, Users, User Stories, Functional Requirements, UX Notes, Data And State, Edge Cases, Acceptance Criteria.`;
+
+export async function generatePrdMarkdown({
+  apiKey,
+  baseURL = "https://api.openai.com/v1",
+  model = "gpt-4.1-mini",
+  markdown = "",
+  instruction = "",
+  pageUrl = "",
+  notes = "",
+  fetchImpl = globalThis.fetch
+}) {
+  if (!apiKey) {
+    throw new Error("OPENAI_API_KEY is required.");
+  }
+
+  if (typeof fetchImpl !== "function") {
+    throw new Error("A fetch implementation is required for AI generation.");
+  }
+
+  const response = await fetchImpl(`${baseURL.replace(/\/+$/, "")}/responses`, {
+    method: "POST",
+    headers: {
+      authorization: `Bearer ${apiKey}`,
+      "content-type": "application/json"
+    },
+    body: JSON.stringify({
+      model,
+      instructions: INSTRUCTIONS,
+      input: buildInput({ markdown, instruction, pageUrl, notes })
+    })
+  });
+
+  const payload = await response.json();
+
+  if (!response.ok) {
+    const message =
+      payload?.error?.message || `Request failed with status ${response.status}`;
+    throw new Error(`OpenAI API request failed: ${message}`);
+  }
+
+  const text = extractResponseText(payload);
+  if (!text) {
+    throw new Error("OpenAI API response did not contain generated text.");
+  }
+
+  return text;
+}
+
+export function extractResponseText(payload) {
+  if (typeof payload?.output_text === "string") {
+    return payload.output_text;
+  }
+
+  if (!Array.isArray(payload?.output)) {
+    return "";
+  }
+
+  return payload.output
+    .flatMap((item) => item?.content ?? [])
+    .filter((content) => content?.type === "output_text" && content.text)
+    .map((content) => content.text)
+    .join("\n")
+    .trim();
+}
+
+function buildInput({ markdown, instruction, pageUrl, notes }) {
+  return [
+    `User instruction:\n${instruction || "Generate or improve this PRD."}`,
+    pageUrl ? `Current prototype URL:\n${pageUrl}` : "",
+    notes ? `Product notes:\n${notes}` : "",
+    `Current PRD Markdown:\n${markdown || "(empty draft)"}`
+  ]
+    .filter(Boolean)
+    .join("\n\n---\n\n");
+}

package/src/paths.js

@@ -0,0 +1,39 @@
+import path from "node:path";
+
+export function resolveInsideRoot(root, targetPath) {
+  const resolvedRoot = path.resolve(root);
+  const resolvedTarget = path.resolve(resolvedRoot, targetPath);
+  const relative = path.relative(resolvedRoot, resolvedTarget);
+
+  if (
+    relative === ".." ||
+    relative.startsWith(`..${path.sep}`) ||
+    path.isAbsolute(relative)
+  ) {
+    throw new Error(`Path "${targetPath}" escapes the project root.`);
+  }
+
+  return resolvedTarget;
+}
+
+export function resolveStoragePaths(root, options) {
+  return {
+    root: path.resolve(root),
+    draftPath: resolveInsideRoot(
+      root,
+      path.join(options.draftDir, options.draftFile)
+    ),
+    draftDirPath: resolveInsideRoot(root, options.draftDir),
+    exportDirPath: resolveInsideRoot(root, options.exportDir)
+  };
+}
+
+export function slugify(value) {
+  const slug = String(value ?? "")
+    .trim()
+    .toLowerCase()
+    .replace(/[^a-z0-9]+/g, "-")
+    .replace(/^-+|-+$/g, "");
+
+  return slug || "prd";
+}