intentdocs 0.11.0 → 0.12.0

package/dist/index.js

@@ -8,11 +8,11 @@ import {
 } from "./chunk-UQDMUKLP.js";
 import {
   ci
-} from "./chunk-65EDM7QH.js";
+} from "./chunk-5GATVQEI.js";
 import {
   setup,
   sync
-} from "./chunk-IORMKLAQ.js";
+} from "./chunk-SDXDVNNP.js";
 import {
   criterionPriority,
   criterionStatusLabel,
@@ -31,7 +31,7 @@ import {
 } from "./chunk-KPQ42YE6.js";
 import {
   scope
-} from "./chunk-ID4B5RZ2.js";
+} from "./chunk-Q6BSSJK5.js";
 import {
   login,
   logout
@@ -57,7 +57,7 @@ import {
   readConfig,
   requireConfig,
   writeConfig
-} from "./chunk-K5SNF6CG.js";
+} from "./chunk-RGFGTIIH.js";
 import {
   ask,
   closePrompt,
@@ -304,7 +304,7 @@ Connecting to "${map2.title}"${project.workspace ? ` in ${project.workspace.name
     await offerAllowList((q) => ask2(rl, q));
     const setUpCi = await ask2(rl, "  Set up CI test reporting now? It creates a key and adds the workflow. (y/N): ");
     if (/^y(es)?$/i.test(setUpCi.trim())) {
-      const { ci: ci2 } = await import("./ci-NOCV3XUV.js");
+      const { ci: ci2 } = await import("./ci-CWPLSRCQ.js");
       await ci2();
     } else {
       console.log("  You can run `npx intentdocs ci` any time to turn it on.\n");
@@ -1634,7 +1634,7 @@ async function start() {
     closePrompt();
     return;
   }
-  const { scope: scope2 } = await import("./scope-RRGJHS2G.js");
+  const { scope: scope2 } = await import("./scope-ORIFXV4P.js");
   await scope2(projectId);
 }
 
@@ -3019,7 +3019,10 @@ program.command("projects").description("List the projects your token can reach
   import("./projects-AYAYVFKL.js").then((m) => void m.projects());
 });
 program.command("push").description("Upload this repo's nikOS intent/ folder: log in, create the project, and link the repo").action(() => {
-  import("./push-33V7ANJW.js").then((m) => m.push());
+  import("./push-7LJ654MJ.js").then((m) => m.push());
+});
+program.command("pull").description("Show web edits to this repo's feature files as a diff, then write the ones you agree to").option("-y, --yes", "write web changes without asking (never settles a story changed on both sides)").action((opts) => {
+  import("./pull-MDI63WI7.js").then((m) => m.pull(opts));
 });
 program.command("init [token]").description("Connect this project to a intentdocs story map").action((token) => void init(token));
 program.command("sync").description("Refresh INTENT.md from the live story map").option("--context", "Refresh only the CLAUDE.md/AGENTS.md context file (not stories)").action((opts) => void sync(opts));
@@ -3034,36 +3037,36 @@ program.command("done <id>").description("Mark a story as done (accepts its key
 program.command("stop <id>").description("Stop development of an in-progress story (resets to todo, signals agents to stop; accepts its key or an ID prefix)").action((id) => void stop(id));
 program.command("add <title>").description("Create a new story").option("-a, --activity <activity>", "Activity to add the story under").option("-p, --priority <priority>", "Priority: must, should, could", "should").option("-e, --effort <effort>", "Effort: S, M, L, XL", "M").action((title, opts) => void add(title, opts));
 var decide = program.command("decide [title]").description("Log an architectural or product decision").option("-d, --description <desc>", "Decision description").option("-c, --category <cat>", "Category: architecture, product, technical, trade-off", "technical").option("-s, --story <id>", "Link to a story (its key like PB-42, or an ID prefix)").action((title, opts) => {
-  import("./log-DFCCAAJN.js").then((m) => void m.logDecision(title, opts));
+  import("./log-VTIAG4PC.js").then((m) => void m.logDecision(title, opts));
 });
 decide.command("list").description("List logged decisions (id, category, title)").action(() => {
-  import("./log-DFCCAAJN.js").then((m) => void m.listLoggedDecisions());
+  import("./log-VTIAG4PC.js").then((m) => void m.listLoggedDecisions());
 });
 decide.command("amend <id>").description("Amend a logged decision's title, description, or category (accepts an ID prefix)").option("-t, --title <title>", "New title").option("-d, --description <desc>", "New description").option("-c, --category <cat>", "New category: architecture, product, technical, trade-off").action((id, opts) => {
-  import("./log-DFCCAAJN.js").then((m) => void m.amendDecision(id, opts));
+  import("./log-VTIAG4PC.js").then((m) => void m.amendDecision(id, opts));
 });
 decide.command("delete <id>").alias("retract").description("Retract a logged decision \u2014 soft-deleted and audited, not removed (accepts an ID prefix)").option("-r, --reason <reason>", "Why this decision is being retracted").option("-y, --yes", "Skip the confirmation prompt (required when there's no TTY)").action((id, opts) => {
-  import("./log-DFCCAAJN.js").then((m) => void m.deleteDecision(id, opts));
+  import("./log-VTIAG4PC.js").then((m) => void m.deleteDecision(id, opts));
 });
 program.command("note <storyId> [note]").description("Add an implementation note to a story (appended to its notes)").action((storyId, note) => {
-  import("./log-DFCCAAJN.js").then((m) => void m.logNote(storyId, note));
+  import("./log-VTIAG4PC.js").then((m) => void m.logNote(storyId, note));
 });
 program.command("example").description("Add a few-shot reference pattern (before/after code) to the project").action(() => void example());
 program.command("complexity [storyId]").description("Analyze story complexity with AI \u2014 scores, risks, effort estimates").action((id) => {
-  import("./complexity-OJVM37NF.js").then((m) => void m.complexity(id));
+  import("./complexity-HLJTXY55.js").then((m) => void m.complexity(id));
 });
 program.command("research [query]").description("Research a topic with AI using your project context").action((query) => {
-  import("./research-SHO5SXVQ.js").then((m) => void m.research(query));
+  import("./research-L27DLYXC.js").then((m) => void m.research(query));
 });
 program.command("import [file]").description("Import a PRD or spec into your story map as stories (reads standard input when no file is given; needs --yes then)").option("-y, --yes", "Import without asking for confirmation (required when reading from standard input)").action((file, opts) => {
-  import("./import-prd-5FCVXCYO.js").then((m) => void m.importPrd(file, opts));
+  import("./import-prd-FQI4J45M.js").then((m) => void m.importPrd(file, opts));
 });
 var map = program.command("map").description("Import or extract story maps from codebases");
 map.command("extract").description("Output a prompt for your coding agent to extract a story map from an existing codebase").action(() => {
-  import("./map-extract-YUCFLGJS.js").then((m) => void m.mapExtract());
+  import("./map-extract-4C44YGGD.js").then((m) => void m.mapExtract());
 });
 map.command("import <file>").description("Import a storymap.json file generated by your coding agent").option("--yes", "Skip confirmation prompt").action((file, opts) => {
-  import("./map-import-7RN2NEUZ.js").then((m) => void m.mapImport(file, opts));
+  import("./map-import-TSSDU766.js").then((m) => void m.mapImport(file, opts));
 });
 map.command("schema").description("Print the JSON Schema for storymap.json").action(() => {
   import("./map-schema-5BEIJM2J.js").then((m) => void m.mapSchema());

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

@@ -17,7 +17,7 @@ import {
 } from "./chunk-KTGQO3AE.js";
 import {
   requireConfig
-} from "./chunk-K5SNF6CG.js";
+} from "./chunk-RGFGTIIH.js";
 import {
   ask,
   closePrompt,

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

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

package/dist/{map-import-7RN2NEUZ.js → map-import-TSSDU766.js}

@@ -8,7 +8,7 @@ import {
 } from "./chunk-KTGQO3AE.js";
 import {
   requireConfig
-} from "./chunk-K5SNF6CG.js";
+} from "./chunk-RGFGTIIH.js";
 import {
   closePrompt,
   confirm

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
+};