intentdocs 0.10.1 → 0.12.0

package/README.md

@@ -182,7 +182,7 @@ The intentdocs MCP server exposes **tools** (actions your agent can take) and **
 
 Give Claude Code or Cursor native tool and resource access to your story map.
 
-Add to `~/.claude/settings.json` (Claude Code) or your Cursor MCP config:
+`intent setup` registers it for Claude Code in the project's `.mcp.json`. To add it yourself, run `claude mcp add --scope project intent -- npx intentdocs mcp` in the project, or add this to `.mcp.json` (Claude Code) or your Cursor MCP config:
 
 ```json
 {

package/dist/{chunk-6X4BORMW.js → chunk-5GATVQEI.js}

@@ -4,7 +4,7 @@ import {
 } from "./chunk-KPQ42YE6.js";
 import {
   requireConfig
-} from "./chunk-JX2RLGOM.js";
+} from "./chunk-RGFGTIIH.js";
 import {
   closePrompt,
   confirm,

package/dist/chunk-64I7RLP3.js

@@ -0,0 +1,171 @@
+import {
+  bindingLabel,
+  clearAuth,
+  getAuth,
+  saveAuth,
+  validateAuth
+} from "./chunk-XZE2XP6O.js";
+import {
+  API_BASE
+} from "./chunk-UYTVTYNB.js";
+
+// src/commands/login.ts
+import { exec } from "child_process";
+function finishLogin(data) {
+  saveAuth({
+    token: data.token,
+    apiBase: API_BASE,
+    ...data.userId && { userId: data.userId },
+    binding: data.binding ?? null,
+    ...data.posthogKey && { posthogKey: data.posthogKey },
+    ...data.posthogHost && { posthogHost: data.posthogHost }
+  });
+  console.log(`
+
+\u2705 Logged in as ${data.userId ?? "unknown user"} \u2014 token ${bindingLabel(data.binding)}
+`);
+  if (data.binding?.approvalStatus === "pending") {
+    console.log("An admin has been asked to approve it. Until they do, this token reads your personal projects only.\n");
+  }
+  console.log("You can now run: npx intentdocs init");
+  console.log(
+    "Optional: add your Anthropic API key to unlock AI features on any plan \u2014 npx intentdocs keys set"
+  );
+}
+function openBrowser(url) {
+  const cmd = process.platform === "darwin" ? `open "${url}"` : process.platform === "win32" ? `start "${url}"` : `xdg-open "${url}"`;
+  exec(cmd);
+}
+function sleep(ms) {
+  return new Promise((r) => setTimeout(r, ms));
+}
+async function login() {
+  const existing = getAuth();
+  if (existing) {
+    const result = await validateAuth();
+    if (result.valid) {
+      console.log(`Already logged in (user: ${result.userId}). Run \`intentdocs logout\` to switch accounts.`);
+      return;
+    }
+    switch (result.reason) {
+      case "revoked":
+        console.log("Your stored token has been revoked. Starting a fresh login...\n");
+        break;
+      case "not_found":
+        console.log("Your stored token is no longer valid. Starting a fresh login...\n");
+        break;
+      case "network_error":
+        console.error("Could not reach intentdocs.com to verify your token. Check your internet connection and try again.");
+        process.exit(1);
+        break;
+    }
+    clearAuth();
+  }
+  console.log("Logging in to intentdocs...\n");
+  const res = await fetch(`${API_BASE}/api/cli/auth`, { method: "POST" });
+  if (!res.ok) {
+    console.error("Failed to start login flow. Try again.");
+    process.exit(1);
+  }
+  const { code } = await res.json();
+  const authUrl = `${API_BASE}/cli/auth?code=${code}`;
+  console.log("Opening browser to authorize...");
+  console.log(`If it doesn't open, visit: ${authUrl}
+`);
+  openBrowser(authUrl);
+  const POLL_INTERVAL_MS = 3e3;
+  const INITIAL_TIMEOUT_S = 300;
+  const EXTEND_TIMEOUT_S = 120;
+  let totalWaitedS = 0;
+  let phase = "initial";
+  let timeoutS = INITIAL_TIMEOUT_S;
+  while (totalWaitedS < timeoutS) {
+    const elapsed = totalWaitedS;
+    const minutesLeft = Math.ceil((timeoutS - elapsed) / 60);
+    if (elapsed === 0) {
+      process.stdout.write("Waiting for browser approval...");
+    } else if (elapsed % 30 === 0) {
+      process.stdout.write(`
+  Still waiting for approval (${minutesLeft}m remaining)...`);
+    } else {
+      process.stdout.write(".");
+    }
+    await sleep(POLL_INTERVAL_MS);
+    totalWaitedS += POLL_INTERVAL_MS / 1e3;
+    try {
+      const checkRes = await fetch(`${API_BASE}/api/cli/auth?code=${code}`);
+      if (!checkRes.ok) continue;
+      const data = await checkRes.json();
+      if (data.status === "approved" && data.token) {
+        finishLogin(data);
+        return;
+      }
+      if (data.status === "expired") {
+        console.error("\n\nThe server-side login request expired. Run `npx intentdocs login` to start a new one.");
+        process.exit(1);
+      }
+    } catch {
+    }
+  }
+  if (phase === "initial") {
+    console.log("\n\nThe initial wait has ended. The browser approval hasn't come through yet.");
+    console.log("This can happen if you needed to create an account or got distracted.\n");
+    const rl = await import("readline");
+    const iface = rl.createInterface({ input: process.stdin, output: process.stdout });
+    const answer = await new Promise(
+      (resolve) => iface.question("Keep waiting? (y/n): ", resolve)
+    );
+    iface.close();
+    if (answer.trim().toLowerCase().startsWith("y")) {
+      phase = "extended";
+      timeoutS = totalWaitedS + EXTEND_TIMEOUT_S;
+      console.log(`
+Waiting ${EXTEND_TIMEOUT_S / 60} more minutes...`);
+      while (totalWaitedS < timeoutS) {
+        const minutesLeft = Math.ceil((timeoutS - totalWaitedS) / 60);
+        if (Math.floor(totalWaitedS) % 30 === 0 && totalWaitedS > INITIAL_TIMEOUT_S) {
+          process.stdout.write(`
+  Still waiting (${minutesLeft}m remaining)...`);
+        } else {
+          process.stdout.write(".");
+        }
+        await sleep(POLL_INTERVAL_MS);
+        totalWaitedS += POLL_INTERVAL_MS / 1e3;
+        try {
+          const checkRes = await fetch(`${API_BASE}/api/cli/auth?code=${code}`);
+          if (!checkRes.ok) continue;
+          const data = await checkRes.json();
+          if (data.status === "approved" && data.token) {
+            finishLogin(data);
+            return;
+          }
+          if (data.status === "expired") {
+            console.error("\n\nThe server-side login request expired. Run `npx intentdocs login` to start a new one.");
+            process.exit(1);
+          }
+        } catch {
+        }
+      }
+    }
+  }
+  console.error("\n\nLogin timed out. Run `npx intentdocs login` to try again.");
+  console.error("If the browser page is still open, complete it and re-run the command \u2014 your approval will still work within 10 minutes.\n");
+  process.exit(1);
+}
+async function logout() {
+  const { existsSync, unlinkSync } = await import("fs");
+  const { join } = await import("path");
+  const { homedir } = await import("os");
+  const authFile = join(homedir(), ".intent", "auth.json");
+  if (existsSync(authFile)) {
+    unlinkSync(authFile);
+    console.log("Logged out.");
+  } else {
+    console.log("Not logged in.");
+  }
+}
+
+export {
+  login,
+  logout
+};

package/dist/{chunk-F52HPVNQ.js → chunk-BNEU6TLJ.js}

@@ -79,9 +79,56 @@ var CONTEXT_DIR = ".intent/stories";
 function storyContextPath(storyId) {
   return join(process.cwd(), CONTEXT_DIR, `${storyId}.md`);
 }
+var HAND_WRITTEN_SECTIONS = {
+  "Approach": "_Plan your approach here",
+  "Implementation notes": "_Notes added via",
+  "Decisions": "_Log decisions via",
+  "Relevant files": "_Add file paths here"
+};
+var GENERATED_HEADINGS = /* @__PURE__ */ new Set([
+  "User story",
+  "Done when",
+  "Design references",
+  "Spec",
+  "Implementation Plan",
+  ...Object.keys(HAND_WRITTEN_SECTIONS)
+]);
+function readHandWrittenSections(content) {
+  const body = content.replace(/\n---\s*\n\s*Mark done:[^\n]*\s*$/, "\n");
+  const sections = /* @__PURE__ */ new Map();
+  let current = null;
+  let buffer = [];
+  const flush = () => {
+    if (current && current in HAND_WRITTEN_SECTIONS) {
+      const placeholder = HAND_WRITTEN_SECTIONS[current];
+      const text = buffer.filter((line) => !line.trim().startsWith(placeholder)).join("\n").trim();
+      if (text) sections.set(current, text);
+    }
+  };
+  for (const line of body.split("\n")) {
+    const heading = line.match(/^## (.+?)\s*$/);
+    if (heading && GENERATED_HEADINGS.has(heading[1])) {
+      flush();
+      current = heading[1];
+      buffer = [];
+      continue;
+    }
+    if (current) buffer.push(line);
+  }
+  flush();
+  return sections;
+}
 function writeStoryContext(story) {
   const dir = join(process.cwd(), CONTEXT_DIR);
   if (!existsSync(dir)) mkdirSync(dir, { recursive: true });
+  const path = storyContextPath(story.id);
+  const kept = existsSync(path) ? readHandWrittenSections(readFileSync(path, "utf-8")) : /* @__PURE__ */ new Map();
+  const section = (heading, placeholder) => [
+    `## ${heading}`,
+    ``,
+    kept.get(heading) ?? placeholder,
+    ``
+  ];
   const acLines = story.acceptance_criteria.length ? story.acceptance_criteria.flatMap((ac) => renderCriterionLines(ac)).join("\n") : "_No acceptance criteria defined._";
   const specSection = story.notes?.trim() ? [`## Spec`, ``, story.notes.trim(), ``] : [];
   const designRefs = story.design_refs ?? [];
@@ -96,13 +143,10 @@ function writeStoryContext(story) {
     plan.markdown,
     ``,
     ...plan.files_to_create?.length ? [`### Files to create`, ``, ...plan.files_to_create.map((f) => `- \`${f}\``), ``] : [],
-    ...plan.files_to_modify?.length ? [`### Files to modify`, ``, ...plan.files_to_modify.map((f) => `- \`${f}\``), ``] : []
-  ] : [
-    `## Approach`,
-    ``,
-    `_Plan your approach here before writing code._`,
-    ``
-  ];
+    ...plan.files_to_modify?.length ? [`### Files to modify`, ``, ...plan.files_to_modify.map((f) => `- \`${f}\``), ``] : [],
+    // An approach written before the plan arrived is still the developer's.
+    ...kept.has("Approach") ? section("Approach", "") : []
+  ] : section("Approach", `_Plan your approach here before writing code._`);
   const md = [
     `# ${story.title}`,
     ``,
@@ -122,23 +166,13 @@ function writeStoryContext(story) {
     ...designRefsSection,
     ...specSection,
     ...approachSection,
-    `## Implementation notes`,
-    ``,
-    `_Notes added via \`npx intentdocs note ${storyRef(story)} "..."\`_`,
-    ``,
-    `## Decisions`,
-    ``,
-    `_Log decisions via \`npx intentdocs decide "..." -s ${storyRef(story)}\`_`,
-    ``,
-    `## Relevant files`,
-    ``,
-    `_Add file paths here as you explore the codebase._`,
-    ``,
+    ...section("Implementation notes", `_Notes added via \`npx intentdocs note ${storyRef(story)} "..."\`_`),
+    ...section("Decisions", `_Log decisions via \`npx intentdocs decide "..." -s ${storyRef(story)}\`_`),
+    ...section("Relevant files", `_Add file paths here as you explore the codebase._`),
     `---`,
     ``,
     `Mark done: \`npx intentdocs done ${storyRef(story)}\``
   ].join("\n");
-  const path = storyContextPath(story.id);
   writeFileSync(path, md);
   return path;
 }

package/dist/chunk-GFKZ5CRL.js

@@ -0,0 +1,12 @@
+// src/lib/notes.ts
+function appendToNotes(existing, note) {
+  const before = existing?.trimEnd() ?? "";
+  const added = note.trim();
+  return before ? `${before}
+
+${added}` : added;
+}
+
+export {
+  appendToNotes
+};

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/{chunk-NHNBCNND.js → chunk-Q6BSSJK5.js}

@@ -1,9 +1,11 @@
 import {
   getContext
-} from "./chunk-34JCN66H.js";
+} from "./chunk-KTGQO3AE.js";
 import {
+  checkoutConfig,
+  hasConfig,
   writeConfig
-} from "./chunk-JX2RLGOM.js";
+} from "./chunk-RGFGTIIH.js";
 import {
   ask,
   closePrompt,
@@ -20,8 +22,36 @@ import {
 // src/commands/scope.ts
 import { writeFileSync, existsSync } from "fs";
 import { join } from "path";
+async function connectCheckout(apiBase, projectId) {
+  if (hasConfig()) {
+    console.log("  This checkout is already connected (.intent/config.json) \u2014 left as is.");
+    console.log("  Run `npx intentdocs sync` to refresh it, or remove .intent/config.json and run `npx intentdocs init` to connect it to this project.\n");
+    return null;
+  }
+  const mapsRes = await authenticatedFetch(`/api/cli/projects/${projectId}/maps`);
+  if (!mapsRes.ok) {
+    console.log("  \u26A0 Could not fetch the project's story map \u2014 run `npx intentdocs init` to connect.\n");
+    return null;
+  }
+  const { maps, appUrl } = await mapsRes.json();
+  const map = maps[0];
+  if (!map) {
+    console.log("  \u26A0 The project has no story map yet \u2014 run `npx intentdocs init` once it has one.\n");
+    return null;
+  }
+  let workspace = null;
+  const projectsRes = await authenticatedFetch("/api/cli/projects");
+  if (projectsRes.ok) {
+    const { projects } = await projectsRes.json();
+    workspace = projects.find((p) => p.id === projectId)?.workspace ?? null;
+  }
+  const config = checkoutConfig({ apiBase, project: { id: projectId, workspace }, map, appUrl });
+  writeConfig(config);
+  console.log("  \u2713 Connected\n");
+  return config;
+}
 async function scope(projectId) {
-  await requireValidAuth();
+  const auth = await requireValidAuth();
   if (!projectId) {
     projectId = await ask("  Project ID (from `intentdocs start`): ");
   }
@@ -112,18 +142,8 @@ async function scope(projectId) {
     console.log("  \u2713 Blueprint generated (couldn't parse summary)\n");
   }
   console.log("\n  Connecting project to your codebase...");
-  const mapsRes = await authenticatedFetch(
-    `/api/storymapper/project/${projectId}`
-  );
-  let mapId = null;
-  if (mapsRes.ok) {
-    const mapData = await mapsRes.json();
-    if (mapData.mapId) mapId = mapData.mapId;
-  }
-  if (mapId) {
-    const config = { apiBase: API_BASE, projectId, mapId };
-    writeConfig(config);
-    console.log("  \u2713 Connected\n");
+  const config = await connectCheckout(auth.apiBase, projectId);
+  if (config) {
     try {
       const md = await getContext(config);
       writeFileSync(join(process.cwd(), "INTENT.md"), md);
@@ -176,7 +196,7 @@ async function scope(projectId) {
     "  Configure your AI tool (Claude Code / Cursor) with intentdocs agent workflows?"
   );
   if (wantSetup) {
-    const { setup } = await import("./setup-WSYIG2CR.js");
+    const { setup } = await import("./setup-W4PKG6GB.js");
     await setup();
     return;
   }
@@ -226,5 +246,6 @@ ${projectId}
 }
 
 export {
+  connectCheckout,
   scope
 };