@warlock.js/core 5.36.0 → 5.37.0

package/esm/release/stage.mjs

@@ -0,0 +1,122 @@
+import { appendLog, readManifest, releaseDir, writeManifest } from "./store.mjs";
+import { randomBytes } from "node:crypto";
+import path from "node:path";
+import { access, cp, mkdir, readdir, rename, rm, stat, symlink, writeFile } from "node:fs/promises";
+
+//#region ../../packages/core/src/release/stage.ts
+async function exists(file) {
+	try {
+		await access(file);
+		return true;
+	} catch {
+		return false;
+	}
+}
+async function countFiles(directory) {
+	let total = 0;
+	for (const entry of await readdir(directory, { withFileTypes: true })) {
+		const location = path.join(directory, entry.name);
+		if (entry.isDirectory()) total += await countFiles(location);
+		else if (entry.isFile()) total += 1;
+	}
+	return total;
+}
+/**
+* Copy the built output, and what is needed to run it, into the candidate's
+* `staged` directory.
+*
+* Staged holds `dist` (or the configured output directory), `package.json`,
+* the lockfile, the configured `include` entries and a `release.json` with
+* the release identity. It is assembled under a temporary name and renamed
+* into place, so a half-copied `staged` never exists. Staging requires a
+* passing gate.
+*
+* @example
+* await stageRelease(context, "1.4.0-a1b2c3d");
+*/
+async function stageRelease(context, id) {
+	const manifest = await readManifest(context, id);
+	if (manifest.status === "active" || manifest.status === "superseded") throw new Error(`Release "${id}" is ${manifest.status}; it cannot be staged again.`);
+	if (!manifest.gate?.passed) throw new Error(`Release "${id}" has not passed the gate. Run \`warlock release gate\` first.`);
+	const directory = releaseDir(context, id);
+	const source = path.join(directory, "source");
+	const distribution = path.join(source, context.config.distDir);
+	if (!await exists(distribution)) throw new Error(`The build output "${context.config.distDir}" is missing in the candidate. Add a build check to the gate.`);
+	const temporary = path.join(directory, `.staged-${randomBytes(6).toString("hex")}`);
+	const staged = path.join(directory, "staged");
+	await mkdir(temporary, { recursive: true });
+	try {
+		await cp(distribution, path.join(temporary, context.config.distDir), { recursive: true });
+		const entries = [
+			"package.json",
+			manifest.lockfile?.file,
+			...context.config.include
+		];
+		for (const entry of entries) {
+			if (!entry) continue;
+			const from = path.resolve(source, entry);
+			if (from !== source && !from.startsWith(`${source}${path.sep}`)) throw new Error(`release.include entry "${entry}" points outside the project.`);
+			if (!await exists(from)) {
+				if (entry === "package.json") throw new Error("The candidate has no package.json.");
+				if (entry === manifest.lockfile?.file) continue;
+				throw new Error(`release.include entry "${entry}" does not exist in the candidate.`);
+			}
+			const to = path.join(temporary, path.relative(source, from));
+			await mkdir(path.dirname(to), { recursive: true });
+			await cp(from, to, { recursive: true });
+		}
+		if (context.config.linkNodeModules && await exists(path.join(source, "node_modules"))) await symlink(path.join(context.root, "node_modules"), path.join(temporary, "node_modules"), "dir");
+		await writeFile(path.join(temporary, "release.json"), `${JSON.stringify({
+			id,
+			version: manifest.version,
+			commit: manifest.commit
+		}, null, 2)}\n`, "utf8");
+		const files = await countFiles(temporary);
+		await rm(staged, {
+			recursive: true,
+			force: true
+		});
+		await rename(temporary, staged);
+		const updated = {
+			...manifest,
+			status: "staged",
+			staged: {
+				at: context.now().toISOString(),
+				files
+			}
+		};
+		await writeManifest(context, updated);
+		await appendLog(context, {
+			event: "stage",
+			release: id,
+			ok: true,
+			detail: `${files} files`
+		});
+		return updated;
+	} catch (error) {
+		await rm(temporary, {
+			recursive: true,
+			force: true
+		});
+		await appendLog(context, {
+			event: "stage",
+			release: id,
+			ok: false,
+			detail: error.message
+		});
+		throw error;
+	}
+}
+/** True when the staged directory holds the build output. */
+async function hasStagedArtefacts(context, id) {
+	const staged = path.join(releaseDir(context, id), "staged");
+	try {
+		return (await stat(path.join(staged, context.config.distDir))).isDirectory();
+	} catch {
+		return false;
+	}
+}
+
+//#endregion
+export { hasStagedArtefacts, stageRelease };
+//# sourceMappingURL=stage.mjs.map

package/esm/release/stage.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"stage.mjs","names":[],"sources":["../../../../../../../../packages/core/src/release/stage.ts"],"sourcesContent":["import { randomBytes } from \"node:crypto\";\nimport { access, cp, mkdir, readdir, rename, rm, stat, symlink, writeFile } from \"node:fs/promises\";\nimport path from \"node:path\";\nimport { appendLog, readManifest, releaseDir, writeManifest, type ReleaseContext } from \"./store\";\nimport type { ReleaseManifest } from \"./types\";\n\nasync function exists(file: string): Promise<boolean> {\n  try {\n    await access(file);\n    return true;\n  } catch {\n    return false;\n  }\n}\n\nasync function countFiles(directory: string): Promise<number> {\n  let total = 0;\n\n  for (const entry of await readdir(directory, { withFileTypes: true })) {\n    const location = path.join(directory, entry.name);\n\n    if (entry.isDirectory()) total += await countFiles(location);\n    else if (entry.isFile()) total += 1;\n  }\n\n  return total;\n}\n\n/**\n * Copy the built output, and what is needed to run it, into the candidate's\n * `staged` directory.\n *\n * Staged holds `dist` (or the configured output directory), `package.json`,\n * the lockfile, the configured `include` entries and a `release.json` with\n * the release identity. It is assembled under a temporary name and renamed\n * into place, so a half-copied `staged` never exists. Staging requires a\n * passing gate.\n *\n * @example\n * await stageRelease(context, \"1.4.0-a1b2c3d\");\n */\nexport async function stageRelease(context: ReleaseContext, id: string): Promise<ReleaseManifest> {\n  const manifest = await readManifest(context, id);\n\n  if (manifest.status === \"active\" || manifest.status === \"superseded\") {\n    throw new Error(`Release \"${id}\" is ${manifest.status}; it cannot be staged again.`);\n  }\n\n  if (!manifest.gate?.passed) {\n    throw new Error(`Release \"${id}\" has not passed the gate. Run \\`warlock release gate\\` first.`);\n  }\n\n  const directory = releaseDir(context, id);\n  const source = path.join(directory, \"source\");\n  const distribution = path.join(source, context.config.distDir);\n\n  if (!(await exists(distribution))) {\n    throw new Error(\n      `The build output \"${context.config.distDir}\" is missing in the candidate. Add a build check to the gate.`,\n    );\n  }\n\n  const temporary = path.join(directory, `.staged-${randomBytes(6).toString(\"hex\")}`);\n  const staged = path.join(directory, \"staged\");\n\n  await mkdir(temporary, { recursive: true });\n\n  try {\n    await cp(distribution, path.join(temporary, context.config.distDir), { recursive: true });\n\n    const entries = [\"package.json\", manifest.lockfile?.file, ...context.config.include];\n\n    for (const entry of entries) {\n      if (!entry) continue;\n\n      const from = path.resolve(source, entry);\n\n      // An include entry may not reach outside the candidate's source.\n      if (from !== source && !from.startsWith(`${source}${path.sep}`)) {\n        throw new Error(`release.include entry \"${entry}\" points outside the project.`);\n      }\n\n      if (!(await exists(from))) {\n        if (entry === \"package.json\") throw new Error(\"The candidate has no package.json.\");\n        if (entry === manifest.lockfile?.file) continue;\n        throw new Error(`release.include entry \"${entry}\" does not exist in the candidate.`);\n      }\n\n      const to = path.join(temporary, path.relative(source, from));\n\n      await mkdir(path.dirname(to), { recursive: true });\n      await cp(from, to, { recursive: true });\n    }\n\n    if (context.config.linkNodeModules && (await exists(path.join(source, \"node_modules\")))) {\n      await symlink(\n        path.join(context.root, \"node_modules\"),\n        path.join(temporary, \"node_modules\"),\n        \"dir\",\n      );\n    }\n\n    await writeFile(\n      path.join(temporary, \"release.json\"),\n      `${JSON.stringify({ id, version: manifest.version, commit: manifest.commit }, null, 2)}\\n`,\n      \"utf8\",\n    );\n\n    const files = await countFiles(temporary);\n\n    // Re-staging replaces this candidate's own staged copy only.\n    await rm(staged, { recursive: true, force: true });\n    await rename(temporary, staged);\n\n    const updated: ReleaseManifest = {\n      ...manifest,\n      status: \"staged\",\n      staged: { at: context.now().toISOString(), files },\n    };\n\n    await writeManifest(context, updated);\n    await appendLog(context, { event: \"stage\", release: id, ok: true, detail: `${files} files` });\n\n    return updated;\n  } catch (error) {\n    await rm(temporary, { recursive: true, force: true });\n    await appendLog(context, {\n      event: \"stage\",\n      release: id,\n      ok: false,\n      detail: (error as Error).message,\n    });\n    throw error;\n  }\n}\n\n/** True when the staged directory holds the build output. */\nexport async function hasStagedArtefacts(context: ReleaseContext, id: string): Promise<boolean> {\n  const staged = path.join(releaseDir(context, id), \"staged\");\n\n  try {\n    return (await stat(path.join(staged, context.config.distDir))).isDirectory();\n  } catch {\n    return false;\n  }\n}\n"],"mappings":"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"}

package/esm/release/store.mjs

@@ -0,0 +1,131 @@
+import { randomBytes } from "node:crypto";
+import path from "node:path";
+import { appendFile, mkdir, readFile, readdir, readlink, rename, rm, symlink, writeFile } from "node:fs/promises";
+
+//#region ../../packages/core/src/release/store.ts
+const RELEASE_ID = /^[0-9A-Za-z][0-9A-Za-z._+-]*$/;
+/** Reject ids that could escape the releases directory. */
+function assertReleaseId(id) {
+	if (!RELEASE_ID.test(id) || id.includes("..")) throw new Error(`"${id}" is not a valid release id.`);
+	return id;
+}
+function baseDir(context) {
+	return path.resolve(context.root, context.config.directory);
+}
+function releasesDir(context) {
+	return path.join(baseDir(context), "releases");
+}
+function releaseDir(context, id) {
+	return path.join(releasesDir(context), assertReleaseId(id));
+}
+function pointerPath(context, name) {
+	return path.join(baseDir(context), name);
+}
+function logPath(context) {
+	return path.join(baseDir(context), "release.log");
+}
+/** Write a file so readers see either the old content or the new, never half. */
+async function writeFileAtomic(file, content) {
+	const temporary = `${file}.${randomBytes(6).toString("hex")}.tmp`;
+	await mkdir(path.dirname(file), { recursive: true });
+	await writeFile(temporary, content, "utf8");
+	try {
+		await rename(temporary, file);
+	} catch (error) {
+		await rm(temporary, { force: true });
+		throw error;
+	}
+}
+async function readManifest(context, id) {
+	const file = path.join(releaseDir(context, id), "manifest.json");
+	try {
+		return JSON.parse(await readFile(file, "utf8"));
+	} catch (error) {
+		if (error.code === "ENOENT") throw new Error(`Release "${id}" does not exist (no manifest at ${file}).`);
+		throw error;
+	}
+}
+async function writeManifest(context, manifest) {
+	await writeFileAtomic(path.join(releaseDir(context, manifest.id), "manifest.json"), `${JSON.stringify(manifest, null, 2)}\n`);
+}
+/** Every release, newest first. */
+async function listManifests(context) {
+	let entries;
+	try {
+		entries = await readdir(releasesDir(context));
+	} catch (error) {
+		if (error.code === "ENOENT") return [];
+		throw error;
+	}
+	const manifests = [];
+	for (const entry of entries) {
+		if (!RELEASE_ID.test(entry)) continue;
+		try {
+			manifests.push(await readManifest(context, entry));
+		} catch {}
+	}
+	return manifests.sort((a, b) => a.createdAt === b.createdAt ? b.id.localeCompare(a.id) : b.createdAt.localeCompare(a.createdAt));
+}
+/** The release id a pointer names, or `null` when it is not set. */
+async function readPointer(context, name) {
+	try {
+		return path.basename(await readlink(pointerPath(context, name)));
+	} catch (error) {
+		const code = error.code;
+		if (code === "ENOENT" || code === "EINVAL") return null;
+		throw error;
+	}
+}
+/**
+* Point `current` or `previous` at a release.
+*
+* The symlink is built under a temporary name and renamed over the old one,
+* so the pointer always names a complete release and is never missing. The
+* target is relative (`releases/<id>`), so the whole directory can move.
+*/
+async function switchPointer(context, name, id) {
+	assertReleaseId(id);
+	const pointer = pointerPath(context, name);
+	const temporary = `${pointer}.${randomBytes(6).toString("hex")}.tmp`;
+	await mkdir(path.dirname(pointer), { recursive: true });
+	await symlink(path.join("releases", id), temporary, "dir");
+	try {
+		await rename(temporary, pointer);
+	} catch (error) {
+		await rm(temporary, { force: true });
+		throw error;
+	}
+}
+async function appendLog(context, entry) {
+	await mkdir(baseDir(context), { recursive: true });
+	await appendFile(logPath(context), `${JSON.stringify({
+		at: context.now().toISOString(),
+		...entry
+	})}\n`, "utf8");
+}
+async function readLog(context) {
+	try {
+		return (await readFile(logPath(context), "utf8")).split("\n").filter(Boolean).map((line) => JSON.parse(line));
+	} catch (error) {
+		if (error.code === "ENOENT") return [];
+		throw error;
+	}
+}
+/**
+* The release a command works on: the id it was given, or the newest release
+* that is not active yet.
+*/
+async function resolveRelease(context, id) {
+	if (id) return readManifest(context, id);
+	const latest = (await listManifests(context)).find((manifest) => [
+		"candidate",
+		"gated",
+		"staged"
+	].includes(manifest.status));
+	if (!latest) throw new Error("No release candidate found. Create one with `warlock release candidate`.");
+	return latest;
+}
+
+//#endregion
+export { appendLog, assertReleaseId, baseDir, listManifests, logPath, pointerPath, readLog, readManifest, readPointer, releaseDir, releasesDir, resolveRelease, switchPointer, writeFileAtomic, writeManifest };
+//# sourceMappingURL=store.mjs.map

package/esm/release/store.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"store.mjs","names":[],"sources":["../../../../../../../../packages/core/src/release/store.ts"],"sourcesContent":["import { randomBytes } from \"node:crypto\";\nimport {\n  appendFile,\n  mkdir,\n  readdir,\n  readFile,\n  readlink,\n  rename,\n  rm,\n  symlink,\n  writeFile,\n} from \"node:fs/promises\";\nimport path from \"node:path\";\nimport type {\n  CommandRunner,\n  ReleaseLogEntry,\n  ReleaseManifest,\n  ResolvedReleaseConfig,\n} from \"./types\";\n\n/** Everything a release operation needs; tests replace `runner` and `now`. */\nexport type ReleaseContext = {\n  /** Project root */\n  root: string;\n  config: ResolvedReleaseConfig;\n  runner: CommandRunner;\n  now: () => Date;\n  nodeVersion: string;\n};\n\nexport type PointerName = \"current\" | \"previous\";\n\nconst RELEASE_ID = /^[0-9A-Za-z][0-9A-Za-z._+-]*$/;\n\n/** Reject ids that could escape the releases directory. */\nexport function assertReleaseId(id: string): string {\n  if (!RELEASE_ID.test(id) || id.includes(\"..\")) {\n    throw new Error(`\"${id}\" is not a valid release id.`);\n  }\n\n  return id;\n}\n\nexport function baseDir(context: ReleaseContext): string {\n  return path.resolve(context.root, context.config.directory);\n}\n\nexport function releasesDir(context: ReleaseContext): string {\n  return path.join(baseDir(context), \"releases\");\n}\n\nexport function releaseDir(context: ReleaseContext, id: string): string {\n  return path.join(releasesDir(context), assertReleaseId(id));\n}\n\nexport function pointerPath(context: ReleaseContext, name: PointerName): string {\n  return path.join(baseDir(context), name);\n}\n\nexport function logPath(context: ReleaseContext): string {\n  return path.join(baseDir(context), \"release.log\");\n}\n\n/** Write a file so readers see either the old content or the new, never half. */\nexport async function writeFileAtomic(file: string, content: string): Promise<void> {\n  const temporary = `${file}.${randomBytes(6).toString(\"hex\")}.tmp`;\n\n  await mkdir(path.dirname(file), { recursive: true });\n  await writeFile(temporary, content, \"utf8\");\n\n  try {\n    await rename(temporary, file);\n  } catch (error) {\n    await rm(temporary, { force: true });\n    throw error;\n  }\n}\n\nexport async function readManifest(context: ReleaseContext, id: string): Promise<ReleaseManifest> {\n  const file = path.join(releaseDir(context, id), \"manifest.json\");\n\n  try {\n    return JSON.parse(await readFile(file, \"utf8\")) as ReleaseManifest;\n  } catch (error) {\n    if ((error as NodeJS.ErrnoException).code === \"ENOENT\") {\n      throw new Error(`Release \"${id}\" does not exist (no manifest at ${file}).`);\n    }\n\n    throw error;\n  }\n}\n\nexport async function writeManifest(\n  context: ReleaseContext,\n  manifest: ReleaseManifest,\n): Promise<void> {\n  await writeFileAtomic(\n    path.join(releaseDir(context, manifest.id), \"manifest.json\"),\n    `${JSON.stringify(manifest, null, 2)}\\n`,\n  );\n}\n\n/** Every release, newest first. */\nexport async function listManifests(context: ReleaseContext): Promise<ReleaseManifest[]> {\n  let entries: string[];\n\n  try {\n    entries = await readdir(releasesDir(context));\n  } catch (error) {\n    if ((error as NodeJS.ErrnoException).code === \"ENOENT\") return [];\n    throw error;\n  }\n\n  const manifests: ReleaseManifest[] = [];\n\n  for (const entry of entries) {\n    if (!RELEASE_ID.test(entry)) continue;\n\n    try {\n      manifests.push(await readManifest(context, entry));\n    } catch {\n      // A directory without a readable manifest is not a release.\n    }\n  }\n\n  return manifests.sort((a, b) =>\n    a.createdAt === b.createdAt ? b.id.localeCompare(a.id) : b.createdAt.localeCompare(a.createdAt),\n  );\n}\n\n/** The release id a pointer names, or `null` when it is not set. */\nexport async function readPointer(\n  context: ReleaseContext,\n  name: PointerName,\n): Promise<string | null> {\n  try {\n    return path.basename(await readlink(pointerPath(context, name)));\n  } catch (error) {\n    const code = (error as NodeJS.ErrnoException).code;\n\n    if (code === \"ENOENT\" || code === \"EINVAL\") return null;\n    throw error;\n  }\n}\n\n/**\n * Point `current` or `previous` at a release.\n *\n * The symlink is built under a temporary name and renamed over the old one,\n * so the pointer always names a complete release and is never missing. The\n * target is relative (`releases/<id>`), so the whole directory can move.\n */\nexport async function switchPointer(\n  context: ReleaseContext,\n  name: PointerName,\n  id: string,\n): Promise<void> {\n  assertReleaseId(id);\n\n  const pointer = pointerPath(context, name);\n  const temporary = `${pointer}.${randomBytes(6).toString(\"hex\")}.tmp`;\n\n  await mkdir(path.dirname(pointer), { recursive: true });\n  await symlink(path.join(\"releases\", id), temporary, \"dir\");\n\n  try {\n    await rename(temporary, pointer);\n  } catch (error) {\n    await rm(temporary, { force: true });\n    throw error;\n  }\n}\n\nexport async function appendLog(\n  context: ReleaseContext,\n  entry: Omit<ReleaseLogEntry, \"at\">,\n): Promise<void> {\n  await mkdir(baseDir(context), { recursive: true });\n  await appendFile(\n    logPath(context),\n    `${JSON.stringify({ at: context.now().toISOString(), ...entry })}\\n`,\n    \"utf8\",\n  );\n}\n\nexport async function readLog(context: ReleaseContext): Promise<ReleaseLogEntry[]> {\n  try {\n    const content = await readFile(logPath(context), \"utf8\");\n\n    return content\n      .split(\"\\n\")\n      .filter(Boolean)\n      .map((line) => JSON.parse(line) as ReleaseLogEntry);\n  } catch (error) {\n    if ((error as NodeJS.ErrnoException).code === \"ENOENT\") return [];\n    throw error;\n  }\n}\n\n/**\n * The release a command works on: the id it was given, or the newest release\n * that is not active yet.\n */\nexport async function resolveRelease(\n  context: ReleaseContext,\n  id?: string,\n): Promise<ReleaseManifest> {\n  if (id) return readManifest(context, id);\n\n  const manifests = await listManifests(context);\n  const latest = manifests.find((manifest) =>\n    [\"candidate\", \"gated\", \"staged\"].includes(manifest.status),\n  );\n\n  if (!latest) {\n    throw new Error(\"No release candidate found. Create one with `warlock release candidate`.\");\n  }\n\n  return latest;\n}\n"],"mappings":"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"}

package/esm/release/types.d.mts

@@ -0,0 +1,102 @@
+//#region ../../packages/core/src/release/types.d.ts
+/**
+ * One named command in the release gate. Checks run in order and the gate
+ * stops at the first one that fails.
+ */
+export type ReleaseCheck = {
+  /** Name shown in the report and recorded in the manifest */
+  name: string;
+  /** Shell command, run inside the candidate's frozen source */
+  command: string;
+  /** Kill the check after this many milliseconds. @default 1_800_000 */
+  timeoutMs?: number;
+};
+/**
+ * Release settings, read from the `release` key of `warlock.config.ts`.
+ *
+ * Every field is optional; the defaults describe a plain Warlock app that
+ * builds into `dist`.
+ */
+export type ReleaseConfig = {
+  /**
+   * Base directory for releases and the `current` / `previous` pointers,
+   * relative to the project root.
+   *
+   * @default ".warlock"
+   */
+  directory?: string;
+  /**
+   * Build output directory, relative to the candidate's source.
+   *
+   * @default "dist"
+   */
+  distDir?: string;
+  /**
+   * Extra files or directories (relative to the candidate's source) copied
+   * next to the build output when staging. `package.json` and the lockfile
+   * are always copied.
+   */
+  include?: string[];
+  /**
+   * Link the project's `node_modules` into the frozen source so gate checks
+   * and the build can run without a second install.
+   *
+   * @default true
+   */
+  linkNodeModules?: boolean;
+  /** The ordered gate checks. Replaces the defaults when set. */
+  gate?: {
+    checks?: ReleaseCheck[];
+  };
+  /** Migration proof settings */
+  migrations?: {
+    /**
+     * Named targets. `--target <name>` applies the target's `env` to this
+     * process before the database connects, so the proof runs against that
+     * database instead of the one the local environment points to.
+     */
+    targets?: Record<string, {
+      env?: Record<string, string>;
+    }>;
+    /**
+     * Migration names that must be the ones executed, in order. Defaults to
+     * the pending set computed before the run.
+     */
+    expected?: string[];
+    /** Tables or collections that must exist after the run. */
+    expectedTables?: string[];
+  };
+  /**
+   * Command that makes the running application pick up the new release.
+   * Warlock never restarts anything on its own: leave it unset and activation
+   * only switches the pointer.
+   *
+   * It runs through the shell with `WARLOCK_RELEASE_ID`,
+   * `WARLOCK_RELEASE_DIR` and `WARLOCK_RELEASE_CURRENT` in its environment.
+   */
+  restart?: {
+    command?: string;
+    timeoutMs?: number;
+  };
+  /** Post-activation health verification */
+  verify?: {
+    /** Health URL. Required by `release verify`. */
+    url?: string;
+    /** @default 200 */
+    expectedStatus?: number;
+    /** Attempts after the first one. @default 5 */
+    retries?: number;
+    /** Wait between attempts in milliseconds. @default 2000 */
+    intervalMs?: number;
+    /** Per-request timeout in milliseconds. @default 5000 */
+    timeoutMs?: number;
+    /** Dotted JSON path of the reported version. @default "version" */
+    versionPath?: string;
+    /** Dotted JSON path of the reported commit. @default "commit" */
+    commitPath?: string;
+    /** Which reported fields must match the active release. @default ["version", "commit"] */
+    match?: Array<"version" | "commit">;
+  };
+};
+//#endregion
+//# sourceMappingURL=types.d.mts.map

package/esm/release/types.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.mts","names":[],"sources":["../../../../../../../../packages/core/src/release/types.ts"],"mappings":";;;;;YAIY;;EAEV;;EAEA;;EAEA;;;;;;;;YASU;;;;;;;EAOV;;;;;;EAMA;;;;;;EAMA;;;;;;;EAOA;;EAEA;IAAS,SAAS;;;EAElB;;;;;;IAME,UAAU;MAAiB,MAAM;;;;;;IAKjC;;IAEA;;;;;;;;;;EAUF;IAAY;IAAkB;;;EAE9B;;IAEE;;IAEA;;IAEA;;IAEA;;IAEA;;IAEA;;IAEA;;IAEA,QAAQ"}

package/esm/release/verify.mjs

@@ -0,0 +1,94 @@
+import { appendLog, readManifest, readPointer, writeManifest } from "./store.mjs";
+
+//#region ../../packages/core/src/release/verify.ts
+function readPath(value, dotted) {
+	let current = value;
+	for (const key of dotted.split(".")) {
+		if (typeof current !== "object" || current === null) return void 0;
+		current = current[key];
+	}
+	return current;
+}
+function sleep(ms) {
+	return new Promise((resolve) => setTimeout(resolve, ms));
+}
+/** Why one attempt failed, or `null` when it matched the release. */
+async function attempt(context, url, expected) {
+	const { verify } = context.config;
+	const controller = new AbortController();
+	const timer = setTimeout(() => controller.abort(), verify.timeoutMs);
+	try {
+		const response = await fetch(url, { signal: controller.signal });
+		if (response.status !== verify.expectedStatus) return `status ${response.status}, expected ${verify.expectedStatus}`;
+		if (verify.match.length === 0) return null;
+		let body;
+		try {
+			body = await response.json();
+		} catch {
+			return "the response is not JSON, so the version cannot be compared";
+		}
+		for (const field of verify.match) {
+			const reported = readPath(body, field === "version" ? verify.versionPath : verify.commitPath);
+			const wanted = expected[field];
+			if (reported === void 0) return `the response reports no ${field} (looked at "${field === "version" ? verify.versionPath : verify.commitPath}")`;
+			if (!(field === "commit" && typeof reported === "string" ? reported.length >= 7 && wanted.startsWith(reported) : reported === wanted)) return `reported ${field} ${String(reported)}, expected ${wanted}`;
+		}
+		return null;
+	} catch (error) {
+		return error.name === "AbortError" ? `no response within ${verify.timeoutMs}ms` : error.message;
+	} finally {
+		clearTimeout(timer);
+	}
+}
+/**
+* GET the health URL until it answers with the expected status and reports
+* the active release's version and commit, retrying with a pause between
+* attempts. The outcome is recorded in the active release's manifest.
+*
+* @example
+* const result = await verifyRelease(context);
+*/
+async function verifyRelease(context) {
+	const { verify } = context.config;
+	const id = await readPointer(context, "current");
+	if (!id) throw new Error("No active release to verify.");
+	if (!verify.url) throw new Error("Set release.verify.url to the health URL first.");
+	const manifest = await readManifest(context, id);
+	let reason = "not attempted";
+	let attempts = 0;
+	for (let index = 0; index <= verify.retries; index++) {
+		if (index > 0) await sleep(verify.intervalMs);
+		attempts += 1;
+		reason = await attempt(context, verify.url, {
+			version: manifest.version,
+			commit: manifest.commit
+		});
+		if (reason === null) break;
+	}
+	const ok = reason === null;
+	await writeManifest(context, {
+		...manifest,
+		verification: {
+			at: context.now().toISOString(),
+			ok,
+			attempts,
+			...ok ? {} : { reason: reason ?? void 0 }
+		}
+	});
+	await appendLog(context, {
+		event: "verify",
+		release: id,
+		ok,
+		detail: ok ? `${attempts} attempt(s)` : reason ?? void 0
+	});
+	return {
+		id,
+		ok,
+		attempts,
+		...ok ? {} : { reason: reason ?? void 0 }
+	};
+}
+
+//#endregion
+export { verifyRelease };
+//# sourceMappingURL=verify.mjs.map

package/esm/release/verify.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"verify.mjs","names":[],"sources":["../../../../../../../../packages/core/src/release/verify.ts"],"sourcesContent":["import { appendLog, readManifest, readPointer, writeManifest, type ReleaseContext } from \"./store\";\n\nexport type VerifyResult = {\n  id: string;\n  ok: boolean;\n  attempts: number;\n  reason?: string;\n};\n\nfunction readPath(value: unknown, dotted: string): unknown {\n  let current: unknown = value;\n\n  for (const key of dotted.split(\".\")) {\n    if (typeof current !== \"object\" || current === null) return undefined;\n    current = (current as Record<string, unknown>)[key];\n  }\n\n  return current;\n}\n\nfunction sleep(ms: number): Promise<void> {\n  return new Promise((resolve) => setTimeout(resolve, ms));\n}\n\n/** Why one attempt failed, or `null` when it matched the release. */\nasync function attempt(\n  context: ReleaseContext,\n  url: string,\n  expected: { version: string; commit: string },\n): Promise<string | null> {\n  const { verify } = context.config;\n  const controller = new AbortController();\n  const timer = setTimeout(() => controller.abort(), verify.timeoutMs);\n\n  try {\n    const response = await fetch(url, { signal: controller.signal });\n\n    if (response.status !== verify.expectedStatus) {\n      return `status ${response.status}, expected ${verify.expectedStatus}`;\n    }\n\n    if (verify.match.length === 0) return null;\n\n    let body: unknown;\n\n    try {\n      body = await response.json();\n    } catch {\n      return \"the response is not JSON, so the version cannot be compared\";\n    }\n\n    for (const field of verify.match) {\n      const reported = readPath(body, field === \"version\" ? verify.versionPath : verify.commitPath);\n      const wanted = expected[field];\n\n      if (reported === undefined) {\n        return `the response reports no ${field} (looked at \"${\n          field === \"version\" ? verify.versionPath : verify.commitPath\n        }\")`;\n      }\n\n      // A reported short commit counts when it is a prefix of the full one.\n      const matches =\n        field === \"commit\" && typeof reported === \"string\"\n          ? reported.length >= 7 && wanted.startsWith(reported)\n          : reported === wanted;\n\n      if (!matches) return `reported ${field} ${String(reported)}, expected ${wanted}`;\n    }\n\n    return null;\n  } catch (error) {\n    return (error as Error).name === \"AbortError\"\n      ? `no response within ${verify.timeoutMs}ms`\n      : (error as Error).message;\n  } finally {\n    clearTimeout(timer);\n  }\n}\n\n/**\n * GET the health URL until it answers with the expected status and reports\n * the active release's version and commit, retrying with a pause between\n * attempts. The outcome is recorded in the active release's manifest.\n *\n * @example\n * const result = await verifyRelease(context);\n */\nexport async function verifyRelease(context: ReleaseContext): Promise<VerifyResult> {\n  const { verify } = context.config;\n  const id = await readPointer(context, \"current\");\n\n  if (!id) throw new Error(\"No active release to verify.\");\n  if (!verify.url) throw new Error(\"Set release.verify.url to the health URL first.\");\n\n  const manifest = await readManifest(context, id);\n  let reason: string | null = \"not attempted\";\n  let attempts = 0;\n\n  for (let index = 0; index <= verify.retries; index++) {\n    if (index > 0) await sleep(verify.intervalMs);\n\n    attempts += 1;\n    reason = await attempt(context, verify.url, {\n      version: manifest.version,\n      commit: manifest.commit,\n    });\n\n    if (reason === null) break;\n  }\n\n  const ok = reason === null;\n\n  await writeManifest(context, {\n    ...manifest,\n    verification: {\n      at: context.now().toISOString(),\n      ok,\n      attempts,\n      ...(ok ? {} : { reason: reason ?? undefined }),\n    },\n  });\n  await appendLog(context, {\n    event: \"verify\",\n    release: id,\n    ok,\n    detail: ok ? `${attempts} attempt(s)` : (reason ?? undefined),\n  });\n\n  return { id, ok, attempts, ...(ok ? {} : { reason: reason ?? undefined }) };\n}\n"],"mappings":";;;AASA,SAAS,SAAS,OAAgB,QAAyB;CACzD,IAAI,UAAmB;CAEvB,KAAK,MAAM,OAAO,OAAO,MAAM,GAAG,GAAG;EACnC,IAAI,OAAO,YAAY,YAAY,YAAY,MAAM,OAAO;EAC5D,UAAW,QAAoC;CACjD;CAEA,OAAO;AACT;AAEA,SAAS,MAAM,IAA2B;CACxC,OAAO,IAAI,SAAS,YAAY,WAAW,SAAS,EAAE,CAAC;AACzD;;AAGA,eAAe,QACb,SACA,KACA,UACwB;CACxB,MAAM,EAAE,WAAW,QAAQ;CAC3B,MAAM,aAAa,IAAI,gBAAgB;CACvC,MAAM,QAAQ,iBAAiB,WAAW,MAAM,GAAG,OAAO,SAAS;CAEnE,IAAI;EACF,MAAM,WAAW,MAAM,MAAM,KAAK,EAAE,QAAQ,WAAW,OAAO,CAAC;EAE/D,IAAI,SAAS,WAAW,OAAO,gBAC7B,OAAO,UAAU,SAAS,OAAO,aAAa,OAAO;EAGvD,IAAI,OAAO,MAAM,WAAW,GAAG,OAAO;EAEtC,IAAI;EAEJ,IAAI;GACF,OAAO,MAAM,SAAS,KAAK;EAC7B,QAAQ;GACN,OAAO;EACT;EAEA,KAAK,MAAM,SAAS,OAAO,OAAO;GAChC,MAAM,WAAW,SAAS,MAAM,UAAU,YAAY,OAAO,cAAc,OAAO,UAAU;GAC5F,MAAM,SAAS,SAAS;GAExB,IAAI,aAAa,QACf,OAAO,2BAA2B,MAAM,eACtC,UAAU,YAAY,OAAO,cAAc,OAAO,WACnD;GASH,IAAI,EAJF,UAAU,YAAY,OAAO,aAAa,WACtC,SAAS,UAAU,KAAK,OAAO,WAAW,QAAQ,IAClD,aAAa,SAEL,OAAO,YAAY,MAAM,GAAG,OAAO,QAAQ,EAAE,aAAa;EAC1E;EAEA,OAAO;CACT,SAAS,OAAO;EACd,OAAQ,MAAgB,SAAS,eAC7B,sBAAsB,OAAO,UAAU,MACtC,MAAgB;CACvB,UAAU;EACR,aAAa,KAAK;CACpB;AACF;;;;;;;;;AAUA,eAAsB,cAAc,SAAgD;CAClF,MAAM,EAAE,WAAW,QAAQ;CAC3B,MAAM,KAAK,MAAM,YAAY,SAAS,SAAS;CAE/C,IAAI,CAAC,IAAI,MAAM,IAAI,MAAM,8BAA8B;CACvD,IAAI,CAAC,OAAO,KAAK,MAAM,IAAI,MAAM,iDAAiD;CAElF,MAAM,WAAW,MAAM,aAAa,SAAS,EAAE;CAC/C,IAAI,SAAwB;CAC5B,IAAI,WAAW;CAEf,KAAK,IAAI,QAAQ,GAAG,SAAS,OAAO,SAAS,SAAS;EACpD,IAAI,QAAQ,GAAG,MAAM,MAAM,OAAO,UAAU;EAE5C,YAAY;EACZ,SAAS,MAAM,QAAQ,SAAS,OAAO,KAAK;GAC1C,SAAS,SAAS;GAClB,QAAQ,SAAS;EACnB,CAAC;EAED,IAAI,WAAW,MAAM;CACvB;CAEA,MAAM,KAAK,WAAW;CAEtB,MAAM,cAAc,SAAS;EAC3B,GAAG;EACH,cAAc;GACZ,IAAI,QAAQ,IAAI,CAAC,CAAC,YAAY;GAC9B;GACA;GACA,GAAI,KAAK,CAAC,IAAI,EAAE,QAAQ,UAAU,OAAU;EAC9C;CACF,CAAC;CACD,MAAM,UAAU,SAAS;EACvB,OAAO;EACP,SAAS;EACT;EACA,QAAQ,KAAK,GAAG,SAAS,eAAgB,UAAU;CACrD,CAAC;CAED,OAAO;EAAE;EAAI;EAAI;EAAU,GAAI,KAAK,CAAC,IAAI,EAAE,QAAQ,UAAU,OAAU;CAAG;AAC5E"}

package/esm/router/index.d.mts

@@ -6,5 +6,5 @@ import { matchesDerivedRouteName, routeNameMethodSuffix } from "./route-name-met
 import { RouteNameTakenError } from "./route-name-taken-error.mjs";
 import { RouteRegistry } from "./route-registry.mjs";
 import { Router, router } from "./router.mjs";
-import { AUTH_GUARD_MARKER, isAuthGuardMiddleware, isUnguardedMutatingRoute, markAuthGuard, reportUnguardedMutatingRoutes, resetUnguardedRouteReports } from "./unguarded-route-diagnostics.mjs";
-export { AUTH_GUARD_MARKER, GroupedRoutesOptions, HttpContext, Middleware, MiddlewareResponse, NamedApiRoute, NamedApiRoutesOptions, PartialPick, PositionalHandlerSuspect, RequestControllerContract, RequestHandler, RequestHandlerType, RequestHandlerValidation, RequestMethod, ResourceMethod, RestfulMiddleware, Route, RouteNameTakenError, RouteOptions, RouteRateLimitOptions, RouteRegistry, RouteResource, Router, RouterGroupCallback, RouterStacks, StaticMountOptions, ValidationFailureContext, ValidationFailureHandler, ValidationFailureResponse, clearPositionalHandlerSuspects, describePositionalHandlerSuspect, forgetPositionalHandlerSuspects, inspectHandlerSignature, isAuthGuardMiddleware, isUnguardedMutatingRoute, listPositionalHandlerSuspects, looksLikePositionalHandler, markAuthGuard, matchesDerivedRouteName, normalizeRequestPath, normalizeRoutePath, reportPositionalHandlerSuspects, reportUnguardedMutatingRoutes, resetUnguardedRouteReports, routeNameMethodSuffix, router };
+import { AUTH_GUARD_MARKER, isAuthGuardMiddleware, isRequiredGuardRoute, isUnguardedMutatingRoute, markAuthGuard, reportUnguardedMutatingRoutes, resetUnguardedRouteReports } from "./unguarded-route-diagnostics.mjs";
+export { AUTH_GUARD_MARKER, GroupedRoutesOptions, HttpContext, Middleware, MiddlewareResponse, NamedApiRoute, NamedApiRoutesOptions, PartialPick, PositionalHandlerSuspect, RequestControllerContract, RequestHandler, RequestHandlerType, RequestHandlerValidation, RequestMethod, ResourceMethod, RestfulMiddleware, Route, RouteNameTakenError, RouteOptions, RouteRateLimitOptions, RouteRegistry, RouteResource, Router, RouterGroupCallback, RouterStacks, StaticMountOptions, ValidationFailureContext, ValidationFailureHandler, ValidationFailureResponse, clearPositionalHandlerSuspects, describePositionalHandlerSuspect, forgetPositionalHandlerSuspects, inspectHandlerSignature, isAuthGuardMiddleware, isRequiredGuardRoute, isUnguardedMutatingRoute, listPositionalHandlerSuspects, looksLikePositionalHandler, markAuthGuard, matchesDerivedRouteName, normalizeRequestPath, normalizeRoutePath, reportPositionalHandlerSuspects, reportUnguardedMutatingRoutes, resetUnguardedRouteReports, routeNameMethodSuffix, router };

package/esm/router/index.mjs

@@ -4,7 +4,7 @@ import { clearPositionalHandlerSuspects, describePositionalHandlerSuspect, forge
 import { matchesDerivedRouteName, routeNameMethodSuffix } from "./route-name-method-suffix.mjs";
 import { RouteNameTakenError } from "./route-name-taken-error.mjs";
 import { RouteRegistry } from "./route-registry.mjs";
-import { AUTH_GUARD_MARKER, isAuthGuardMiddleware, isUnguardedMutatingRoute, markAuthGuard, reportUnguardedMutatingRoutes, resetUnguardedRouteReports } from "./unguarded-route-diagnostics.mjs";
+import { AUTH_GUARD_MARKER, isAuthGuardMiddleware, isRequiredGuardRoute, isUnguardedMutatingRoute, markAuthGuard, reportUnguardedMutatingRoutes, resetUnguardedRouteReports } from "./unguarded-route-diagnostics.mjs";
 import { Router, router } from "./router.mjs";
 
-export { AUTH_GUARD_MARKER, RouteNameTakenError, RouteRegistry, Router, clearPositionalHandlerSuspects, describePositionalHandlerSuspect, forgetPositionalHandlerSuspects, inspectHandlerSignature, isAuthGuardMiddleware, isUnguardedMutatingRoute, listPositionalHandlerSuspects, looksLikePositionalHandler, markAuthGuard, matchesDerivedRouteName, normalizeRequestPath, normalizeRoutePath, reportPositionalHandlerSuspects, reportUnguardedMutatingRoutes, resetUnguardedRouteReports, routeNameMethodSuffix, router };
+export { AUTH_GUARD_MARKER, RouteNameTakenError, RouteRegistry, Router, clearPositionalHandlerSuspects, describePositionalHandlerSuspect, forgetPositionalHandlerSuspects, inspectHandlerSignature, isAuthGuardMiddleware, isRequiredGuardRoute, isUnguardedMutatingRoute, listPositionalHandlerSuspects, looksLikePositionalHandler, markAuthGuard, matchesDerivedRouteName, normalizeRequestPath, normalizeRoutePath, reportPositionalHandlerSuspects, reportUnguardedMutatingRoutes, resetUnguardedRouteReports, routeNameMethodSuffix, router };

package/esm/router/router.d.mts

@@ -221,8 +221,10 @@ export declare class Router {
    *
    * Names are the registered names, including method suffixes. `all` stays
    * intact as route metadata; consumers decide whether their use supports it.
-   * A route that opted out with `clientVisible: false` carries that flag, and
-   * only that flag, so browser-facing consumers can leave it out.
+   * A route that opted out with `clientVisible: false` carries that flag so
+   * browser-facing consumers can leave it out. `sites` is present only on a
+   * route that declared some, and `guarded: true` only on a route with an auth
+   * guard in its middleware chain (group middleware included).
    */
   getNamedApiRoutes(options?: NamedApiRoutesOptions): readonly NamedApiRoute[];
   /**

package/esm/router/router.d.mts.map

@@ -1 +1 @@
-{"version":3,"file":"router.d.mts","names":[],"sources":["../../../../../../../../packages/core/src/router/router.ts"],"mappings":";;;;;;qBAqKa;;;;UAIH;;;;;;;;;UAUA;;;;;UAMA;;;;;UAUA;;;;iBAKO;;;;YAKL;IACR,SAAS;IACT,WAAW;;;;;YAMH,gBAAgB,iBAAiB,QAAQ,QAAQ,QAAQ;;;;;YAOzD,QAAQ;;;;SASJ,eAAW;UAQlB;;;;EAOA,eAAe,WAAW,QAAQ,QAAQ,QAAQ;;;;EASlD,cAAc,WAAW,QAAQ,QAAQ,QAAQ;;;;EASjD,SAAS,cAAc,YAAY;;;;;;;;;;;;;;EAmBnC,UAAU,SAAS,sBAAsB,eAAc;;YAOpD,0BAA0B,QAAQ;;;;;;YAelC,mBACR,cACA,SAAS,gBACT,eAAc;;;;EAmBT,KACL,cACA,kBACA,oBACA,eAAc;;;;EAcT,WACL,cACA,kBACA,oBACA,eAAc;;;;EAcT,MACL,OAAO,wBACP,oBACA,eAAc;;;;EAUT,YACL,OAAO,wBACP,oBACA,eAAc;;;;EAUT,MACL,cACA,iBACA,UAAU,KAAK;EAEV,MAAM,SAAS;;;;EAoBf,IACL,QAAQ,iBACR,yBACA,SAAS,oBACT,UAAS;;;;EA8HJ,IAAI,cAAc,SAAS,oBAAoB,UAAS;;;;EAOxD,IAAI,cAAc,SAAS,oBAAoB,UAAS;;;;EAOxD,KAAK,yBAAyB,SAAS,oBAAoB,UAAS;;;;EAOpE,IAAI,cAAc,SAAS,oBAAoB,UAAS;;;;EAOxD,OAAO,yBAAyB,SAAS,oBAAoB,UAAS;;;;EAOtE,MAAM,cAAc,SAAS,oBAAoB,UAAS;;;;EAO1D,KAAK,cAAc,SAAS,oBAAoB,UAAS;;;;EAOzD,QAAQ,cAAc,SAAS,oBAAoB,UAAS;;;;EAO5D,MAAM,cAAc,UAAS,eAAiB;;;;;;;;;;;EAc9C,gBACL,cACA,UAAU,eACV,UAAS;IACP,OAAO;IACP,SAAS;IACT,UAAU,QAAQ,OAAO,gBAAgB;MACvC,aAAa;;;;;;EAsGZ,MAAM,SAAS,sBAAsB,UAAU;;;;EA4D/C,OAAO,gBAAgB;;;;;;;;;;;;;EAgBvB,QAAQ,0BAA0B;;;;;;;EAU5B,eAAe,SAC1B,oBACA,gBAAgB,IAAI,QAAQ,KAC3B,QAAQ;;;;;;EAiCJ,yBAAyB;;;;;;;;;EA0BnB,2BAA2B,GACtC,aAAa,kBACb,eAAe,IAAI,QAAQ,KAC1B,QAAQ;;;;UAoDH;;;;EA4ED,QAAI;;;;;;;;;EAYJ,kBAAkB,UAAS,iCAAsC;;;;;;;;;EAgCjE;;;;EAOA,KAAK,QAAQ;;;;;EAqDb,cAAc,QAAQ;;;;EAiKtB,SAAS,cAAc,SAAQ;;;;UAkC9B;;qBA+EG,QAAM"}
+{"version":3,"file":"router.d.mts","names":[],"sources":["../../../../../../../../packages/core/src/router/router.ts"],"mappings":";;;;;;qBAqKa;;;;UAIH;;;;;;;;;UAUA;;;;;UAMA;;;;;UAUA;;;;iBAKO;;;;YAKL;IACR,SAAS;IACT,WAAW;;;;;YAMH,gBAAgB,iBAAiB,QAAQ,QAAQ,QAAQ;;;;;YAOzD,QAAQ;;;;SASJ,eAAW;UAQlB;;;;EAOA,eAAe,WAAW,QAAQ,QAAQ,QAAQ;;;;EASlD,cAAc,WAAW,QAAQ,QAAQ,QAAQ;;;;EASjD,SAAS,cAAc,YAAY;;;;;;;;;;;;;;EAmBnC,UAAU,SAAS,sBAAsB,eAAc;;YAOpD,0BAA0B,QAAQ;;;;;;YAelC,mBACR,cACA,SAAS,gBACT,eAAc;;;;EAmBT,KACL,cACA,kBACA,oBACA,eAAc;;;;EAcT,WACL,cACA,kBACA,oBACA,eAAc;;;;EAcT,MACL,OAAO,wBACP,oBACA,eAAc;;;;EAUT,YACL,OAAO,wBACP,oBACA,eAAc;;;;EAUT,MACL,cACA,iBACA,UAAU,KAAK;EAEV,MAAM,SAAS;;;;EAoBf,IACL,QAAQ,iBACR,yBACA,SAAS,oBACT,UAAS;;;;EAsIJ,IAAI,cAAc,SAAS,oBAAoB,UAAS;;;;EAOxD,IAAI,cAAc,SAAS,oBAAoB,UAAS;;;;EAOxD,KAAK,yBAAyB,SAAS,oBAAoB,UAAS;;;;EAOpE,IAAI,cAAc,SAAS,oBAAoB,UAAS;;;;EAOxD,OAAO,yBAAyB,SAAS,oBAAoB,UAAS;;;;EAOtE,MAAM,cAAc,SAAS,oBAAoB,UAAS;;;;EAO1D,KAAK,cAAc,SAAS,oBAAoB,UAAS;;;;EAOzD,QAAQ,cAAc,SAAS,oBAAoB,UAAS;;;;EAO5D,MAAM,cAAc,UAAS,eAAiB;;;;;;;;;;;EAc9C,gBACL,cACA,UAAU,eACV,UAAS;IACP,OAAO;IACP,SAAS;IACT,UAAU,QAAQ,OAAO,gBAAgB;MACvC,aAAa;;;;;;EAsGZ,MAAM,SAAS,sBAAsB,UAAU;;;;EAqE/C,OAAO,gBAAgB;;;;;;;;;;;;;EAgBvB,QAAQ,0BAA0B;;;;;;;EAU5B,eAAe,SAC1B,oBACA,gBAAgB,IAAI,QAAQ,KAC3B,QAAQ;;;;;;EAiCJ,yBAAyB;;;;;;;;;EA0BnB,2BAA2B,GACtC,aAAa,kBACb,eAAe,IAAI,QAAQ,KAC1B,QAAQ;;;;UAoDH;;;;EA4ED,QAAI;;;;;;;;;;;EAcJ,kBAAkB,UAAS,iCAAsC;;;;;;;;;EAkCjE;;;;EAOA,KAAK,QAAQ;;;;;EAqDb,cAAc,QAAQ;;;;EAiKtB,SAAS,cAAc,SAAQ;;;;UAkC9B;;qBA+EG,QAAM"}

package/esm/router/router.mjs

@@ -15,7 +15,7 @@ import { buildRequestLogSnapshot } from "../http/request-log-snapshot.mjs";
 import { Request } from "../http/request.mjs";
 import { describeRouteForLog } from "./describe-route-for-log.mjs";
 import { logRequestLifecycle } from "./log-request-lifecycle.mjs";
-import { reportUnguardedMutatingRoutes } from "./unguarded-route-diagnostics.mjs";
+import { isRequiredGuardRoute, reportUnguardedMutatingRoutes } from "./unguarded-route-diagnostics.mjs";
 import { RouteBuilder } from "./route-builder.mjs";
 import { resolveRouteRateLimit, resolveStaticRateLimit } from "./resolve-route-rate-limit.mjs";
 import { DEV_DISPATCH_METHODS, buildNotFoundBody, createDevRateLimiter } from "./dev-dispatch.mjs";
@@ -229,6 +229,8 @@ var Router = class Router {
 		if (middlewarePrecedence === "before") options.middleware = [...options.middleware || [], ...this.stacks.middleware];
 		else options.middleware = [...this.stacks.middleware, ...options.middleware || []];
 		if (options.public === void 0 && (this.stacks.public ?? 0) > 0) options.public = true;
+		const groupSites = this.stacks.sites?.at(-1);
+		if (options.sites === void 0 && groupSites !== void 0) options.sites = groupSites;
 		if (Array.isArray(handler)) {
 			const [controller, action] = handler;
 			if (typeof controller[action] !== "function") throw new WarlockError("WL3002", `Invalid controller action "${action}" for controller "${controller.constructor.name}"`);
@@ -391,7 +393,8 @@ var Router = class Router {
 	* Group routes with options
 	*/
 	group(options, callback) {
-		const { prefix, name = prefix ? trim(prefix.replace(/\//g, "."), ".") : void 0, middleware, public: isPublic } = options;
+		const { prefix, name = prefix ? trim(prefix.replace(/\//g, "."), ".") : void 0, middleware, public: isPublic, sites } = options;
+		if (sites) (this.stacks.sites ??= []).push(sites);
 		if (isPublic) this.stacks.public = (this.stacks.public ?? 0) + 1;
 		if (prefix) this.stacks.prefix.push(prefix);
 		if (name) this.stacks.name.push(name);
@@ -403,6 +406,7 @@ var Router = class Router {
 			if (name) this.stacks.name.pop();
 			if (middleware) this.stacks.middleware.splice(this.stacks.middleware.length - middleware.length, middleware.length);
 			if (isPublic) this.stacks.public = (this.stacks.public ?? 1) - 1;
+			if (sites) this.stacks.sites?.pop();
 		}
 		return this;
 	}
@@ -554,8 +558,10 @@ var Router = class Router {
 	*
 	* Names are the registered names, including method suffixes. `all` stays
 	* intact as route metadata; consumers decide whether their use supports it.
-	* A route that opted out with `clientVisible: false` carries that flag, and
-	* only that flag, so browser-facing consumers can leave it out.
+	* A route that opted out with `clientVisible: false` carries that flag so
+	* browser-facing consumers can leave it out. `sites` is present only on a
+	* route that declared some, and `guarded: true` only on a route with an auth
+	* guard in its middleware chain (group middleware included).
 	*/
 	getNamedApiRoutes(options = {}) {
 		return Object.freeze(this.routes.filter((route) => !route.isPage && typeof route.name === "string" && route.name.length > 0).map((route) => {
@@ -563,7 +569,9 @@ var Router = class Router {
 				name: route.name,
 				path: route.path,
 				method: route.method,
-				...route.clientVisible === false ? { clientVisible: false } : {}
+				...route.clientVisible === false ? { clientVisible: false } : {},
+				...route.sites === void 0 ? {} : { sites: Object.freeze([...route.sites]) },
+				...isRequiredGuardRoute(route) ? { guarded: true } : {}
 			};
 			const schema = route.handler?.responseSchema;
 			const response = schema ? options.resolveResponse?.(schema, route) : void 0;