intentdocs 0.8.0

package/dist/keys-EDWET3WG.js

@@ -0,0 +1,90 @@
+import {
+  ask,
+  closePrompt
+} from "./chunk-WPVDURTJ.js";
+import {
+  requireAuth
+} from "./chunk-PCNDP5SX.js";
+
+// src/commands/keys.ts
+var KEYS_DOC_URL = "https://console.anthropic.com/settings/keys";
+async function byokRequest(method, body) {
+  const auth = requireAuth();
+  const res = await fetch(`${auth.apiBase}/api/settings/byok`, {
+    method,
+    headers: {
+      Authorization: `Bearer ${auth.token}`,
+      ...body ? { "Content-Type": "application/json" } : {}
+    },
+    ...body ? { body: JSON.stringify(body) } : {}
+  });
+  const data = await res.json().catch(() => null);
+  return { ok: res.ok, status: res.status, data };
+}
+async function keysSet(key) {
+  let value = key?.trim();
+  if (!value) {
+    console.log("\n  Optionally add your Anthropic API key to unlock AI features on any plan.");
+    console.log("  Your key is encrypted at rest and only used for your AI operations.");
+    console.log(`  Get one at: ${KEYS_DOC_URL}
+`);
+    value = (await ask("  Anthropic API key (sk-ant-...): ")).trim();
+    closePrompt();
+  }
+  if (!value) {
+    console.error("  No key provided. Run `intent keys set` to try again.");
+    process.exit(1);
+  }
+  try {
+    const { ok, data } = await byokRequest("POST", { key: value });
+    if (!ok) {
+      console.error(`
+  \u2717 ${data?.message ?? "Failed to save your key. Try again."}`);
+      process.exit(1);
+    }
+    console.log(`
+  \u2705 Key saved: ${data?.maskedKey}`);
+    console.log("  AI commands (complexity, research, import) now run on your key.\n");
+  } catch {
+    console.error("\n  \u2717 Could not reach intentdocs. Check your connection and try again.");
+    process.exit(1);
+  }
+}
+async function keysStatus() {
+  try {
+    const { ok, data } = await byokRequest("GET");
+    if (!ok) {
+      console.error("  \u2717 Failed to fetch key status.");
+      process.exit(1);
+    }
+    if (data?.enabled) {
+      console.log(`
+  Anthropic API key: ${data.maskedKey ?? "(stored but unreadable \u2014 re-run `intent keys set`)"}`);
+      console.log("  AI features run on your key.\n");
+    } else {
+      console.log("\n  No Anthropic API key set.");
+      console.log("  Add one with `intent keys set` to unlock AI features on any plan.\n");
+    }
+  } catch {
+    console.error("  \u2717 Could not reach intentdocs. Check your connection and try again.");
+    process.exit(1);
+  }
+}
+async function keysRemove() {
+  try {
+    const { ok } = await byokRequest("DELETE");
+    if (!ok) {
+      console.error("  \u2717 Failed to remove your key.");
+      process.exit(1);
+    }
+    console.log("\n  Key removed. AI features fall back to your plan's platform limits.\n");
+  } catch {
+    console.error("  \u2717 Could not reach intentdocs. Check your connection and try again.");
+    process.exit(1);
+  }
+}
+export {
+  keysRemove,
+  keysSet,
+  keysStatus
+};

package/dist/log-TT2UCJP7.js

@@ -0,0 +1,94 @@
+import {
+  appendNoteToContext,
+  storyContextPath
+} from "./chunk-6FGYJ3W2.js";
+import {
+  ask,
+  closePrompt
+} from "./chunk-WPVDURTJ.js";
+import {
+  apiFetch
+} from "./chunk-6XKB6RTU.js";
+import {
+  requireConfig
+} from "./chunk-ICOMMHKG.js";
+import "./chunk-PCNDP5SX.js";
+
+// src/commands/log.ts
+async function logDecision(title, opts) {
+  const config = requireConfig();
+  if (!title) {
+    title = await ask("  Decision title: ");
+  }
+  let description = opts?.description;
+  if (!description) {
+    description = await ask("  Description (what was decided and why): ");
+  }
+  if (!title?.trim() || !description?.trim()) {
+    console.log("  Title and description required.");
+    closePrompt();
+    return;
+  }
+  const res = await apiFetch(config, "/decisions", {
+    method: "POST",
+    headers: { "Content-Type": "application/json" },
+    body: JSON.stringify({
+      title: title.trim(),
+      description: description.trim(),
+      category: opts?.category ?? "technical",
+      story_id: opts?.story ?? void 0
+    })
+  });
+  if (res.ok) {
+    console.log(`  \u2713 Decision logged: ${title}`);
+  } else {
+    console.error("  Failed to log decision.");
+  }
+  closePrompt();
+}
+async function logNote(storyId, note) {
+  const config = requireConfig();
+  if (!note) {
+    note = await ask("  Note: ");
+  }
+  if (!note?.trim()) {
+    console.log("  Note required.");
+    closePrompt();
+    return;
+  }
+  const listRes = await apiFetch(config, "/stories");
+  if (!listRes.ok) {
+    console.error("  Failed to fetch stories.");
+    closePrompt();
+    return;
+  }
+  const data = await listRes.json();
+  const match = data.stories.find((s) => s.id.startsWith(storyId));
+  if (!match) {
+    console.error(`  No story found matching "${storyId}"`);
+    closePrompt();
+    return;
+  }
+  const res = await apiFetch(config, "/stories", {
+    method: "PATCH",
+    headers: { "Content-Type": "application/json" },
+    body: JSON.stringify({
+      stories: [{ id: match.id, notes: note.trim() }]
+    })
+  });
+  if (res.ok) {
+    console.log(`  \u2713 Note added to: ${match.title.slice(0, 60)}`);
+  } else {
+    console.error("  Failed to add note.");
+  }
+  const appended = appendNoteToContext(match.id, note.trim());
+  if (appended) {
+    const relPath = storyContextPath(match.id).replace(process.cwd() + "/", "");
+    console.log(`  \u2713 Updated local context: ${relPath}`);
+  }
+  closePrompt();
+}
+export {
+  logDecision,
+  logNote
+};

package/dist/map-extract-I3AACTGL.js

@@ -0,0 +1,98 @@
+import {
+  requireConfig
+} from "./chunk-ICOMMHKG.js";
+
+// src/commands/map-extract.ts
+function mapExtract() {
+  requireConfig();
+  const prompt = `You are reverse-engineering a *user-facing story map* from an existing codebase for intentdocs. Your job is to describe _what real customers do in this product_ \u2014 not to document the code. Work only from evidence in the repository. Do not invent product intent.
+
+1. Investigate (read-only)
+Build an understanding of the product from these sources, in roughly this priority:
+\u2022 User entry points \u2014 routes/pages (e.g. app/, pages/, router configs), and the navigation between them. These are the strongest signal for what users _do_.
+\u2022 Auth & access boundaries \u2014 what's public vs. authenticated vs. role-gated. This tells you who each activity is _for_.
+\u2022 API surface customers hit \u2014 request handlers, server actions, GraphQL/REST endpoints that are triggered by user actions (not internal cron/admin-only jobs).
+\u2022 Data model \u2014 DB schema, migrations, ORM models. Extract the core entities and their relationships.
+\u2022 Stack \u2014 read package.json / lockfiles / framework config to identify the actual frameworks, auth, DB, and payment providers in use.
+\u2022 Billing / plans \u2014 if there's a payments integration, capture the plans and what each gates.
+
+2. Rules of evidence
+\u2022 Map only user-facing behavior. Exclude dead code, half-built features behind disabled flags, internal tooling, admin-only scripts, and pure infrastructure.
+\u2022 If a feature exists in code but you can't tell whether it's live or what user need it serves, do not guess \u2014 add it to open_questions instead.
+\u2022 Prefer describing activities in the user's language ("Invite a teammate"), not the code's ("POST /api/memberships").
+\u2022 When features appear behind a paywall/plan gate, note which plan unlocks them.
+
+3. Output \u2014 write storymap.json to the repo root
+Emit only valid JSON in exactly this shape. No prose, no markdown fences in the file.
+
+{
+  "schema_version": "1",
+  "source": "brownfield-extraction",
+  "product_summary": "1-2 sentences: what this product does and for whom.",
+  "backbone": [
+    {
+      "activity": "High-level thing a user does (backbone step)",
+      "tasks": [
+        {
+          "task": "A concrete task under this activity",
+          "stories": [
+            {
+              "story": "As a <role>, I can <do something> so that <outcome>",
+              "evidence": "file path(s) or route that prove this exists",
+              "plan_gate": "free | pro | team | null",
+              "confidence": "high | medium | low"
+            }
+          ]
+        }
+      ]
+    }
+  ],
+  "data_model": [
+    {
+      "entity": "EntityName",
+      "description": "what it represents to the user",
+      "key_fields": ["field_a", "field_b"],
+      "relationships": ["belongs_to X", "has_many Y"],
+      "evidence": "migration or model file path"
+    }
+  ],
+  "build_order": [
+    "Ordered list of the major capabilities as they appear to have been built / layered"
+  ],
+  "critical_assumptions": [
+    "Assumptions this product's design bakes in (e.g. 'users have a GitHub repo')"
+  ],
+  "open_questions": [
+    "Things you could NOT determine from code and need the founder to confirm"
+  ],
+  "stack": {
+    "framework": "",
+    "auth": "",
+    "database": "",
+    "payments": "",
+    "ai": ""
+  }
+}
+
+Field rules:
+\u2022 Every story MUST start with "As a " or "As an " followed by a role. Example: "As a founder, I can invite teammates so that we can collaborate". The importer will reject stories that don't match this format.
+\u2022 Activities have only two fields: "activity" and "tasks". Do NOT add "user_role" or any other field to activities.
+\u2022 Every story MUST include an evidence path. If you have no evidence, it doesn't belong in the backbone \u2014 move it to open_questions.
+\u2022 confidence: "low" is expected and useful. Be honest; a low-confidence story the founder can correct is worth more than a confident wrong one.
+\u2022 Keep the backbone to the ~5-9 activities that define the product. Don't flatten every endpoint into its own activity.
+
+4. Hand back to intentdocs
+After writing storymap.json, run:
+
+intent map import ./storymap.json
+
+Then tell me (the founder): a one-paragraph summary of the map you produced, the count of stories by confidence level, and the top open questions you need me to answer.`;
+  console.log("\n  Copy the prompt below and paste it into your coding agent");
+  console.log("  (Claude Code, Cursor, etc.) from the root of your repo.\n");
+  console.log("  \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\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\n");
+  console.log(prompt);
+  console.log("\n  \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\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\n");
+}
+export {
+  mapExtract
+};

package/dist/map-import-IYUMRASO.js

@@ -0,0 +1,358 @@
+import {
+  closePrompt,
+  confirm
+} from "./chunk-WPVDURTJ.js";
+import {
+  isPlanGated,
+  printUpgradeMessage
+} from "./chunk-ITQUQYWB.js";
+import {
+  apiUrl
+} from "./chunk-6XKB6RTU.js";
+import {
+  requireConfig
+} from "./chunk-ICOMMHKG.js";
+import "./chunk-PCNDP5SX.js";
+
+// src/commands/map-import.ts
+import { readFileSync, existsSync } from "fs";
+import ora from "ora";
+function validateString(value, fieldName, maxLength) {
+  if (typeof value !== "string") {
+    throw new Error(`${fieldName} must be a string`);
+  }
+  const trimmed = value.trim();
+  if (!trimmed) {
+    throw new Error(`${fieldName} cannot be empty`);
+  }
+  if (trimmed.length > maxLength) {
+    throw new Error(
+      `${fieldName} exceeds max length of ${maxLength} characters`
+    );
+  }
+  if (/[\x00-\x08\x0b\x0c\x0e-\x1f\x7f]/.test(trimmed)) {
+    throw new Error(`${fieldName} contains invalid control characters`);
+  }
+  return trimmed;
+}
+function validateStringArray(value, fieldName, maxItems, itemMaxLength) {
+  if (!Array.isArray(value)) {
+    throw new Error(`${fieldName} must be an array`);
+  }
+  if (value.length > maxItems) {
+    throw new Error(`${fieldName} exceeds max items of ${maxItems}`);
+  }
+  return value.map((item, idx) => {
+    return validateString(
+      item,
+      `${fieldName}[${idx}]`,
+      itemMaxLength
+    );
+  });
+}
+function validateConfidence(value) {
+  if (typeof value !== "string") {
+    throw new Error("Confidence must be a string");
+  }
+  if (!["high", "medium", "low"].includes(value)) {
+    throw new Error(
+      `Confidence must be one of: high, medium, low (got: ${value})`
+    );
+  }
+  return value;
+}
+function validatePlanGate(value) {
+  if (value === null || value === void 0) {
+    return null;
+  }
+  if (typeof value !== "string") {
+    throw new Error("plan_gate must be a string or null");
+  }
+  if (!["free", "pro", "team"].includes(value)) {
+    throw new Error(
+      `plan_gate must be one of: free, pro, team, null (got: ${value})`
+    );
+  }
+  return value;
+}
+function validateStory(value, actIdx, taskIdx, storyIdx) {
+  if (typeof value !== "object" || value === null) {
+    throw new Error(
+      `Story [${actIdx}][${taskIdx}][${storyIdx}] must be an object`
+    );
+  }
+  const obj = value;
+  const story = validateString(
+    obj.story,
+    `Story [${actIdx}][${taskIdx}][${storyIdx}].story`,
+    500
+  );
+  const evidence = validateString(
+    obj.evidence,
+    `Story [${actIdx}][${taskIdx}][${storyIdx}].evidence`,
+    500
+  );
+  const confidence = validateConfidence(obj.confidence);
+  if (!story.toLowerCase().startsWith("as a ") && !story.toLowerCase().startsWith("as an ")) {
+    throw new Error(
+      `Story [${actIdx}][${taskIdx}][${storyIdx}] should follow the format: "As a..., I can... so that..."`
+    );
+  }
+  const plan_gate = "plan_gate" in obj ? validatePlanGate(obj.plan_gate) : null;
+  const allowedKeys = /* @__PURE__ */ new Set(["story", "evidence", "plan_gate", "confidence"]);
+  for (const key of Object.keys(obj)) {
+    if (!allowedKeys.has(key)) {
+      throw new Error(
+        `Story [${actIdx}][${taskIdx}][${storyIdx}] contains unknown field: ${key}`
+      );
+    }
+  }
+  return {
+    story,
+    evidence,
+    confidence,
+    ...plan_gate && { plan_gate }
+  };
+}
+function validateTask(value, actIdx, taskIdx) {
+  if (typeof value !== "object" || value === null) {
+    throw new Error(`Task [${actIdx}][${taskIdx}] must be an object`);
+  }
+  const obj = value;
+  const task = validateString(
+    obj.task,
+    `Task [${actIdx}][${taskIdx}].task`,
+    200
+  );
+  if (!Array.isArray(obj.stories)) {
+    throw new Error(`Task [${actIdx}][${taskIdx}].stories must be an array`);
+  }
+  if (obj.stories.length === 0) {
+    throw new Error(
+      `Task [${actIdx}][${taskIdx}].stories must have at least 1 story`
+    );
+  }
+  if (obj.stories.length > 50) {
+    throw new Error(
+      `Task [${actIdx}][${taskIdx}].stories exceeds max 50 items`
+    );
+  }
+  const stories = obj.stories.map(
+    (s, sIdx) => validateStory(s, actIdx, taskIdx, sIdx)
+  );
+  const allowedKeys = /* @__PURE__ */ new Set(["task", "stories"]);
+  for (const key of Object.keys(obj)) {
+    if (!allowedKeys.has(key)) {
+      throw new Error(
+        `Task [${actIdx}][${taskIdx}] contains unknown field: ${key}`
+      );
+    }
+  }
+  return { task, stories };
+}
+function validateActivity(value, actIdx) {
+  if (typeof value !== "object" || value === null) {
+    throw new Error(`Activity [${actIdx}] must be an object`);
+  }
+  const obj = value;
+  const activity = validateString(
+    obj.activity,
+    `Activity [${actIdx}].activity`,
+    200
+  );
+  if (!Array.isArray(obj.tasks)) {
+    throw new Error(`Activity [${actIdx}].tasks must be an array`);
+  }
+  if (obj.tasks.length === 0) {
+    throw new Error(`Activity [${actIdx}].tasks must have at least 1 task`);
+  }
+  if (obj.tasks.length > 30) {
+    throw new Error(`Activity [${actIdx}].tasks exceeds max 30 items`);
+  }
+  const tasks = obj.tasks.map((t, tIdx) => validateTask(t, actIdx, tIdx));
+  const allowedKeys = /* @__PURE__ */ new Set(["activity", "tasks"]);
+  for (const key of Object.keys(obj)) {
+    if (!allowedKeys.has(key)) {
+      throw new Error(`Activity [${actIdx}] contains unknown field: ${key}`);
+    }
+  }
+  return { activity, tasks };
+}
+function validateStorymapJSON(data) {
+  if (typeof data !== "object" || data === null) {
+    throw new Error("Storymap must be a JSON object");
+  }
+  const obj = data;
+  if (obj.schema_version !== "1") {
+    throw new Error(
+      `schema_version must be "1" (got: ${JSON.stringify(obj.schema_version)})`
+    );
+  }
+  const product_summary = validateString(
+    obj.product_summary,
+    "product_summary",
+    1e3
+  );
+  if (!Array.isArray(obj.backbone)) {
+    throw new Error("backbone must be an array");
+  }
+  if (obj.backbone.length < 1 || obj.backbone.length > 20) {
+    throw new Error(
+      "backbone must have between 1 and 20 activities (got: " + obj.backbone.length + ")"
+    );
+  }
+  const backbone = obj.backbone.map((act, idx) => validateActivity(act, idx));
+  let open_questions = [];
+  if ("open_questions" in obj && obj.open_questions !== null) {
+    open_questions = validateStringArray(
+      obj.open_questions,
+      "open_questions",
+      50,
+      500
+    );
+  }
+  const source = typeof obj.source === "string" ? obj.source.trim() : "unknown";
+  const allowedKeys = /* @__PURE__ */ new Set([
+    "schema_version",
+    "source",
+    "product_summary",
+    "backbone",
+    "data_model",
+    "build_order",
+    "critical_assumptions",
+    "open_questions",
+    "stack"
+  ]);
+  for (const key of Object.keys(obj)) {
+    if (!allowedKeys.has(key)) {
+      throw new Error(`Unknown top-level field: ${key}`);
+    }
+  }
+  const result = {
+    schema_version: "1",
+    source,
+    product_summary,
+    backbone,
+    open_questions
+  };
+  if (Array.isArray(obj.data_model)) result.data_model = obj.data_model;
+  if (Array.isArray(obj.build_order)) result.build_order = obj.build_order;
+  if (Array.isArray(obj.critical_assumptions)) result.critical_assumptions = obj.critical_assumptions;
+  if (obj.stack && typeof obj.stack === "object") result.stack = obj.stack;
+  return result;
+}
+function printSummary(storymap) {
+  console.log();
+  console.log("  \x1B[1mStorymap Summary\x1B[0m\n");
+  console.log(`  \x1B[36mProduct:\x1B[0m ${storymap.product_summary}`);
+  console.log();
+  let totalTasks = 0;
+  let totalStories = 0;
+  const confidenceCounts = { high: 0, medium: 0, low: 0 };
+  for (const activity of storymap.backbone) {
+    for (const task of activity.tasks) {
+      totalTasks++;
+      totalStories += task.stories.length;
+      for (const story of task.stories) {
+        confidenceCounts[story.confidence]++;
+      }
+    }
+  }
+  console.log(
+    `  \x1B[33mActivities:\x1B[0m ${storymap.backbone.length} | \x1B[33mTasks:\x1B[0m ${totalTasks} | \x1B[33mStories:\x1B[0m ${totalStories}`
+  );
+  console.log(`  \x1B[32mHigh confidence:\x1B[0m ${confidenceCounts.high}`);
+  console.log(`  \x1B[33mMedium confidence:\x1B[0m ${confidenceCounts.medium}`);
+  console.log(`  \x1B[31mLow confidence:\x1B[0m ${confidenceCounts.low}`);
+  if (storymap.open_questions && storymap.open_questions.length > 0) {
+    console.log(
+      `  \x1B[36mOpen questions:\x1B[0m ${storymap.open_questions.length}`
+    );
+  }
+  console.log();
+}
+async function mapImport(filePath, opts) {
+  const config = requireConfig();
+  if (!filePath) {
+    console.error("  File path is required");
+    return;
+  }
+  if (!existsSync(filePath)) {
+    console.error(`  File not found: ${filePath}`);
+    return;
+  }
+  console.log(`
+  Importing storymap from ${filePath}...
+`);
+  const spinner = ora("  Validating storymap...").start();
+  try {
+    const jsonText = readFileSync(filePath, "utf-8");
+    let storymap;
+    try {
+      storymap = validateStorymapJSON(JSON.parse(jsonText));
+    } catch (validationErr) {
+      spinner.fail(`  Validation failed: ${validationErr.message}`);
+      return;
+    }
+    spinner.succeed("  Storymap is valid\n");
+    printSummary(storymap);
+    if (!opts?.yes) {
+      const doImport = await confirm(
+        `  Import this storymap into your story map?`
+      );
+      if (!doImport) {
+        console.log("  Import cancelled.\n");
+        closePrompt();
+        return;
+      }
+    }
+    const uploadSpinner = ora("  Uploading storymap...").start();
+    const res = await fetch(apiUrl(config, "/map-import"), {
+      method: "POST",
+      headers: { "Content-Type": "application/json" },
+      body: JSON.stringify(storymap)
+    });
+    if (!res.ok) {
+      if (isPlanGated(res.status)) {
+        uploadSpinner.fail("  Storymap import is not available on your plan");
+        printUpgradeMessage();
+        closePrompt();
+        return;
+      }
+      if (res.status === 401) {
+        uploadSpinner.fail("  Sync token expired or invalid");
+        console.error(
+          "\n  Your sync token has expired. Run \x1B[36mstc link\x1B[0m to generate a fresh one.\n"
+        );
+        closePrompt();
+        return;
+      }
+      uploadSpinner.fail("  Upload failed");
+      const errText = await res.text();
+      console.error(`  ${errText.slice(0, 200)}`);
+      closePrompt();
+      return;
+    }
+    const result = await res.json();
+    uploadSpinner.succeed(
+      `  \u2713 Successfully imported storymap
+`
+    );
+    console.log(
+      `  \x1B[32m${result.stories}\x1B[0m stories across \x1B[32m${result.activities}\x1B[0m activities and \x1B[32m${result.steps}\x1B[0m steps`
+    );
+    if (result.openQuestions > 0) {
+      console.log(
+        `  \x1B[36m${result.openQuestions}\x1B[0m open questions for you to review in the web UI`
+      );
+    }
+    console.log();
+    closePrompt();
+  } catch (err) {
+    spinner.fail(`  Error: ${err.message}`);
+    closePrompt();
+  }
+}
+export {
+  mapImport
+};