@kurtbruns/kestrel 1.19.0 → 1.21.0

package/migrations/0021_notifications_outage_receipts.sql

@@ -0,0 +1,46 @@
+-- 0021_notifications_outage_receipts: one outage, at most two emails, and a notice of silence (SPEC §8).
+--
+-- `not_sending` is now one notice for each stretch email is refusing rather than one a UTC day:
+-- its episode is when the refusal began. A second kind, `not_sending_held`, keyed the same way,
+-- is the one further email when a post is first held after that notice named none, so a unique
+-- index on each kind's episode is what holds an outage to two. `no_receipts` is a send's notice
+-- that the provider's receipts may not be reaching the app. The publisher is no longer told of
+-- an import, so a pending `import` notice is closed as cleared rather than sent; the kind stays
+-- admitted, with the column it reads, since the rows already recorded keep their history and the
+-- settings surface may still show the latest. A STRICT table's CHECK can't be altered, so the
+-- table is rebuilt, every row and column carried over.
+--
+-- What can't be recovered: nothing but the pending import notices, which were only ever going
+-- to tell of an import already on the record.
+
+CREATE TABLE notifications_next (
+  send_id    TEXT REFERENCES sends (id),       -- null for a test, an import notice, and an account notice
+  import_id  TEXT REFERENCES imports (id),     -- set only for an import notice
+  kind       TEXT NOT NULL
+               CHECK (kind IN ('finished', 'refused', 'stuck', 'wedged', 'missed', 'no_receipts', 'test', 'import', 'sandbox', 'not_sending', 'not_sending_held')),
+  episode    INTEGER NOT NULL DEFAULT 0,
+  status     TEXT NOT NULL DEFAULT 'pending'
+               CHECK (status IN ('pending', 'sent', 'failed', 'unaddressed', 'cleared')),
+  attempts   INTEGER NOT NULL DEFAULT 0,
+  error      TEXT,
+  created_at INTEGER NOT NULL,
+  updated_at INTEGER NOT NULL,
+  sent_to    TEXT NOT NULL DEFAULT '[]' CHECK (json_valid(sent_to)),
+  UNIQUE (send_id, kind, episode),
+  UNIQUE (import_id),
+  CHECK ((send_id IS NULL) = (kind IN ('test', 'import', 'sandbox', 'not_sending', 'not_sending_held'))),
+  CHECK ((import_id IS NULL) = (kind <> 'import'))
+) STRICT;
+
+INSERT INTO notifications_next (send_id, import_id, kind, episode, status, attempts, error, created_at, updated_at, sent_to)
+  SELECT send_id, import_id, kind, episode,
+         CASE WHEN kind = 'import' AND status = 'pending' THEN 'cleared' ELSE status END,
+         attempts, error, created_at, updated_at, sent_to
+    FROM notifications;
+
+DROP TABLE notifications;
+ALTER TABLE notifications_next RENAME TO notifications;
+CREATE INDEX idx_notifications_status ON notifications (status, created_at);
+CREATE UNIQUE INDEX idx_notifications_sandbox_day ON notifications (episode) WHERE kind = 'sandbox';
+CREATE UNIQUE INDEX idx_notifications_not_sending ON notifications (episode) WHERE kind = 'not_sending';
+CREATE UNIQUE INDEX idx_notifications_not_sending_held ON notifications (episode) WHERE kind = 'not_sending_held';

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kurtbruns/kestrel",
-  "version": "1.19.0",
+  "version": "1.21.0",
   "type": "module",
   "description": "An open-source, self-hosted newsletter app where you own the list and the archive. Work in the editor, or just ask Claude. Runs on Cloudflare Workers.",
   "license": "MIT",
@@ -68,21 +68,21 @@
   "dependencies": {
     "@css-inline/css-inline-wasm": "^0.21.2",
     "aws4fetch": "^1.0.20",
-    "jose": "^6.2.12",
-    "marked": "^18.0.12"
+    "jose": "^6.2.14",
+    "marked": "^18.1.3"
   },
   "peerDependencies": {
-    "wrangler": "^4.152.0"
+    "wrangler": "^4.156.0"
   },
   "devDependencies": {
-    "@biomejs/biome": "2.5.6",
-    "@cloudflare/vitest-plugin": "^1.4.7",
-    "@types/node": "^22.20.1",
-    "esbuild": "0.28.1",
-    "happy-dom": "^20.14.5",
+    "@biomejs/biome": "2.6.4",
+    "@cloudflare/vitest-plugin": "^1.4.11",
+    "@types/node": "^22.20.5",
+    "esbuild": "0.28.2",
+    "happy-dom": "^21.0.4",
     "typescript": "~5.9.3",
     "vitest": "^4.1.12",
-    "wrangler": "^4.152.0"
+    "wrangler": "^4.156.0"
   },
   "allowScripts": {
     "esbuild": true,

package/packages/kestrel/lib/api.mjs

@@ -5,11 +5,12 @@
  * Deployed, it sends the access token `kestrel login` stored, refreshing it from the
  * refresh token when it is about to expire or Access has turned it away, and storing what
  * comes back. Locally there is no Access: the target is this directory's dev server, and
- * the credential is the dev server's human token, so a local run is a person via Claude
- * Code just as a deployed one is. Every request carries `Kestrel-Client: claude-code`
- * unless `--client` names another program, so a person's own script can name itself. It
- * never names the editor: the server trusts the name it is sent (SPEC, Trusted, not guarded),
- * and the editor's name lifts a step only a person in the editor may take (SPEC §7).
+ * the credential is the dev server's human token, so a local run is a person through a
+ * client just as a deployed one is. Every request names its client in `Kestrel-Client`:
+ * `defaultClient` says which, unless `--client` names another program, so a person's own script
+ * can name itself. It never names the editor: the server trusts the name it is sent (SPEC,
+ * Trusted, not guarded), and the editor's name lifts a step only a person in the editor may take
+ * (SPEC §7).
  *
  * It prints the answer's body as it came, so a script or Claude reads a refusal whole; a
  * non-2xx answer also prints its status, and a refusal's code, message, field, and next move,
@@ -24,10 +25,13 @@ import { readFileSync } from "node:fs";
 import { basename } from "node:path";
 import { readSignIn, readSignIns, withCredentialsLock, writeSignInHeld } from "./credentials.mjs";
 import { devTarget } from "./dev-api.mjs";
+import { fileMediaType } from "./media-types.mjs";
 import {
-  DEFAULT_CLIENT,
+  CLAUDE_CODE_CLIENT,
+  defaultClient,
   instanceOrigin,
   isLoopback,
+  KESTREL_CLI_CLIENT,
   needsRefresh,
   refreshTokens,
   SignInError,
@@ -54,14 +58,16 @@ const USAGE = `Usage: kestrel api <method> <path> [options]
   --form <name=value>           a multipart field, repeatable; name=@file attaches a file
   --url <url>                   the instance (default: KESTREL_URL, else the only one you're signed in to)
   --local                       this directory's dev server, started by kestrel dev
-  --client <name>               your own script's Kestrel-Client name (default ${DEFAULT_CLIENT});
-                                never editor, which only the editor names itself
+  --client <name>               your own script's Kestrel-Client name (default ${CLAUDE_CODE_CLIENT}
+                                when Claude Code runs this, otherwise ${KESTREL_CLI_CLIENT}); never
+                                editor, which only the editor names itself
 
 The routes, fields, and refusals come from the instance's own /api/openapi.json, so they
 match the release it runs. A field the route doesn't take is refused before the request.`;
 
-// The name only the editor sends; `kestrel api` refuses to claim it (SPEC §7, §11).
-const EDITOR_CLIENT = "editor";
+// The name only the editor sends; `kestrel api` refuses to claim it (SPEC §7, §11). Mirrored
+// from shared/who_acted.ts, since the CLI is plain Node; a spec holds the two equal.
+export const EDITOR_CLIENT = "editor";
 
 // The server's rule for a client name (shared/who_acted.ts), mirrored since the CLI is plain
 // Node; a spec holds the two equal. Checking it here, after the trim fetch applies to a header
@@ -227,7 +233,8 @@ async function requestBody({ data, type, forms }) {
       const value = field.slice(at + 1);
       if (value.startsWith("@")) {
         const file = value.slice(1);
-        form.append(name, new Blob([readFileSync(file)]), basename(file));
+        const type = fileMediaType(file);
+        form.append(name, new Blob([readFileSync(file)], { type }), basename(file));
       } else {
         form.append(name, value);
       }
@@ -416,7 +423,7 @@ export async function apiCommand(argv) {
   let call;
   try {
     const args = parseApiArgs(argv);
-    const client = args.client ?? DEFAULT_CLIENT;
+    const client = args.client ?? defaultClient();
     call = await openTarget(args, client);
     if (args.mode === "list") {
       console.log(listRoutes(await readOpenApi(call), args.resource));

package/packages/kestrel/lib/login.mjs

@@ -13,7 +13,7 @@ import { signedInFetch } from "./api.mjs";
 import { credentialsFile, readSignIn, readSignIns, writeSignIn } from "./credentials.mjs";
 import {
   authorizeUrl,
-  DEFAULT_CLIENT,
+  defaultClient,
   discover,
   exchangeCode,
   instanceOrigin,
@@ -86,7 +86,7 @@ export async function signIn(origin, { browser }) {
   } finally {
     listener.close();
   }
-  const res = await signedInFetch(origin, PROTECTED_PATH, { client: DEFAULT_CLIENT });
+  const res = await signedInFetch(origin, PROTECTED_PATH, { client: defaultClient() });
   const body = await res.json().catch(() => null);
   if (!res.ok) {
     const move = unauthorizedMove(body);

package/packages/kestrel/lib/media-types.mjs

@@ -0,0 +1,34 @@
+/*
+ * A file's media type, read from its extension. An instance reads an upload's format from its
+ * bytes and holds the label to them, but this client also calls instances on older releases,
+ * which read only what the multipart part declares and refuse one with no type, so it states one:
+ * `kestrel api --form` does, and so does `kestrel seed`, which imports this rather than keep
+ * its own copy (the client may not import from cli/, but cli/ imports from the client).
+ */
+import { basename } from "node:path";
+
+/**
+ * The extensions of the raster formats an instance takes as an image. The Worker's list is
+ * src/lib/image_types.ts, mirrored since the client is plain Node; a spec holds the two equal.
+ */
+export const IMAGE_TYPE_BY_EXTENSION = {
+  ".png": "image/png",
+  ".jpg": "image/jpeg",
+  ".jpeg": "image/jpeg",
+  ".webp": "image/webp",
+  ".gif": "image/gif",
+};
+
+/** What a file goes as when its extension says nothing: a statement of no kind, not a guess. */
+const UNKNOWN_MEDIA_TYPE = "application/octet-stream";
+
+/**
+ * The media type a file's name says it is, in any case (a camera's `IMG_0042.JPG`), read just as
+ * the server reads a name's claim (shared/images.ts), so the two agree on a file called `.png`.
+ */
+export function fileMediaType(path) {
+  const name = basename(path);
+  return (
+    IMAGE_TYPE_BY_EXTENSION[name.slice(name.lastIndexOf(".")).toLowerCase()] ?? UNKNOWN_MEDIA_TYPE
+  );
+}

package/packages/kestrel/lib/oauth.mjs

@@ -19,8 +19,25 @@ import { createServer } from "node:http";
 /** The path discovery and the sign-in's check ask: protected, and it answers who signed in. */
 export const PROTECTED_PATH = "/api/whoami";
 
-/** The name `kestrel api` gives its requests, unless told another (SPEC §11, Who acted). */
-export const DEFAULT_CLIENT = "claude-code";
+// The names `kestrel api` gives itself (SPEC §11, Who acted). Mirrored from shared/who_acted.ts,
+// since the client is plain Node; a spec holds them equal.
+export const CLAUDE_CODE_CLIENT = "claude-code";
+export const KESTREL_CLI_CLIENT = "kestrel-cli";
+
+/**
+ * The name a request carries unless told another: Claude Code's when Claude Code ran this
+ * process, and the command's own otherwise, so what a person runs never reads as Claude's.
+ * CLAUDE_CODE_CHILD_SESSION is set only by Claude Code, on what its tools launch. CLAUDECODE
+ * won't do: IDE extensions also set it in their integrated terminals, where a person types.
+ *
+ * That makes the name truthful in the normal case, not proven, as with every client name. Claude
+ * Code older than v2.1.172 doesn't set the variable, so its calls read as the command's own; and
+ * a `screen` session or a background launcher Claude Code started passes it on, so what a person
+ * later runs inside one reads as Claude Code's.
+ */
+export function defaultClient() {
+  return process.env.CLAUDE_CODE_CHILD_SESSION === "1" ? CLAUDE_CODE_CLIENT : KESTREL_CLI_CLIENT;
+}
 
 // How long before its expiry an access token is refreshed rather than sent.
 const REFRESH_MARGIN_MS = 60_000;

package/packages/kestrel/lib/openapi.mjs

@@ -278,7 +278,7 @@ export function describeRoute(doc, method, path) {
     }
     const raw = types.filter((t) => t !== "application/json" && t !== "multipart/form-data");
     if (raw.length) {
-      how.push(`the file itself, with --data @file --type ${raw[0]}`);
+      how.push(`the file itself, with --data @file --type <its own type> (${raw.join(", ")})`);
     }
     out.push(`  Send it as ${how.join("; or ")}.`);
     const example = op.requestBody.content["application/json"]?.example;

package/template/README.md

@@ -23,7 +23,7 @@ Open the editor at http://localhost:8787/dashboard/. Email goes to a stand-in th
 | `npm run sync-migrations` | Copies the installed release's migrations into `migrations/` |
 | `npm run check-context` | Compares the Claude files in `.claude/` with the installed release's |
 | `npx kestrel login <url>` | Signs Claude Code in to the deployed instance as you, in your browser |
-| `npx kestrel api <method> <path>` | Calls the API as you, via Claude Code (`--local` for the local app); `--list` lists the routes and `help <method> <path>` describes one |
+| `npx kestrel api <method> <path>` | Calls the API as you (`--local` for the local app); `--list` lists the routes and `help <method> <path>` describes one |
 | `npx wrangler deploy --env production` | Deploys the instance |
 | `npx wrangler d1 migrations apply DB --remote --env production` | Applies new migrations to the production database |
 

package/template/claude/CLAUDE.md

@@ -29,7 +29,7 @@ Deploying, migrating the production database, and anything that sends mail or ch
 - **Locally,** with `npm run dev` running, add `--local`: it calls this folder's dev server as its stand-in person, via Claude Code, with no sign-in. `GET /api/dev/outbox` shows the email the stand-in caught.
 - **`npx kestrel api --list` lists the instance's routes** (`--list sends` one resource's), and **`npx kestrel api help <method> <path>` describes one**: its parameters, body fields, answer, and refusals with their next moves. Both read the instance's own OpenAPI document, so they match the release it runs.
 - **Read `GET /api/reference.md` first:** how to authenticate, what a status and an error body tell you and the refusals any route can give, paging, acting safely, and every route on one line. **Before calling a route, read its resource's reference,** `GET /api/reference/<resource>.md` (the index names it, such as `sends.md`): the object the routes return, and each route's parameters, body, answer, refusals (each with what to do next), and an example. Read a resource's reference once per conversation, not before every call.
-- **Posts with images:** upload each image from a file on disk (an image pasted into the chat isn't one; ask the person to save it into this folder), then reference it in the Markdown by its `filename`, with alt text, `![a short description](cover.jpg)`, never by the upload's `url`. The preview warns on a `url` reference, and on a name the post doesn't have.
+- **Posts with images:** upload each image from its original file, asking the person to save it into this folder (the Claude desktop app saves a pasted image to a temporary folder, converted and under a generated name, so it can be uploaded but isn't the file they had), then reference it in the Markdown by the `filename` the upload answers, with alt text, `![a short description](cover.jpg)`, never by the upload's `url`. That name may differ from the one you sent, since spaces and characters that would break a reference become hyphens, and a name the post already has gets a number. An upload never replaces an image: to swap one, upload the new image, reference its `filename`, and delete the old one. The preview warns on a `url` reference, on a name the post doesn't have, on a reference that didn't become an image, and on an uploaded image the post doesn't use.
 - **Never overwrite someone else's edit.** A save names the revision it was based on (the posts reference says how). On `stale_revision`, someone else changed the post (the refusal's `author` says who): read it again and re-apply your change to the newer revision, or ask.
 - **Offer only what a post's or a send's `actions` list,** as the reference's Acting safely says, so a post with no `schedule` or `send_now` (no email provider connected) isn't offered for sending. Read the answer to an act, or its refusal, before telling the publisher what happened or deciding again: it carries the resource as it now stands.
 - **Resolve a wedged send only on the publisher's choice.** Relay the `wedged` condition's message and ask which `resolution` they want, in the words the editor's Resolve dialog shows them: `unsent` is **Assume not sent**, which puts those readers in front of the next post, and `accepted` is **Assume sent**, which records them as sent. Never choose it yourself.

package/template/claude/skills/upgrade/SKILL.md

@@ -11,6 +11,7 @@ An upgrade moves the instance to a newer release of `@kurtbruns/kestrel`. The gu
 ## What's yours to judge
 
 - **Which release, and what it asks.** The installed version is in `package.json`. Read every changelog section between it and the target (the release notes at `https://github.com/kurtbruns/kestrel/releases`, or the new `CHANGELOG.md` once installed). Name each **Breaking** entry and each step in an *Upgrading* paragraph, and say what it means for this instance.
+- **Anything not yet committed.** If the page's `git status` lists anything, show the person and ask whether to commit it first, as its own commit. If they'd rather not, the upgrade waits until the repository is clean. Never let it go into the upgrade's commit: the page's **Go back** reverts that commit, and would undo it too.
 - **The context check.** `npm run check-context` compares this repository's Claude files with the release's. Show the person what it reports. When Kestrel changed a file the person has edited, show what changed, merge it with their edits, and run the command it suggests to record the merge. A change marked as bearing on safety comes first.
 - **The local try.** Ask the person to try what they care about on `npm run dev` before anything reaches production.
 - **The checks.** Report each one's result. A failure stops the upgrade until it's fixed or the person decides.