@kurtbruns/kestrel 1.17.0 → 1.18.0

package/.dev.vars.example

@@ -41,3 +41,13 @@ MIN_LEAD_SECONDS="60"
 # For one run, set it in the shell instead: SIMULATE_SENDS=ses npm run dev
 # Only honored in a dev-shaped env (fake transport, no Access, APP_ORIGIN on localhost).
 SIMULATE_SENDS="ses"
+
+# --- SES account simulation (local only) ---
+# Stands in for the SES account the app reads, so Settings and the dashboard show a state a
+# real account would: sandbox, pending (AWS reviewing a request for production access),
+# denied, production, or permission (the AWS key isn't allowed to read the account). Add
+# ":unrouted" (e.g. "sandbox:unrouted") for bounces that reach no configuration set, which
+# shows the bounces warning. It changes what the editor shows, not how a simulated send goes
+# out. Needs SIMULATE_SENDS=ses; "off" leaves the account unread.
+# For one run, set it in the shell instead: SIMULATE_ACCOUNT=sandbox npm run dev
+SIMULATE_ACCOUNT="off"

package/CHANGELOG.md

@@ -10,6 +10,34 @@ 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.18.0] - 2026-10-26
+
+**Upgrading from 1.17.0.** In your instance's repository, run `npm run sync-migrations`, which brings in one database migration, `0015_provider_account`: a new table where the app keeps what it reads of your SES account, which rewrites nothing. Apply it before you deploy, with `npx wrangler d1 migrations apply DB --remote --env production` (and `--local` for local development). If your instance already sends through Amazon SES, let the app's AWS key read the account before you deploy: in the IAM console, open **Policies**, then `kestrel-send-email`, choose **Edit**, add `"ses:GetAccount"` and `"ses:GetEmailIdentity"` to its `Action` list in the JSON editor, and save. Otherwise the app's first check finds the key not allowed, Settings says so with **Add the permission**, and the app asks again only hourly. An instance not yet connected to SES skips this, since Connect Amazon SES's policy now includes both. Then deploy with `npx wrangler deploy --env production`. `SES_MAX_SEND_RATE` is now a cap: a send keeps to the lower of it and your account's own rate, so the old guide's `"1"` would hold every send at one a second even after AWS grants production access. Once Settings → Email sender shows a **Sandbox** or **Production** badge beside Amazon SES, the app has read your account: remove `SES_MAX_SEND_RATE` from the `production` block's `vars` in `wrangler.jsonc`, or raise it to the most you want, and deploy again. Run `npm run check-context`: this release changes the operator's Claude context, and a copy you've edited is merged by hand. An existing instance keeps its Worker, database, and bucket names: don't rename them, and don't copy a new instance's names from the template into your `wrangler.jsonc`. If you're partway through the setup guide, continue from its renumbered pages: 1.17.0's Connect Amazon SES section 4 is now its own page, Request production access, after Connect Amazon SES.
+
+### Added
+
+- On Amazon SES, the app reads the account itself, about every ten minutes while nothing is sending (SPEC §9). Settings → Email sender shows whether SES is still in the sandbox, where AWS's review of a production-access request stands, and the send rate and where it comes from, and says when the app's AWS key isn't allowed to read the account; the dashboard's setup steps add Request production access, checked off once AWS grants it; and a warning says when no configuration set applies, so bounces and complaints would never reach the app. `GET /api/provider` carries all of it for Claude, and an AWS key that can't read the account reads as unknown, never as an error.
+- `kestrel init` takes `--name` to name a new instance, which otherwise takes its folder's name: lowercase letters, digits, and hyphens, at most 46 characters. It names the instance's Worker, D1 database, and R2 bucket after it instead of `kestrel`: `NAME-production` for the Worker and the database, `NAME-media-production` for the bucket, and `NAME-dev` for the development Worker a deploy without `--env production` would create. So a second instance in the same Cloudflare account no longer deploys over the first. Deploy the app now recommends naming the repository after the publication. An existing instance keeps its names, and nothing changes for it.
+- Local development can stand in for the SES account with `SIMULATE_ACCOUNT` (`sandbox`, `pending`, `denied`, `production`, or `permission`, optionally `:unrouted`, beside `SIMULATE_SENDS=ses`), so Settings and the dashboard can be seen in each state without an AWS account. `kestrel dev` takes it from the shell for one run.
+- Get started has a new step, Create an AWS account, before Connect Amazon SES. It covers the sign-up path, plan, and support choices, securing the root user, a budget alert, and what running several publications through one account shares. Deploy the app's Before you begin says to start it early.
+
+### Changed
+
+- Until a post is listed, the home page is the subscribe form itself, with its line saying each signup is confirmed by email. A first visitor, or AWS reviewing the site for SES production access, sees how joining works without a click.
+- Before any post is listed and while no email provider is connected, the home page reads "No posts yet. Subscribe to get the first one.", as two sentences without a dash.
+- Name your publication now suggests a tagline that says what the newsletter covers and how often it goes out.
+- A send keeps to your SES account's own maximum send rate once the app has read it, or to `SES_MAX_SEND_RATE` where that is lower, so a raise from AWS needs no deploy (SPEC §12). The setup guide no longer sets the rate to 1 in the sandbox and changes it after the grant, and its IAM policy adds `ses:GetAccount` and `ses:GetEmailIdentity`.
+- The setup guide asks AWS for SES production access on a page of its own, Request production access, after Connect Amazon SES, so AWS's reviewer finds a live site with SES connected and bounces handled. It ends by checking the grant, in Settings or from `GET /api/provider`, and Go live opens by pointing there. Verify it works now runs wholly in the sandbox, while AWS reviews the request.
+- Connect Amazon SES sets the custom MAIL FROM domain on the Create identity form, so all five DNS records go to Cloudflare in one trip, with a zone file to import. It verifies your two test addresses in its own section, and checks each piece in the section that sets it up.
+- The setup guide's pages from Connect Amazon SES on, and the sections of Connect Amazon SES and Verify it works, are renumbered. A bookmark to a section now lands at its page's top, and a GitHub link to a renamed page, such as `docs/get-started/04-ses.md` or `05-verify.md`, finds no page. The editor's Docs links keep working.
+- The operator's Claude context reads whether SES is in the sandbox from `GET /api/provider` before helping share the subscribe link, instead of asking the publisher, and names the two permissions to add when the app's AWS key can't read the account. For production access it points to Request production access, instead of a Go live section that doesn't exist. The connector's instructions read the same state. Merge it into an edited copy by hand.
+- The operator's Claude context names the Worker a deploy without `--env production` creates by the top-level `name` in `wrangler.jsonc`, not as `kestrel`, since a new instance's is its own name. Merge it into an edited copy by hand.
+- The operator's Claude context, following a setup guide page, runs the check that ends each section, and the page's **Check it** list where it has one, since Connect Amazon SES and Request production access have none. Merge it into an edited copy by hand.
+
+### Fixed
+
+- A locked editor (before Access is set up, or after a sign-in Kestrel refuses) no longer flashes the editor's sidebar before its explanation: the dashboard shows the publication's chrome only once it knows who is signing in.
+
 ## [1.17.0] - 2026-10-26
 
 ### Changed
@@ -661,7 +689,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.17.0...HEAD
+[Unreleased]: https://github.com/kurtbruns/kestrel/compare/v1.18.0...HEAD
+[1.18.0]: https://github.com/kurtbruns/kestrel/releases/tag/v1.18.0
 [1.17.0]: https://github.com/kurtbruns/kestrel/releases/tag/v1.17.0
 [1.16.0]: https://github.com/kurtbruns/kestrel/releases/tag/v1.16.0
 [1.15.1]: https://github.com/kurtbruns/kestrel/releases/tag/v1.15.1

package/bin/kestrel.mjs

@@ -26,7 +26,7 @@ const HELP = `kestrel ${PACKAGE.version}
 
 Usage: kestrel <command> [options]
 
-  init [dir]                    write a new instance repository here (or in dir)
+  init [dir] [--name <name>]    write a new instance repository here (or in dir)
   dev [wrangler dev args]       run locally, with the send sweep once a minute (PORT picks the port)
   sync-migrations               copy this release's migrations into migrations/
   check-context [--update]      compare the Claude files in .claude/ with this release's

package/cli/dev.mjs

@@ -22,8 +22,8 @@
  * D1 route would 500 until the migrations ran. The local database is probed and, when its
  * tables are missing, migrated before the server starts. Never for `--remote`.
  *
- * Per-run settings. `SIMULATE_SENDS`, `MIN_LEAD_SECONDS`, and `SUBREQUEST_BUDGET` set in the
- * shell are forwarded over `.dev.vars`, so `SIMULATE_SENDS=ses kestrel dev` picks a
+ * Per-run settings. `SIMULATE_SENDS`, `SIMULATE_ACCOUNT`, `MIN_LEAD_SECONDS`, and
+ * `SUBREQUEST_BUDGET` set in the shell are forwarded over `.dev.vars`, so `SIMULATE_SENDS=ses kestrel dev` picks a
  * simulation profile for one run without editing a file. A `.dev.vars` missing a setting that
  * `.dev.vars.example` gives a value is named, rather than left to differ quietly. What
  * `SIMULATE_SENDS` makes of this run (a simulated provider, or not connected) is said in one
@@ -49,7 +49,7 @@ import { captureWrangler, runWrangler, spawnWrangler } from "./wrangler.mjs";
 const PREFERRED_PORT = 8787;
 
 // The dev settings a shell may set for one run (see the header).
-const OVERRIDABLE = ["SIMULATE_SENDS", "MIN_LEAD_SECONDS", "SUBREQUEST_BUDGET"];
+const OVERRIDABLE = ["SIMULATE_SENDS", "SIMULATE_ACCOUNT", "MIN_LEAD_SECONDS", "SUBREQUEST_BUDGET"];
 
 // Whether a TCP port can be bound on loopback right now. A momentary check, so what it
 // reports can go stale before wrangler binds: the same check-then-bind race autoPort lives with.

package/cli/init.mjs

@@ -8,6 +8,11 @@
  * wrangler config and one-line Worker entry, `.dev.vars.example`, the Claude context with its
  * headers (cli/context.mjs), and this release's migrations.
  *
+ * The scaffold's wrangler config names the Worker, the D1 database, and the R2 bucket
+ * `kestrel…`; init renames each after the instance (the folder's name, or `--name`), so a
+ * second instance in the same Cloudflare account never deploys over the first or collides
+ * with its database and bucket. An instance already written keeps the names it has.
+ *
  * A few files ship under other names and are renamed here: npm leaves `.gitignore` and
  * `.npmrc` out of a published package, and the Claude files sit outside `.claude/` so they
  * don't load into sessions in Kestrel's own repository. Init never overwrites: if any file it
@@ -62,9 +67,92 @@ function packageName(dir) {
   return name || "newsletter";
 }
 
-/** `kestrel init [dir]`. */
+// The longest name init derives is `<name>-media-production`, and an R2 bucket's name, like a
+// Worker's on workers.dev, is at most 63 characters. Each resource takes lowercase letters,
+// digits, and hyphens, never a hyphen at either end: the rules R2 and workers.dev share, and
+// D1 accepts. Every name init makes ends in a suffix (`-dev`, `-production`), so no instance's
+// name can make another's: the development Worker's `NAME-dev` never equals a production
+// `OTHER-production`. `kestrel` alone is refused, being what instances made by earlier
+// releases are named.
+const NAME_MAX = 63 - "-media-production".length;
+const NAME_RULE = /^[a-z0-9](?:[a-z0-9-]*[a-z0-9])?$/;
+
+/** Why `name` can't name an instance's resources, or null when it can. */
+export function nameRefusal(name) {
+  if (name.length > NAME_MAX) {
+    return `"${name}" is ${name.length} characters; an instance's name is at most ${NAME_MAX}`;
+  }
+  if (!NAME_RULE.test(name)) {
+    return `"${name}" isn't a valid instance name: use lowercase letters, digits, and hyphens, starting and ending with a letter or digit`;
+  }
+  if (name === "kestrel") {
+    return `"kestrel" names the instances made by earlier releases, so a new one takes a name of its own`;
+  }
+  return null;
+}
+
+/**
+ * The instance name a folder's name makes: accents dropped (`Café` is `cafe`), each run of
+ * other characters a hyphen, or `newsletter` when nothing is left.
+ */
+export function nameFromFolder(dir) {
+  const name = basename(dir)
+    .normalize("NFKD")
+    .replace(/\p{M}/gu, "")
+    .toLowerCase()
+    .replace(/[^a-z0-9]+/g, "-")
+    .replace(/^-+/, "")
+    .slice(0, NAME_MAX)
+    .replace(/-+$/, "");
+  return name || "newsletter";
+}
+
+// The scaffold's resource names: `kestrel`, then a suffix such as `-media-production`.
+const RESOURCE_NAME = /("(?:name|database_name|bucket_name)":\s*")kestrel((?:-[a-z]+)*")/g;
+const RESOURCE_COUNT = 6;
+
+/** The scaffold's wrangler config with its Worker, database, and bucket named after `name`. */
+export function nameResources(config, name) {
+  let count = 0;
+  const named = config.replace(RESOURCE_NAME, (_, key, suffix) => {
+    count++;
+    return `${key}${name}${suffix}`;
+  });
+  // A scaffold whose names this no longer finds would write an instance named `kestrel`.
+  if (count !== RESOURCE_COUNT) {
+    throw new Error(`template/wrangler.jsonc names ${count} resources, not ${RESOURCE_COUNT}`);
+  }
+  return named;
+}
+
+/** The instance directory and the `--name` flag's value, if given, from init's arguments. */
+export function parseInitArgs(argv) {
+  let dir;
+  let name;
+  for (let i = 0; i < argv.length; i++) {
+    const arg = argv[i];
+    if (arg === "--name") {
+      name = argv[++i] ?? "";
+    } else if (arg.startsWith("--name=")) {
+      name = arg.slice("--name=".length);
+    } else if (!arg.startsWith("-") && dir === undefined) {
+      dir = arg;
+    }
+  }
+  return { dir: dir ?? ".", name };
+}
+
+/** `kestrel init [dir] [--name <name>]`. */
 export function initCommand(argv) {
-  const root = resolve(argv.find((a) => !a.startsWith("-")) ?? ".");
+  const args = parseInitArgs(argv);
+  const root = resolve(args.dir);
+  const name = args.name ?? nameFromFolder(root);
+  const refusal = nameRefusal(name);
+  if (refusal) {
+    const hint = args.name === undefined ? " Name it with --name, or rename the folder." : "";
+    console.error(`[init] refused: ${refusal}.${hint}`);
+    process.exit(1);
+  }
   const files = [
     ...scaffoldFiles(),
     [join(PACKAGE_ROOT, ".dev.vars.example"), ".dev.vars.example"],
@@ -93,12 +181,14 @@ export function initCommand(argv) {
   // nodejs_compat) and stops ending the typecheck with "Action required"; the scaffold's
   // tsconfig lists no `types`, so they never enter the program and the Worker's types win.
   const pkg = JSON.parse(readFileSync(join(root, "package.json"), "utf8"));
-  pkg.name = packageName(root);
+  pkg.name = args.name ?? packageName(root);
   pkg.dependencies[PACKAGE.name] = PACKAGE.version;
   pkg.devDependencies["@types/node"] = PACKAGE.devDependencies["@types/node"];
   pkg.devDependencies.typescript = PACKAGE.devDependencies.typescript;
   pkg.devDependencies.wrangler = PACKAGE.peerDependencies.wrangler;
   writeFileSync(join(root, "package.json"), `${JSON.stringify(pkg, null, 2)}\n`);
+  const config = join(root, "wrangler.jsonc");
+  writeFileSync(config, nameResources(readFileSync(config, "utf8"), name));
   for (const file of CONTEXT_FILES) {
     writeShipped(root, file);
   }
@@ -107,7 +197,11 @@ export function initCommand(argv) {
   // A path from here when the instance is below this directory, else the absolute one.
   const rel = relative(process.cwd(), root);
   const where = rel.startsWith("..") ? root : rel;
-  console.log(`[init] a Kestrel ${PACKAGE.version} instance${where ? ` in ${where}` : ""}. Next:`);
+  console.log(`[init] a Kestrel ${PACKAGE.version} instance${where ? ` in ${where}` : ""}.`);
+  console.log(
+    `[init] named ${name}${args.name === undefined ? " after its folder (--name picks another)" : ""}: ` +
+      `Worker and database ${name}-production, image bucket ${name}-media-production. Next:`,
+  );
   console.log(
     [
       ...(where ? [`  cd ${where}`] : []),