@glw907/cairn-cms 0.60.1 → 0.62.1

package/src/lib/sveltekit/editors-routes.ts

@@ -23,6 +23,9 @@ function parseRole(value: FormDataEntryValue | null): Role {
   return value === 'owner' ? 'owner' : 'editor';
 }
 
+/**
+ *
+ */
 export function createEditorRoutes() {
   /** GET /admin/editors. Owner-only. Returns the allowlist and the acting owner's email. */
   async function editorsLoad(event: RequestContext): Promise<{ editors: Editor[]; self: string }> {

package/src/lib/sveltekit/guard.ts

@@ -102,9 +102,11 @@ export function createAuthGuard() {
   };
 }
 
-/** For a protected load/action: the session the guard already resolved, or a login redirect.
+/**
+ * For a protected load/action: the session the guard already resolved, or a login redirect.
  *  The parameter is the minimal structural need (just `locals`), so every engine event shape
- *  (RequestContext, the content routes' ContentEvent) and a real RequestEvent all satisfy it. */
+ *  (RequestContext, the content routes' ContentEvent) and a real RequestEvent all satisfy it.
+ */
 export function requireSession(event: { locals: { editor?: Editor | null } }): Editor {
   const editor = event.locals.editor;
   if (!editor) throw redirect(303, '/admin/login');

package/src/lib/sveltekit/https-required-page.ts

@@ -9,7 +9,7 @@ import { renderStaticAdminPage } from './static-admin-page.js';
 
 /**
  * Render the full HTML document for the HTTPS-required page.
- * @param httpsUrl The same request rebuilt over https, offered as the one-click recovery link.
+ * @param httpsUrl - The same request rebuilt over https, offered as the one-click recovery link.
  */
 export function httpsRequiredPage(httpsUrl: string): string {
   const href = escapeHtml(httpsUrl);

package/src/lib/sveltekit/index.ts

@@ -11,6 +11,9 @@ export type {
   EntrySummary,
   ListData,
   EditData,
+  AdvisoryNotice,
+  AdvisoryAction,
+  HelpData,
   MediaUsageInfo,
   MediaLibraryData,
   ContentEvent,

package/src/lib/sveltekit/media-route.ts

@@ -17,13 +17,17 @@ import type { ResolvedAssetConfig } from '../media/config.js';
 /** A 16-character lowercase hex content-hash prefix, validated before any R2 lookup. */
 const HASH_RE = /^[0-9a-f]{16}$/;
 
-/** The closed delivery extension allow-list. A filename ext outside this set is a 404 with no R2
- *  read, so the route can never serve a type it cannot vouch for. */
+/**
+ * The closed delivery extension allow-list. A filename ext outside this set is a 404 with no R2
+ *  read, so the route can never serve a type it cannot vouch for.
+ */
 const DELIVERY_EXTS: ReadonlySet<string> = new Set(['jpg', 'jpeg', 'png', 'gif', 'webp', 'avif']);
 
-/** The load-bearing XSS control: set on every non-404 response, so a served object can never run as
+/**
+ * The load-bearing XSS control: set on every non-404 response, so a served object can never run as
  *  active content. `Content-Type` comes from the stored, server-validated metadata via
- *  `writeHttpMetadata`; these override or add to it. */
+ *  `writeHttpMetadata`; these override or add to it.
+ */
 function applySecurityHeaders(headers: Headers, etag: string): void {
   headers.set('X-Content-Type-Options', 'nosniff');
   headers.set('Content-Disposition', 'inline');
@@ -36,8 +40,10 @@ function applySecurityHeaders(headers: Headers, etag: string): void {
   if (!headers.has('Content-Type')) headers.set('Content-Type', 'application/octet-stream');
 }
 
-/** True when the returned object carries a body (a full or ranged read), narrowing it to the body
- *  variant. R2 returns a body-less object on an `If-None-Match` hit. */
+/**
+ * True when the returned object carries a body (a full or ranged read), narrowing it to the body
+ *  variant. R2 returns a body-less object on an `If-None-Match` hit.
+ */
 function hasBody(obj: DeliveryObject | DeliveryObjectBody): obj is DeliveryObjectBody {
   return 'body' in obj && (obj as DeliveryObjectBody).body != null;
 }
@@ -48,8 +54,7 @@ function hasBody(obj: DeliveryObject | DeliveryObjectBody): obj is DeliveryObjec
  * The handler validates the hash and extension before any R2 call, derives the object key from the
  * validated values only (never trusting the URL's fan-out), guards the Cloudflare Images self-loop,
  * and sets the security headers on every served response.
- *
- * @param resolved the adapter's resolved media config; when media is off the handler always 404s.
+ * @param resolved - the adapter's resolved media config; when media is off the handler always 404s.
  */
 export function createMediaRoute(resolved: ResolvedAssetConfig): RequestHandler {
   return async (event) => {

package/src/lib/sveltekit/nav-routes.ts

@@ -29,11 +29,16 @@ export interface NavLoadData {
 
 /** Injectable dependencies; tests stub the token mint to avoid signing a real key. */
 export interface NavRoutesDeps {
-  /** Mint a GitHub App installation token from the Worker env. Defaults to the real signer.
-   *  A bare string works too; the routes await whatever comes back. */
+  /**
+   * Mint a GitHub App installation token from the Worker env. Defaults to the real signer.
+   *  A bare string works too; the routes await whatever comes back.
+   */
   mintToken?: (env: GithubKeyEnv) => string | Promise<string>;
 }
 
+/**
+ *
+ */
 export function createNavRoutes(runtime: CairnRuntime, deps: NavRoutesDeps = {}) {
   const mintToken =
     deps.mintToken ?? ((env: GithubKeyEnv) => cachedInstallationToken(appCredentials(runtime.backend, env)));

package/src/lib/sveltekit/types.ts

@@ -23,9 +23,11 @@ export interface PlatformContext<Env> {
   context?: { waitUntil(promise: Promise<unknown>): void };
 }
 
-/** The structural core every engine event type extends, parameterized by the Worker env the
+/**
+ * The structural core every engine event type extends, parameterized by the Worker env the
  *  surface reads. Each shared field is defined once here; the extensions add only what their
- *  surface needs (cookies, params, setHeaders). */
+ *  surface needs (cookies, params, setHeaders).
+ */
 export interface EventBase<Env> {
   url: URL;
   request: Request;

package/src/lib/vite/index.ts

@@ -10,15 +10,19 @@ import { writeFile, mkdir } from 'node:fs/promises';
 import { dirname, join } from 'node:path';
 import { resolveViteRoot } from './resolve-root.js';
 
-/** The key the cairnManifest plugin stashes its options under, so the write path can read them off the
- *  plugin instance in the consumer's loaded config without re-parsing the config file. */
+/**
+ * The key the cairnManifest plugin stashes its options under, so the write path can read them off the
+ *  plugin instance in the consumer's loaded config without re-parsing the config file.
+ */
 const CAIRN_OPTIONS = Symbol.for('cairn-cms.manifest-options');
 
 /** A cairnManifest plugin instance with its options stashed for the write path to read. */
 type CairnManifestPlugin = Plugin & { [CAIRN_OPTIONS]?: CairnManifestOptions };
 
-/** Options for {@link cairnManifest}. Paths are app-root-absolute (the form `import.meta.glob` wants),
- *  so they match the build's own resolution. */
+/**
+ * Options for {@link cairnManifest}. Paths are app-root-absolute (the form `import.meta.glob` wants),
+ *  so they match the build's own resolution.
+ */
 export interface CairnManifestOptions {
   /** The module exporting the `cairn` adapter and the parsed `siteConfig`, app-root-absolute. */
   configModule: string;
@@ -34,9 +38,11 @@ const RESOLVED_ID = '\0' + VIRTUAL_ID;
 /** The default committed manifest path, app-root-absolute. */
 const DEFAULT_MANIFEST_PATH = '/src/content/.cairn/index.json';
 
-/** Build the virtual module source. In verify mode it throws on drift; in write mode it exports the
+/**
+ * Build the virtual module source. In verify mode it throws on drift; in write mode it exports the
  *  serialized manifest as `result`. The module runs in the app graph, so its `import.meta.glob`,
- *  package, and `?raw` resolution is the build's own. */
+ *  package, and `?raw` resolution is the build's own.
+ */
 function virtualSource(opts: CairnManifestOptions, mode: 'verify' | 'write'): string {
   const manifestPath = opts.manifestPath ?? DEFAULT_MANIFEST_PATH;
   const globEntries = Object.entries(opts.content)
@@ -62,11 +68,13 @@ export const result = ${resultExpr};
 `;
 }
 
-/** Evaluate a virtual module source inside the consumer's own Vite resolution, then return the
+/**
+ * Evaluate a virtual module source inside the consumer's own Vite resolution, then return the
  *  module's `result`. It reuses the consumer's loaded config (so `$lib`, the config module,
  *  `import.meta.glob`, and `?raw` resolve exactly as the build does) and strips the cairnManifest
  *  plugin from the nested server's plugin list, so its buildStart never recurses. This runs at
- *  build time and in the bins, never in the request lifecycle. */
+ *  build time and in the bins, never in the request lifecycle.
+ */
 async function evalVirtual(source: string, root: string): Promise<string> {
   const { createServer, loadConfigFromFile } = await import('vite');
   // Load the consumer's real Vite config so the nested server inherits SvelteKit's resolution
@@ -91,38 +99,48 @@ async function evalVirtual(source: string, root: string): Promise<string> {
   }
 }
 
-/** True for any plugin object whose name is the cairnManifest plugin, so the nested server drops it
+/**
+ * True for any plugin object whose name is the cairnManifest plugin, so the nested server drops it
  *  and cannot recurse into another buildStart. The consumer's plugin list may nest arrays and hold
- *  falsy slots, so guard the shape. */
+ *  falsy slots, so guard the shape.
+ */
 function isCairnManifestPlugin(p: unknown): boolean {
   return !!p && typeof p === 'object' && 'name' in p && (p as { name?: unknown }).name === 'cairn-manifest';
 }
 
-/** Flatten the consumer's plugins option and drop the cairnManifest plugin at any nesting depth, so
+/**
+ * Flatten the consumer's plugins option and drop the cairnManifest plugin at any nesting depth, so
  *  the nested verify server can never re-enter its buildStart. Vite supports (and flattens) nested
  *  plugin arrays, and findCairnOptions recurses into them, so a flat single-level filter would miss a
  *  cairnManifest nested inside a shared preset's sub-array and let it survive into the nested server.
- *  This mirrors findCairnOptions's recursion. Falsy slots pass through, which Vite tolerates. */
+ *  This mirrors findCairnOptions's recursion. Falsy slots pass through, which Vite tolerates.
+ */
 export function stripCairnManifest(plugins: PluginOption | PluginOption[]): PluginOption[] {
   if (Array.isArray(plugins)) return plugins.flatMap(stripCairnManifest);
   if (isCairnManifestPlugin(plugins)) return [];
   return [plugins];
 }
 
-/** Verify the committed manifest against the corpus from a Vite context, throwing on drift. The bin
- *  and the plugin share this; the spike proved it runs cleanly inside the consumer's config. */
+/**
+ * Verify the committed manifest against the corpus from a Vite context, throwing on drift. The bin
+ *  and the plugin share this; the spike proved it runs cleanly inside the consumer's config.
+ */
 export async function verifyManifestFromVite(opts: CairnManifestOptions, root: string): Promise<void> {
   await evalVirtual(virtualSource(opts, 'verify'), root);
 }
 
-/** Regenerate the serialized manifest from the corpus in a Vite context, sharing the build's
- *  resolution. The cairn-manifest bin (a later task) will call this and write the result. */
+/**
+ * Regenerate the serialized manifest from the corpus in a Vite context, sharing the build's
+ *  resolution. The cairn-manifest bin (a later task) will call this and write the result.
+ */
 export async function buildManifestFromVite(opts: CairnManifestOptions, root: string): Promise<string> {
   return evalVirtual(virtualSource(opts, 'write'), root);
 }
 
-/** The cairnManifest plugin. It serves the verify virtual module to the app graph and, in
- *  buildStart, evaluates it through a nested Vite SSR load so a manifest drift fails the build. */
+/**
+ * The cairnManifest plugin. It serves the verify virtual module to the app graph and, in
+ *  buildStart, evaluates it through a nested Vite SSR load so a manifest drift fails the build.
+ */
 export function cairnManifest(opts: CairnManifestOptions): Plugin {
   let root = process.cwd();
   const plugin: CairnManifestPlugin = {
@@ -152,13 +170,15 @@ export function cairnManifest(opts: CairnManifestOptions): Plugin {
   return plugin;
 }
 
-/** Regenerate the committed manifest from the consumer's corpus and write it to the configured
+/**
+ * Regenerate the committed manifest from the consumer's corpus and write it to the configured
  *  manifestPath. It searches for the consumer's Vite config from `cwd`, derives the authoritative
  *  Vite root from the loaded config (so a configured `root` or a non-root cwd resolves correctly),
  *  reads the cairnManifest plugin's options off the instance, evaluates the write-mode virtual
  *  module through the build's own resolution, and writes the serialized manifest under the Vite
  *  root. The cairn-manifest bin calls this; it is exported so the write logic is testable apart
- *  from the CLI shell. */
+ *  from the CLI shell.
+ */
 export async function writeManifest(cwd: string = process.cwd()): Promise<void> {
   const { loadConfigFromFile } = await import('vite');
   const loaded = await loadConfigFromFile({ command: 'build', mode: 'production' }, undefined, cwd);
@@ -181,8 +201,10 @@ export async function writeManifest(cwd: string = process.cwd()): Promise<void>
   await writeFile(outPath, serialized);
 }
 
-/** Walk a Vite plugins option (which may nest arrays, hold falsy slots, or be a thenable) and return
- *  the stashed cairnManifest options from the first matching plugin, or null if there is none. */
+/**
+ * Walk a Vite plugins option (which may nest arrays, hold falsy slots, or be a thenable) and return
+ *  the stashed cairnManifest options from the first matching plugin, or null if there is none.
+ */
 function findCairnOptions(plugins: unknown): CairnManifestOptions | null {
   if (!plugins) return null;
   if (Array.isArray(plugins)) {
@@ -198,8 +220,10 @@ function findCairnOptions(plugins: unknown): CairnManifestOptions | null {
   return null;
 }
 
-/** A minimal plugin that serves only the given virtual module source, for the nested SSR load. It
- *  carries no buildStart, so the nested server never recurses into the verify. */
+/**
+ * A minimal plugin that serves only the given virtual module source, for the nested SSR load. It
+ *  carries no buildStart, so the nested server never recurses into the verify.
+ */
 function cairnVirtualOnly(source: string): Plugin {
   return {
     name: 'cairn-manifest-virtual',
@@ -220,15 +244,19 @@ export interface AdapterFacts {
   repo?: string;
   /** `cairn.sender.from`. */
   from?: string;
-  /** `cairn.assets.bucketBinding`, the media R2 binding name; undefined when the adapter declares no
-   *  assets. The doctor's conditional media-bucket check reads it. */
+  /**
+   * `cairn.assets.bucketBinding`, the media R2 binding name; undefined when the adapter declares no
+   *  assets. The doctor's conditional media-bucket check reads it.
+   */
   mediaBucketBinding?: string;
 }
 
-/** Build the virtual module that reads only the adapter facts the doctor derives. It imports the
+/**
+ * Build the virtual module that reads only the adapter facts the doctor derives. It imports the
  *  configured config module and exports the string-typed `owner`, `repo`, `from`, and the media
  *  `bucketBinding` as JSON, so nothing else of the adapter (least of all a secret) crosses the
- *  boundary. */
+ *  boundary.
+ */
 function adapterFactsSource(opts: CairnManifestOptions): string {
   return `
 import { cairn } from ${JSON.stringify(opts.configModule)};
@@ -244,12 +272,14 @@ export const result = JSON.stringify(facts);
 `;
 }
 
-/** Read `{ owner, repo, from }` off the consumer's adapter by evaluating a tiny virtual module
+/**
+ * Read `{ owner, repo, from }` off the consumer's adapter by evaluating a tiny virtual module
  *  through the consumer's own Vite resolution, the same machinery the cairn-manifest bin uses.
  *  cairn-doctor calls this to fill inputs the operator did not pass. Derivation is best-effort:
  *  any failure (no Vite config, no cairnManifest plugin, a config module that throws) returns
  *  null, so the doctor degrades to flags instead of crashing. This runs only on the bin path,
- *  never in a Worker. */
+ *  never in a Worker.
+ */
 export async function readAdapterFacts(cwd: string = process.cwd()): Promise<AdapterFacts | null> {
   try {
     const { loadConfigFromFile } = await import('vite');

package/src/lib/vite/resolve-root.ts

@@ -2,8 +2,10 @@
 // /vite surface (only src/lib/vite/index.ts is the package subpath; this sibling is internal).
 import { dirname, isAbsolute, resolve } from 'node:path';
 
-/** The shape of `loadConfigFromFile`'s result that the root derivation reads: the config file's own
- *  path and its `root` field. Typed structurally so the helper is testable without a real load. */
+/**
+ * The shape of `loadConfigFromFile`'s result that the root derivation reads: the config file's own
+ *  path and its `root` field. Typed structurally so the helper is testable without a real load.
+ */
 export interface LoadedViteConfig {
   /** The resolved path of the config file Vite loaded. */
   path: string;
@@ -11,11 +13,13 @@ export interface LoadedViteConfig {
   config: { root?: string };
 }
 
-/** The authoritative Vite root for the manifest bin, derived from the loaded config the way Vite
+/**
+ * The authoritative Vite root for the manifest bin, derived from the loaded config the way Vite
  *  resolves a relative `root`: against the config file's own directory, not cwd. An absolute `root`
  *  stands as given, and no `root` falls back to `cwd` (the directory the bin was run from). This
  *  separates the config-search dir (cwd) from the Vite root, so a non-root cwd or a config that
- *  sets `root` reads and writes the manifest under the real app root. */
+ *  sets `root` reads and writes the manifest under the real app root.
+ */
 export function resolveViteRoot(loaded: LoadedViteConfig, cwd: string): string {
   const root = loaded.config.root;
   if (!root) return cwd;