specstocode 0.5.0

package/dist/chunk-J22FYEMI.js

@@ -0,0 +1,84 @@
+// src/lib/story-context.ts
+import { mkdirSync, writeFileSync, readFileSync, existsSync } from "fs";
+import { join } from "path";
+var CONTEXT_DIR = ".specstocode/stories";
+function storyContextPath(storyId) {
+  return join(process.cwd(), CONTEXT_DIR, `${storyId}.md`);
+}
+function writeStoryContext(story) {
+  const dir = join(process.cwd(), CONTEXT_DIR);
+  if (!existsSync(dir)) mkdirSync(dir, { recursive: true });
+  const acLines = story.acceptance_criteria.length ? story.acceptance_criteria.map((ac) => `- [${ac.done ? "x" : " "}] ${ac.text}`).join("\n") : "_No acceptance criteria defined._";
+  const specSection = story.notes?.trim() ? [`## Spec`, ``, story.notes.trim(), ``] : [];
+  const md = [
+    `# ${story.title}`,
+    ``,
+    `**ID:** \`${story.id}\``,
+    `**Activity:** ${story.activity}`,
+    `**Priority:** ${story.priority} | **Effort:** ${story.effort} | **Release:** ${story.release}`,
+    `**Status:** ${story.status}`,
+    ``,
+    `## User story`,
+    ``,
+    story.user_story ?? "_No user story defined._",
+    ``,
+    `## Done when`,
+    ``,
+    acLines,
+    ``,
+    ...specSection,
+    `## Approach`,
+    ``,
+    `_Plan your approach here before writing code._`,
+    ``,
+    `## Implementation notes`,
+    ``,
+    `_Notes added via \`npx specstocode note ${story.id.slice(0, 8)} "..."\`_`,
+    ``,
+    `## Decisions`,
+    ``,
+    `_Log decisions via \`npx specstocode decide "..." -s ${story.id.slice(0, 8)}\`_`,
+    ``,
+    `## Relevant files`,
+    ``,
+    `_Add file paths here as you explore the codebase._`,
+    ``,
+    `---`,
+    ``,
+    `Mark done: \`npx specstocode done ${story.id.slice(0, 8)}\``
+  ].join("\n");
+  const path = storyContextPath(story.id);
+  writeFileSync(path, md);
+  return path;
+}
+function appendNoteToContext(storyId, note) {
+  const path = storyContextPath(storyId);
+  if (!existsSync(path)) return false;
+  const content = readFileSync(path, "utf-8");
+  const timestamp = (/* @__PURE__ */ new Date()).toISOString().replace("T", " ").slice(0, 16);
+  const noteEntry = `- [${timestamp}] ${note}`;
+  const marker = "## Implementation notes";
+  const markerIdx = content.indexOf(marker);
+  if (markerIdx === -1) return false;
+  const placeholder = "_Notes added via";
+  if (content.includes(placeholder)) {
+    writeFileSync(path, content.replace(
+      /^_Notes added via.*$/m,
+      `${noteEntry}`
+    ));
+  } else {
+    const nextSection = content.indexOf("\n## ", markerIdx + marker.length);
+    const insertAt = nextSection === -1 ? content.length : nextSection;
+    writeFileSync(
+      path,
+      content.slice(0, insertAt).trimEnd() + "\n" + noteEntry + "\n" + content.slice(insertAt)
+    );
+  }
+  return true;
+}
+
+export {
+  storyContextPath,
+  writeStoryContext,
+  appendNoteToContext
+};

package/dist/chunk-NAOZWXOF.js

@@ -0,0 +1,39 @@
+// src/lib/config.ts
+import { readFileSync, writeFileSync, mkdirSync, existsSync } from "fs";
+import { join } from "path";
+var CONFIG_DIR = ".specstocode";
+var CONFIG_FILE = "config.json";
+function configPath() {
+  return join(process.cwd(), CONFIG_DIR, CONFIG_FILE);
+}
+function hasConfig() {
+  return existsSync(configPath());
+}
+function readConfig() {
+  try {
+    const raw = readFileSync(configPath(), "utf-8");
+    return JSON.parse(raw);
+  } catch {
+    return null;
+  }
+}
+function writeConfig(config) {
+  const dir = join(process.cwd(), CONFIG_DIR);
+  if (!existsSync(dir)) mkdirSync(dir, { recursive: true });
+  writeFileSync(configPath(), JSON.stringify(config, null, 2) + "\n");
+}
+function requireConfig() {
+  const config = readConfig();
+  if (!config) {
+    console.error("Not initialized. Run: npx specstocode init");
+    process.exit(1);
+  }
+  return config;
+}
+
+export {
+  hasConfig,
+  readConfig,
+  writeConfig,
+  requireConfig
+};

package/dist/chunk-P4M7CVDK.js

@@ -0,0 +1,249 @@
+import {
+  API_BASE,
+  requireAuth
+} from "./chunk-CYA6I7NV.js";
+import {
+  getContext
+} from "./chunk-QKMZ2SBR.js";
+import {
+  ask,
+  closePrompt,
+  confirm
+} from "./chunk-WPVDURTJ.js";
+import {
+  writeConfig
+} from "./chunk-NAOZWXOF.js";
+
+// src/commands/scope.ts
+import { writeFileSync, existsSync } from "fs";
+import { join } from "path";
+async function apiFetch(path, token, opts = {}) {
+  return fetch(`${API_BASE}${path}`, {
+    ...opts,
+    headers: {
+      "Content-Type": "application/json",
+      Authorization: `Bearer ${token}`,
+      ...opts.headers ?? {}
+    }
+  });
+}
+async function scope(projectId) {
+  const auth = requireAuth();
+  const { token } = auth;
+  if (!projectId) {
+    projectId = await ask("  Project ID (from `npx specstocode start`): ");
+  }
+  if (!projectId?.trim()) {
+    console.log("  Project ID required.");
+    closePrompt();
+    return;
+  }
+  console.log("\n  \u{1F52C} Scoping your product\n");
+  console.log("  I'll ask a few questions to build your story map.\n");
+  const journey = await ask(
+    "  What are the main steps a user takes through your product?\n  (e.g. Sign up \u2192 Browse \u2192 Purchase \u2192 Review)\n  > "
+  );
+  const personas = await ask(
+    "\n  Who are the key personas? Describe 1-2 types of user.\n  (e.g. 'Sarah, a busy marketing manager who needs...')\n  > "
+  );
+  const mvp = await ask(
+    "\n  What's the minimum you need to build to test the idea?\n  (e.g. 'A simple landing page with a sign-up form and one core workflow')\n  > "
+  );
+  const constraints = await ask(
+    "\n  Any technical constraints or preferences?\n  (e.g. 'Must be a web app, using React and Supabase')\n  > "
+  );
+  console.log("\n  Generating blueprint + story map...");
+  console.log("  This takes 1-3 minutes. Doing this manually takes hours.\n");
+  const scopingContext = [
+    journey ? `User journey: ${journey}` : "",
+    personas ? `Key personas: ${personas}` : "",
+    mvp ? `MVP scope: ${mvp}` : "",
+    constraints ? `Technical constraints: ${constraints}` : ""
+  ].filter(Boolean).join("\n");
+  const res = await apiFetch("/api/blueprint/generate", token, {
+    method: "POST",
+    body: JSON.stringify({
+      projectId,
+      phase: "generation",
+      idea: scopingContext,
+      messages: [
+        { role: "user", content: scopingContext }
+      ]
+    })
+  });
+  if (!res.ok) {
+    const errText = await res.text();
+    if (errText.includes("RATE_LIMIT")) {
+      console.error("  Rate limit reached. Try again later or upgrade your plan.");
+    } else {
+      console.error(`  Generation failed: ${errText.slice(0, 200)}`);
+    }
+    closePrompt();
+    return;
+  }
+  const reader = res.body?.getReader();
+  const decoder = new TextDecoder();
+  let fullResponse = "";
+  let dots = 0;
+  if (reader) {
+    while (true) {
+      const { done, value } = await reader.read();
+      if (done) break;
+      fullResponse += decoder.decode(value, { stream: true });
+      dots++;
+      if (dots % 20 === 0) process.stdout.write(".");
+    }
+  }
+  console.log("\n");
+  try {
+    const cleaned = fullResponse.replace(/^\s*```json\s*/m, "").replace(/\s*```\s*$/m, "").trim();
+    const firstBrace = cleaned.indexOf("{");
+    const lastBrace = cleaned.lastIndexOf("}");
+    if (firstBrace !== -1 && lastBrace > firstBrace) {
+      const bp = JSON.parse(cleaned.slice(firstBrace, lastBrace + 1));
+      console.log("  \u2713 Blueprint generated!\n");
+      if (bp.founding_hypothesis) {
+        console.log(`  Hypothesis: ${bp.founding_hypothesis.slice(0, 150)}${bp.founding_hypothesis.length > 150 ? "..." : ""}
+`);
+      }
+      if (bp.personas?.length) {
+        console.log(`  Personas: ${bp.personas.map((p) => p.name).join(", ")}`);
+      }
+      if (bp.stories?.length) {
+        console.log(`  Stories: ${bp.stories.length} user stories generated`);
+      }
+      if (bp.build_order?.length) {
+        console.log(`  Build order: ${bp.build_order.length} steps`);
+      }
+    }
+  } catch {
+    console.log("  \u2713 Blueprint generated (couldn't parse summary)\n");
+  }
+  console.log("\n  Connecting project to your codebase...");
+  const mapsRes = await apiFetch(
+    `/api/storymapper/project/${projectId}`,
+    token
+  );
+  let syncToken = null;
+  if (mapsRes.ok) {
+    const mapData = await mapsRes.json();
+    if (mapData.mapId) {
+      const tokenRes = await apiFetch(
+        `/api/storymapper/${mapData.mapId}/sync-token`,
+        token,
+        { method: "POST" }
+      );
+      if (tokenRes.ok) {
+        const tokenData = await tokenRes.json();
+        syncToken = tokenData.sync_token;
+      }
+    }
+  }
+  if (syncToken) {
+    writeConfig({ syncToken, apiBase: API_BASE });
+    console.log("  \u2713 Connected\n");
+    try {
+      const config = { syncToken, apiBase: API_BASE };
+      const md = await getContext(config);
+      writeFileSync(join(process.cwd(), "SPECSTOCODE.md"), md);
+      console.log("  \u2713 Downloaded SPECSTOCODE.md\n");
+    } catch {
+      console.log("  \u26A0 Could not download SPECSTOCODE.md\n");
+    }
+  }
+  const wantMockup = await confirm(
+    "  Want to generate an HTML mockup of your product?"
+  );
+  if (wantMockup) {
+    const designSystem = await ask(
+      "\n  Any existing design system? (e.g. Tailwind + shadcn, Material UI, or 'none')\n  > "
+    );
+    const inspiration = await ask(
+      "\n  Any products or sites that inspire the look & feel?\n  > "
+    );
+    const mockupPrompt = buildMockupPrompt(projectId, designSystem, inspiration);
+    const mockupPath = join(process.cwd(), "MOCKUP_PROMPT.md");
+    writeFileSync(mockupPath, mockupPrompt);
+    console.log(`
+  \u2713 Saved MOCKUP_PROMPT.md
+`);
+    console.log("  To generate the mockup, tell your AI coding tool:");
+    console.log("    'Read MOCKUP_PROMPT.md and generate the HTML mockup'\n");
+  }
+  const hasGit = existsSync(join(process.cwd(), ".git"));
+  if (!hasGit) {
+    const wantRepo = await confirm("  Initialize a git repo for this project?");
+    if (wantRepo) {
+      const { execSync } = await import("child_process");
+      try {
+        execSync("git init", { stdio: "ignore" });
+        execSync("git add SPECSTOCODE.md", { stdio: "ignore" });
+        if (existsSync(join(process.cwd(), "MOCKUP_PROMPT.md"))) {
+          execSync("git add MOCKUP_PROMPT.md", { stdio: "ignore" });
+        }
+        execSync('git commit -m "Initial commit \u2014 specstocode project context"', {
+          stdio: "ignore"
+        });
+        console.log("  \u2713 Git repo initialized with first commit\n");
+      } catch {
+        console.log("  \u26A0 Git init failed \u2014 do it manually\n");
+      }
+    }
+  }
+  const { confirm: confirmSetup } = await import("./prompt-WAWCRGHN.js");
+  const wantSetup = await confirmSetup(
+    "  Configure your AI tool (Claude Code / Cursor) with specstocode agent workflows?"
+  );
+  if (wantSetup) {
+    const { setup } = await import("./setup-VBFEFGTK.js");
+    await setup();
+    return;
+  }
+  console.log(`
+  \u2705 Your project is scoped and ready to build!
+
+  Next steps:
+    \u2022 npx specstocode setup     \u2014 configure your AI tool
+    \u2022 npx specstocode status    \u2014 see your story map progress
+    \u2022 npx specstocode next      \u2014 see what to build first
+    \u2022 npx specstocode done <id> \u2014 mark stories as you complete them
+
+  Your story map is also live at ${API_BASE}
+  Seek advice from the community and our resources.
+  `);
+  closePrompt();
+}
+function buildMockupPrompt(projectId, designSystem, inspiration) {
+  return `# Mockup Generation Prompt
+
+Read SPECSTOCODE.md for the full product context (personas, stories, acceptance criteria).
+
+## Task
+Generate a single-file HTML mockup that demonstrates the core user journey.
+The mockup should be a clickable prototype \u2014 not production code, but enough
+to validate the UX with real users.
+
+## Requirements
+- Single HTML file with inline CSS and minimal JS
+- Mobile-first responsive design
+- All key screens from the user journey (see SPECSTOCODE.md)
+- Realistic placeholder content (not lorem ipsum)
+- Navigation between screens via anchor links or simple JS
+
+## Design
+${designSystem && designSystem !== "none" ? `- Design system: ${designSystem}` : "- Use a clean, modern design with system fonts"}
+${inspiration ? `- Inspiration: ${inspiration}` : "- Keep it simple and functional"}
+- Dark mode preferred
+- Accessible (proper contrast, semantic HTML)
+
+## Output
+Save as \`mockup.html\` in the project root.
+
+## Project ID
+${projectId}
+`;
+}
+
+export {
+  scope
+};

package/dist/chunk-QKMZ2SBR.js

@@ -0,0 +1,39 @@
+// src/lib/api.ts
+function apiUrl(config, path) {
+  return `${config.apiBase}/api/sync/${config.syncToken}${path}`;
+}
+async function listStories(config) {
+  const res = await fetch(apiUrl(config, "/stories"));
+  if (!res.ok) throw new Error(`API error: ${res.status}`);
+  return res.json();
+}
+async function getContext(config) {
+  const res = await fetch(apiUrl(config, "/context"));
+  if (!res.ok) throw new Error(`API error: ${res.status}`);
+  return res.text();
+}
+async function updateStories(config, stories) {
+  const res = await fetch(apiUrl(config, "/stories"), {
+    method: "PATCH",
+    headers: { "Content-Type": "application/json" },
+    body: JSON.stringify({ stories })
+  });
+  if (!res.ok) throw new Error(`API error: ${res.status}`);
+  return res.json();
+}
+async function createStories(config, stories) {
+  const res = await fetch(apiUrl(config, "/stories"), {
+    method: "POST",
+    headers: { "Content-Type": "application/json" },
+    body: JSON.stringify({ stories })
+  });
+  if (!res.ok) throw new Error(`API error: ${res.status}`);
+  return res.json();
+}
+
+export {
+  listStories,
+  getContext,
+  updateStories,
+  createStories
+};

package/dist/chunk-WPVDURTJ.js

@@ -0,0 +1,79 @@
+// src/lib/prompt.ts
+import { createInterface } from "readline";
+var rl = null;
+function getRL() {
+  if (!rl) {
+    rl = createInterface({
+      input: process.stdin,
+      output: process.stdout
+    });
+  }
+  return rl;
+}
+function ask(question) {
+  return new Promise((resolve) => {
+    getRL().question(question, (answer) => {
+      resolve(answer.trim());
+    });
+  });
+}
+function askMultiline(question) {
+  console.log(question);
+  console.log("  (Press Enter twice to finish)\n");
+  return new Promise((resolve) => {
+    const lines = [];
+    let emptyCount = 0;
+    const handler = (line) => {
+      if (line === "") {
+        emptyCount++;
+        if (emptyCount >= 2) {
+          process.stdin.removeListener("line", handler);
+          resolve(lines.join("\n").trim());
+          return;
+        }
+      } else {
+        emptyCount = 0;
+      }
+      lines.push(line);
+    };
+    process.stdin.on("line", handler);
+  });
+}
+async function confirm(question) {
+  const answer = await ask(`${question} (y/n) `);
+  return answer.toLowerCase().startsWith("y");
+}
+async function choose(question, options) {
+  console.log(`
+${question}
+`);
+  for (let i = 0; i < options.length; i++) {
+    console.log(`  ${i + 1}. ${options[i]}`);
+  }
+  const answer = await ask(`
+Choice (1-${options.length}): `);
+  const idx = parseInt(answer, 10) - 1;
+  if (idx < 0 || idx >= options.length) return 0;
+  return idx;
+}
+function closePrompt() {
+  if (rl) {
+    rl.close();
+    rl = null;
+  }
+}
+function pausePrompt() {
+  if (rl) {
+    rl.close();
+    rl = null;
+  }
+}
+
+export {
+  ask,
+  askMultiline,
+  confirm,
+  choose,
+  closePrompt,
+  pausePrompt
+};

package/dist/complexity-TUS6F2UI.js

@@ -0,0 +1,71 @@
+import {
+  listStories
+} from "./chunk-QKMZ2SBR.js";
+import {
+  requireConfig
+} from "./chunk-NAOZWXOF.js";
+
+// src/commands/complexity.ts
+import ora from "ora";
+async function complexity(storyId) {
+  const config = requireConfig();
+  const spinner = ora("  Analyzing complexity...").start();
+  try {
+    const data = await listStories(config);
+    let storyIds;
+    if (storyId) {
+      const match = data.stories.find((s) => s.id.startsWith(storyId));
+      if (!match) {
+        spinner.fail(`  No story found matching "${storyId}"`);
+        return;
+      }
+      storyIds = [match.id];
+    } else {
+      storyIds = data.stories.filter((s) => s.status !== "done").map((s) => s.id);
+    }
+    if (!storyIds.length) {
+      spinner.succeed("  No stories to analyze \u2014 all done!");
+      return;
+    }
+    const res = await fetch(
+      `${config.apiBase}/api/sync/${config.syncToken}/complexity`,
+      {
+        method: "POST",
+        headers: { "Content-Type": "application/json" },
+        body: JSON.stringify({ story_ids: storyIds })
+      }
+    );
+    if (!res.ok) {
+      spinner.fail("  Complexity analysis failed");
+      return;
+    }
+    const result = await res.json();
+    spinner.succeed(`  Analyzed ${result.stories.length} stories
+`);
+    const sorted = result.stories.sort((a, b) => b.complexity - a.complexity);
+    for (const s of sorted) {
+      const bar = "\u2588".repeat(s.complexity) + "\u2591".repeat(10 - s.complexity);
+      const color = s.complexity >= 8 ? "\x1B[31m" : s.complexity >= 5 ? "\x1B[33m" : "\x1B[32m";
+      const reset = "\x1B[0m";
+      console.log(`  ${color}${bar}${reset} ${s.complexity}/10  ${s.title}`);
+      console.log(`    ${s.reasoning}`);
+      if (s.risks?.length) {
+        console.log(`    \u26A0 ${s.risks.join(", ")}`);
+      }
+      console.log(`    Suggested effort: ${s.suggested_effort}
+`);
+    }
+    const avg = sorted.reduce((a, s) => a + s.complexity, 0) / sorted.length;
+    const high = sorted.filter((s) => s.complexity >= 7).length;
+    console.log(`  \u2500\u2500 Summary \u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500`);
+    console.log(`  Average complexity: ${avg.toFixed(1)}/10`);
+    console.log(`  High complexity (7+): ${high} stories`);
+    console.log(`  Total analyzed: ${sorted.length}
+`);
+  } catch (err) {
+    spinner.fail(`  Error: ${err.message}`);
+  }
+}
+export {
+  complexity
+};

package/dist/import-prd-HP66GKRA.js

@@ -0,0 +1,114 @@
+import {
+  closePrompt,
+  confirm
+} from "./chunk-WPVDURTJ.js";
+import {
+  requireConfig
+} from "./chunk-NAOZWXOF.js";
+
+// src/commands/import-prd.ts
+import { readFileSync, existsSync } from "fs";
+import ora from "ora";
+async function importPrd(filePath) {
+  const config = requireConfig();
+  let prdText;
+  let format = "PRD";
+  if (filePath) {
+    if (!existsSync(filePath)) {
+      console.error(`  File not found: ${filePath}`);
+      return;
+    }
+    prdText = readFileSync(filePath, "utf-8");
+    if (filePath.endsWith(".md")) format = "Markdown";
+    else if (filePath.endsWith(".txt")) format = "text";
+  } else {
+    console.log("  Paste your PRD below (press Ctrl+D when done):\n");
+    const chunks = [];
+    for await (const chunk of process.stdin) {
+      chunks.push(chunk);
+    }
+    prdText = Buffer.concat(chunks).toString("utf-8");
+  }
+  if (!prdText.trim()) {
+    console.error("  No content to import.");
+    return;
+  }
+  console.log(`
+  Importing ${format} (${prdText.length} chars)...
+`);
+  const spinner = ora("  Parsing into stories...").start();
+  try {
+    const res = await fetch(
+      `${config.apiBase}/api/sync/${config.syncToken}/import`,
+      {
+        method: "POST",
+        headers: { "Content-Type": "application/json" },
+        body: JSON.stringify({ prd: prdText, format })
+      }
+    );
+    if (!res.ok) {
+      spinner.fail("  Import failed");
+      const errText = await res.text();
+      console.error(`  ${errText.slice(0, 200)}`);
+      return;
+    }
+    const result = await res.json();
+    spinner.succeed(`  Parsed ${result.count} stories
+`);
+    const byActivity = /* @__PURE__ */ new Map();
+    for (const story of result.stories) {
+      const activity = story.activity || "Uncategorised";
+      if (!byActivity.has(activity)) byActivity.set(activity, []);
+      byActivity.get(activity).push(story);
+    }
+    for (const [activity, stories] of byActivity) {
+      console.log(`  ${activity}:`);
+      for (const s of stories) {
+        const priorityColor = s.priority === "must" ? "\x1B[31m" : s.priority === "should" ? "\x1B[33m" : "\x1B[32m";
+        const reset = "\x1B[0m";
+        console.log(`    ${priorityColor}[${s.priority}]${reset} ${s.title} (${s.effort})`);
+        if (s.acceptance_criteria?.length) {
+          console.log(`      ${s.acceptance_criteria.length} acceptance criteria`);
+        }
+      }
+      console.log();
+    }
+    const doImport = await confirm(
+      `  Import these ${result.count} stories into your story map?`
+    );
+    if (doImport) {
+      const importSpinner = ora("  Creating stories...").start();
+      const createRes = await fetch(
+        `${config.apiBase}/api/sync/${config.syncToken}/stories`,
+        {
+          method: "POST",
+          headers: { "Content-Type": "application/json" },
+          body: JSON.stringify({
+            stories: result.stories.map((s) => ({
+              title: s.title,
+              activity: s.activity,
+              priority: s.priority,
+              effort: s.effort,
+              acceptance_criteria: s.acceptance_criteria
+            }))
+          })
+        }
+      );
+      if (createRes.ok) {
+        const createResult = await createRes.json();
+        importSpinner.succeed(`  \u2713 Created ${createResult.created} stories in your story map
+`);
+      } else {
+        importSpinner.fail("  Failed to create stories");
+      }
+    } else {
+      console.log("  Import cancelled.\n");
+    }
+    closePrompt();
+  } catch (err) {
+    spinner.fail(`  Error: ${err.message}`);
+  }
+}
+export {
+  importPrd
+};