leglas 0.7.3 → 0.8.0

package/dist/index.js

@@ -281,6 +281,19 @@ function parseArgs(argv) {
     }
     return { kind: "requests", json: rest.includes("--json"), clear: rest.includes("--clear") };
   }
+  if (argv[0] === "log") {
+    const rest = argv.slice(1);
+    const flags = rest.filter((argument) => argument.startsWith("--"));
+    const unknown = flags.find((flag) => flag !== "--json");
+    if (unknown !== void 0) {
+      return { kind: "error", message: `leglas log does not take ${unknown}.` };
+    }
+    const names = rest.filter((argument) => !argument.startsWith("--"));
+    if (names.length > 1) {
+      return { kind: "error", message: "leglas log takes one entry at most." };
+    }
+    return { kind: "log", entry: names[0] ?? null, json: flags.includes("--json") };
+  }
   if (argv[0] === "list") {
     const rest = argv.slice(1);
     const unknown = rest.find((argument) => argument !== "--json");
@@ -725,6 +738,12 @@ out of the ignored directory, deletes the rest of the exploration, and drops
 them from the rail. Then change their component to use the kept component
 instead of the switcher.
 
+Keeping also writes what the exploration was into \`design-log/\`, which is
+committed. Before exploring a surface, read \`npx leglas log --json\` and any
+entry for that surface: it says what was already tried there, in the user's own
+words, and which direction won. Proposing something that was already rejected
+wastes their time, and the record is there so you do not have to ask.
+
 Useful to know:
 
 - \`.leglas/\` is gitignored. Exploration is disposable and nothing in there
@@ -785,6 +804,84 @@ ${AGENTS_SECTION}`
 // src/keep.ts
 import { basename as basename4, extname as extname4, normalize as normalize2 } from "path";
 
+// ../server/dist/log.js
+var DEFAULT_LOG_DIR = "design-log";
+function slugify(value) {
+  return value.toLowerCase().replace(/[^a-z0-9]+/g, "-").replace(/^-|-$/g, "") || "untitled";
+}
+function frameFor(title, requests) {
+  let found = null;
+  for (const request of requests) {
+    if (request.title !== title)
+      continue;
+    for (const attachment of request.attachments ?? []) {
+      if (attachment.kind === "frame")
+        found = attachment;
+    }
+  }
+  return found;
+}
+function askedOf(title, requests) {
+  return requests.filter((request) => request.title === title && request.status !== "failed" && request.intent.trim() !== "").map((request) => request.intent.trim());
+}
+function composeEntry(input) {
+  const slug = `${input.date}-${slugify(input.surface)}`;
+  const pictures = [];
+  const lines2 = [];
+  lines2.push(`# ${input.surface}, ${input.date}`);
+  lines2.push("");
+  lines2.push(`**${input.won.title}** won and became \`${input.won.to}\`. ${input.previews.length === 1 ? "It was the only direction." : `${input.previews.length} directions were compared.`}`);
+  lines2.push("");
+  for (const preview of input.previews) {
+    const won = preview.title === input.won.title;
+    lines2.push(`## ${preview.title}${won ? " \u2014 kept" : ""}`);
+    lines2.push("");
+    if (preview.note !== void 0 && preview.note.trim() !== "") {
+      lines2.push(preview.note.trim());
+      lines2.push("");
+    }
+    const frame = frameFor(preview.title, input.requests);
+    if (frame !== null) {
+      const name = `${slugify(preview.title)}.png`;
+      pictures.push({ from: frame.file, to: name });
+      lines2.push(`![${preview.title}](${slug}/${name})`);
+      lines2.push("");
+    }
+    if (preview.basedOn !== void 0) {
+      lines2.push(`A variant of ${preview.basedOn}.`);
+      lines2.push("");
+    }
+    const asked = askedOf(preview.title, input.requests);
+    if (asked.length > 0) {
+      lines2.push("Asked for:");
+      lines2.push("");
+      for (const words of asked)
+        lines2.push(`- ${words}`);
+      lines2.push("");
+    }
+    const notes = input.annotations.filter((note) => note.title === preview.title);
+    if (notes.length > 0) {
+      lines2.push("Marked on the design:");
+      lines2.push("");
+      for (const note of notes)
+        lines2.push(`- ${note.note}`);
+      lines2.push("");
+    }
+  }
+  const failed = input.requests.filter((request) => request.status === "failed");
+  if (failed.length > 0) {
+    lines2.push("## Changes that did not land");
+    lines2.push("");
+    for (const request of failed) {
+      const why = request.failure?.message;
+      lines2.push(`- ${request.title}: ${request.intent}${why === void 0 ? "" : ` (${why})`}`);
+    }
+    lines2.push("");
+  }
+  return { slug, markdown: `${lines2.join("\n").trimEnd()}
+`, pictures };
+}
+
 // ../server/dist/config.js
 var DEFAULT_DEV_SERVER = "http://localhost:3000";
 var DEFAULT_INSTALL_COMMAND = "npm install";
@@ -903,6 +1000,10 @@ function normalizeConfig(raw, options = {}) {
   if (requireDevCommand && previews.some((preview) => preview.branch !== void 0) && devCommand === void 0) {
     errors.push("A preview names a branch, so devCommand is required: Leglas has to start that checkout itself.");
   }
+  const logDir = source["logDir"] ?? DEFAULT_LOG_DIR;
+  if (typeof logDir !== "string" || logDir.trim() === "") {
+    errors.push("logDir must be a non-empty string.");
+  }
   const installCommand = source["installCommand"] ?? DEFAULT_INSTALL_COMMAND;
   if (typeof installCommand !== "string" || installCommand.trim() === "") {
     errors.push("installCommand must be a non-empty string.");
@@ -919,7 +1020,8 @@ function normalizeConfig(raw, options = {}) {
       previews,
       scanPreviews,
       devCommand: typeof devCommand === "string" ? devCommand : void 0,
-      installCommand
+      installCommand,
+      logDir
     },
     errors: []
   };
@@ -1697,6 +1799,7 @@ import net from "net";
 function createProxyHandler(options) {
   const target = new URL(options.target);
   const host = target.hostname;
+  const dialHost = host.replace(/^\[|\]$/g, "");
   const port = Number(target.port || (target.protocol === "https:" ? 443 : 80));
   const authority = target.port ? `${host}:${target.port}` : host;
   function upstreamHeaders(req) {
@@ -1713,7 +1816,19 @@ function createProxyHandler(options) {
   }
   return {
     request(req, res, publicOrigin) {
-      const upstream = http.request({ host, port, method: req.method, path: req.url, headers: upstreamHeaders(req) }, (upstreamRes) => {
+      options.onActivity?.();
+      options.onOpen?.();
+      let open = true;
+      const close = () => {
+        if (!open)
+          return;
+        open = false;
+        options.onActivity?.();
+        options.onClose?.();
+      };
+      res.once("finish", close);
+      res.once("close", close);
+      const upstream = http.request({ host: dialHost, port, method: req.method, path: req.url, headers: upstreamHeaders(req) }, (upstreamRes) => {
         const headers = { ...upstreamRes.headers };
         const location = rewriteLocation(typeof headers.location === "string" ? headers.location : void 0, publicOrigin);
         if (location !== void 0)
@@ -1735,7 +1850,17 @@ Start it, or point Leglas somewhere else with --user-port.`);
       req.pipe(upstream);
     },
     upgrade(req, socket, head) {
-      const upstream = net.connect(port, host, () => {
+      options.onActivity?.();
+      options.onOpen?.();
+      let open = true;
+      const closeActivity = () => {
+        if (!open)
+          return;
+        open = false;
+        options.onActivity?.();
+        options.onClose?.();
+      };
+      const upstream = net.connect(port, dialHost, () => {
         const headers = Object.entries(upstreamHeaders(req)).map(([key, value]) => `${key}: ${Array.isArray(value) ? value.join(", ") : value}\r
 `).join("");
         upstream.write(`${req.method} ${req.url} HTTP/1.1\r
@@ -1747,6 +1872,7 @@ ${headers}\r
         socket.pipe(upstream);
       });
       const shutdown = () => {
+        closeActivity();
         upstream.destroy();
         socket.destroy();
       };
@@ -1757,6 +1883,62 @@ ${headers}\r
     }
   };
 }
+function startProxyServer(options) {
+  return new Promise((resolve5, reject) => {
+    let open = 0;
+    const handler = createProxyHandler({
+      ...options,
+      onOpen: () => {
+        open += 1;
+        options.onOpen?.();
+      },
+      onClose: () => {
+        open = Math.max(0, open - 1);
+        options.onClose?.();
+      }
+    });
+    const server = http.createServer((req, res) => {
+      const address = server.address();
+      const port = typeof address === "object" && address !== null ? address.port : 0;
+      handler.request(req, res, `http://127.0.0.1:${port}`);
+    });
+    const sockets = /* @__PURE__ */ new Set();
+    server.on("connection", (socket) => {
+      sockets.add(socket);
+      socket.once("close", () => sockets.delete(socket));
+    });
+    server.on("upgrade", (req, socket, head) => handler.upgrade(req, socket, head));
+    const onError = (error) => {
+      server.removeListener("listening", onListening);
+      reject(error);
+    };
+    const onListening = () => {
+      server.removeListener("error", onError);
+      const address = server.address();
+      const port = typeof address === "object" && address !== null ? address.port : 0;
+      let closed = null;
+      resolve5({
+        active: () => open > 0,
+        close: () => {
+          if (closed !== null)
+            return closed;
+          closed = new Promise((done) => {
+            for (const socket of sockets)
+              socket.destroy();
+            sockets.clear();
+            server.closeAllConnections();
+            server.close(() => done());
+          });
+          return closed;
+        },
+        url: `http://127.0.0.1:${port}`
+      });
+    };
+    server.once("error", onError);
+    server.once("listening", onListening);
+    server.listen(0, "127.0.0.1");
+  });
+}
 
 // ../server/dist/browser.js
 import { randomBytes } from "crypto";
@@ -3121,6 +3303,141 @@ async function startAppProcess(options) {
   throw new Error(`${options.label} did not start within ${Math.round(readyTimeoutMs / 1e3)}s. Check that its dev command serves the port it is given.`);
 }
 
+// ../server/dist/branches.js
+var BRANCH_IDLE_MS = 10 * 60 * 1e3;
+var BRANCH_SWEEP_MS = 3e4;
+function publicBranchState(state) {
+  if (state.status === "ready")
+    return { status: "ready" };
+  return state;
+}
+function createBranchRegistry(options) {
+  const states = new Map(options.previews.map((preview) => [preview.title, { status: "idle" }]));
+  const previews = new Map(options.previews.map((preview) => [preview.title, preview]));
+  const inflight = /* @__PURE__ */ new Map();
+  const stopping = /* @__PURE__ */ new Map();
+  const lastActivity = /* @__PURE__ */ new Map();
+  const proxies = /* @__PURE__ */ new Map();
+  const boot = options.startWorktree ?? startWorktree;
+  const proxy = options.startProxy ?? startProxyServer;
+  let closed = false;
+  let stopPromise = null;
+  const transition = (title, state) => {
+    const previous = states.get(title);
+    if (previous?.status === "starting" && state.status === "starting" && previous.phase === state.phase) {
+      return previous;
+    }
+    states.set(title, state);
+    options.onChange?.(title, state);
+    return state;
+  };
+  const stopReady = (title, state, toIdle) => {
+    const current = stopping.get(title);
+    if (current !== void 0)
+      return current;
+    const pending = (async () => {
+      await proxies.get(title)?.close().catch(() => {
+      });
+      await state.worktree.stop().catch(() => {
+      });
+      proxies.delete(title);
+      lastActivity.delete(title);
+      if (toIdle && !closed && states.get(title) === state) {
+        transition(title, { status: "idle" });
+      }
+    })().finally(() => {
+      stopping.delete(title);
+    });
+    stopping.set(title, pending);
+    return pending;
+  };
+  const sweep = () => {
+    const now = Date.now();
+    for (const [title, state] of states) {
+      const branchProxy = proxies.get(title);
+      if (state.status !== "ready" || branchProxy === void 0 || stopping.has(title))
+        continue;
+      if (branchProxy.active()) {
+        lastActivity.set(title, now);
+        continue;
+      }
+      const seen = lastActivity.get(title) ?? now;
+      if (now - seen >= BRANCH_IDLE_MS)
+        void stopReady(title, state, true);
+    }
+  };
+  const sweepTimer = setInterval(sweep, BRANCH_SWEEP_MS);
+  sweepTimer.unref();
+  const begin = (title) => {
+    const preview = previews.get(title);
+    const current = states.get(title);
+    if (preview === void 0 || current === void 0 || closed)
+      return void 0;
+    if (current.status === "starting")
+      return inflight.get(title);
+    if (current.status === "ready")
+      return Promise.resolve(current);
+    transition(title, { status: "starting", phase: "checking out" });
+    let checkout;
+    try {
+      checkout = Promise.resolve(boot({
+        cwd: options.cwd,
+        branch: preview.branch,
+        installCommand: options.installCommand,
+        devCommand: options.devCommand ?? "",
+        onLog: (line) => {
+          transition(title, {
+            status: "starting",
+            phase: line.startsWith("installing ") ? "installing" : "starting"
+          });
+        }
+      }));
+    } catch (error) {
+      checkout = Promise.reject(error);
+    }
+    const starting = checkout.then(async (worktree) => {
+      transition(title, { status: "starting", phase: "starting" });
+      try {
+        const branchProxy = await proxy({
+          target: worktree.url,
+          onActivity: () => lastActivity.set(title, Date.now())
+        });
+        proxies.set(title, branchProxy);
+        lastActivity.set(title, Date.now());
+        return transition(title, { status: "ready", worktree });
+      } catch (error) {
+        await worktree.stop().catch(() => {
+        });
+        throw error;
+      }
+    }).catch((error) => transition(title, {
+      status: "failed",
+      reason: error instanceof Error ? error.message : String(error)
+    })).finally(() => {
+      inflight.delete(title);
+    });
+    inflight.set(title, starting);
+    return starting;
+  };
+  return {
+    state: (title) => states.get(title),
+    url: (title) => proxies.get(title)?.url,
+    start: begin,
+    stop: () => {
+      if (stopPromise !== null)
+        return stopPromise;
+      closed = true;
+      clearInterval(sweepTimer);
+      stopPromise = Promise.allSettled([...inflight.values()]).then(async () => {
+        await Promise.allSettled([...stopping.values()]);
+        const ready = [...states.entries()].filter((entry) => entry[1].status === "ready" && proxies.has(entry[0]));
+        await Promise.all(ready.map(([title, state]) => stopReady(title, state, false)));
+      });
+      return stopPromise;
+    }
+  };
+}
+
 // ../server/dist/failure.js
 var NEEDS_TRUST = /not inside a trusted directory|--skip-git-repo-check/i;
 var MISSING_BINARY = /\b(ENOENT|EACCES|ENOTDIR)\b/;
@@ -5211,6 +5528,7 @@ function resolveTitle(input, titles, renames) {
 
 // ../server/dist/server.js
 import { createReadStream, existsSync as existsSync3, statSync, unwatchFile, watch as watchFs, watchFile } from "fs";
+import { createHash as createHash2 } from "crypto";
 import { mkdir as mkdir8, readdir as readdir3, writeFile as writeFile8 } from "fs/promises";
 import http2 from "http";
 import net3 from "net";
@@ -5289,6 +5607,30 @@ function sendJson(res, status, body) {
   });
   res.end(payload);
 }
+function etagMatches(value, etag) {
+  if (value === void 0)
+    return false;
+  const values = Array.isArray(value) ? value : [value];
+  return values.some((header) => header.split(",").some((candidate) => {
+    const tag = candidate.trim();
+    return tag === "*" || tag === etag || tag === `W/${etag}`;
+  }));
+}
+function sendConditionalJson(req, res, body) {
+  const payload = JSON.stringify(body);
+  const etag = `"${createHash2("sha256").update(payload).digest("base64url")}"`;
+  if (etagMatches(req.headers["if-none-match"], etag)) {
+    res.writeHead(304, { etag, "cache-control": "private, no-cache" });
+    res.end();
+    return;
+  }
+  res.writeHead(200, {
+    "content-type": "application/json; charset=utf-8",
+    "cache-control": "private, no-cache",
+    etag
+  });
+  res.end(payload);
+}
 var CAPTURE_DEADLINE_MS = 15e3;
 var CAPTURE_LOAD_MS = Math.floor(CAPTURE_DEADLINE_MS * LOAD_SHARE);
 function captureSlug(title) {
@@ -5668,6 +6010,33 @@ async function startServer(options) {
   const { config, configErrors = [], configWarnings = [], shellDir = null, project = "", cwd = process.cwd(), leglasCommand = "npx -y leglas", fileMounts = /* @__PURE__ */ new Map(), detect = () => detectAgents() } = options;
   const browserPool = options.pool ?? createBrowserPool();
   const live = options.live ?? createLiveHub();
+  const branches = createBranchRegistry({
+    cwd,
+    previews: (config?.previews ?? []).flatMap((preview) => preview.branch === void 0 ? [] : [{ title: preview.title, branch: preview.branch }]),
+    installCommand: config?.installCommand ?? DEFAULT_INSTALL_COMMAND,
+    devCommand: config?.devCommand,
+    onChange: () => live.nudge("config"),
+    ...options.startWorktree === void 0 ? {} : { startWorktree: options.startWorktree }
+  });
+  const previewForConfig = (preview) => {
+    if (preview.branch === void 0)
+      return preview;
+    const state = branches.state(preview.title) ?? { status: "idle" };
+    const { url: route, ...withoutUrl } = preview;
+    const branchUrl = branches.url(preview.title);
+    return state.status === "ready" ? {
+      ...withoutUrl,
+      url: `${branchUrl ?? state.worktree.url}${route}`,
+      state: publicBranchState(state)
+    } : { ...withoutUrl, state: publicBranchState(state) };
+  };
+  const previewsForConfig = (previews) => previews.map(previewForConfig);
+  const readyPreview = (preview) => {
+    if (preview.branch === void 0)
+      return preview;
+    const state = branches.state(preview.title);
+    return state?.status === "ready" ? { ...preview, url: `${branches.url(preview.title) ?? state.worktree.url}${preview.url}` } : null;
+  };
   if (options.pool === void 0) {
     void reapOrphanedBrowsers().catch(() => {
     });
@@ -5701,7 +6070,7 @@ async function startServer(options) {
     }
     return Promise.resolve(agentsCache.agents);
   };
-  const livePreviews = async () => {
+  const livePreviewDefinitions = async () => {
     const localRead = await readLocalPreviews(cwd).catch(() => null);
     const local = localRead?.errors.length === 0 ? localRead.previews : [];
     const localTitles = new Set(local.map((entry) => entry.title));
@@ -5711,6 +6080,7 @@ async function startServer(options) {
     const fresh = local.filter((entry) => !known.has(entry.title) && entry.branch === void 0 && entry.file === void 0);
     return [...boot, ...fresh];
   };
+  const livePreviews = async () => (await livePreviewDefinitions()).map(readyPreview).filter((preview) => preview !== null);
   void probeAgents().catch(() => {
   });
   const server = http2.createServer((req, res) => {
@@ -5728,11 +6098,11 @@ async function startServer(options) {
         errors.push(notice);
       return void readLocalPreviews(cwd).then(({ previews: local, errors: localErrors }) => {
         if (localErrors.length > 0) {
-          return sendJson(res, 200, {
+          return sendConditionalJson(req, res, {
             project,
             devServer: target,
             scanPreviews: config?.scanPreviews ?? true,
-            previews: boot,
+            previews: previewsForConfig(boot),
             errors,
             warnings: configWarnings
           });
@@ -5741,23 +6111,58 @@ async function startServer(options) {
         const currentBoot = boot.filter((preview) => preview.local !== true || localTitles.has(preview.title));
         const known = new Set(currentBoot.map((preview) => preview.title));
         const fresh = local.filter((preview) => !known.has(preview.title) && preview.branch === void 0 && preview.file === void 0);
-        sendJson(res, 200, {
+        sendConditionalJson(req, res, {
           project,
           devServer: target,
           scanPreviews: config?.scanPreviews ?? true,
-          previews: [...currentBoot, ...fresh],
+          previews: previewsForConfig([...currentBoot, ...fresh]),
           errors,
           warnings: configWarnings
         });
-      }).catch(() => sendJson(res, 200, {
+      }).catch(() => sendConditionalJson(req, res, {
         project,
         devServer: target,
         scanPreviews: config?.scanPreviews ?? true,
-        previews: boot,
+        previews: previewsForConfig(boot),
         errors,
         warnings: configWarnings
       }));
     }
+    if (path === `${LEGLAS_PREFIX}/api/previews/start` && req.method === "POST") {
+      let body = "";
+      req.on("data", (chunk) => body += chunk);
+      return void req.on("end", async () => {
+        const parsed = jsonBody(body);
+        if (parsed === null) {
+          return sendJson(res, 400, { ok: false, error: "Body must be JSON." });
+        }
+        if (typeof parsed.title !== "string" || parsed.title.trim() === "") {
+          return sendJson(res, 400, { ok: false, error: "Body needs a direction title." });
+        }
+        const preview = (await livePreviewDefinitions()).find((entry) => entry.title === parsed.title);
+        if (preview === void 0) {
+          return sendJson(res, 404, { ok: false, error: "No such direction." });
+        }
+        if (preview.branch === void 0) {
+          return sendJson(res, 400, {
+            ok: false,
+            error: `"${preview.title}" is not a branch preview.`
+          });
+        }
+        if (config?.devCommand === void 0) {
+          return sendJson(res, 400, {
+            ok: false,
+            error: `"${preview.title}" cannot start because the config sets no devCommand.`
+          });
+        }
+        void branches.start(preview.title);
+        const state = branches.state(preview.title);
+        if (state === void 0) {
+          return sendJson(res, 404, { ok: false, error: "No such branch preview." });
+        }
+        return sendJson(res, 200, { ok: true, state: publicBranchState(state) });
+      });
+    }
     if (path === `${LEGLAS_PREFIX}/api/previews/delete` && req.method === "POST") {
       let body = "";
       req.on("data", (chunk) => body += chunk);
@@ -6149,7 +6554,7 @@ async function startServer(options) {
         waiting: null,
         failedIds: []
       };
-      return void readRequests(cwd).then((requests) => sendJson(res, 200, {
+      return void readRequests(cwd).then((requests) => sendConditionalJson(req, res, {
         requests: requests.map(({ id, title, intent, mode, status, failure, notes }) => ({
           id,
           title,
@@ -6252,7 +6657,7 @@ async function startServer(options) {
       });
     }
     if (path === `${LEGLAS_PREFIX}/api/annotations` && req.method === "GET") {
-      return void readAnnotations(cwd).then((annotations) => sendJson(res, 200, { annotations }));
+      return void readAnnotations(cwd).then((annotations) => sendConditionalJson(req, res, { annotations }));
     }
     if (path === `${LEGLAS_PREFIX}/api/annotations` && req.method === "POST") {
       if (!hasJsonBody(req)) {
@@ -6378,7 +6783,7 @@ async function startServer(options) {
       });
     }
     if (path === `${LEGLAS_PREFIX}/api/health`) {
-      return void probe(target).then((reachable) => sendJson(res, 200, { devServer: target, reachable, cwd }));
+      return void probe(target).then((reachable) => sendConditionalJson(req, res, { devServer: target, reachable, cwd }));
     }
     if (path.startsWith(`${FILES_PREFIX}/`)) {
       const rest = path.slice(FILES_PREFIX.length + 1);
@@ -6452,7 +6857,12 @@ async function startServer(options) {
         return closePromise;
       liveFiles.close();
       liveHealth.close();
-      closePromise = Promise.all([runner.stop(), browserPool.close(), live.close()]).then(() => new Promise((done) => {
+      closePromise = Promise.all([
+        branches.stop(),
+        runner.stop(),
+        browserPool.close(),
+        live.close()
+      ]).then(() => new Promise((done) => {
         for (const socket of sockets)
           socket.destroy();
         sockets.clear();
@@ -6563,7 +6973,7 @@ async function runInit(options, deps) {
 
 // src/run-keep.ts
 import { existsSync as existsSync4 } from "fs";
-import { mkdir as mkdir9, readFile as readFile13, rm as rm5, writeFile as writeFile10 } from "fs/promises";
+import { copyFile as copyFile2, mkdir as mkdir9, readFile as readFile13, rm as rm5, writeFile as writeFile10 } from "fs/promises";
 import { dirname as dirname9, join as join14 } from "path";
 
 // src/resolve-title.ts
@@ -6591,6 +7001,29 @@ function renameExport(source, to) {
     to
   );
 }
+async function writeLogEntry(options) {
+  const entry = composeEntry({
+    surface: options.surface,
+    won: options.won,
+    previews: options.previews,
+    requests: await readRequests(options.cwd),
+    annotations: await readAnnotations(options.cwd),
+    date: (/* @__PURE__ */ new Date()).toISOString().slice(0, 10)
+  });
+  const dir = join14(options.cwd, options.logDir);
+  await mkdir9(dir, { recursive: true });
+  const file = join14(dir, `${entry.slug}.md`);
+  await writeFile10(file, entry.markdown, "utf8");
+  if (entry.pictures.length > 0) {
+    const pictureDir = join14(dir, entry.slug);
+    await mkdir9(pictureDir, { recursive: true });
+    for (const picture of entry.pictures) {
+      await copyFile2(join14(options.cwd, picture.from), join14(pictureDir, picture.to)).catch(() => {
+      });
+    }
+  }
+  return `${options.logDir}/${entry.slug}.md`;
+}
 async function runKeep(options, deps) {
   const loaded = await loadConfig(options.cwd);
   const local = await readLocalPreviews(options.cwd);
@@ -6619,6 +7052,20 @@ async function runKeep(options, deps) {
   const source = await readFile13(from, "utf8");
   await mkdir9(dirname9(to), { recursive: true });
   await writeFile10(to, renameExport(source, plan.exportName), "utf8");
+  const surface = plan.removeDir.slice(plan.removeDir.lastIndexOf("/") + 1);
+  let logged = null;
+  let logError = null;
+  try {
+    logged = await writeLogEntry({
+      cwd: options.cwd,
+      logDir: loaded.config?.logDir ?? DEFAULT_LOG_DIR,
+      surface,
+      won: { title: resolved.title, to: plan.move.to },
+      previews: previews.filter((preview) => plan.dropTitles.includes(preview.title))
+    });
+  } catch (error) {
+    logError = error instanceof Error ? error.message : String(error);
+  }
   await rm5(join14(options.cwd, plan.removeDir), { recursive: true, force: true });
   const dropped = await dropLocalPreviews(options.cwd, plan.dropTitles);
   if (options.json) {
@@ -6630,6 +7077,8 @@ async function runKeep(options, deps) {
         exportName: plan.exportName,
         removed: plan.removeDir,
         droppedPreviews: dropped,
+        logged,
+        logError,
         instructions: plan.instructions
       })
     );
@@ -6637,6 +7086,8 @@ async function runKeep(options, deps) {
   }
   deps.log(`  kept     ${plan.move.to}`);
   deps.log(`  removed  ${plan.removeDir}`);
+  if (logged !== null) deps.log(`  logged   ${logged}`);
+  if (logError !== null) deps.error(`  The decision log could not be written: ${logError}`);
   if (dropped > 0) {
     deps.log(`  dropped  ${dropped} direction${dropped === 1 ? "" : "s"} from the rail`);
   }
@@ -7367,8 +7818,7 @@ async function run3(options, deps) {
   const local = await readLocalPreviews(options.cwd);
   let devServer = options.userPort === void 0 ? loaded.config?.devServer ?? "http://localhost:3000" : `http://localhost:${options.userPort}`;
   const merged = loaded.config === null ? null : { ...loaded.config, devServer, previews: [...loaded.config.previews, ...local.previews] };
-  const worktrees = [];
-  const worktreeErrors = [];
+  const previewErrors = [];
   const previews = [];
   let app = null;
   const needsApp = (merged?.previews ?? []).some(
@@ -7385,7 +7835,7 @@ async function run3(options, deps) {
       devServer = app.url;
       merged.devServer = app.url;
     } catch (error) {
-      worktreeErrors.push(error instanceof Error ? error.message : String(error));
+      previewErrors.push(error instanceof Error ? error.message : String(error));
     }
   }
   const fileMounts = /* @__PURE__ */ new Map();
@@ -7393,7 +7843,7 @@ async function run3(options, deps) {
     if (preview.file !== void 0) {
       const absolute = join19(options.cwd, preview.file);
       if (!existsSync6(absolute)) {
-        worktreeErrors.push(
+        previewErrors.push(
           `"${preview.title}" names file ${preview.file}, which does not exist. The preview is skipped.`
         );
         continue;
@@ -7409,29 +7859,7 @@ async function run3(options, deps) {
       });
       continue;
     }
-    if (preview.branch === void 0) {
-      previews.push(preview);
-      continue;
-    }
-    if (merged?.devCommand === void 0) {
-      worktreeErrors.push(
-        `"${preview.title}" names branch ${preview.branch}, but the config sets no devCommand, so Leglas cannot start that checkout. Add devCommand (with {port}) to the config.`
-      );
-      continue;
-    }
-    if (!options.json) deps.log(`  starting ${preview.branch}\u2026`);
-    try {
-      const worktree = await startWorktree({
-        cwd: options.cwd,
-        branch: preview.branch,
-        installCommand: merged.installCommand,
-        devCommand: merged.devCommand
-      });
-      worktrees.push(worktree);
-      previews.push({ ...preview, url: `${worktree.url}${preview.url}` });
-    } catch (error) {
-      worktreeErrors.push(error instanceof Error ? error.message : String(error));
-    }
+    previews.push(preview);
   }
   const config = merged === null ? null : { ...merged, previews };
   const configWarnings = [];
@@ -7441,7 +7869,7 @@ async function run3(options, deps) {
   const ownerWarning = needsApp && app === null ? inspectLocalDevServer(devServer).then((owners) => devServerOwnerWarning(devServer, projectRoot, owners)).catch(() => null) : Promise.resolve(null);
   const serverPromise = startServer({
     config,
-    configErrors: [...loaded.errors, ...local.errors, ...worktreeErrors],
+    configErrors: [...loaded.errors, ...local.errors, ...previewErrors],
     configWarnings,
     fileMounts,
     shellDir: findShellDir(),
@@ -7480,9 +7908,9 @@ async function run3(options, deps) {
     );
     deps.log(`config   ${configLabel}`);
     deps.log(`          ${previewCount} preview${previewCount === 1 ? "" : "s"}`);
-    if (loaded.errors.length + worktreeErrors.length > 0) {
+    if (loaded.errors.length + previewErrors.length > 0) {
       deps.log("");
-      for (const error of [...loaded.errors, ...worktreeErrors]) deps.log(`  ! ${error}`);
+      for (const error of [...loaded.errors, ...previewErrors]) deps.log(`  ! ${error}`);
       deps.log("  Fix the config and reload; Leglas will pick it up on restart.");
     }
     if (configWarnings.length > 0) {
@@ -7505,8 +7933,6 @@ async function run3(options, deps) {
     devServer,
     previewCount,
     stop: async () => {
-      await Promise.all(worktrees.map((worktree) => worktree.stop().catch(() => {
-      })));
       await app?.stop().catch(() => {
       });
       await server.close();