intentdocs 0.10.0 → 0.11.0

package/README.md

@@ -98,6 +98,11 @@ intent sync          # Refresh INTENT.md
 intent sync --context  # Regenerate CLAUDE.md from your project page
 ```
 
+`intent` is a short alias for typing. Another tool on your machine may also be
+called `intent`, so everything the CLI writes for your agent (CLAUDE.md, slash
+commands, hints) spells commands as `npx intentdocs …`, which always runs this
+package.
+
 ---
 
 ## All Commands
@@ -177,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-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-IDNUBI2P.js → chunk-65EDM7QH.js}

@@ -1,10 +1,10 @@
 import {
   captureCli,
   shutdownCliAnalytics
-} from "./chunk-HEHHSSUM.js";
+} from "./chunk-KPQ42YE6.js";
 import {
   requireConfig
-} from "./chunk-UF535HZL.js";
+} from "./chunk-K5SNF6CG.js";
 import {
   closePrompt,
   confirm,
@@ -13,7 +13,7 @@ import {
 import {
   authenticatedFetch,
   requireValidAuth
-} from "./chunk-LXQXJULN.js";
+} from "./chunk-XZE2XP6O.js";
 import {
   canonicalApiBase
 } from "./chunk-UYTVTYNB.js";
@@ -173,7 +173,7 @@ async function listKeys(projectId) {
 async function reportStatus(projectId) {
   const keys = (await listKeys(projectId)).filter((k) => !k.revoked_at);
   if (keys.length === 0) {
-    console.log("No CI key yet. Run `intentdocs ci` to set up test reporting.");
+    console.log("No CI key yet. Run `npx intentdocs ci` to set up test reporting.");
     return;
   }
   const reported = keys.filter((k) => k.last_report_at);
@@ -198,7 +198,7 @@ async function ci(opts = {}) {
   await requireValidAuth();
   const projectId = config.projectId;
   if (!projectId) {
-    console.error("This checkout has no project id. Run `intentdocs init` to reconnect.");
+    console.error("This checkout has no project id. Run `npx intentdocs init` to reconnect.");
     process.exit(1);
   }
   if (opts.status) {
@@ -278,7 +278,7 @@ Tell your agent to save each test with its file and full name so CI results can
       { project: projectId }
     );
     console.log(`
-After your next default-branch CI run, check how results matched with: intentdocs ci --status
+After your next default-branch CI run, check how results matched with: npx intentdocs ci --status
 `);
   } finally {
     closePrompt();

package/dist/{chunk-NFIXRIHM.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 \`intentdocs note ${storyRef(story)} "..."\`_`,
-    ``,
-    `## Decisions`,
-    ``,
-    `_Log decisions via \`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: \`intentdocs done ${storyRef(story)}\``
+    `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-5USVG4DW.js → chunk-ID4B5RZ2.js}

@@ -1,9 +1,11 @@
 import {
   getContext
-} from "./chunk-YUW3W43S.js";
+} from "./chunk-KTGQO3AE.js";
 import {
+  checkoutConfig,
+  hasConfig,
   writeConfig
-} from "./chunk-UF535HZL.js";
+} from "./chunk-K5SNF6CG.js";
 import {
   ask,
   closePrompt,
@@ -12,7 +14,7 @@ import {
 import {
   authenticatedFetch,
   requireValidAuth
-} from "./chunk-LXQXJULN.js";
+} from "./chunk-XZE2XP6O.js";
 import {
   API_BASE
 } from "./chunk-UYTVTYNB.js";
@@ -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-YLUPBLK6.js");
+    const { setup } = await import("./setup-UILQVYIB.js");
     await setup();
     return;
   }
@@ -184,10 +204,10 @@ async function scope(projectId) {
   \u2705 Your project is scoped and ready to build!
 
   Next steps:
-    \u2022 intent setup          \u2014 configure your AI tool
-    \u2022 intent status         \u2014 see your story map progress
-    \u2022 intent next           \u2014 see what to build first
-    \u2022 intent done <id>      \u2014 mark stories as you complete them
+    \u2022 npx intentdocs setup          \u2014 configure your AI tool
+    \u2022 npx intentdocs status         \u2014 see your story map progress
+    \u2022 npx intentdocs next           \u2014 see what to build first
+    \u2022 npx intentdocs 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.
@@ -226,5 +246,6 @@ ${projectId}
 }
 
 export {
+  connectCheckout,
   scope
 };