intentdocs 0.10.1 → 0.12.0

package/dist/{keys-UVXCCWCS.js → keys-2W5V56FS.js}

@@ -9,6 +9,16 @@ import "./chunk-UYTVTYNB.js";
 
 // src/commands/keys.ts
 var KEYS_DOC_URL = "https://console.anthropic.com/settings/keys";
+var XAI_KEYS_URL = "https://console.x.ai/";
+var ANTHROPIC_RE = /^sk-ant-[A-Za-z0-9_-]{24,250}$/;
+var XAI_RE = /^xai-[A-Za-z0-9_-]{20,250}$/;
+var OPENAI_PROJ_RE = /^sk-proj-[A-Za-z0-9_-]{20,250}$/;
+var OPENAI_SK_RE = /^sk-[A-Za-z0-9_-]{20,250}$/;
+function acceptedLocally(value) {
+  if (ANTHROPIC_RE.test(value) || XAI_RE.test(value) || OPENAI_PROJ_RE.test(value)) return true;
+  if (!OPENAI_SK_RE.test(value)) return false;
+  return !/^(sk-ant-|sk-proj-|sk-admin-|sk-svcacct-)/.test(value);
+}
 async function byokRequest(method, body) {
   const auth = await requireValidAuth();
   const res = await fetch(`${auth.apiBase}/api/settings/byok`, {
@@ -25,17 +35,22 @@ async function byokRequest(method, body) {
 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("\n  Optionally add an Anthropic, xAI, or OpenAI 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();
+    console.log(`  Anthropic keys start with sk-ant-. Get one at: ${KEYS_DOC_URL}`);
+    console.log(`  xAI keys start with xai-. Get one at: ${XAI_KEYS_URL}`);
+    console.log("  OpenAI keys start with sk- or sk-proj-. Get one at: https://platform.openai.com/api-keys\n");
+    value = (await ask("  API key (sk-ant-..., xai-..., sk-..., or sk-proj-...): ")).trim();
     closePrompt();
   }
   if (!value) {
     console.error("  No key provided. Run `npx intentdocs keys set` to try again.");
     process.exit(1);
   }
+  if (!acceptedLocally(value)) {
+    console.error("\n  \u2717 That key is not accepted. Use an sk-ant- key, an xai- key, an sk- key, or an sk-proj- key.");
+    process.exit(1);
+  }
   try {
     const { ok, data } = await byokRequest("POST", { key: value });
     if (!ok) {
@@ -59,12 +74,18 @@ async function keysStatus() {
       process.exit(1);
     }
     if (data?.enabled) {
+      const anthropic = data.anthropic?.mask || "not set";
+      const xai = data.xai?.mask || "not set";
+      const openai = data.openai?.mask || "not set";
       console.log(`
-  Anthropic API key: ${data.maskedKey ?? "(stored but unreadable \u2014 re-run `npx intentdocs keys set`)"}`);
-      console.log("  AI features run on your key.\n");
+  Anthropic API key: ${anthropic}`);
+      console.log(`  xAI API key: ${xai}`);
+      console.log(`  OpenAI API key: ${openai}`);
+      if (data.active_provider) console.log(`  Active: ${data.active_provider}`);
+      console.log("  AI features run on your active key.\n");
     } else {
-      console.log("\n  No Anthropic API key set.");
-      console.log("  Add one with `npx intentdocs keys set` to unlock AI features on any plan.\n");
+      console.log("\n  No API key set.");
+      console.log("  Add an sk-ant-, xai-, sk-, or sk-proj- key with `npx intentdocs keys set` to unlock AI features on any plan.\n");
     }
   } catch {
     console.error("  \u2717 Could not reach intentdocs. Check your connection and try again.");
@@ -78,7 +99,7 @@ async function keysRemove() {
       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");
+    console.log("\n  Key removed. Revoke it at the provider. AI features fall back when no key remains.\n");
   } catch {
     console.error("  \u2717 Could not reach intentdocs. Check your connection and try again.");
     process.exit(1);

package/dist/{log-XIH4BGFL.js → log-VTIAG4PC.js}

@@ -1,7 +1,10 @@
+import {
+  appendToNotes
+} from "./chunk-GFKZ5CRL.js";
 import {
   appendNoteToContext,
   storyContextPath
-} from "./chunk-F52HPVNQ.js";
+} from "./chunk-BNEU6TLJ.js";
 import {
   matchesStoryRef
 } from "./chunk-LQTPZL2Y.js";
@@ -9,11 +12,12 @@ import {
   amendDecision,
   apiFetch,
   listDecisions,
+  listStories,
   retractDecision
-} from "./chunk-34JCN66H.js";
+} from "./chunk-KTGQO3AE.js";
 import {
   requireConfig
-} from "./chunk-JX2RLGOM.js";
+} from "./chunk-RGFGTIIH.js";
 import {
   ask,
   closePrompt,
@@ -38,6 +42,18 @@ async function logDecision(title, opts) {
     closePrompt();
     return;
   }
+  let storyId;
+  if (opts?.story) {
+    const { stories } = await listStories(config);
+    const match = stories.find((s) => matchesStoryRef(s, opts.story));
+    if (!match) {
+      console.error(`  No story found matching "${opts.story}" \u2014 decision not logged.`);
+      closePrompt();
+      process.exitCode = 1;
+      return;
+    }
+    storyId = match.id;
+  }
   const res = await apiFetch(config, "/decisions", {
     method: "POST",
     headers: { "Content-Type": "application/json" },
@@ -45,7 +61,7 @@ async function logDecision(title, opts) {
       title: title.trim(),
       description: description.trim(),
       category: opts?.category ?? "technical",
-      story_id: opts?.story ?? void 0
+      story_id: storyId
     })
   });
   if (res.ok) {
@@ -182,7 +198,7 @@ async function logNote(storyId, note) {
     method: "PATCH",
     headers: { "Content-Type": "application/json" },
     body: JSON.stringify({
-      stories: [{ id: match.id, notes: note.trim() }]
+      stories: [{ id: match.id, notes: appendToNotes(match.notes, note) }]
     })
   });
   if (res.ok) {

package/dist/{map-extract-V6D27I3H.js → map-extract-4C44YGGD.js}

@@ -1,6 +1,6 @@
 import {
   requireConfig
-} from "./chunk-JX2RLGOM.js";
+} from "./chunk-RGFGTIIH.js";
 import "./chunk-UYTVTYNB.js";
 
 // src/commands/map-extract.ts

package/dist/{map-import-LORTI4K4.js → map-import-TSSDU766.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-RGFGTIIH.js";
 import {
   closePrompt,
   confirm
@@ -322,11 +322,12 @@ async function mapImport(filePath, opts) {
         return;
       }
       if (res.status === 401) {
-        uploadSpinner.fail("  Sync token expired or invalid");
+        uploadSpinner.fail("  Your login is no longer valid");
         console.error(
-          "\n  Your sync token has expired. Run \x1B[36mstc link\x1B[0m to generate a fresh one.\n"
+          "\n  Run \x1B[36mnpx intentdocs login\x1B[0m to log in again, then re-run the import.\n"
         );
         closePrompt();
+        process.exitCode = 1;
         return;
       }
       uploadSpinner.fail("  Upload failed");

package/dist/pull-MDI63WI7.js

@@ -0,0 +1,476 @@
+import {
+  listStories
+} from "./chunk-KTGQO3AE.js";
+import {
+  classify,
+  featureFiles,
+  findIntentDir,
+  newFeature,
+  parseFeature,
+  readIntentFolder,
+  readSyncBase,
+  renderFeature,
+  requireConfig,
+  slug,
+  specOfPushStory,
+  specOfStory,
+  writeSyncBase
+} from "./chunk-RGFGTIIH.js";
+import {
+  choose,
+  closePrompt,
+  confirm,
+  isInteractive
+} from "./chunk-WRRUCCVZ.js";
+import "./chunk-XZE2XP6O.js";
+import "./chunk-UYTVTYNB.js";
+
+// src/commands/pull.ts
+import { existsSync, mkdirSync, readFileSync, readdirSync, writeFileSync } from "fs";
+import { dirname, join, relative } from "path";
+import { parse } from "yaml";
+
+// src/lib/pull-files.ts
+import { isMap, isScalar, isSeq, parseDocument, stringify } from "yaml";
+var YAML_OUT = { lineWidth: 0, flowCollectionPadding: false };
+function edit(text, change) {
+  const doc = parseDocument(text);
+  change(doc);
+  return doc.toString(YAML_OUT);
+}
+var seqOf = (doc, key) => {
+  const node = doc.get(key, true);
+  if (isSeq(node)) return node;
+  const seq = doc.createNode([]);
+  doc.set(key, seq);
+  return seq;
+};
+var itemsOf = (seq) => seq.items.filter((i) => isMap(i));
+function releaseItem(doc, number, title) {
+  const releases = seqOf(doc, "releases");
+  const found = itemsOf(releases).find((r) => r.get("number") === number);
+  if (found) return found;
+  const created = doc.createNode({ number, title, stories: [] });
+  created.get("stories", true).flow = true;
+  const after = itemsOf(releases).findIndex((r) => Number(r.get("number")) > number);
+  if (after < 0) releases.items.push(created);
+  else releases.items.splice(releases.items.indexOf(itemsOf(releases)[after]), 0, created);
+  return created;
+}
+function setReleaseTitle(text, number, title) {
+  return edit(text, (doc) => releaseItem(doc, number, title).set("title", title));
+}
+function setActivityTitle(text, id, title) {
+  return edit(text, (doc) => {
+    const activities = seqOf(doc, "activities");
+    const found = itemsOf(activities).find((a) => a.get("id") === id);
+    if (found) found.set("title", title);
+    else activities.items.push(doc.createNode({ id, title }));
+  });
+}
+function ensureActivity(text, id, title) {
+  const has = itemsOf(seqOf(parseDocument(text), "activities")).some((a) => a.get("id") === id);
+  return has ? text : setActivityTitle(text, id, title);
+}
+function placeStory(text, key, number, releaseTitle) {
+  return edit(text, (doc) => {
+    const target = releaseItem(doc, number, releaseTitle);
+    for (const release of itemsOf(seqOf(doc, "releases"))) {
+      const stories = release.get("stories", true);
+      if (!isSeq(stories)) continue;
+      const at = stories.items.findIndex((s) => isScalar(s) && s.value === key);
+      if (at >= 0 && release !== target) stories.items.splice(at, 1);
+    }
+    const existing = target.get("stories", true);
+    let seq;
+    if (isSeq(existing)) {
+      seq = existing;
+    } else {
+      seq = doc.createNode([]);
+      seq.flow = true;
+      target.set("stories", seq);
+    }
+    if (!seq.items.some((s) => isScalar(s) && s.value === key)) seq.items.push(doc.createNode(key));
+  });
+}
+function setState(text, key, fields) {
+  return edit(text, (doc) => {
+    for (const [field, value] of Object.entries(fields)) if (value !== void 0) doc.setIn(["stories", key, field], value);
+  });
+}
+function planVersions(names, key) {
+  const re = new RegExp(`^${key.replace(/[-]/g, "\\-")}\\.v(\\d+)\\.md$`);
+  return names.map((n) => re.exec(n)?.[1]).filter((v) => !!v).map(Number).sort((a, b) => a - b);
+}
+function planBody(text) {
+  return text.replace(/^---\n[\s\S]*?\n---\n?/, "").trim();
+}
+function renderPlan(key, version, plan, labelOf, today) {
+  const meta = { story: key, version, created: today };
+  if (version > 1) meta.supersedes = version - 1;
+  if (plan.summary) meta.summary = plan.summary;
+  const steps = plan.steps.map((step, i) => {
+    const title = step.title ?? step.text.split("\n")[0] ?? `Step ${i + 1}`;
+    const lines = [`## ${i + 1}. ${title}`];
+    if (step.why) lines.push(`**Why:** ${step.why}`);
+    const criteria = step.criteria.map((id) => labelOf(id) ?? id);
+    if (criteria.length) lines.push(`**Criteria:** ${criteria.join(", ")}`);
+    if (step.files.length) lines.push(`**Files:** ${step.files.join(", ")}`);
+    if (step.tests.length) lines.push(`**Tests:** ${step.tests.join(", ")}`);
+    if (step.needs_you) lines.push(`**Needs you:** ${step.needs_you}`);
+    const notes = step.title ? step.agent_notes : step.text;
+    if (notes) lines.push("", notes.trim());
+    return lines.join("\n");
+  });
+  return `---
+${stringify(meta, YAML_OUT)}---
+
+${steps.join("\n\n")}
+`;
+}
+
+// src/lib/text-diff.ts
+function ops(a, b) {
+  const lcs = Array.from({ length: a.length + 1 }, () => new Array(b.length + 1).fill(0));
+  for (let i2 = a.length - 1; i2 >= 0; i2--) {
+    for (let j2 = b.length - 1; j2 >= 0; j2--) {
+      lcs[i2][j2] = a[i2] === b[j2] ? lcs[i2 + 1][j2 + 1] + 1 : Math.max(lcs[i2 + 1][j2], lcs[i2][j2 + 1]);
+    }
+  }
+  const out = [];
+  let i = 0;
+  let j = 0;
+  while (i < a.length || j < b.length) {
+    if (i < a.length && j < b.length && a[i] === b[j]) {
+      out.push({ kind: " ", line: a[i], a: i++, b: j++ });
+    } else if (i < a.length && (j >= b.length || lcs[i + 1][j] >= lcs[i][j + 1])) {
+      out.push({ kind: "-", line: a[i], a: i++, b: j });
+    } else {
+      out.push({ kind: "+", line: b[j], a: i, b: j++ });
+    }
+  }
+  return out;
+}
+function unifiedDiff(before, after, label, context = 3) {
+  if (before === after) return "";
+  const all = ops(before.split("\n"), after.split("\n"));
+  const changed = all.map((o, n) => o.kind === " " ? -1 : n).filter((n) => n >= 0);
+  const hunks = [];
+  for (const n of changed) {
+    const start = Math.max(0, n - context);
+    const end = Math.min(all.length - 1, n + context);
+    const last = hunks[hunks.length - 1];
+    if (last && start <= last[1] + 1) last[1] = end;
+    else hunks.push([start, end]);
+  }
+  const lines = [`--- ${label} (in the repo)`, `+++ ${label} (from intentdocs)`];
+  for (const [start, end] of hunks) {
+    const slice = all.slice(start, end + 1);
+    const aLen = slice.filter((o) => o.kind !== "+").length;
+    const bLen = slice.filter((o) => o.kind !== "-").length;
+    lines.push(`@@ -${slice[0].a + 1},${aLen} +${slice[0].b + 1},${bLen} @@`);
+    for (const o of slice) lines.push(`${o.kind}${o.line}`);
+  }
+  return lines.join("\n");
+}
+
+// src/commands/pull.ts
+var Files = class _Files {
+  constructor(read) {
+    this.read = read;
+  }
+  changed = /* @__PURE__ */ new Map();
+  get(path) {
+    return this.changed.has(path) ? this.changed.get(path) : this.read(path);
+  }
+  set(path, text) {
+    this.changed.set(path, text);
+  }
+  clone() {
+    const copy = new _Files(this.read);
+    for (const [p, t] of this.changed) copy.set(p, t);
+    return copy;
+  }
+  /** Paths whose text differs from the file on disk. */
+  edits() {
+    return [...this.changed].filter(([p, t]) => this.read(p) !== t);
+  }
+};
+var PullError = class extends Error {
+  constructor(message, details = []) {
+    super(message);
+    this.details = details;
+    this.name = "PullError";
+  }
+};
+var KIND_LABEL = {
+  web: "From intentdocs",
+  clash: "Changed in intentdocs AND in the repo since the last sync",
+  unrecorded: "Differs from intentdocs, with no sync record to say which side changed"
+};
+var STATUSES = /* @__PURE__ */ new Set(["todo", "in_progress", "needs_rework", "done"]);
+function planUnits(deps, response, base, nextBase, outcome) {
+  const intentDir = findIntentDir(deps.cwd);
+  const read = readIntentFolder(deps.cwd);
+  if (!read.ok) throw new PullError(`intent/ needs fixing before a pull (${read.dir}):`, read.errors);
+  const storymapPath = join(intentDir, "storymap.yaml");
+  const statePath = join(intentDir, "state.yaml");
+  const plansDir = join(intentDir, "plans");
+  const today = deps.now().toISOString().slice(0, 10);
+  const files = featureFiles(intentDir);
+  const local = new Map(read.payload.stories.map((s) => [s.key, s]));
+  const storymap = parse(deps.readFile(storymapPath) ?? "");
+  const state = parse(deps.readFile(statePath) ?? "") ?? {};
+  const remoteReleases = new Map((response.releases ?? []).map((r) => [r.number, r.title]));
+  const releaseTitle = (n) => remoteReleases.get(n) ?? storymap.releases?.find((r) => r.number === n)?.title ?? `Release ${n}`;
+  const units = [];
+  for (const [number, title] of remoteReleases) {
+    const mine = storymap.releases?.find((r) => r.number === number)?.title;
+    const was = base.releases[String(number)];
+    const kind = mine === void 0 && was === void 0 ? "web" : classify(mine, title, was);
+    if (kind === null) nextBase.releases[String(number)] = title;
+    else if (kind !== "local") {
+      units.push({
+        title: mine === void 0 ? `New release ${number}: ${title}` : `Release ${number} renamed to "${title}"`,
+        kind,
+        apply: (f) => f.set(storymapPath, setReleaseTitle(f.get(storymapPath), number, title)),
+        record: (b) => b.releases[String(number)] = title
+      });
+    }
+  }
+  for (const activity of response.activities ?? []) {
+    if (!activity.ref?.startsWith("nikos:")) continue;
+    const id = activity.ref.slice("nikos:".length);
+    const mine = storymap.activities?.find((a) => a.id === id)?.title;
+    if (mine === void 0) continue;
+    const kind = classify(mine, activity.title, base.activities[id]);
+    if (kind === null) nextBase.activities[id] = activity.title;
+    else if (kind !== "local") {
+      units.push({
+        title: `Activity ${id} renamed to "${activity.title}"`,
+        kind,
+        apply: (f) => f.set(storymapPath, setActivityTitle(f.get(storymapPath), id, activity.title)),
+        record: (b) => b.activities[id] = activity.title
+      });
+    }
+  }
+  const live = response.stories.filter((s) => s.key);
+  outcome.cancelled = live.filter((s) => s.cancelled_at && files.has(s.key)).map((s) => s.key);
+  for (const story of live.filter((s) => !s.cancelled_at)) {
+    const key = story.key;
+    const theirs = specOfStory(story, storymap.activities ?? []);
+    const mine = local.get(key);
+    const path = files.get(key);
+    if (mine && path) {
+      const kind = classify(specOfPushStory(mine), theirs, base.stories[key]);
+      if (kind === null) nextBase.stories[key] = theirs;
+      else if (kind === "local") outcome.localOnly.push(key);
+      else units.push(storyUnit(key, path, mine, theirs, story, kind));
+    } else if (!mine) {
+      units.push(newStoryUnit(key, theirs, story));
+    }
+  }
+  function placeIn(f, key, theirs, story) {
+    let map = f.get(storymapPath);
+    map = ensureActivity(map, theirs.activity, story.activity);
+    map = placeStory(map, key, theirs.release, releaseTitle(theirs.release));
+    f.set(storymapPath, map);
+  }
+  function storyUnit(key, path, mine, theirs, story, kind) {
+    return {
+      title: `${key} ${theirs.title}`,
+      kind,
+      apply: (f) => {
+        f.set(path, renderFeature(f.get(path), theirs));
+        if (mine.release !== theirs.release || mine.activity_id !== theirs.activity) placeIn(f, key, theirs, story);
+      },
+      record: (b) => b.stories[key] = theirs
+    };
+  }
+  function newStoryUnit(key, theirs, story) {
+    const dir = join(intentDir, "features", theirs.activity);
+    const name = slug(theirs.title);
+    const path = deps.readFile(join(dir, `${name}.feature`)) === null ? join(dir, `${name}.feature`) : join(dir, `${name}-${key.toLowerCase()}.feature`);
+    const status = STATUSES.has(story.status) ? story.status : "todo";
+    return {
+      title: `New story ${key} ${theirs.title}`,
+      kind: "web",
+      apply: (f) => {
+        f.set(path, newFeature(key, theirs));
+        placeIn(f, key, theirs, story);
+        f.set(statePath, setState(f.get(statePath), key, { status, updated: today }));
+        if (story.agent_plan) writePlan(f, key, path, story, story.agent_plan);
+      },
+      record: (b) => {
+        b.stories[key] = theirs;
+        b.statuses[key] = status;
+        if (story.agent_plan) b.plans[key] = story.agent_plan.version;
+      }
+    };
+  }
+  function writePlan(f, key, featurePath, story, plan) {
+    const existing = planVersions(deps.listDir(plansDir), key);
+    let next = (existing[existing.length - 1] ?? 0) + 1;
+    while (f.get(join(plansDir, `${key}.v${next}.md`)) !== null) next++;
+    const criteria = parseFeature(f.get(featurePath) ?? "")?.criteria ?? [];
+    const textOf = new Map(story.acceptance_criteria.map((c) => [c.id, c.text.trim()]));
+    const labelOf = (id) => criteria.find((c) => c.text.trim() === textOf.get(id))?.label || void 0;
+    f.set(join(plansDir, `${key}.v${next}.md`), renderPlan(key, next, plan, labelOf, today));
+    f.set(statePath, setState(f.get(statePath), key, { plan_version: next }));
+  }
+  const statusChanges = [];
+  const notMoved = [];
+  for (const s of live.filter((s2) => !s2.cancelled_at && STATUSES.has(s2.status) && state.stories?.[s2.key])) {
+    const key = s.key;
+    const mine = state.stories[key].status ?? "todo";
+    const was = base.statuses[key];
+    if (mine === s.status) nextBase.statuses[key] = s.status;
+    else if (was === s.status || was === void 0 && s.status === "todo") {
+      nextBase.statuses[key] = s.status;
+      notMoved.push(`${key} (${mine} here)`);
+    } else statusChanges.push({ key, from: mine, to: s.status });
+  }
+  outcome.statusNotMoved = notMoved;
+  if (statusChanges.length) {
+    units.push({
+      title: `Statuses: ${statusChanges.map((c) => `${c.key} ${c.from} \u2192 ${c.to}`).join(", ")}`,
+      kind: "web",
+      apply: (f) => {
+        let text = f.get(statePath);
+        for (const c of statusChanges) text = setState(text, c.key, { status: c.to, updated: today });
+        f.set(statePath, text);
+      },
+      record: (b) => {
+        for (const c of statusChanges) b.statuses[c.key] = c.to;
+      }
+    });
+  }
+  for (const story of live.filter((s) => !s.cancelled_at && s.agent_plan && files.has(s.key) && local.has(s.key))) {
+    const key = story.key;
+    const plan = story.agent_plan;
+    if ((base.plans[key] ?? 0) >= plan.version) continue;
+    const versions = planVersions(deps.listDir(plansDir), key);
+    const latest = versions[versions.length - 1];
+    const path = files.get(key);
+    const preview = new Files(deps.readFile);
+    writePlan(preview, key, path, story, plan);
+    const drafted = preview.edits().find(([p]) => p.startsWith(plansDir))?.[1] ?? "";
+    const current = latest ? deps.readFile(join(plansDir, `${key}.v${latest}.md`)) : null;
+    if (current && planBody(current) === planBody(drafted)) {
+      nextBase.plans[key] = plan.version;
+      continue;
+    }
+    units.push({
+      title: `Plan for ${key}: intentdocs plan v${plan.version} as ${key}.v${(latest ?? 0) + 1}.md`,
+      kind: "web",
+      apply: (f) => writePlan(f, key, path, story, plan),
+      record: (b) => b.plans[key] = plan.version
+    });
+  }
+  return units;
+}
+async function runPull(deps) {
+  const response = await deps.listStories();
+  const base = deps.readSyncBase();
+  const nextBase = structuredClone(base);
+  const outcome = { units: [], written: [], localOnly: [], cancelled: [], statusNotMoved: [] };
+  outcome.units = planUnits(deps, response, base, nextBase, outcome);
+  const disk = new Files(deps.readFile);
+  for (const unit of outcome.units) {
+    deps.log(`
+${KIND_LABEL[unit.kind]}: ${unit.title}`);
+    const preview = disk.clone();
+    unit.apply(preview);
+    for (const [path, after] of preview.edits()) {
+      const rel = relative(deps.cwd, path);
+      const before = deps.readFile(path);
+      deps.log(before === null ? `+++ ${rel} (new file)
+${after.trimEnd().split("\n").map((l) => `+${l}`).join("\n")}` : unifiedDiff(before, after, rel));
+    }
+  }
+  if (outcome.localOnly.length) deps.log(`
+Changed only in the repo, so nothing to pull: ${outcome.localOnly.join(", ")}. \`intentdocs push\` sends them.`);
+  if (outcome.statusNotMoved.length)
+    deps.log(`
+intentdocs hasn't moved these since the last sync, so their status here is kept: ${outcome.statusNotMoved.join(", ")}.`);
+  if (outcome.cancelled.length) deps.log(`Cancelled in intentdocs, left as they are here: ${outcome.cancelled.join(", ")}.`);
+  const safe = outcome.units.filter((u) => u.kind === "web");
+  const risky = outcome.units.filter((u) => u.kind !== "web");
+  const apply = /* @__PURE__ */ new Set();
+  if (outcome.units.length === 0) {
+    if (!outcome.localOnly.length && !outcome.statusNotMoved.length) deps.log("\nThe repo already matches intentdocs.");
+  } else if (deps.yes) {
+    for (const u of safe) apply.add(u);
+    if (risky.length) deps.log(`
+--yes doesn't settle: ${risky.map((u) => u.title).join("; ")}. Run \`intentdocs pull\` in a terminal to choose.`);
+  } else if (!deps.interactive) {
+    deps.log("\nNothing written. Run `intentdocs pull` in a terminal to choose, or `intentdocs pull --yes` once you've agreed to the changes above.");
+  } else {
+    if (safe.length) {
+      const pick = await deps.choose(`Write ${safe.length === 1 ? "this change" : `these ${safe.length} changes`} from intentdocs?`, [
+        "Write nothing",
+        `Write ${safe.length === 1 ? "it" : `all ${safe.length}`}`,
+        "Choose one by one"
+      ]);
+      if (pick === 1) for (const u of safe) apply.add(u);
+      if (pick === 2) {
+        for (const u of safe) if (await deps.confirm(`Write: ${u.title}?`)) apply.add(u);
+      }
+    }
+    for (const u of risky) {
+      if (await deps.confirm(`${u.title}: replace the repo's version with intentdocs' (your local edits to it are lost)?`)) apply.add(u);
+    }
+  }
+  const result = new Files(deps.readFile);
+  for (const unit of outcome.units.filter((u) => apply.has(u))) {
+    unit.apply(result);
+    unit.record(nextBase);
+  }
+  for (const [path, text] of result.edits()) {
+    deps.writeFile(path, text);
+    outcome.written.push(relative(deps.cwd, path));
+  }
+  deps.writeSyncBase(nextBase);
+  if (outcome.written.length) deps.log(`
+\u2713 Wrote ${outcome.written.join(", ")}`);
+  else if (outcome.units.length) deps.log("\nNothing was written.");
+  return outcome;
+}
+async function pull(opts = {}) {
+  const config = requireConfig();
+  try {
+    await runPull({
+      cwd: process.cwd(),
+      listStories: () => listStories(config),
+      readSyncBase,
+      writeSyncBase,
+      readFile: (p) => existsSync(p) ? readFileSync(p, "utf-8") : null,
+      writeFile: (p, t) => {
+        mkdirSync(dirname(p), { recursive: true });
+        writeFileSync(p, t);
+      },
+      listDir: (p) => existsSync(p) ? readdirSync(p) : [],
+      interactive: isInteractive(),
+      yes: opts.yes ?? false,
+      choose,
+      confirm,
+      log: (line) => console.log(line),
+      now: () => /* @__PURE__ */ new Date()
+    });
+  } catch (err) {
+    if (err instanceof PullError) {
+      console.error(`\u2717 ${err.message}`);
+      for (const d of err.details) console.error(`  - ${d}`);
+    } else {
+      console.error(`\u2717 Pull failed: ${err.message}`);
+    }
+    process.exitCode = 1;
+  } finally {
+    closePrompt();
+  }
+}
+export {
+  PullError,
+  pull,
+  runPull
+};