@kurtbruns/kestrel 1.13.0 → 1.15.0

package/{cli → packages/kestrel/lib}/dev-api.mjs

@@ -8,9 +8,13 @@
  * 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).
  *
+ * It lives in the client package, beside `kestrel api`, because `kestrel api --local` finds and
+ * signs in to the dev server the same way; the instance package's seed and reset import it
+ * from the copy of the client it ships, so the two never disagree about the record.
+ *
  * 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
+ * server there that reports the run ID recorded with it (packages/kestrel/lib/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.
@@ -68,12 +72,18 @@ export function ownsServer(target, reportedId) {
 /**
  * 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>`.
+ * argument, if any; `tag` names the command, as in `npm run <tag>`. `kind` is the token's
+ * principal: `service` for a script, as seed and reset are, and `human` for a person working
+ * through a client, as `kestrel api` is (SPEC §11, Who acted).
  */
-export async function devTarget(arg, tag) {
+export async function devTarget(arg, tag, kind = "service") {
   const target = chooseTarget({ arg, record: readDevServer() });
+  const naming =
+    tag === "api"
+      ? "`npx kestrel api --url http://localhost:<port> …`"
+      : `\`npm run ${tag} -- <port>\``;
   const deliberately = [
-    `To act on a server deliberately, name its port: \`npm run ${tag} -- <port>\`.`,
+    `To act on a server deliberately, name its port: ${naming}.`,
     ...(process.env.PORT
       ? [
           `(PORT=${process.env.PORT} is set, but PORT doesn't name a target here: a shell can carry it unawares.)`,
@@ -88,7 +98,7 @@ export async function devTarget(arg, tag) {
       ...deliberately,
     );
   }
-  const { token, runId } = await devToken(target.base, tag);
+  const { token, runId } = await devToken(target.base, tag, kind);
   if (!ownsServer(target, runId)) {
     fail(
       tag,
@@ -101,7 +111,7 @@ export async function devTarget(arg, tag) {
     );
   }
   if (target.explicit) {
-    console.log(`[${tag}] acting on ${target.base}, as named`);
+    console.error(`[${tag}] acting on ${target.base}, as named`);
   }
   return { base: target.base, token };
 }
@@ -116,13 +126,13 @@ export function fail(tag, ...lines) {
   process.exit(1);
 }
 
-/** 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. */
-async function devToken(base, tag) {
+/** Mint a local admin token for a principal of `kind`, 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. */
+async function devToken(base, tag, kind) {
   let res;
   try {
-    res = await fetch(`${base}/api/dev/token?kind=service`);
+    res = await fetch(`${base}/api/dev/token?kind=${kind}`);
   } catch (err) {
     fail(
       tag,

package/{cli → packages/kestrel/lib}/dev-server.mjs

@@ -1,5 +1,5 @@
 /*
- * The record of this directory's dev server, shared between `kestrel dev` (cli/dev.mjs) and
+ * The record of this directory's dev server, shared between `kestrel dev` (cli/dev.mjs in @kurtbruns/kestrel) 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
@@ -12,7 +12,7 @@
  * 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).
+ * the recorded port, and only when the server there reports this record's ID (packages/kestrel/lib/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.

package/packages/kestrel/lib/handoff.mjs

@@ -0,0 +1,118 @@
+/*
+ * How the client hands an instance command to the instance package, so `kestrel <command>`
+ * stays one entry point although the commands live in two packages.
+ *
+ * `init`, `dev`, `seed`, `reset`, `sync-migrations`, and `check-context` act on an instance's
+ * repository and belong to the release it runs, so they live in `@kurtbruns/kestrel`, which
+ * each instance installs and pins. The client finds that install from the directory it runs
+ * in, the way Node resolves an import from there, and runs its `kestrel` command with the same
+ * arguments. `init` alone runs where nothing is installed yet: it fetches the instance package
+ * at the client's own version through npx, so `npx kestrel@X.Y.Z init` writes an X.Y.Z
+ * instance. Plain Node, no dependency, as the whole client is.
+ */
+import { spawn } from "node:child_process";
+import { readFileSync } from "node:fs";
+import { createRequire } from "node:module";
+import { constants } from "node:os";
+import { dirname, join } from "node:path";
+
+/** The package that holds the instance commands. */
+export const INSTANCE_PACKAGE = "@kurtbruns/kestrel";
+
+/** The commands that act on an instance's repository, and so run from the instance package. */
+export const INSTANCE_COMMANDS = [
+  "init",
+  "dev",
+  "sync-migrations",
+  "check-context",
+  "seed",
+  "reset",
+];
+
+/**
+ * The instance package as installed for `dir` (or a directory above it): `{ root, bin }`, with
+ * `bin` the path of its `kestrel` script, or undefined when the install has none; or undefined
+ * when no install is found.
+ */
+export function findInstance(dir = process.cwd()) {
+  let manifest;
+  try {
+    manifest = createRequire(join(dir, "package.json")).resolve(`${INSTANCE_PACKAGE}/package.json`);
+  } catch {
+    return undefined;
+  }
+  const root = dirname(manifest);
+  const { bin } = JSON.parse(readFileSync(manifest, "utf8"));
+  const script = typeof bin === "string" ? bin : bin?.kestrel;
+  return { root, bin: script ? join(root, script) : undefined };
+}
+
+/** One argument for cmd.exe, which splits on spaces and reads its own metacharacters. */
+function quoteForCmd(arg) {
+  return /^[\w@=./:\\-]+$/.test(arg) ? arg : `"${arg.replace(/"/g, '""')}"`;
+}
+
+/**
+ * How to run instance `command`, as `{ cmd, args, shell }`, or `{ refuse }` with words for the
+ * person when there is no install to run it from. `version` is the client's, which `init`
+ * fetches when nothing is installed. `KESTREL_INSTANCE_PACKAGE` names another package spec to
+ * fetch, such as a packed tarball, which the package check uses before a release exists.
+ */
+export function handoff(
+  command,
+  argv,
+  { dir = process.cwd(), version, env = process.env, platform = process.platform } = {},
+) {
+  const found = findInstance(dir);
+  if (found?.bin) {
+    return { cmd: process.execPath, args: [found.bin, command, ...argv], shell: false };
+  }
+  if (found) {
+    return {
+      refuse: `the ${INSTANCE_PACKAGE} installed at ${found.root} has no kestrel command, so it can't run \`kestrel ${command}\`. Reinstall it with \`npm install\`.`,
+    };
+  }
+  if (command === "init") {
+    const spec = env.KESTREL_INSTANCE_PACKAGE || `${INSTANCE_PACKAGE}@${version}`;
+    const args = ["--yes", `--package=${spec}`, "--", "kestrel", command, ...argv];
+    // npx is a .cmd script on Windows, which Node spawns only through a shell, and a shell
+    // splits what it is given: so it gets one command line, each argument quoted for cmd.exe.
+    if (platform === "win32") {
+      return { cmd: ["npx.cmd", ...args].map(quoteForCmd).join(" "), args: [], shell: true };
+    }
+    return { cmd: "npx", args, shell: false };
+  }
+  return {
+    refuse: `\`kestrel ${command}\` runs in an instance's repository, with ${INSTANCE_PACKAGE} installed, and none is installed here. Run it in your instance's repository after \`npm install\`, or write a new instance with \`npx kestrel init\`.`,
+  };
+}
+
+// The signals passed on to the child when they are sent to this process alone.
+const FORWARDED = ["SIGTERM", "SIGHUP", "SIGQUIT"];
+
+/**
+ * Run instance `command` through the instance package, with the terminal attached, and exit
+ * as it does. A Ctrl-C reaches the child from the terminal itself, so this process only waits
+ * for it to finish (`kestrel dev` stops its server on the way out); another signal sent to
+ * this process alone is passed on. A child ended by a signal exits 128 plus its number, as a
+ * shell reports it.
+ */
+export function runInstanceCommand(command, argv, version) {
+  const plan = handoff(command, argv, { version });
+  if (plan.refuse) {
+    console.error(`kestrel: ${plan.refuse}`);
+    process.exit(1);
+  }
+  const child = spawn(plan.cmd, plan.args, { stdio: "inherit", shell: plan.shell });
+  process.on("SIGINT", () => {});
+  for (const signal of FORWARDED) {
+    process.on(signal, () => child.kill(signal));
+  }
+  child.on("error", (err) => {
+    console.error(`kestrel: could not run ${INSTANCE_PACKAGE}: ${err.message}`);
+    process.exit(1);
+  });
+  child.on("exit", (code, signal) => {
+    process.exit(code ?? (signal ? 128 + (constants.signals[signal] ?? 0) : 0));
+  });
+}

package/packages/kestrel/lib/login.mjs

@@ -0,0 +1,155 @@
+/*
+ * `kestrel login` and `kestrel logout`: sign this computer in to a deployed instance as the
+ * person at it, through Cloudflare Access's Managed OAuth, and forget that sign-in again.
+ *
+ * The person approves the sign-in in their browser, through the same Access policy the
+ * editor's sign-in passes, so Claude Code working through `kestrel api` afterwards is that
+ * person, not a token of its own (SPEC §11). The OAuth steps are packages/kestrel/lib/oauth.mjs, and where
+ * the result is kept is packages/kestrel/lib/credentials.mjs.
+ */
+import { spawn } from "node:child_process";
+import { randomBytes } from "node:crypto";
+import { signedInFetch } from "./api.mjs";
+import { credentialsFile, readSignIn, readSignIns, writeSignIn } from "./credentials.mjs";
+import {
+  authorizeUrl,
+  DEFAULT_CLIENT,
+  discover,
+  exchangeCode,
+  instanceOrigin,
+  isLoopback,
+  listenForCode,
+  PROTECTED_PATH,
+  pkcePair,
+  registerClient,
+  revokeTokens,
+  SignInError,
+  tokenFields,
+} from "./oauth.mjs";
+import { unauthorizedMove } from "./openapi.mjs";
+
+/** Open `url` in the person's browser, best effort: the URL is printed either way. */
+function openBrowser(url) {
+  const [command, args] =
+    process.platform === "darwin"
+      ? ["open", [url]]
+      : process.platform === "win32"
+        ? ["cmd", ["/c", "start", '""', url.replace(/&/g, "^&")]]
+        : ["xdg-open", [url]];
+  try {
+    const child = spawn(command, args, { stdio: "ignore", detached: true });
+    child.on("error", () => {});
+    child.unref();
+  } catch {
+    /* no browser to open: the printed URL still works */
+  }
+}
+
+/** Sign in to `origin`, store the result, and answer who it signed in as. */
+export async function signIn(origin, { browser }) {
+  const found = await discover(origin);
+  const stored = readSignIn(origin);
+  // A client registered for this computer is reused while its redirect can be served again,
+  // so a sign-in doesn't leave a new registration in Access each time.
+  const reuse =
+    stored?.client_id && stored.registration_endpoint === found.registration_endpoint
+      ? stored
+      : undefined;
+  const state = randomBytes(16).toString("base64url");
+  const listener = await listenForCode({
+    port: reuse ? Number(new URL(reuse.redirect_uri).port) : undefined,
+    state,
+  });
+  try {
+    const clientId =
+      reuse && reuse.redirect_uri === listener.redirectUri
+        ? reuse.client_id
+        : await registerClient(found.registration_endpoint, listener.redirectUri);
+    const entry = { ...found, client_id: clientId, redirect_uri: listener.redirectUri };
+    const { verifier, challenge } = pkcePair();
+    const url = authorizeUrl({
+      endpoint: found.authorization_endpoint,
+      clientId,
+      redirectUri: listener.redirectUri,
+      challenge,
+      state,
+      resource: found.resource,
+    });
+    console.log(`Approve the sign-in to ${origin} in your browser.`);
+    console.log(`If it didn't open, go to:\n\n  ${url}\n`);
+    if (browser) {
+      openBrowser(url);
+    }
+    const code = await listener.code;
+    const fields = tokenFields(await exchangeCode(entry, { code, verifier }));
+    await writeSignIn(origin, { ...entry, ...fields });
+  } finally {
+    listener.close();
+  }
+  const res = await signedInFetch(origin, PROTECTED_PATH, { client: DEFAULT_CLIENT });
+  const body = await res.json().catch(() => null);
+  if (!res.ok) {
+    const move = unauthorizedMove(body);
+    throw new SignInError(
+      move
+        ? `Signed in to Access, but ${origin}${PROTECTED_PATH} answered ${res.status} (${body.reason}). ${move}.`
+        : `Signed in to Access, but ${origin}${PROTECTED_PATH} answered ${res.status}${body?.message ? `: ${body.message}` : ""}.`,
+    );
+  }
+  return body?.principal;
+}
+
+/** `kestrel login <url> [--no-browser]`. */
+export async function loginCommand(argv) {
+  const browser = !argv.includes("--no-browser");
+  const urls = argv.filter((a) => a !== "--no-browser");
+  try {
+    if (urls.length !== 1) {
+      throw new SignInError("Usage: kestrel login <url> [--no-browser]");
+    }
+    const origin = instanceOrigin(urls[0]);
+    if (isLoopback(origin)) {
+      throw new SignInError(
+        "A local dev server needs no sign-in: `npx kestrel api --local …` calls it as you.",
+      );
+    }
+    const principal = await signIn(origin, { browser });
+    const who = principal?.email ?? principal?.kind ?? "someone";
+    console.log(`Signed in to ${origin} as ${who}.`);
+    console.log(
+      `Stored in ${credentialsFile()}. \`npx kestrel api GET /api/posts\` calls it as you.`,
+    );
+  } catch (err) {
+    console.error(`kestrel login: ${err instanceof Error ? err.message : String(err)}`);
+    process.exit(1);
+  }
+}
+
+/** `kestrel logout [url]`: revoke and forget one sign-in, or the only one stored. */
+export async function logoutCommand(argv) {
+  try {
+    const origins = Object.keys(readSignIns());
+    const origin = argv[0] ? instanceOrigin(argv[0]) : origins.length === 1 ? origins[0] : null;
+    if (!origin) {
+      throw new SignInError(
+        origins.length
+          ? `You're signed in to ${origins.join(", ")}. Name the one to sign out of.`
+          : "You aren't signed in to any instance.",
+      );
+    }
+    const entry = readSignIn(origin);
+    if (!entry) {
+      throw new SignInError(`You aren't signed in to ${origin}.`);
+    }
+    const revoked = await revokeTokens(entry);
+    await writeSignIn(origin, undefined);
+    console.log(
+      revoked
+        ? `Signed out of ${origin}, and Access revoked the sign-in.`
+        : `Signed out of ${origin} on this computer. Access didn't confirm revoking it; it ends with the Access application's grant session.`,
+    );
+  } catch (err) {
+    console.error(`kestrel logout: ${err instanceof Error ? err.message : String(err)}`);
+    process.exit(1);
+  }
+}