@kurtbruns/kestrel 1.5.0 → 1.6.0

package/CHANGELOG.md

@@ -10,6 +10,57 @@ To move a running instance from one version to another, follow [Upgrade to a new
 
 <!-- Add entries under Added / Changed / Fixed / Breaking. One operator-facing line each; see .claude/rules/changelog.md. Upgrade steps (a migration, a new setting) go once, in the Upgrading paragraph, never on an entry. -->
 
+## [1.6.0] - 2026-10-11
+
+**Upgrading from 1.5.0.** One database migration: run `npm run sync-migrations`, then `npx wrangler d1 migrations apply DB --remote --env production` (and `--local` for local development) before deploying. Existing posts keep their slugs and read as set by hand; tick *Auto-generate from subject* on a draft to have its slug follow the subject again. On npm 12, to end `npm install` without the blocked-install-scripts warning, add this to your `package.json` (a new instance has it already): `"allowScripts": { "esbuild": true, "fsevents": true, "workerd": true }`.
+
+### Breaking
+
+- Cancel, reschedule, and Resolve no longer take a precondition: an `If-Match` header on them, and Resolve's `expected_count`, are now ignored, and the `precondition_failed` and `count_changed` refusals are gone. Each act applies to the send as it stands and answers with the result, so a retry after a lost answer is answered `changed: false` instead of a 412, and two acts made moments apart both land, each shown at once and reversible before the fire time (SPEC §1, §8).
+
+### Added
+
+- Settings has a **Reader pages** section that shows every page a reader can land on, including the expired and invalid links a reader rarely meets and the landing page and archive as visitors find them before your first post: an outline lists each journey (subscribe, confirm, unsubscribe, reading) with its pages, and the one you pick shows beside it at desktop or phone width. Each is the real page rendered with your publication's identity and sample values, so you can see what readers see without walking the flows; nothing on a preview acts (SPEC §5).
+- The editor shows a post's **web version**: the post as its public page will look, with the template's email-only parts left out and the masthead and display font added, so you can proof the page before it's permanent. **Web version ↗** in the editor opens it in a new tab, under a strip above the page that says where the post stands and where its public page will be, and replaces **Open in browser**, which showed the same email as the Preview tab. The email's own "View in browser" link in the Preview tab opens the web version too, rather than a public page that doesn't exist yet. Once a post's send starts, the web version opens its public page (SPEC §5).
+
+### Changed
+
+- A logo you upload in Settings is now cropped to its center square and saved as a 256 × 256 image, so it looks the same everywhere and is never stretched in an email. The tile shows the result, the confirmation says when the edges were cropped, and Replace picks another. A logo you uploaded before that isn't square is flagged in Settings, since emails show it stretched; upload it again to have it cropped.
+- Settings orders its sections by whom they serve, editable first: your publication's identity; then, in the order a reader meets them, the ways to subscribe, the confirmation email, and the reader pages; then the email template and your test recipients; then notifications; and last, read-only, what only a redeploy changes (the email sender and the instance). The embeddable form's Styled | Plain choice is now the same toggle as the page's other two-way choices.
+- The subscribe page and the Styled embed tell a reader what happens next in plain words, "We'll email you a link to confirm. Unsubscribe anytime.", instead of "Double opt-in".
+- Settings' **Ways to subscribe** shows its two ways as matching parts of one card, the subscribe page first and the embeddable form second, each with a line on what it is for. The page's address reads as a value with Copy and Open beside it, and the embeddable form shows beside its snippet, both in view at once, with the Styled | Plain choice named only on its toggle and a **Copy HTML** button at the end, where the form's one act belongs. The **Styled** snippet, now offered first, looks like your hosted subscribe page: a Georgia serif headline over a sans body, in the reader pages' ink colors. A form already pasted into a site keeps the look it was copied with; copy it again to take the new one.
+- Copying in the editor says it worked on the Copy itself, its glyph turning to a check for a moment, instead of a "Copied" toast: the subscribe page's address and the embeddable form in Settings, the addresses and setup step on the dashboard, and the whole template on the Template page.
+- A post now records whether its slug follows the subject or was set by hand (`slug_auto` on the post and on a save), which the editor's *Auto-generate from subject* box now shows rather than guesses. A slug that follows is derived and numbered afresh on every draft save, through the API as well as the editor, so a script that creates posts should take the slug from each save's answer rather than keep the one it was created with. A draft numbered because another post held its slug (`spring-update-2`) drops the number once that post is deleted, and a slug set by hand that looks numbered, like `spring-update-2027`, is no longer mistaken for one that follows and replaced by a subject edit (SPEC §4).
+- A post's page, the archive index, and the landing page show a post as soon as its send starts, dated by when it went out, so a reader who opens "View in browser" while a large send is still going out finds the post instead of "Not found". A send's view links the published post from the start too (SPEC §5).
+- The confirm, unsubscribe, and post-not-found pages now wear your publication's reader look (its name, logo, and serif headline), like the subscribe page, instead of a plain grey card, so a reader arriving from an email sees your newsletter, and the pages that ask a reader to confirm or to unsubscribe name it in their headline when it has a name ("Confirm your subscription to …", "Unsubscribe from …?"). They carry no subscribe call to action in the masthead, and they are never cached or indexed, since some show the reader's address (SPEC §5).
+- A test email's links now land on pages that say what they are. Its "View in browser" link, before the send starts, opens "Nothing here yet" (the same page any archive address without a published post shows, so a scheduled post is never revealed) instead of "Not found", and its unsubscribe link, like the one in the editor's preview, opens the page a subscriber sees instead of "This link is invalid": marked as a test, with a sample address, and walking through it changes no one's subscription (SPEC §5, §7).
+- The operator's Claude context no longer tells Claude to send `If-Match` when it acts on a send, or to handle `precondition_failed`, since neither applies any more. It now says an act is safe to repeat and that every answer carries the send as it now stands. `npm run check-context` reports the change; if you edited your `.claude/CLAUDE.md`, replace that line by hand.
+- `kestrel seed` and `kestrel reset` (`npm run seed`, `npm run reset`) with no port given now act only on the dev server `kestrel dev` started in the same folder, and refuse otherwise: when none is running there, or when the server on its port isn't that one (started some other way, or another folder's). Before, they fell back to port 8787 and could wipe another local server's database. `PORT` no longer aims them, since a shell can carry it unawares; to act on another server on purpose, name its port as an argument: `npm run seed -- 8787`.
+- The operator's Claude context now says that seed and reset act only on the dev server started in the instance's folder, and tells Claude to start that server when they refuse rather than name another server's port, which the person must mean. It bears on safety: both wipe the database they reach. `npm run check-context` reports the change; if you edited your `.claude/CLAUDE.md`, add the sentence by hand.
+
+### Fixed
+
+- An email you've sent, and its archive page, now keep the logo it went out with. Before, uploading a new logo changed it in every past email and archive page beside their original name and tagline, and removing the logo left a broken image in all of them. Each upload is now kept, and a new one or a removal changes only what you send from then on. A logo uploaded before this release stays where its past emails point, and from now on is never replaced (SPEC §9).
+- A publication with no name, and no display name on its sending address, is no longer called "Newsletter" on its reader pages while its email carries no name. Every surface now reads the name the same way and, with none, shows none: the pages say "Subscribe", "Confirm your subscription", and "Unsubscribe?", their tab titles drop the name, the masthead shows only what you've set (or a link home reading "Archive"), and the subscribe embed in Settings reads "Subscribe" (SPEC §9).
+- Toasts no longer pile up in a column up the middle of the screen. At most three show at once, a repeated message (clicking Copy five times, or a save failing again while you type) restarts the one already showing instead of adding another, and one leaving lets the rest slide into place. A longer toast on a phone now uses the screen's width instead of wrapping into a narrow column.
+- A new instance's `npm install` on npm 12 no longer ends with a warning that install scripts were blocked for esbuild and workerd (and fsevents on a Mac). The instance's `package.json` now allows them by name, so their scripts run as wrangler expects and the entry doesn't go stale when wrangler moves to a new version.
+- Two send-now requests for the same post that arrive at the same moment (from Claude and the editor, say) now both answer with the one send they made. Before, the one that lost the race was refused with "post already has an active send", though the send was scheduled and no one was mailed twice; a later repeat already answered this way (SPEC §6).
+- A draft deleted elsewhere (in another tab, or by Claude) now says so once and goes to Drafts, instead of failing each save with "Couldn't save your changes". Opening a post that is no longer there goes to Drafts and says so, instead of an error page whose Retry can only fail again. Canceling a scheduled post that was deleted elsewhere says the same, and a Cancel that lands after the send time now says plainly that it's too late and the email is going out, instead of showing the server's refusal (SPEC §4).
+- A link in a notification email now opens the send it is about even when you have to sign in first. Before, the sign-in dropped the page from the link and you landed on the dashboard home (SPEC §8).
+- Leaving a draft while a save was still going (just after leaving the subject or slug field, say) no longer warns "Changed elsewhere — your edits weren't saved" about your own save, and an edit made while that save was going is no longer lost. The editor now waits for the save to land and saves what is left on top of it.
+- A link in a post's Preview tab, or in the sample email on the Template page and in Settings, now opens in a new tab. Before, it loaded in the preview's frame, which went blank when the page refused to be framed, as most do, and the preview was lost until you switched tabs.
+- The sample email on the Template page and in Settings no longer runs script a template carries. A template with an inline handler (an image's `onerror`, say) could act in the editor with your session; the sample now shows the template the way the Preview tab shows a post, with nothing in it able to run (SPEC §5).
+- On a draft's Preview tab, "Paste, drop, or click to add images" now dims and ignores clicks, like the formatting toolbar. Before, a click there added the image to the hidden Edit text and left the preview unchanged. Dropping an image still works and switches to Edit.
+- A send wedged on recipients whose delivery is unknown now keeps its count and its Resolve control until you resolve it. A delivery receipt that named the address but not the message could settle those recipients in its place, so the count you saw shrank, and once the last one was reached the Resolve control vanished and the send sat stuck with nothing in the editor or the API to finish it (SPEC §12).
+- The editor's slug field shows only the slug the post actually has. It used to preview a slug from the subject while you typed, and tabbing through the slug field into the body could leave that preview showing a slug another post already held until the next save. The field now updates when the subject is left, with the slug the server gave, numbered if it was taken. Enter in the subject or slug field saves, as leaving it does, and so does ticking the box that has the slug follow the subject. A slug you're typing by hand is never rewritten under the cursor: what it was saved as shows once you leave the field.
+- On a checkout with Windows line endings, `npm run sync-migrations` no longer refuses every migration as edited, and `npm run check-context` no longer reports the Claude Code files as having no header.
+- `kestrel init` on Windows no longer leaves an extra `claude` folder beside `.claude`, and `npm run check-context -- --merged` accepts a Windows path.
+- `npm run check-context` now prints commands that run as written (`npm run check-context -- --update`, `-- --merged`), where it printed a bare `kestrel` that isn't on the path.
+- `kestrel init` refuses before writing anything when a migration of the release's is already there, where it wrote the other files first.
+- When the web version, a post's Preview tab, or a send's CSV export can't be loaded, the editor now says why, such as "post has no content yet". Before, a deployed instance, served over HTTP/2, showed an empty error box or toast, and a local one only "Not Found" or "Bad Request". A web version address with no post says "There's no post here. It may have been deleted.", and a preview whose post was deleted elsewhere says so. An error page that isn't the API's own, such as a proxy's, now names its HTTP status anywhere in the editor, where it could show a JSON parse error.
+- The Worker no longer writes "using deprecated parameters for the initialization function" to its logs the first time it renders an email after starting, a plain-text line among the structured ones.
+- The Worker no longer writes "Called .text() on an HTTP body which does not appear to be text" to its logs when a request to the API sends a body that isn't JSON (a form post, say); the request is still refused the same way.
+
 ## [1.5.0] - 2026-10-09
 
 **Upgrading from 1.4.0.** No migration. Any script or API client that saves posts must send the revision it read, as `base_revision` or `If-Match`; the editor already does.
@@ -236,7 +287,8 @@ The first tagged release: a self-contained newsletter app on a Cloudflare Worker
 - A build-version stamp: every instance reports its version, commit, and build time, read-only in the editor and at `GET /api/version`.
 - This changelog and a semantic-versioning release process.
 
-[Unreleased]: https://github.com/kurtbruns/kestrel/compare/v1.5.0...HEAD
+[Unreleased]: https://github.com/kurtbruns/kestrel/compare/v1.6.0...HEAD
+[1.6.0]: https://github.com/kurtbruns/kestrel/releases/tag/v1.6.0
 [1.5.0]: https://github.com/kurtbruns/kestrel/releases/tag/v1.5.0
 [1.4.0]: https://github.com/kurtbruns/kestrel/releases/tag/v1.4.0
 [1.3.0]: https://github.com/kurtbruns/kestrel/releases/tag/v1.3.0

package/cli/context.mjs

@@ -41,8 +41,15 @@ export function shippedPath(file) {
 // The header line, as a Markdown comment or, inside a skill's front matter, a YAML one.
 const HEADER = /^.*@kurtbruns\/kestrel (\S+), sha256:([0-9a-f]{64}).*\n/m;
 
+// Files are compared and hashed with LF line endings, so a checkout that turns them into CRLF
+// (git's autocrlf on Windows) reads as the same file, not as an edit.
+const lf = (text) => text.replace(/\r\n/g, "\n");
+const read = (path) => lf(readFileSync(path, "utf8"));
 const sha256 = (text) => createHash("sha256").update(text).digest("hex");
 
+// How an operator runs this command: `kestrel` is on the PATH only inside an npm script.
+const RUN = "npm run check-context --";
+
 /** A context file's header (`version`, `hash`, or null when it has none) and its body. */
 function parse(text) {
   const m = HEADER.exec(text);
@@ -72,17 +79,17 @@ export function stamp(body, hash = sha256(body)) {
 export function writeShipped(root, file) {
   const to = join(root, file);
   mkdirSync(dirname(to), { recursive: true });
-  writeFileSync(to, stamp(readFileSync(shippedPath(file), "utf8")));
+  writeFileSync(to, stamp(read(shippedPath(file))));
 }
 
 /** Where a context file stands against the installed release. */
 function status(root, file) {
   const path = join(root, file);
-  const release = readFileSync(shippedPath(file), "utf8");
+  const release = read(shippedPath(file));
   if (!existsSync(path)) {
     return { state: "missing" };
   }
-  const { header, body } = parse(readFileSync(path, "utf8"));
+  const { header, body } = parse(read(path));
   const releaseHash = sha256(release);
   if (sha256(body) === releaseHash) {
     return { state: "current", header, restamp: header?.hash !== releaseHash };
@@ -104,8 +111,8 @@ function diff(root, file) {
   const dir = mkdtempSync(join(tmpdir(), "kestrel-context-"));
   const name = basename(file);
   for (const [side, text] of [
-    ["yours", parse(readFileSync(join(root, file), "utf8")).body],
-    ["release", readFileSync(shippedPath(file), "utf8")],
+    ["yours", parse(read(join(root, file))).body],
+    ["release", read(shippedPath(file))],
   ]) {
     mkdirSync(join(dir, side));
     writeFileSync(join(dir, side, name), text);
@@ -129,7 +136,7 @@ function diff(root, file) {
 export function checkContextCommand(argv, root = process.cwd()) {
   const mergedAt = argv.indexOf("--merged");
   if (mergedAt !== -1) {
-    const file = relative(root, resolve(root, argv[mergedAt + 1] ?? ""));
+    const file = relative(root, resolve(root, argv[mergedAt + 1] ?? "")).replaceAll("\\", "/");
     if (!CONTEXT_FILES.includes(file) || !existsSync(join(root, file))) {
       console.error(
         `[check-context] --merged takes one of: ${CONTEXT_FILES.join(", ")} (and it must exist).`,
@@ -137,8 +144,8 @@ export function checkContextCommand(argv, root = process.cwd()) {
       process.exit(1);
     }
     // The body stays the operator's; the header now says it has this release's changes.
-    const { body } = parse(readFileSync(join(root, file), "utf8"));
-    const release = readFileSync(shippedPath(file), "utf8");
+    const { body } = parse(read(join(root, file)));
+    const release = read(shippedPath(file));
     writeFileSync(join(root, file), stamp(body, sha256(release)));
     console.log(`[check-context] ${file}: recorded as merged with ${PACKAGE.version}`);
     return;
@@ -162,7 +169,9 @@ export function checkContextCommand(argv, root = process.cwd()) {
           console.log(`[check-context] ${file}: restored from ${PACKAGE.version}`);
         } else {
           pending++;
-          console.log(`[check-context] ${file}: missing; --update writes ${PACKAGE.version}'s`);
+          console.log(
+            `[check-context] ${file}: missing; \`${RUN} --update\` writes ${PACKAGE.version}'s`,
+          );
         }
         break;
       case "outdated":
@@ -172,7 +181,7 @@ export function checkContextCommand(argv, root = process.cwd()) {
         } else {
           pending++;
           console.log(
-            `[check-context] ${file}: Kestrel ${PACKAGE.version} changed it${had}, and you haven't edited it; --update takes the new one`,
+            `[check-context] ${file}: Kestrel ${PACKAGE.version} changed it${had}, and you haven't edited it; \`${RUN} --update\` takes the new one`,
           );
         }
         break;
@@ -191,7 +200,7 @@ export function checkContextCommand(argv, root = process.cwd()) {
             : `  From yours to ${PACKAGE.version}'s, header aside (lines starting + are the release's):\n${d}`,
         );
         console.log(
-          `  Merge what you want of it into yours, then record that: kestrel check-context --merged ${file}`,
+          `  Merge what you want of it into yours, then record that: ${RUN} --merged ${file}`,
         );
         break;
       }

package/cli/dev-api.mjs

@@ -7,8 +7,15 @@
  * they do is what the editor or Claude could do, and it lands in the database the server
  * is actually serving. The token comes from the dev-only `/api/dev/token` route, which
  * exists only on a local dev server (fake transport, no Access, a loopback origin).
+ *
+ * Seed and reset wipe the database of the server they reach, so a target they find for
+ * themselves must prove it is this directory's: the port `kestrel dev` recorded here, and a
+ * server there that reports the run ID recorded with it (cli/dev-server.mjs). A target the
+ * caller names, a port or URL argument, is their choice and is used as given. `PORT` names
+ * nothing here: a shell can carry it without the caller meaning anything by it, and a
+ * target that wipes a database has to be named on purpose.
  */
-import { readDevPort } from "./dev-port.mjs";
+import { readDevServer } from "./dev-server.mjs";
 
 /** Split argv into `--flag value` / `--flag=value` pairs, bare `--flag`s (true), and
  *  positionals, so a script's flags can be given in any order. */
@@ -35,13 +42,68 @@ export function parseArgs(argv, booleans = []) {
   return { flags, positional };
 }
 
-/** The dev server's base URL: a URL or port argument, else `PORT`, else the port the
- *  dev server recorded in this directory (cli/dev-port.mjs), else 8787. */
-export function baseUrl(arg) {
+/**
+ * Where a dev command aims, decided from what it was given and this directory's record:
+ * `{ base, explicit: true }` for a port or URL argument, used as given;
+ * `{ base, expectId }` for the recorded server, which must then report that ID
+ * (`ownsServer`); or `{ refuse: "unrecorded" }` when nothing names a server and none is
+ * recorded here. There is no fallback port: a guess could be another directory's server.
+ */
+export function chooseTarget({ arg, record }) {
   if (arg) {
-    return /^https?:\/\//.test(arg) ? arg : `http://localhost:${arg}`;
+    return { base: /^https?:\/\//.test(arg) ? arg : `http://localhost:${arg}`, explicit: true };
+  }
+  if (!record) {
+    return { refuse: "unrecorded" };
+  }
+  return { base: `http://localhost:${record.port}`, expectId: record.id };
+}
+
+/** Whether the server at `target` may be acted on, given the run ID it reported (undefined
+ *  when it reported none): always for a target the caller named, else only on a match. */
+export function ownsServer(target, reportedId) {
+  return target.explicit === true || (reportedId !== undefined && reportedId === target.expectId);
+}
+
+/**
+ * The dev server to act on and a local admin token for it, `{ base, token }`, or exit saying
+ * why there is none to act on (see `chooseTarget`). `arg` is the command's port or URL
+ * argument, if any; `tag` names the command, as in `npm run <tag>`.
+ */
+export async function devTarget(arg, tag) {
+  const target = chooseTarget({ arg, record: readDevServer() });
+  const deliberately = [
+    `To act on a server deliberately, name its port: \`npm run ${tag} -- <port>\`.`,
+    ...(process.env.PORT
+      ? [
+          `(PORT=${process.env.PORT} is set, but PORT doesn't name a target here: a shell can carry it unawares.)`,
+        ]
+      : []),
+  ];
+  if (target.refuse) {
+    fail(
+      tag,
+      "no dev server is recorded in this directory, so there is no server here to act on.",
+      "Start one here with `npm run dev` (it runs `kestrel dev`, which records it), then run this again.",
+      ...deliberately,
+    );
+  }
+  const { token, runId } = await devToken(target.base, tag);
+  if (!ownsServer(target, runId)) {
+    fail(
+      tag,
+      `the server at ${target.base} isn't this directory's dev server, so it was left alone.`,
+      runId === undefined
+        ? "It reports no run ID, so it wasn't started by `npm run dev` here."
+        : "It reports another run's ID: the server recorded here has stopped, and another holds its port.",
+      "Start this directory's with `npm run dev`, then run this again.",
+      ...deliberately,
+    );
+  }
+  if (target.explicit) {
+    console.log(`[${tag}] acting on ${target.base}, as named`);
   }
-  return `http://localhost:${process.env.PORT || readDevPort() || "8787"}`;
+  return { base: target.base, token };
 }
 
 /** Print a failure under the script's tag and exit. */
@@ -54,9 +116,10 @@ export function fail(tag, ...lines) {
   process.exit(1);
 }
 
-/** Mint a local admin token, a `service` principal as Claude is in production, or exit
+/** Mint a local admin token, a `service` principal as Claude is in production, with the run
+ *  ID the server reports (undefined when it reports none), as `{ token, runId }`, or exit
  *  saying why the server can't give one. */
-export async function devToken(base, tag) {
+async function devToken(base, tag) {
   let res;
   try {
     res = await fetch(`${base}/api/dev/token?kind=service`);
@@ -76,7 +139,8 @@ export async function devToken(base, tag) {
   if (!res.ok) {
     fail(tag, `could not mint a dev token: ${res.status} ${res.statusText}`);
   }
-  return (await res.json()).token;
+  const { token, runId } = await res.json();
+  return { token, runId: typeof runId === "string" && runId ? runId : undefined };
 }
 
 /** Call the API as `token`: JSON in, JSON out. Resolves `{ status, ok, body }`, or exits

package/cli/dev-server.mjs

@@ -0,0 +1,72 @@
+/*
+ * The record of this directory's dev server, shared between `kestrel dev` (cli/dev.mjs) and
+ * the seed and reset commands: the port it bound and the ID of that run.
+ *
+ * Why this exists: seed and reset wipe the database of whichever server they reach, and more
+ * than one dev server can be running on this machine (a second worktree, an instance repository
+ * beside this one). `npm run dev` can bind a port other than 8787 (Claude Code's preview
+ * autoPort picks a free one and hands it over in PORT; `kestrel dev` falls back to a free one
+ * when 8787 is busy), and that choice reaches only the dev child, so a `npm run seed` in another
+ * terminal never sees it. The port alone isn't proof either: a server started some other way
+ * (a raw `wrangler dev --port N`) leaves no record, and a record left by a server that has since
+ * stopped can name a port another directory's server now holds. So `kestrel dev` makes up an ID
+ * for each run, records it here with the port, and hands it to the Worker (the `DEV_RUN_ID`
+ * var), which reports it beside the dev token. Seed and reset with no target given go only to
+ * the recorded port, and only when the server there reports this record's ID (cli/dev-api.mjs).
+ *
+ * Scope: the file lives under `.wrangler/`, which is gitignored and per-directory (each worktree
+ * has its own `.wrangler/state`), so the record is scoped to this directory and never committed.
+ * It replaces the bare-port `.wrangler/dev-port` of earlier releases, which is removed when a dev
+ * server starts and is never read: a port with no ID proves nothing.
+ */
+import { randomUUID } from "node:crypto";
+import { mkdirSync, readFileSync, rmSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+
+// Under the directory the command runs in: this repository, or an instance repository. The
+// directory is a parameter only so the suite can point these at a scratch one.
+const recordFile = (dir) => join(dir, ".wrangler", "dev-server.json");
+const legacyPortFile = (dir) => join(dir, ".wrangler", "dev-port");
+
+/** A fresh ID for one run of the dev server. */
+export function newDevRunId() {
+  return randomUUID();
+}
+
+/** Record the port and run ID of the dev server starting here. Best-effort: on failure there
+ *  is no record, and seed and reset refuse an implicit target rather than guess one. */
+export function writeDevServer(port, id, dir = process.cwd()) {
+  try {
+    mkdirSync(join(dir, ".wrangler"), { recursive: true });
+    writeFileSync(recordFile(dir), `${JSON.stringify({ port: String(port), id })}\n`, "utf8");
+    rmSync(legacyPortFile(dir), { force: true });
+  } catch {
+    /* best effort */
+  }
+}
+
+/** Remove this run's record when its dev server exits, so a later seed/reset says no server is
+ *  recorded rather than chase a port nothing is listening on. Only when the record is still
+ *  this run's: a second `kestrel dev` here overwrites it, and the first one stopping must not
+ *  erase the record of the one still serving. Best-effort. */
+export function clearDevServer(id, dir = process.cwd()) {
+  try {
+    if (readDevServer(dir)?.id === id) {
+      rmSync(recordFile(dir), { force: true });
+    }
+  } catch {
+    /* best effort */
+  }
+}
+
+/** The dev server last recorded in this directory, `{ port, id }`, or undefined when none is. */
+export function readDevServer(dir = process.cwd()) {
+  try {
+    const { port, id } = JSON.parse(readFileSync(recordFile(dir), "utf8"));
+    return /^\d+$/.test(String(port)) && typeof id === "string" && id
+      ? { port: String(port), id }
+      : undefined;
+  } catch {
+    return undefined;
+  }
+}

package/cli/dev.mjs

@@ -15,7 +15,8 @@
  * `--port`. This reads PORT and forwards it as `--port`. With no PORT it prefers 8787 and
  * falls back to a free port, so a second server still starts. The resolved port drives the
  * origin overrides, so the absolute URLs an email carries point at the server actually bound,
- * and is recorded (cli/dev-port.mjs) so seed and reset find this server.
+ * and is recorded with an ID made up for this run (cli/dev-server.mjs), which the Worker is
+ * handed too, so seed and reset find this server and can tell it from another directory's.
  *
  * A fresh local database. A new checkout or worktree has an empty `.wrangler/state`, so every
  * D1 route would 500 until the migrations ran. The local database is probed and, when its
@@ -34,7 +35,7 @@ import { existsSync, readFileSync } from "node:fs";
 import { createServer } from "node:net";
 import { join } from "node:path";
 import { parseEnv } from "node:util";
-import { clearDevPort, writeDevPort } from "./dev-port.mjs";
+import { clearDevServer, newDevRunId, writeDevServer } from "./dev-server.mjs";
 import { startSweepTicker } from "./sweep-ticker.mjs";
 import { captureWrangler, runWrangler, spawnWrangler } from "./wrangler.mjs";
 
@@ -69,7 +70,8 @@ function findFreePort() {
 
 // Migrate the local database when its `posts` table is genuinely missing. Wrangler's "no such
 // table" text is matched rather than any failure, so a transient probe failure (the file still
-// locked by a server just stopped) doesn't trigger a needless migrate. Best-effort: a failed
+// locked by a server just stopped) doesn't trigger a needless migrate. In a terminal, wrangler
+// asks to confirm the migrations first, as it does for any apply. Best-effort: a failed
 // bootstrap leaves things no worse than an unmigrated database would be on its own.
 function bootstrapDatabase() {
   const probe = captureWrangler([
@@ -175,28 +177,54 @@ export async function devCommand(argv, { onStop = () => {} } = {}) {
     checkDevVars(fromShell);
   }
 
-  writeDevPort(port);
+  // The Worker reports this ID beside the dev token, and seed and reset with no target given
+  // check it against the record, so they never wipe a server this directory didn't start.
+  // Not for --remote: its database is a deployed one, which an unnamed seed must never reach.
+  const runId = newDevRunId();
+  const runIdArgs = isRemote ? [] : ["--var", `DEV_RUN_ID:${runId}`];
+
+  if (!isRemote) {
+    writeDevServer(port, runId);
+  }
   // A remote session runs against deployed resources, where the real cron and the real
   // webhooks are the ones that count.
   const stopTicker = isRemote ? () => {} : startSweepTicker(origin);
   const stop = () => {
-    clearDevPort();
+    clearDevServer(runId);
     stopTicker();
     onStop();
   };
 
-  const child = spawnWrangler(["dev", "--port", port, ...originArgs, ...overrideArgs, ...argv]);
+  const child = spawnWrangler([
+    "dev",
+    "--port",
+    port,
+    ...originArgs,
+    ...overrideArgs,
+    ...runIdArgs,
+    ...argv,
+  ]);
 
   // A signal aimed at this process alone (a harness stop, `kill <pid>`) must not leave
   // wrangler serving, the ticker calling a server that is gone, or the caller's companions
-  // running. Pass it to wrangler and stop the rest, then re-raise: `once` means the re-raised
-  // signal meets the default disposition and ends us. (A terminal Ctrl-C reaches the whole
-  // group, wrangler included, and ends the same way.)
+  // running. Stop the rest at once and pass the signal to wrangler, then end once wrangler has
+  // (the exit handler below re-raises it), or after a few seconds if it doesn't. A terminal's
+  // Ctrl-C already reaches wrangler with the whole group, so SIGINT is passed on only if
+  // wrangler is still running a moment later: a second SIGINT would cut its shutdown short.
   for (const signal of ["SIGINT", "SIGTERM", "SIGHUP"]) {
     process.once(signal, () => {
-      child.kill(signal);
       stop();
-      process.kill(process.pid, signal);
+      const forward = () => {
+        if (child.exitCode === null && child.signalCode === null) {
+          child.kill(signal);
+        }
+      };
+      if (signal === "SIGINT") {
+        setTimeout(forward, 500).unref();
+      } else {
+        forward();
+      }
+      setTimeout(() => process.kill(process.pid, signal), 5000).unref();
     });
   }
 

package/cli/init.mjs

@@ -40,8 +40,9 @@ function scaffoldFiles(dir = TEMPLATE, out = []) {
       scaffoldFiles(from, out);
       continue;
     }
+    // Split on either separator, so the names match on Windows too.
     const to = relative(TEMPLATE, from)
-      .split("/")
+      .split(/[\\/]/)
       .map((part) => RENAMED[part] ?? part)
       .join("/");
     if (!CONTEXT_FILES.includes(to)) {
@@ -67,7 +68,12 @@ export function initCommand(argv) {
     ...scaffoldFiles(),
     [join(PACKAGE_ROOT, ".dev.vars.example"), ".dev.vars.example"],
   ];
-  const writes = [...files.map(([, to]) => to), ...CONTEXT_FILES];
+  // A migration of this release's already there counts too, since sync-migrations refuses
+  // to overwrite one, and by then everything else would have been written.
+  const migrations = readdirSync(join(PACKAGE_ROOT, "migrations"))
+    .filter((f) => f.endsWith(".sql"))
+    .map((f) => `migrations/${f}`);
+  const writes = [...files.map(([, to]) => to), ...CONTEXT_FILES, ...migrations];
   const taken = writes.filter((to) => existsSync(join(root, to)));
   if (taken.length > 0) {
     console.error(

package/cli/reset.mjs

@@ -6,12 +6,11 @@
  * settings), so this needs the dev server up. It shows the first-run dashboard and setup
  * checklist an operator meets when they deploy. The target is found as for seed.
  */
-import { baseUrl, callApi, devToken, fail } from "./dev-api.mjs";
+import { callApi, devTarget, fail } from "./dev-api.mjs";
 
 /** `kestrel reset [port|url]`. */
 export async function resetCommand(argv) {
-  const base = baseUrl(argv[0]);
-  const token = await devToken(base, "reset");
+  const { base, token } = await devTarget(argv[0], "reset");
   const res = await callApi(base, token, "/api/dev/reset", { method: "POST", tag: "reset" });
   if (!res.ok) {
     fail("reset", `request failed: ${res.status}`, JSON.stringify(res.body));

package/cli/seed.mjs

@@ -9,8 +9,11 @@
  * never talks to D1 or R2 directly. The images travel through the running Worker so they land
  * in the same R2 the dev server serves.
  *
- * The target defaults to the port the dev server recorded in this directory
- * (cli/dev-port.mjs); override it with `PORT` or a URL or port argument. Scale the demo list
+ * With no target given, it goes only to the dev server `kestrel dev` recorded in this
+ * directory, and only when that server reports the run ID recorded with it, so it never wipes
+ * another directory's database (cli/dev-api.mjs, cli/dev-server.mjs); with none recorded it
+ * refuses rather than guess a port. A URL or port argument names a server deliberately, and
+ * is used as given; `PORT` names nothing here (cli/dev-api.mjs says why). Scale the demo list
  * with `--size` (100 / 1k / 10k / 100k, an approximate target) and pin the seeded PRNG with
  * `--seed`. Without `--size`, the curated story-shaped list (~155 subscribers) loads.
  */
@@ -18,7 +21,7 @@ import { existsSync } from "node:fs";
 import { readdir, readFile } from "node:fs/promises";
 import { dirname, join } from "node:path";
 import { fileURLToPath } from "node:url";
-import { baseUrl, devToken, fail, parseArgs } from "./dev-api.mjs";
+import { devTarget, fail, parseArgs } from "./dev-api.mjs";
 
 // The demo ships beside the CLI, in this repository and in the package.
 const root = join(dirname(fileURLToPath(import.meta.url)), "..");
@@ -117,8 +120,7 @@ export async function seedDemo(base, token, { size, seed } = {}, tag = "seed") {
 /** `kestrel seed [--size n] [--seed s] [port|url]`. */
 export async function seedCommand(argv) {
   const { flags, positional } = parseArgs(argv);
-  const base = baseUrl(positional[0]);
-  const token = await devToken(base, "seed");
+  const { base, token } = await devTarget(positional[0], "seed");
   const summary = await seedDemo(base, token, { size: flags.size, seed: flags.seed });
   console.log("[seed] done:");
   if (flags.size) {

package/cli/sync-migrations.mjs

@@ -23,6 +23,10 @@ import { fileURLToPath } from "node:url";
 
 const SHIPPED = join(dirname(fileURLToPath(import.meta.url)), "..", "migrations");
 
+// A file's text with LF line endings, so a checkout that turned them into CRLF (git's autocrlf
+// on Windows) isn't taken for an edited migration.
+const sameText = (path) => readFileSync(path, "utf8").replace(/\r\n/g, "\n");
+
 /** `kestrel sync-migrations`, into the `migrations/` of `root` (the current directory). */
 export function syncMigrationsCommand(root = process.cwd()) {
   const target = join(root, "migrations");
@@ -41,7 +45,7 @@ export function syncMigrationsCommand(root = process.cwd()) {
     if (!existsSync(to)) {
       copyFileSync(from, to);
       copied.push(name);
-    } else if (!readFileSync(to).equals(readFileSync(from))) {
+    } else if (sameText(to) !== sameText(from)) {
       differ.push(name);
     }
   }