@rijalpermana/spec-forge 0.1.1 → 0.2.0

package/README.md

@@ -70,6 +70,7 @@ forge smelt btn-fraud-check       # interactive Q&A -> brief.md + prd.md stub
 
 forge schema btn-fraud-check      # schema.dbml (requires prd.md)
 forge contract btn-fraud-check    # api-contract.md (requires prd.md)
+forge mockup btn-fraud-check      # mockup.html (requires prd.md)
 forge tasks btn-fraud-check       # tasks.md (requires prd.md)
 forge testcase btn-fraud-check    # testcases.md (requires prd.md)
 forge verify btn-fraud-check      # reports missing files / unresolved [TODO]s
@@ -132,6 +133,7 @@ the writing.
 | `forge smelt <feature>` | — | `brief.md`, `prd.md` (stub), `INDEX.md` entry (`draft`) | Yes — refuses if `brief.md` exists |
 | `forge schema <feature>` | `prd.md` | `schema.dbml` (stub) | Yes |
 | `forge contract <feature>` | `prd.md` | `api-contract.md` (stub) | Yes |
+| `forge mockup <feature>` | `prd.md` | `mockup.html` (stub) | Yes |
 | `forge tasks <feature>` | `prd.md` | `tasks.md` (stub) | Yes |
 | `forge testcase <feature>` | `prd.md` | `testcases.md` (stub) | Yes |
 | `forge verify <feature>` | — | Console report, `INDEX.md` status → `active` if complete | N/A (read-only on spec files) |
@@ -149,6 +151,7 @@ your-project/
 │       ├── prd.md              # goal, actors, user stories, business rules, out-of-scope
 │       ├── schema.dbml          # entities derived from prd.md
 │       ├── api-contract.md       # Title / endpoint / Request / Response / Note format
+│       ├── mockup.html            # throwaway wireframe (plain HTML/CSS, no framework)
 │       ├── tasks.md               # WBS, sequenced data -> logic -> UI
 │       └── testcases.md            # No/Scenario/Case/Type/Expected/Actual/Status/Remark table
 ├── .claude/commands/forge/         # if target = claude

package/dist/cli.js

@@ -6775,6 +6775,9 @@ var require_prompts3 = __commonJS((exports, module) => {
   module.exports = isNodeLT("8.6.0") ? require_dist() : require_lib();
 });
 
+// src/cli.ts
+import { createRequire as createRequire2 } from "node:module";
+
 // node_modules/commander/esm.mjs
 var import__ = __toESM(require_commander(), 1);
 var {
@@ -6845,7 +6848,7 @@ var COMMAND_SPECS = [
     description: "Extract raw requirements into a grounding brief, then draft the PRD",
     requiresPrd: false,
     readOnly: false,
-    instructions: GROUND_IN_RULES + "This command is interactive — it prompts for goal, actors, constraints, and " + "out-of-scope items in the terminal. Once it completes, read {{brief}} and " + "draft {{prd}} following the structure already stubbed there. Do not invent " + "scope, actors, or rules that aren't grounded in the brief — if something's " + "missing, ask what to clarify instead of guessing."
+    instructions: GROUND_IN_RULES + "This command has two input modes. Default: it prompts for goal, actors, " + "constraints, and out-of-scope items in the terminal. With --from <file>: it " + "stages an existing BRD/requirements document verbatim in the feature folder as " + "source-brd.<ext> (extension preserved — .md, .pdf, .docx, …) and leaves " + "'[TODO: extract from source-brd.<ext>]' markers in {{brief}}. If a source-brd.* " + "file exists, read it (if your tool can't open that format — e.g. .docx — say so " + "and ask the user to export it to Markdown or PDF) and replace each marker in " + "{{brief}} with the value extracted from the document, citing the BRD section it " + "came from so every requirement stays traceable. Then read {{brief}} and draft " + "{{prd}} following the structure already stubbed there. Do not invent scope, " + "actors, or rules that aren't grounded in the brief or the BRD — if something's " + "missing, ask what to clarify instead of guessing."
   },
   {
     name: "schema",
@@ -6869,6 +6872,14 @@ var COMMAND_SPECS = [
 ` + `Response: [full JSON example]
 ` + "Note: [only if needed]"
   },
+  {
+    name: "mockup",
+    argumentHint: "[feature-name]",
+    description: "Scaffold mockup.html, then draft it from prd.md",
+    requiresPrd: true,
+    readOnly: false,
+    instructions: GROUND_IN_RULES + "Read {{prd}} and fill {{mockup}} — a throwaway wireframe (plain HTML/CSS, no " + "framework, no build step) covering the screens/states implied by the PRD's user " + "stories: primary view, secondary views or modals, and empty/loading/error states " + "where the PRD calls for them. This is for reviewing flow and layout, not visual " + "design or production markup — don't invent screens, fields, or copy that aren't " + "traceable to the PRD."
+  },
   {
     name: "tasks",
     argumentHint: "[feature-name]",
@@ -6913,6 +6924,7 @@ var SPEC_FILES = {
   prd: "prd.md",
   schema: "schema.dbml",
   contract: "api-contract.md",
+  mockup: "mockup.html",
   tasks: "tasks.md",
   testcases: "testcases.md"
 };
@@ -7155,7 +7167,8 @@ Next: forge smelt <feature-name>`);
 
 // src/commands/smelt.ts
 var import_prompts = __toESM(require_prompts3(), 1);
-import { join as join8 } from "node:path";
+import { copyFileSync, mkdirSync as mkdirSync5 } from "node:fs";
+import { basename, extname, join as join8, resolve } from "node:path";
 
 // src/lib/template.ts
 import { readFileSync as readFileSync2, existsSync as existsSync3, mkdirSync as mkdirSync4, writeFileSync as writeFileSync4 } from "node:fs";
@@ -7178,7 +7191,8 @@ function fileExists(path) {
 }
 
 // src/commands/smelt.ts
-async function smelt(feature) {
+var SOURCE_DOC_BASE = "source-brd";
+async function smelt(feature, opts = {}) {
   const cwd = process.cwd();
   const dir = featureDir(feature, cwd);
   const briefPath = join8(dir, SPEC_FILES.brief);
@@ -7195,36 +7209,20 @@ async function smelt(feature) {
     console.log(`Existing features: ${existingFeatures.join(", ")}
 `);
   }
-  const answers = await import_prompts.default([
-    { type: "text", name: "goal", message: "One-sentence goal — what must this feature deliver?" },
-    { type: "text", name: "actors", message: "Who are the actors/roles involved?" },
-    { type: "text", name: "constraints", message: "Key constraints (regulatory, technical, deadline)?" },
-    { type: "text", name: "outOfScope", message: "What's explicitly OUT of scope?" },
-    {
-      type: "text",
-      name: "dependsOn",
-      message: "Does this depend on another existing feature? (feature name, or leave blank)"
-    }
-  ]);
-  if (!answers.goal) {
-    console.log("Smelting cancelled.");
+  const briefVars = opts.from ? stageSourceDoc(opts.from, dir) : await runInteractive(feature);
+  if (!briefVars)
     return;
-  }
   const briefRaw = readTemplate(join8(templatesDir, SPEC_FILES.brief));
   const brief = renderTemplate(briefRaw, {
     feature,
     date: new Date().toISOString().slice(0, 10),
-    goal: answers.goal ?? "",
-    actors: answers.actors ?? "",
-    constraints: answers.constraints ?? "",
-    outOfScope: answers.outOfScope ?? ""
+    ...briefVars
   });
   writeIfAbsent(briefPath, brief);
   const prdRaw = readTemplate(join8(templatesDir, SPEC_FILES.prd));
   const prd = renderTemplate(prdRaw, { feature });
   const prdWritten = writeIfAbsent(prdPath, prd);
-  const dependsOn = answers.dependsOn?.trim() || "-";
-  upsertIndexEntry(cwd, feature, { status: "draft", dependsOn });
+  upsertIndexEntry(cwd, feature, { status: "draft", dependsOn: briefVars.dependsOn });
   console.log(`
 Wrote ${briefPath}`);
   if (prdWritten)
@@ -7233,6 +7231,55 @@ Wrote ${briefPath}`);
   console.log(`
 Next: open this project in your AI tool and draft prd.md from brief.md ` + `— use the /forge:smelt, /forge-smelt, or AGENTS.md instructions, depending ` + `on which bridge you initialized.`);
 }
+function stageSourceDoc(from, dir) {
+  const srcPath = resolve(process.cwd(), from);
+  if (!fileExists(srcPath)) {
+    console.log(`Source document not found: ${srcPath}`);
+    process.exitCode = 1;
+    return;
+  }
+  const docName = `${SOURCE_DOC_BASE}${extname(srcPath).toLowerCase()}`;
+  const destPath = join8(dir, docName);
+  if (fileExists(destPath)) {
+    console.log(`${destPath} already exists — leaving it in place.`);
+  } else {
+    mkdirSync5(dir, { recursive: true });
+    copyFileSync(srcPath, destPath);
+    console.log(`Staged ${basename(srcPath)} → ${destPath}`);
+  }
+  const marker = `[TODO: extract from ${docName}]`;
+  return {
+    goal: marker,
+    actors: marker,
+    constraints: marker,
+    outOfScope: marker,
+    dependsOn: "-"
+  };
+}
+async function runInteractive(feature) {
+  const answers = await import_prompts.default([
+    { type: "text", name: "goal", message: "One-sentence goal — what must this feature deliver?" },
+    { type: "text", name: "actors", message: "Who are the actors/roles involved?" },
+    { type: "text", name: "constraints", message: "Key constraints (regulatory, technical, deadline)?" },
+    { type: "text", name: "outOfScope", message: "What's explicitly OUT of scope?" },
+    {
+      type: "text",
+      name: "dependsOn",
+      message: "Does this depend on another existing feature? (feature name, or leave blank)"
+    }
+  ]);
+  if (!answers.goal) {
+    console.log("Smelting cancelled.");
+    return null;
+  }
+  return {
+    goal: answers.goal ?? "",
+    actors: answers.actors ?? "",
+    constraints: answers.constraints ?? "",
+    outOfScope: answers.outOfScope ?? "",
+    dependsOn: answers.dependsOn?.trim() || "-"
+  };
+}
 
 // src/commands/scaffold.ts
 import { join as join9 } from "node:path";
@@ -7299,8 +7346,8 @@ function verify(feature) {
 }
 
 // src/commands/scan.ts
-import { existsSync as existsSync4, readFileSync as readFileSync4, readdirSync, mkdirSync as mkdirSync5, writeFileSync as writeFileSync5 } from "node:fs";
-import { join as join11, extname, relative, basename } from "node:path";
+import { existsSync as existsSync4, readFileSync as readFileSync4, readdirSync, mkdirSync as mkdirSync6, writeFileSync as writeFileSync5 } from "node:fs";
+import { join as join11, extname as extname2, relative, basename as basename2 } from "node:path";
 var IGNORE_DIRS = new Set([
   "node_modules",
   ".git",
@@ -7340,7 +7387,7 @@ function scan(options = {}) {
     apis: pathListOrNone(apis),
     tree: renderTree(cwd, depth)
   });
-  mkdirSync5(specsDir(cwd), { recursive: true });
+  mkdirSync6(specsDir(cwd), { recursive: true });
   const outPath = join11(specsDir(cwd), "CODEBASE.md");
   writeFileSync5(outPath, rendered, "utf-8");
   console.log(`Wrote ${outPath}`);
@@ -7427,8 +7474,8 @@ function detectStack(root) {
   return found;
 }
 function isSchemaFile(f) {
-  const ext = extname(f).toLowerCase();
-  const base = basename(f).toLowerCase();
+  const ext = extname2(f).toLowerCase();
+  const base = basename2(f).toLowerCase();
   if (ext === ".dbml" || ext === ".prisma" || ext === ".sql")
     return true;
   if (/schema/.test(base) && [".ts", ".js", ".py", ".rb", ".go", ".json"].includes(ext))
@@ -7439,7 +7486,7 @@ function isSchemaFile(f) {
 }
 function isApiFile(f) {
   const p = f.toLowerCase();
-  const base = basename(p);
+  const base = basename2(p);
   if (/(openapi|swagger)\.(ya?ml|json)$/.test(base))
     return true;
   if (/\.(controller|route|router|resolver)\.(ts|js|py)$/.test(base))
@@ -7449,7 +7496,7 @@ function isApiFile(f) {
   return false;
 }
 function renderProject(root, fileCount) {
-  let name = basename(root);
+  let name = basename2(root);
   const pkgPath = join11(root, "package.json");
   if (existsSync4(pkgPath)) {
     try {
@@ -7480,7 +7527,7 @@ function renderProject(root, fileCount) {
 function fileStats(files) {
   const counts = new Map;
   for (const f of files) {
-    const ext = extname(f).toLowerCase() || "(no ext)";
+    const ext = extname2(f).toLowerCase() || "(no ext)";
     counts.set(ext, (counts.get(ext) ?? 0) + 1);
   }
   const top = [...counts.entries()].sort((a, b) => b[1] - a[1]).slice(0, 12);
@@ -7488,7 +7535,7 @@ function fileStats(files) {
 `);
 }
 function renderTree(root, maxDepth) {
-  const lines = [`${basename(root) || root}/`];
+  const lines = [`${basename2(root) || root}/`];
   walkTree(root, "", maxDepth, lines);
   return lines.join(`
 `);
@@ -7552,15 +7599,18 @@ Every forge drafting command (smelt, schema, contract, tasks, testcase) ` + `wil
 }
 
 // src/cli.ts
+var require2 = createRequire2(import.meta.url);
+var { version } = require2("../package.json");
 var program2 = new Command;
-program2.name("forge").description("Spec-driven development CLI — scaffolds specs, schemas, API contracts, tasks, and test cases.").version("0.1.0");
+program2.name("forge").description("Spec-driven development CLI — scaffolds specs, schemas, API contracts, tasks, and test cases.").version(version);
 program2.command("init").description("Scaffold specs/ folder and an AI-tool bridge in the current project").option("-t, --target <target>", "bridge target: claude, cursor, windsurf, or generic", "claude").action((options) => init({ target: options.target }));
 program2.command("bridge <target>").description("(Re)generate AI-tool bridge commands: claude, cursor, windsurf, or generic").action((target) => bridge(target));
 program2.command("scan").description("Inventory the existing project structure into specs/CODEBASE.md").option("-d, --depth <n>", "directory-tree depth to include in the report", "2").action((options) => scan({ depth: Number(options.depth) }));
 program2.command("rules").description("Scaffold specs/RULES.md — project conventions the AI follows when drafting").action(() => rules());
-program2.command("smelt <feature>").description("Extract raw requirements into a grounding brief and stub the PRD").action(smelt);
+program2.command("smelt <feature>").description("Extract raw requirements into a grounding brief and stub the PRD").option("-f, --from <file>", "extract from an existing BRD/requirements document instead of interactive Q&A").action((feature, options) => smelt(feature, { from: options.from }));
 program2.command("schema <feature>").description("Scaffold schema.dbml (requires prd.md)").action(makeScaffoldCommand({ file: SPEC_FILES.schema, label: "schema" }));
 program2.command("contract <feature>").description("Scaffold api-contract.md (requires prd.md)").action(makeScaffoldCommand({ file: SPEC_FILES.contract, label: "contract" }));
+program2.command("mockup <feature>").description("Scaffold mockup.html (requires prd.md)").action(makeScaffoldCommand({ file: SPEC_FILES.mockup, label: "mockup" }));
 program2.command("tasks <feature>").description("Scaffold tasks.md WBS (requires prd.md)").action(makeScaffoldCommand({ file: SPEC_FILES.tasks, label: "tasks" }));
 program2.command("testcase <feature>").description("Scaffold testcases.md (requires prd.md)").action(makeScaffoldCommand({ file: SPEC_FILES.testcases, label: "testcase" }));
 program2.command("verify <feature>").description("Check that all spec files exist and have no unresolved [TODO] markers").action(verify);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@rijalpermana/spec-forge",
-  "version": "0.1.1",
+  "version": "0.2.0",
   "description": "Spec-driven development CLI: scaffolds specs, schemas, API contracts, task lists, and test cases; bridges into Claude Code as slash commands.",
   "type": "module",
   "license": "MIT",

package/templates/mockup.html

@@ -0,0 +1,45 @@
+<!-- Mockup — {{feature}}
+     Generated by `forge mockup {{feature}}`. Derive screens/sections from prd.md's
+     user stories — do not invent flows that aren't grounded in the PRD. This is a
+     throwaway wireframe for review, not production markup: plain HTML/CSS, no
+     framework, no build step. Open directly in a browser. -->
+<!doctype html>
+<html lang="en">
+<head>
+  <meta charset="utf-8" />
+  <meta name="viewport" content="width=device-width, initial-scale=1" />
+  <title>{{feature}} — mockup</title>
+  <style>
+    :root { color-scheme: light dark; }
+    body { font-family: system-ui, sans-serif; max-width: 960px; margin: 2rem auto; padding: 0 1rem; line-height: 1.5; }
+    header { border-bottom: 1px solid #8888; margin-bottom: 1.5rem; padding-bottom: 1rem; }
+    h1 { font-size: 1.25rem; margin: 0; }
+    .note { color: #888; font-size: 0.85rem; }
+    section { margin-bottom: 2rem; padding: 1rem; border: 1px dashed #8886; border-radius: 8px; }
+    section h2 { font-size: 1rem; margin-top: 0; }
+    .todo { color: #b8860b; font-weight: 600; }
+    button, input, select { font: inherit; padding: 0.4rem 0.6rem; }
+  </style>
+</head>
+<body>
+  <header>
+    <h1>{{feature}}</h1>
+    <p class="note">Wireframe only — grounded in prd.md. Replace each placeholder section below.</p>
+  </header>
+
+  <section>
+    <h2>[TODO] Primary screen / view</h2>
+    <p class="todo">[TODO] Lay out the main UI for this feature's core user story — key fields, actions, and states (empty, loading, error).</p>
+  </section>
+
+  <section>
+    <h2>[TODO] Secondary screen / modal (if any)</h2>
+    <p class="todo">[TODO] Add a screen per additional user story from prd.md, or delete this section if there's only one.</p>
+  </section>
+
+  <section>
+    <h2>[TODO] Notes</h2>
+    <p class="todo">[TODO] Call out anything ambiguous in prd.md that this mockup had to assume.</p>
+  </section>
+</body>
+</html>