intentdocs 0.10.1 → 0.11.0

package/dist/{chunk-PUGYRSMK.js → chunk-IORMKLAQ.js}

@@ -1,19 +1,19 @@
+import {
+  writeStoryContext
+} from "./chunk-BNEU6TLJ.js";
 import {
   captureCli,
   shutdownCliAnalytics
 } from "./chunk-KPQ42YE6.js";
-import {
-  writeStoryContext
-} from "./chunk-F52HPVNQ.js";
 import {
   apiFetch,
   getContext,
   listStories
-} from "./chunk-34JCN66H.js";
+} from "./chunk-KTGQO3AE.js";
 import {
   hasConfig,
   requireConfig
-} from "./chunk-JX2RLGOM.js";
+} from "./chunk-K5SNF6CG.js";
 import {
   choose,
   closePrompt
@@ -23,9 +23,8 @@ import {
 } from "./chunk-XZE2XP6O.js";
 
 // src/commands/setup.ts
-import { existsSync as existsSync2, mkdirSync, writeFileSync as writeFileSync2, readFileSync, unlinkSync } from "fs";
-import { join as join2, dirname } from "path";
-import { homedir } from "os";
+import { existsSync as existsSync3, mkdirSync, writeFileSync as writeFileSync3, readFileSync as readFileSync2, unlinkSync } from "fs";
+import { join as join3 } from "path";
 
 // src/commands/sync.ts
 import { writeFileSync, readdirSync, existsSync, statSync } from "fs";
@@ -120,6 +119,61 @@ async function sync(opts) {
   await shutdownCliAnalytics();
 }
 
+// src/lib/claude-mcp-config.ts
+import { existsSync as existsSync2, readFileSync, writeFileSync as writeFileSync2 } from "fs";
+import { join as join2 } from "path";
+import { homedir } from "os";
+var LOCAL_SERVER_NAME = "intent";
+var LOCAL_SERVER_ENTRY = { type: "stdio", command: "npx", args: ["intentdocs", "mcp"], env: {} };
+var CLAUDE_MCP_ADD_COMMAND = `claude mcp add --scope project ${LOCAL_SERVER_NAME} -- npx intentdocs mcp`;
+function sameEntry(a, b) {
+  return JSON.stringify(a) === JSON.stringify(b);
+}
+function registerLocalServerInMcpJson(cwd = process.cwd()) {
+  const path = join2(cwd, ".mcp.json");
+  let config = {};
+  if (existsSync2(path)) {
+    try {
+      const parsed = JSON.parse(readFileSync(path, "utf-8"));
+      if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) return { status: "unreadable", path };
+      config = parsed;
+    } catch {
+      return { status: "unreadable", path };
+    }
+  }
+  const rawServers = config.mcpServers;
+  if (rawServers !== void 0 && (typeof rawServers !== "object" || rawServers === null || Array.isArray(rawServers))) {
+    return { status: "unreadable", path };
+  }
+  const servers = { ...rawServers ?? {} };
+  const before = servers[LOCAL_SERVER_NAME];
+  if (sameEntry(before, LOCAL_SERVER_ENTRY)) return { status: "unchanged", path };
+  servers[LOCAL_SERVER_NAME] = { ...LOCAL_SERVER_ENTRY, args: [...LOCAL_SERVER_ENTRY.args], env: {} };
+  writeFileSync2(path, JSON.stringify({ ...config, mcpServers: servers }, null, 2) + "\n");
+  return { status: before === void 0 ? "added" : "updated", path };
+}
+var LEGACY_SETTINGS_ENTRY = { command: "npx", args: ["intentdocs", "mcp"] };
+function removeLegacySettingsEntry(home = homedir()) {
+  const path = join2(home, ".claude", "settings.json");
+  if (!existsSync2(path)) return false;
+  let settings;
+  try {
+    settings = JSON.parse(readFileSync(path, "utf-8"));
+  } catch {
+    return false;
+  }
+  if (!settings || typeof settings !== "object" || Array.isArray(settings)) return false;
+  const servers = settings.mcpServers;
+  if (!servers || typeof servers !== "object" || !sameEntry(servers[LOCAL_SERVER_NAME], LEGACY_SETTINGS_ENTRY)) return false;
+  const rest = { ...servers };
+  delete rest[LOCAL_SERVER_NAME];
+  const next = { ...settings };
+  if (Object.keys(rest).length > 0) next.mcpServers = rest;
+  else delete next.mcpServers;
+  writeFileSync2(path, JSON.stringify(next, null, 2) + "\n");
+  return true;
+}
+
 // src/commands/setup.ts
 async function setup() {
   await requireValidAuth();
@@ -174,7 +228,7 @@ async function setup() {
 }
 function setupClaudeCode() {
   const cwd = process.cwd();
-  const claudeMdPath = join2(cwd, "CLAUDE.md");
+  const claudeMdPath = join3(cwd, "CLAUDE.md");
   const claudeBlock = `
 # intentdocs Integration
 
@@ -194,29 +248,29 @@ story map, decisions, examples, tools, and guardrails.
 | \`npx intentdocs sync --context\` | Regenerate this file from intentdocs |
 | \`npx intentdocs status\` | Show recent activity |
 `;
-  if (existsSync2(claudeMdPath)) {
-    const existing = readFileSync(claudeMdPath, "utf-8");
+  if (existsSync3(claudeMdPath)) {
+    const existing = readFileSync2(claudeMdPath, "utf-8");
     if (!existing.includes("intentdocs Integration")) {
-      writeFileSync2(claudeMdPath, existing + "\n" + claudeBlock);
+      writeFileSync3(claudeMdPath, existing + "\n" + claudeBlock);
       console.log("  \u2713 Updated CLAUDE.md with intentdocs agent workflow");
     } else {
       console.log("  \u2713 CLAUDE.md already configured");
     }
   } else {
-    writeFileSync2(claudeMdPath, claudeBlock.trim() + "\n");
+    writeFileSync3(claudeMdPath, claudeBlock.trim() + "\n");
     console.log("  \u2713 Created CLAUDE.md with intentdocs agent workflow");
   }
-  const commandsDir = join2(cwd, ".claude", "commands");
-  if (!existsSync2(commandsDir)) mkdirSync(commandsDir, { recursive: true });
+  const commandsDir = join3(cwd, ".claude", "commands");
+  if (!existsSync3(commandsDir)) mkdirSync(commandsDir, { recursive: true });
   const oldPbCommands = ["pb-next", "pb-implement", "pb-review", "pb-document", "pb-test", "pb-status", "pb-done", "pb-sync", "pb-propose", "pb-context"];
   for (const name of oldPbCommands) {
-    const oldPath = join2(commandsDir, name + ".md");
-    if (existsSync2(oldPath)) {
+    const oldPath = join3(commandsDir, name + ".md");
+    if (existsSync3(oldPath)) {
       unlinkSync(oldPath);
     }
   }
-  writeFileSync2(
-    join2(commandsDir, "intent-next.md"),
+  writeFileSync3(
+    join3(commandsDir, "intent-next.md"),
     `# Pick up the next story
 
 1. Run \`npx intentdocs next\` to get the highest-priority story
@@ -227,8 +281,8 @@ story map, decisions, examples, tools, and guardrails.
 6. Ask for confirmation before proceeding
 `
   );
-  writeFileSync2(
-    join2(commandsDir, "intent-implement.md"),
+  writeFileSync3(
+    join3(commandsDir, "intent-implement.md"),
     `# Implement a story
 
 ## Context to load first
@@ -275,8 +329,8 @@ story map, decisions, examples, tools, and guardrails.
 - Never mark a story done with a failing or unreported \`must\` criterion.
 `
   );
-  writeFileSync2(
-    join2(commandsDir, "intent-review.md"),
+  writeFileSync3(
+    join3(commandsDir, "intent-review.md"),
     `# Review against acceptance criteria
 
 1. Identify the story being worked on
@@ -287,8 +341,8 @@ story map, decisions, examples, tools, and guardrails.
 4. Summarise: what's done, what needs work, any concerns
 `
   );
-  writeFileSync2(
-    join2(commandsDir, "intent-document.md"),
+  writeFileSync3(
+    join3(commandsDir, "intent-document.md"),
     `# Document a feature
 
 1. Check which story was just completed
@@ -306,8 +360,8 @@ story map, decisions, examples, tools, and guardrails.
 7. Update CONVENTIONS.md if new patterns were introduced
 `
   );
-  writeFileSync2(
-    join2(commandsDir, "intent-test.md"),
+  writeFileSync3(
+    join3(commandsDir, "intent-test.md"),
     `# Write tests for a story
 
 1. Get the story details: \`npx intentdocs next\` or provided story ID
@@ -317,12 +371,12 @@ story map, decisions, examples, tools, and guardrails.
 5. Run the tests to verify they pass
 `
   );
-  writeFileSync2(
-    join2(commandsDir, "intent-status.md"),
+  writeFileSync3(
+    join3(commandsDir, "intent-status.md"),
     `Run \`npx intentdocs status\` and \`npx intentdocs stories --filter todo\` to show current progress and remaining backlog. Summarise what's done and what's left.`
   );
-  writeFileSync2(
-    join2(commandsDir, "intent-done.md"),
+  writeFileSync3(
+    join3(commandsDir, "intent-done.md"),
     `Ask which story was just completed, then run \`npx intentdocs done <id>\`.
 \`npx intentdocs done\` prints the acceptance-criteria table first. If any \`must\` criterion is still failing or was
 never reported via \`report_criteria\`, it will list them and ask "Mark done anyway?" \u2014 only confirm that
@@ -331,8 +385,8 @@ The CLI will prompt for an optional decision or lesson learned \u2014 encourage
 Also ask if there are implementation notes to add: \`npx intentdocs note <id> "..."\`
 Both decisions and notes flow back to the project page on intentdocs.com.`
   );
-  writeFileSync2(
-    join2(commandsDir, "intent-sync.md"),
+  writeFileSync3(
+    join3(commandsDir, "intent-sync.md"),
     `# Refresh context from intentdocs
 
 ## Refresh story map summary
@@ -349,8 +403,8 @@ Run \`npx intentdocs sync --context\` \u2014 rebuilds CLAUDE.md from your projec
 
 Run \`npx intentdocs sync --context\` after updating any section on intentdocs.com.`
   );
-  writeFileSync2(
-    join2(commandsDir, "intent-propose.md"),
+  writeFileSync3(
+    join3(commandsDir, "intent-propose.md"),
     `# Propose a new change
 
 Use this when you want to plan a new feature, improvement, or fix before writing code.
@@ -374,8 +428,8 @@ stories there AND saves a local spec for the AI to reference during implementati
 - If the change is already defined in the UI, just run \`npx intentdocs sync\` instead
 `
   );
-  writeFileSync2(
-    join2(commandsDir, "intent-context.md"),
+  writeFileSync3(
+    join3(commandsDir, "intent-context.md"),
     `# Load current story context
 
 Use this to focus on a single story without loading the full story map.
@@ -398,8 +452,8 @@ Use this to focus on a single story without loading the full story map.
 The file is at \`.intent/stories/<full-story-id>.md\` \u2014 read it directly.
 `
   );
-  writeFileSync2(
-    join2(commandsDir, "intent-decide.md"),
+  writeFileSync3(
+    join3(commandsDir, "intent-decide.md"),
     `# Log an architectural or product decision
 
 Use this when you've made a decision that future agents (or teammates) should know about.
@@ -417,8 +471,8 @@ Good decisions to log:
 - "Decided not to do Z because..."
 - "This pattern is used throughout because..."`
   );
-  writeFileSync2(
-    join2(commandsDir, "intent-example.md"),
+  writeFileSync3(
+    join3(commandsDir, "intent-example.md"),
     `# Log a reference pattern for this codebase
 
 Use this when you've written code that represents the right way to do something in this project.
@@ -437,24 +491,22 @@ and are included in CLAUDE.md as Reference Patterns the next time you run \`npx
   registerMcpWithClaudeCode();
 }
 function registerMcpWithClaudeCode() {
-  const settingsPath = join2(homedir(), ".claude", "settings.json");
-  let settings = {};
-  if (existsSync2(settingsPath)) {
-    try {
-      settings = JSON.parse(readFileSync(settingsPath, "utf-8"));
-    } catch {
-    }
+  const result = registerLocalServerInMcpJson(process.cwd());
+  if (result.status === "unreadable") {
+    console.log(`  \u26A0 Couldn't read ${result.path}, so it was left as it is. Add the IntentDocs server yourself:`);
+    console.log(`      ${CLAUDE_MCP_ADD_COMMAND}`);
+  } else if (result.status === "unchanged") {
+    console.log(`  \u2713 MCP server "${LOCAL_SERVER_NAME}" already registered in .mcp.json`);
+  } else {
+    console.log(`  \u2713 Registered MCP server "${LOCAL_SERVER_NAME}" in .mcp.json \u2014 restart Claude Code and approve it when asked`);
+  }
+  if (removeLegacySettingsEntry()) {
+    console.log("  \u2713 Removed the old entry from ~/.claude/settings.json, where Claude Code doesn't read MCP servers");
   }
-  const servers = settings.mcpServers ?? {};
-  servers.intent = { command: "npx", args: ["intentdocs", "mcp"] };
-  settings.mcpServers = servers;
-  mkdirSync(dirname(settingsPath), { recursive: true });
-  writeFileSync2(settingsPath, JSON.stringify(settings, null, 2) + "\n");
-  console.log("  \u2713 Registered MCP server in ~/.claude/settings.json \u2014 restart Claude Code to activate");
 }
 function setupCursor() {
   const cwd = process.cwd();
-  const cursorRulesPath = join2(cwd, ".cursorrules");
+  const cursorRulesPath = join3(cwd, ".cursorrules");
   const cursorBlock = `
 # intentdocs Integration
 
@@ -463,6 +515,11 @@ function setupCursor() {
 2. **ARCHITECTURE.md** \u2014 technical decisions and system structure
 3. **CONVENTIONS.md** \u2014 coding patterns, naming, file structure
 
+## First run
+- No story started yet? The founder's next step is their first story:
+  claim it with \`npx intentdocs next\` (or \`start_story\` over MCP), build it,
+  report each criterion, then mark it done.
+
 ## Workflow
 - Next story: \`npx intentdocs next\`
 - Mark done: \`npx intentdocs done <id>\`
@@ -489,14 +546,14 @@ function setupCursor() {
 - Log decisions and trade-offs back to intentdocs
 - Follow patterns in CONVENTIONS.md
 `;
-  if (existsSync2(cursorRulesPath)) {
-    const existing = readFileSync(cursorRulesPath, "utf-8");
+  if (existsSync3(cursorRulesPath)) {
+    const existing = readFileSync2(cursorRulesPath, "utf-8");
     if (!existing.includes("intentdocs Integration")) {
-      writeFileSync2(cursorRulesPath, existing + "\n" + cursorBlock);
+      writeFileSync3(cursorRulesPath, existing + "\n" + cursorBlock);
       console.log("  \u2713 Updated .cursorrules");
     }
   } else {
-    writeFileSync2(cursorRulesPath, cursorBlock.trim() + "\n");
+    writeFileSync3(cursorRulesPath, cursorBlock.trim() + "\n");
     console.log("  \u2713 Created .cursorrules");
   }
   console.log(`
@@ -515,9 +572,9 @@ function setupCursor() {
 }
 function generateAgentDocs() {
   const cwd = process.cwd();
-  const archPath = join2(cwd, "ARCHITECTURE.md");
-  if (!existsSync2(archPath)) {
-    writeFileSync2(
+  const archPath = join3(cwd, "ARCHITECTURE.md");
+  if (!existsSync3(archPath)) {
+    writeFileSync3(
       archPath,
       `# Architecture
 
@@ -544,9 +601,9 @@ _Record trade-offs and why._
     );
     console.log("  \u2713 Created ARCHITECTURE.md scaffold");
   }
-  const convPath = join2(cwd, "CONVENTIONS.md");
-  if (!existsSync2(convPath)) {
-    writeFileSync2(
+  const convPath = join3(cwd, "CONVENTIONS.md");
+  if (!existsSync3(convPath)) {
+    writeFileSync3(
       convPath,
       `# Conventions
 

package/dist/{chunk-JX2RLGOM.js → chunk-K5SNF6CG.js}

@@ -5,6 +5,16 @@ import {
 // src/lib/config.ts
 import { readFileSync, writeFileSync, mkdirSync, existsSync } from "fs";
 import { join, dirname } from "path";
+function checkoutConfig(input) {
+  return {
+    apiBase: input.apiBase,
+    mapTitle: input.map.title,
+    projectId: input.project.id,
+    mapId: input.map.id,
+    workspace: input.project.workspace ? { orgId: input.project.workspace.orgId, name: input.project.workspace.name } : { orgId: null, name: null },
+    ...input.appUrl && { appUrl: input.appUrl }
+  };
+}
 var CONFIG_DIR = ".intent";
 var CONFIG_FILE = "config.json";
 function configPath() {
@@ -52,6 +62,7 @@ function requireConfig() {
 }
 
 export {
+  checkoutConfig,
   hasConfig,
   readConfig,
   writeConfig,

package/dist/{chunk-34JCN66H.js → chunk-KTGQO3AE.js}

@@ -9,6 +9,14 @@ var AuthError = class extends Error {
     this.name = "AuthError";
   }
 };
+var ApiError = class extends Error {
+  constructor(message, status, code = null) {
+    super(message);
+    this.status = status;
+    this.code = code;
+    this.name = "ApiError";
+  }
+};
 function checkoutMismatch(config, binding) {
   const checkout = config.workspace;
   if (!checkout || !checkout.orgId) return null;
@@ -42,6 +50,17 @@ async function refusalMessage(res) {
   }
   return null;
 }
+async function errorCode(res) {
+  try {
+    const body = await res.clone().json();
+    if (typeof body.error === "string") return body.error;
+    if (body.error && typeof body.error === "object" && typeof body.error.code === "string") {
+      return body.error.code;
+    }
+  } catch {
+  }
+  return null;
+}
 async function apiFetch(config, path, init) {
   const auth = getAuth();
   const mismatch = checkoutMismatch(config, auth?.binding);
@@ -65,7 +84,10 @@ async function apiFetch(config, path, init) {
       said ?? "Access denied \u2014 you may not have permission for this project. Run `npx intentdocs login` to re-authenticate."
     );
   }
-  if (!res.ok) throw new Error(`API error: ${res.status}`);
+  if (!res.ok) {
+    const said = await refusalMessage(res);
+    throw new ApiError(said ?? `API error: ${res.status}`, res.status, await errorCode(res));
+  }
   return res;
 }
 function apiUrl(config, path) {
@@ -154,6 +176,7 @@ async function retractDecision(config, decisionId, reason) {
 }
 
 export {
+  checkoutMismatch,
   syncHeaders,
   apiFetch,
   apiUrl,

package/dist/{ci-XCOXFTLB.js → ci-NOCV3XUV.js}

@@ -1,8 +1,8 @@
 import {
   ci
-} from "./chunk-6X4BORMW.js";
+} from "./chunk-65EDM7QH.js";
 import "./chunk-KPQ42YE6.js";
-import "./chunk-JX2RLGOM.js";
+import "./chunk-K5SNF6CG.js";
 import "./chunk-WRRUCCVZ.js";
 import "./chunk-XZE2XP6O.js";
 import "./chunk-UYTVTYNB.js";

package/dist/{complexity-X3IJKNNV.js → complexity-OJVM37NF.js}

@@ -9,10 +9,10 @@ import {
   apiUrl,
   listStories,
   syncHeaders
-} from "./chunk-34JCN66H.js";
+} from "./chunk-KTGQO3AE.js";
 import {
   requireConfig
-} from "./chunk-JX2RLGOM.js";
+} from "./chunk-K5SNF6CG.js";
 import "./chunk-XZE2XP6O.js";
 import "./chunk-UYTVTYNB.js";
 

package/dist/{import-prd-IJTM6FZE.js → import-prd-5FCVXCYO.js}

@@ -5,10 +5,10 @@ import {
 import {
   apiUrl,
   syncHeaders
-} from "./chunk-34JCN66H.js";
+} from "./chunk-KTGQO3AE.js";
 import {
   requireConfig
-} from "./chunk-JX2RLGOM.js";
+} from "./chunk-K5SNF6CG.js";
 import {
   closePrompt,
   confirm
@@ -19,8 +19,15 @@ import "./chunk-UYTVTYNB.js";
 // src/commands/import-prd.ts
 import { readFileSync, existsSync } from "fs";
 import ora from "ora";
-async function importPrd(filePath) {
+async function importPrd(filePath, opts = {}) {
   const config = requireConfig();
+  if (!filePath && !opts.yes) {
+    console.error("  Reading the document from standard input leaves nothing to answer the confirmation with.");
+    console.error("  Pass a file to review before importing:  npx intentdocs import prd.md");
+    console.error("  Or import without asking:                npx intentdocs import --yes < prd.md");
+    process.exitCode = 1;
+    return;
+  }
   let prdText;
   let format = "PRD";
   if (filePath) {
@@ -32,7 +39,7 @@ async function importPrd(filePath) {
     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");
+    if (process.stdin.isTTY) console.log("  Paste your PRD below (press Ctrl+D when done):\n");
     const chunks = [];
     for await (const chunk of process.stdin) {
       chunks.push(chunk);
@@ -86,7 +93,7 @@ async function importPrd(filePath) {
       }
       console.log();
     }
-    const doImport = await confirm(
+    const doImport = opts.yes ? true : await confirm(
       `  Import this story map structure?`
     );
     if (doImport) {