@glw907/cairn-cms 0.60.0 → 0.62.1

package/src/lib/render/resolve-media.ts

@@ -15,18 +15,22 @@ import { log } from '../log/index.js';
 /** The VFile data key the renderer sets the per-call media resolver under. */
 export const MEDIA_RESOLVE = 'mediaResolve';
 
-/** Resolve a media reference to its delivery URL. `undefined` is a preview miss (the plugin marks
+/**
+ * Resolve a media reference to its delivery URL. `undefined` is a preview miss (the plugin marks
  *  the image broken); a resolver that throws is the build backstop (the error propagates out of
- *  render and fails the build), exactly like LinkResolve. */
+ *  render and fails the build), exactly like LinkResolve.
+ */
 export type MediaResolve = (ref: MediaRef) => string | undefined;
 
-/** Build the per-call media resolver, closing over the manifest and the resolved config. The
+/**
+ * Build the per-call media resolver, closing over the manifest and the resolved config. The
  *  returned resolver looks a ref's content hash up in the manifest and builds the canonical delivery
  *  path from the manifest entry's slug and ext, not the token's, so a rename never breaks the
  *  reference. With a preset and zone transformations on it returns the variant URL; without a preset,
  *  or when transformations are off, it returns the bare full-size path so a fresh zone with Image
  *  Transformations disabled serves correct thumbnails rather than dead /cdn-cgi/image URLs. It returns
- *  undefined when media is off or no entry carries the hash (the preview-miss backstop). */
+ *  undefined when media is off or no entry carries the hash (the preview-miss backstop).
+ */
 export function makeMediaResolver(
   manifest: MediaManifest,
   resolved: ResolvedAssetConfig,
@@ -49,11 +53,13 @@ export function makeMediaResolver(
   };
 }
 
-/** A resolver backed by the lean `mediaTargets` projection, for the admin preview. It mirrors
+/**
+ * A resolver backed by the lean `mediaTargets` projection, for the admin preview. It mirrors
  *  manifestLinkResolver: a hash present in the projection builds the slug delivery path
  *  (`/media/<slug>.<hash>.<ext>`); a miss returns undefined, so the render step marks the image
  *  broken rather than throwing. Pure over the projection, with no manifest and no config, so the
- *  edit page reaches it with the data it actually has. */
+ *  edit page reaches it with the data it actually has.
+ */
 export function manifestMediaResolver(
   targets: Record<string, { slug: string; ext: string; contentType: string }>,
 ): MediaResolve {
@@ -69,9 +75,11 @@ interface ImageNode {
   data?: { hProperties?: Record<string, unknown> };
 }
 
-/** Resolve media: image nodes against the VFile's resolver. A non-media src and a malformed token
+/**
+ * Resolve media: image nodes against the VFile's resolver. A non-media src and a malformed token
  *  pass through. A missing target is marked with the cairn-broken-media class (the resolver returns
- *  undefined) or, when the resolver throws, the error propagates and fails the build. */
+ *  undefined) or, when the resolver throws, the error propagates and fails the build.
+ */
 export function remarkResolveMedia() {
   return (tree: unknown, file: VFile): void => {
     const resolve = file.data[MEDIA_RESOLVE] as MediaResolve | undefined;

package/src/lib/sveltekit/admin-dispatch.ts

@@ -17,15 +17,18 @@ export type AdminView =
   | { view: 'editors' }
   | { view: 'nav' }
   | { view: 'media' }
-  | { view: 'settings' };
+  | { view: 'settings' }
+  | { view: 'help' };
 
 /**
  * Fixed first segments that never resolve as concepts. The engine only allows posts and pages
  * today, so no collision is possible, but the parser does not depend on that: a reserved
- * segment wins before concept lookup. `settings`, `nav`, and `media` are decided as views below,
- * so they are not in this no-view set.
+ * segment wins before concept lookup. `nav` and `media` are decided as views below, so they are
+ * not in this no-view set. `settings` and `help` are decided as views below AND kept here, so a
+ * deeper path (or a future concept claiming the segment) can never reach the two-segment edit
+ * branch through them.
  */
-const RESERVED_SEGMENTS = new Set(['login', 'auth', 'editors', 'nav', 'settings']);
+const RESERVED_SEGMENTS = new Set(['login', 'auth', 'editors', 'nav', 'settings', 'help']);
 
 /**
  * Parse a raw `URL.pathname` (the caller passes `event.url.pathname`, never a SvelteKit rest
@@ -66,6 +69,9 @@ export function parseAdminPath(
     // settings is its own view, a peer of editors and nav. /admin/settings/<anything> 404s naturally
     // (the two-segment branch never matches settings), which is the correct shape.
     if (head === 'settings') return { view: 'settings' };
+    // help is its own view (the Help home, editor-help Pass 2), decided here like settings. It is
+    // also in the reserved set so /admin/help/<anything> 404s and no concept can claim the segment.
+    if (head === 'help') return { view: 'help' };
     if (RESERVED_SEGMENTS.has(head)) return null;
     const concept = findConcept(concepts, head);
     return concept ? { view: 'list', concept } : null;

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

@@ -45,6 +45,9 @@ function scrubSendError(err: unknown): string {
     .slice(0, 300);
 }
 
+/**
+ *
+ */
 export function createAuthRoutes(config: AuthRoutesConfig) {
   const send = config.send ?? cloudflareSend;
 

package/src/lib/sveltekit/cairn-admin.ts

@@ -16,6 +16,7 @@ import {
   type EditData,
   type MediaLibraryData,
   type SettingsData,
+  type HelpData,
 } from './content-routes.js';
 import { createEditorRoutes } from './editors-routes.js';
 import { createNavRoutes, type NavLoadData } from './nav-routes.js';
@@ -35,15 +36,19 @@ export interface AdminEvent extends EventBase<GithubKeyEnv & AuthEnv> {
   setHeaders(headers: Record<string, string>): void;
 }
 
-/** Injectable dependencies. Branding defaults from the runtime's siteName and sender, so a
+/**
+ * Injectable dependencies. Branding defaults from the runtime's siteName and sender, so a
  *  site overrides it only to change the magic-link email identity; `send` and `mintToken`
- *  are the same seams the underlying factories take. */
+ *  are the same seams the underlying factories take.
+ */
 export interface CairnAdminDeps {
   branding?: AuthBranding;
   send?: SendMagicLink;
   mintToken?: ContentRoutesDeps['mintToken'];
-  /** Build the Anthropic client for the tidy action. Forwarded to the content routes; a site that
-   *  enables tidy injects a stub here to avoid a real network call. Defaults to the real SDK client. */
+  /**
+   * Build the Anthropic client for the tidy action. Forwarded to the content routes; a site that
+   *  enables tidy injects a stub here to avoid a real network call. Defaults to the real SDK client.
+   */
   anthropic?: ContentRoutesDeps['anthropic'];
   /** The tidy action's own request deadline in milliseconds. Forwarded to the content routes. */
   tidyTimeoutMs?: ContentRoutesDeps['tidyTimeoutMs'];
@@ -62,8 +67,12 @@ export type AdminData =
   | { view: 'editors'; layout: LayoutData; page: { editors: Editor[]; self: string } }
   | { view: 'nav'; layout: LayoutData; page: NavLoadData }
   | { view: 'media'; layout: LayoutData; page: MediaLibraryData }
-  | { view: 'settings'; layout: LayoutData; page: SettingsData };
+  | { view: 'settings'; layout: LayoutData; page: SettingsData }
+  | { view: 'help'; layout: LayoutData; page: HelpData };
 
+/**
+ *
+ */
 export function createCairnAdmin(runtime: CairnRuntime, deps: CairnAdminDeps = {}) {
   // The runtime already composes the site name and the sender identity, so the magic-link
   // branding needs no second copy of either unless a site overrides it.
@@ -82,11 +91,13 @@ export function createCairnAdmin(runtime: CairnRuntime, deps: CairnAdminDeps = {
   // The nav surface exists only when the site configures a menu; without one its view is a 404.
   const nav = runtime.navMenu ? createNavRoutes(runtime, { mintToken: deps.mintToken }) : null;
 
-  /** Build the event a wrapped content load reads. The catch-all route carries only a rest
+  /**
+   * Build the event a wrapped content load reads. The catch-all route carries only a rest
    *  param, so `concept` and `id` are synthesized from the parsed view. The override names
    *  each field explicitly rather than spreading: a real RequestEvent's fields can sit behind
    *  getters a bare spread copies poorly, and the structural ContentEvent contract needs only
-   *  these. */
+   *  these.
+   */
   function contentEvent(event: AdminEvent, params: Record<string, string>): ContentEvent {
     return {
       url: event.url,
@@ -98,9 +109,11 @@ export function createCairnAdmin(runtime: CairnRuntime, deps: CairnAdminDeps = {
     };
   }
 
-  /** Serve the admin view the pathname names, or a 404 for any shape the parser refuses.
+  /**
+   * Serve the admin view the pathname names, or a 404 for any shape the parser refuses.
    *  The authed views run the layout load and the view load concurrently; both mint a GitHub
-   *  token, and the installation-token cache coalesces the mints into one signing. */
+   *  token, and the installation-token cache coalesces the mints into one signing.
+   */
   async function load(event: AdminEvent): Promise<AdminData> {
     const view = parseAdminPath(event.url.pathname, runtime.concepts);
     if (!view) throw error(404, 'Not found');
@@ -145,12 +158,19 @@ export function createCairnAdmin(runtime: CairnRuntime, deps: CairnAdminDeps = {
         const [layout, page] = await Promise.all([content.layoutLoad(delegated), content.settingsLoad(delegated)]);
         return { view: 'settings', layout, page };
       }
+      case 'help': {
+        const delegated = contentEvent(event, {});
+        const [layout, page] = await Promise.all([content.layoutLoad(delegated), content.helpLoad(delegated)]);
+        return { view: 'help', layout, page };
+      }
     }
   }
 
-  /** Wrap a delegate in the parse-and-check every action shares: parse the pathname exactly
+  /**
+   * Wrap a delegate in the parse-and-check every action shares: parse the pathname exactly
    *  as load does, 404 on a null parse or a view outside the allowed set, then hand the
-   *  narrowed view to the delegate. */
+   *  narrowed view to the delegate.
+   */
   function viewAction<V extends AdminView['view'], R>(
     allowed: readonly V[],
     delegate: (event: AdminEvent, view: Extract<AdminView, { view: V }>) => Promise<R>,
@@ -164,14 +184,16 @@ export function createCairnAdmin(runtime: CairnRuntime, deps: CairnAdminDeps = {
   }
 
   // The topbar posts publishAll from every authed admin page; login and confirm may not.
-  const authedViews = ['list', 'edit', 'editors', 'nav', 'media', 'settings'] as const;
+  const authedViews = ['list', 'edit', 'editors', 'nav', 'media', 'settings', 'help'] as const;
   // An editor signs out from wherever they are, so logout accepts any parsed view.
-  const anyView = ['index', 'login', 'confirm', 'list', 'edit', 'editors', 'nav', 'media', 'settings'] as const;
+  const anyView = ['index', 'login', 'confirm', 'list', 'edit', 'editors', 'nav', 'media', 'settings', 'help'] as const;
 
-  /** The full admin action vocabulary, one named async function per action, so a site's
+  /**
+   * The full admin action vocabulary, one named async function per action, so a site's
    *  catch-all route exports `admin.actions` directly. Each wrapper stays thin: parse,
    *  validate the view, synthesize the params the wrapped action reads, delegate. The
-   *  editor actions gate themselves with requireOwner, so no second gate is added here. */
+   *  editor actions gate themselves with requireOwner, so no second gate is added here.
+   */
   const actions = {
     request: viewAction(['login'], (event) => auth.requestAction(event)),
     confirm: viewAction(['confirm'], (event) => auth.confirmAction(event)),