@micacms/runtime 0.5.0 → 0.6.0-rc.1

package/src/routes/admin-content.ts

@@ -0,0 +1,197 @@
+/**
+ * Admin routes for entries and singletons. The content store holds every rule;
+ * these routes only parse and serialize. The API path is the repository path,
+ * Git is the history, and `revision` makes concurrent edits safe.
+ */
+
+import { ReadOnlyError, ValidationError } from "../services/content-store.js";
+import { ConflictError } from "../workspace/files.js";
+import { collectionEntryPath, compareEntries, entryTitle, LayoutError, singletonPath } from "@micacms/core";
+import { Hono } from "hono";
+import { z } from "zod";
+
+import { ApiError, badRequest, notFound } from "../lib/errors.js";
+import type { Env } from "../http.js";
+
+const saveSchema = z.object({
+  data: z.record(z.string(), z.unknown()),
+  slug: z.string().max(120).optional(),
+  /**
+   * The revision the editor opened. `null` asserts that the entry does not
+   * exist, so two parallel creates cannot overwrite.
+   */
+  revision: z.string().nullable().optional(),
+});
+
+const reorderSchema = z.object({ slugs: z.array(z.string().min(1)).max(2000) });
+
+async function jsonBody(c: { req: { json(): Promise<unknown> } }): Promise<unknown> {
+  return c.req.json().catch(() => {
+    throw badRequest("The request body must be valid JSON.");
+  });
+}
+
+/** Maps a conflict to 409 and a validation failure to 422; other errors go to the error handler. */
+async function handled<T>(run: () => Promise<T>): Promise<T> {
+  try {
+    return await run();
+  } catch (error) {
+    if (error instanceof ConflictError || error instanceof ReadOnlyError || error instanceof LayoutError) {
+      throw new ApiError("conflict", error.message);
+    }
+    if (error instanceof ValidationError) {
+      throw new ApiError("validation_failed", error.message, { issues: error.issues });
+    }
+    throw error;
+  }
+}
+
+export function adminContentRoutes(): Hono<Env> {
+  const app = new Hono<Env>();
+
+  app.get("/collections/:collection/entries", async (c) => {
+    const { content } = c.get("ctx").services;
+    const collection = c.req.param("collection");
+    const def = content.requireCollection(collection);
+
+    const entries = await handled(() => content.list(collection));
+    const search = c.req.query("search")?.trim().toLowerCase();
+
+    const items = entries
+      .map((entry) => ({
+        slug: entry.slug,
+        position: entry.position,
+        title: entryTitle(def, entry.data),
+        data: entry.data,
+      }))
+      // Content trees are small, so an in-memory substring match is sufficient.
+      .filter((item) => !search || JSON.stringify(item.data).toLowerCase().includes(search))
+      .sort(compareEntries(def));
+
+    return c.json({ items, total: items.length });
+  });
+
+  app.post("/collections/:collection/entries", async (c) => {
+    const { content } = c.get("ctx").services;
+    const parsed = saveSchema.safeParse(await jsonBody(c));
+    if (!parsed.success) throw badRequest("The entry payload is malformed.");
+
+    const saved = await handled(() =>
+      content.save(c.req.param("collection"), {
+        data: parsed.data.data,
+        expectedRevision: parsed.data.revision ?? null,
+      }),
+    );
+
+    return c.json(saved, 201);
+  });
+
+  app.post("/collections/:collection/reorder", async (c) => {
+    const { content } = c.get("ctx").services;
+    const parsed = reorderSchema.safeParse(await jsonBody(c));
+    if (!parsed.success) throw badRequest("Expected a list of entry slugs.");
+
+    await handled(() => content.reorder(c.req.param("collection"), parsed.data.slugs));
+    return c.json({ ok: true });
+  });
+
+  /** Server-side slug generation, so the URL preview matches what is saved. */
+  app.get("/collections/:collection/slug", async (c) => {
+    const { content } = c.get("ctx").services;
+    const source = c.req.query("source") ?? "";
+    if (!source.trim()) return c.json({ slug: "" });
+
+    return c.json({
+      slug: await handled(() =>
+        content.suggestSlug(c.req.param("collection"), source, c.req.query("except")),
+      ),
+    });
+  });
+
+  app.get("/collections/:collection/entries/:slug", async (c) => {
+    const { content } = c.get("ctx").services;
+    const collection = c.req.param("collection");
+    const slug = c.req.param("slug");
+
+    const entry = await handled(() => content.get(collection, slug));
+    if (!entry) throw notFound("This entry no longer exists.");
+
+    const def = content.requireCollection(collection);
+
+    return c.json({
+      collection,
+      slug: entry.slug,
+      position: entry.position,
+      title: entryTitle(def, entry.data),
+      data: entry.data,
+      // From the model, so the editor need not know when an entry is a directory.
+      path: collectionEntryPath(def.fields, collection, entry.slug),
+      revision: await content.revisionOf(collection, slug),
+    });
+  });
+
+  app.put("/collections/:collection/entries/:slug", async (c) => {
+    const { content } = c.get("ctx").services;
+    const parsed = saveSchema.safeParse(await jsonBody(c));
+    if (!parsed.success) throw badRequest("The entry payload is malformed.");
+
+    const saved = await handled(() =>
+      content.save(c.req.param("collection"), {
+        data: parsed.data.data,
+        slug: c.req.param("slug"),
+        expectedRevision: parsed.data.revision,
+      }),
+    );
+
+    return c.json(saved);
+  });
+
+  app.delete("/collections/:collection/entries/:slug", async (c) => {
+    const { content } = c.get("ctx").services;
+
+    await handled(() =>
+      content.remove(c.req.param("collection"), c.req.param("slug")),
+    );
+
+    return c.json({ ok: true });
+  });
+
+  /** Entries elsewhere that point at this one — shown before a delete. */
+  app.get("/collections/:collection/entries/:slug/references", async (c) => {
+    const { content } = c.get("ctx").services;
+    const references = await handled(() =>
+      content.findReferences(c.req.param("collection"), c.req.param("slug")),
+    );
+
+    return c.json({ references });
+  });
+
+  app.get("/singletons/:name", async (c) => {
+    const { content } = c.get("ctx").services;
+    const name = c.req.param("name");
+    const def = content.requireSingleton(name);
+
+    return c.json({
+      name,
+      label: def.label,
+      path: singletonPath(def.fields, name),
+      data: await handled(() => content.getSingleton(name)),
+      revision: await content.revisionOfSingleton(name),
+    });
+  });
+
+  app.put("/singletons/:name", async (c) => {
+    const { content } = c.get("ctx").services;
+    const body = (await jsonBody(c)) as { data?: unknown; revision?: string | null };
+
+    const saved = await handled(() =>
+      content.saveSingleton(c.req.param("name"), body?.data ?? {}, {
+        expectedRevision: body?.revision,
+      }),
+    );
+
+    return c.json(saved);
+  });
+
+  return app;
+}

package/src/routes/admin-media.ts

@@ -0,0 +1,96 @@
+/**
+ * Admin media routes. Media is files in the content repository, and there is no delete endpoint.
+ * An upload is written on its own, before the entry save, because the editor needs its path first.
+ */
+
+import { Hono } from "hono";
+
+import { ApiError, badRequest, notFound } from "../lib/errors.js";
+import { isImageType } from "../lib/file-type.js";
+import { MAX_FILES_PER_UPLOAD } from "../middleware/index.js";
+import type { Env } from "../http.js";
+
+export function adminMediaRoutes(): Hono<Env> {
+  const app = new Hono<Env>();
+
+  app.get("/", async (c) => {
+    const { media } = c.get("ctx").services;
+    return c.json({ items: await media.list() });
+  });
+
+  app.post("/", async (c) => {
+    const ctx = c.get("ctx");
+    const form = await c.req.formData().catch(() => {
+      throw badRequest("Expected a multipart upload.");
+    });
+
+    // The cast picks one of the two structurally different `File` types (Node's and undici's).
+    const files = form
+      .getAll("file")
+      .filter((value) => typeof value !== "string") as unknown as File[];
+
+    if (files.length === 0) throw badRequest("No file was uploaded.");
+    if (files.length > MAX_FILES_PER_UPLOAD) {
+      throw badRequest(`Upload at most ${MAX_FILES_PER_UPLOAD} files at a time.`);
+    }
+
+    const accept = form.get("accept");
+    // An entry's own `media/` directory or the shared one; the media service refuses anything else.
+    const directory = typeof form.get("directory") === "string" ? String(form.get("directory")) : undefined;
+    // The media service accepts `/gallery/x/media` too; take the owner from the path it will write to.
+    const owner = (directory ?? "").replace(/^[/\\]+/, "").split(/[/\\]/)[0] ?? "";
+    const readOnly = ctx.site.readOnly.get(`collections.${owner}`) ?? ctx.site.readOnly.get(`singletons.${owner}`);
+    if (readOnly) throw new ApiError("conflict", readOnly);
+
+    const prepared = await Promise.all(
+      files.map((file) =>
+        ctx.services.media.prepare({
+          file,
+          directory,
+          accept: accept === "image" || accept === "document" ? accept : "any",
+        }),
+      ),
+    );
+
+    await ctx.site.contentRepository.apply({
+      changes: prepared.map((item) => ({
+        type: "write" as const,
+        path: item.file.path,
+        contents: item.contents,
+      })),
+    });
+
+    return c.json({ items: prepared.map((item) => item.file) }, 201);
+  });
+
+  /**
+   * Serves a file to the editor, behind the admin gate. The site build reads
+   * the repository, not this route.
+   */
+  app.get("/file/*", async (c) => {
+    const { media } = c.get("ctx").services;
+    const mediaPath = c.req.path.replace(/^.*\/file\//, "");
+
+    let decoded: string;
+    try {
+      decoded = decodeURIComponent(mediaPath);
+    } catch {
+      throw badRequest("The file path is not valid.");
+    }
+
+    const found = await media.read(decoded);
+    if (!found) throw notFound("No such file.");
+
+    return c.body(found.bytes as unknown as ArrayBuffer, 200, {
+      // Text without a charset is decoded by guessing; the repository's text is UTF-8.
+      "content-type": found.mimeType.startsWith("text/") ? `${found.mimeType}; charset=utf-8` : found.mimeType,
+      "cache-control": "private, max-age=60",
+      // A file opened directly runs nothing and reaches nothing on this origin.
+      "content-security-policy": "sandbox; default-src 'none'",
+      // An image is shown as a preview; anything else is downloaded, never rendered here.
+      ...(isImageType(found.mimeType) ? {} : { "content-disposition": "attachment" }),
+    });
+  });
+
+  return app;
+}

package/src/routes/admin-spa.ts

@@ -0,0 +1,82 @@
+/**
+ * Serves the built administration SPA.
+ *
+ * Small enough to do directly rather than pull in a static-file middleware,
+ * and doing it here means the caching rules are explicit: hashed asset files
+ * are immutable, `index.html` never is — otherwise a deploy leaves editors on
+ * a stale bundle pointing at assets that no longer exist.
+ */
+
+import fs from "node:fs";
+import fsp from "node:fs/promises";
+import path from "node:path";
+import { Readable } from "node:stream";
+
+import { Hono, type Context } from "hono";
+
+import type { Env } from "../http.js";
+
+const CONTENT_TYPES: Record<string, string> = {
+  ".html": "text/html; charset=utf-8",
+  ".js": "text/javascript; charset=utf-8",
+  ".css": "text/css; charset=utf-8",
+  ".json": "application/json; charset=utf-8",
+  ".svg": "image/svg+xml",
+  ".png": "image/png",
+  ".jpg": "image/jpeg",
+  ".webp": "image/webp",
+  ".ico": "image/x-icon",
+  ".woff2": "font/woff2",
+  ".woff": "font/woff",
+  ".map": "application/json; charset=utf-8",
+};
+
+export function adminAssetsExist(directory: string): boolean {
+  return fs.existsSync(path.join(directory, "index.html"));
+}
+
+export function adminSpaRoutes(directory: string): Hono<Env> {
+  const app = new Hono<Env>();
+  const root = path.resolve(directory);
+
+  const send = async (c: Context<Env>, filePath: string, immutable: boolean) => {
+    const stat = await fsp.stat(filePath);
+    const extension = path.extname(filePath).toLowerCase();
+
+    return c.body(Readable.toWeb(fs.createReadStream(filePath)) as ReadableStream<Uint8Array>, 200, {
+      "content-type": CONTENT_TYPES[extension] ?? "application/octet-stream",
+      "content-length": String(stat.size),
+      "cache-control": immutable
+        ? "public, max-age=31536000, immutable"
+        : "no-cache, must-revalidate",
+    });
+  };
+
+  app.get("/*", async (c) => {
+    const url = new URL(c.req.url);
+    const relative = decodeURIComponent(url.pathname.replace(/^\/admin\/?/, ""));
+    const target = path.join(root, relative);
+
+    // Never serve outside the build directory, whatever the path contains.
+    if (relative && !path.relative(root, target).startsWith("..")) {
+      try {
+        const stat = await fsp.stat(target);
+        if (stat.isFile()) {
+          // Vite emits hashed filenames under /assets, so those are immutable.
+          return await send(c, target, relative.startsWith("assets/"));
+        }
+      } catch {
+        // Fall through to the SPA entry point.
+      }
+    }
+
+    // Any other path belongs to the client-side router.
+    try {
+      return await send(c, path.join(root, "index.html"), false);
+    } catch {
+      return c.text("The admin interface has not been built. Run `rush build`.", 503);
+    }
+  });
+
+  return app;
+}

package/src/routes/admin-staging.ts

@@ -0,0 +1,126 @@
+/**
+ * Admin routes for the pending changes and Publish. Sync and conflict
+ * resolution exist only for a clone that Mica keeps. `committed-pending-push`
+ * is a 200: the commit is real, and an error status would tell the editor that
+ * nothing happened.
+ */
+
+import { Hono } from "hono";
+import { z } from "zod";
+
+import { actorOf, type Env } from "../http.js";
+import { ApiError, badRequest } from "../lib/errors.js";
+import { ConflictError } from "../workspace/files.js";
+
+const publishSchema = z.object({
+  message: z.string().max(500),
+  /** The reviewed paths, with the revision each had in the review. */
+  paths: z.record(z.string().min(1), z.string().nullable()),
+});
+
+const resolveSchema = z.object({
+  group: z.string().min(1),
+  choice: z.enum(["mine", "website"]),
+});
+
+const discardSchema = z.object({ paths: z.array(z.string().min(1)).min(1).max(2000) });
+
+const compareSchema = z.discriminatedUnion("kind", [
+  z.object({
+    kind: z.literal("entry"),
+    collection: z.string().min(1),
+    slug: z.string().min(1),
+    from: z.string().min(1).optional(),
+  }),
+  z.object({ kind: z.literal("singleton"), name: z.string().min(1) }),
+  z.object({ kind: z.literal("order"), collection: z.string().min(1) }),
+]);
+
+async function jsonBody(c: { req: { json(): Promise<unknown> } }): Promise<unknown> {
+  return c.req.json().catch(() => {
+    throw badRequest("The request body must be valid JSON.");
+  });
+}
+
+/** A repository conflict is 409 and recoverable — refresh, review, retry. */
+async function handled<T>(run: () => Promise<T>): Promise<T> {
+  try {
+    return await run();
+  } catch (error) {
+    if (error instanceof ConflictError) throw new ApiError("conflict", error.message);
+    throw error;
+  }
+}
+
+export function adminStagingRoutes(): Hono<Env> {
+  const app = new Hono<Env>();
+
+  app.get("/changes", async (c) => {
+    const { staging } = c.get("ctx").services;
+    return c.json(await staging.status());
+  });
+
+  // Raw data before and after one pending change; the editor renders the comparison.
+  app.get("/changes/compare", async (c) => {
+    const { staging } = c.get("ctx").services;
+    const parsed = compareSchema.safeParse({
+      kind: c.req.query("kind"),
+      collection: c.req.query("collection"),
+      slug: c.req.query("slug"),
+      from: c.req.query("from"),
+      name: c.req.query("name"),
+    });
+    if (!parsed.success) throw badRequest("The compare target is malformed.");
+    const against = c.req.query("against") === "origin" ? "origin" : "head";
+
+    return c.json(await staging.compare(parsed.data, against));
+  });
+
+  app.post("/publish", async (c) => {
+    const { staging } = c.get("ctx").services;
+    const parsed = publishSchema.safeParse(await jsonBody(c));
+    if (!parsed.success) throw badRequest("The publish payload is malformed.");
+
+    const actor = actorOf(c);
+    const result = await handled(() =>
+      staging.publish({
+        message: parsed.data.message,
+        paths: parsed.data.paths,
+        author: actor ? { name: actor.name || actor.email, email: actor.email } : undefined,
+      }),
+    );
+
+    return c.json(result);
+  });
+
+  app.post("/publish/push", async (c) => {
+    const { staging } = c.get("ctx").services;
+    return c.json(await handled(() => staging.push()));
+  });
+
+  // "Try again" after a sync error.
+  app.post("/sync", async (c) => {
+    const { staging } = c.get("ctx").services;
+    await staging.sync();
+    return c.json(await staging.status());
+  });
+
+  app.post("/changes/resolve", async (c) => {
+    const { staging } = c.get("ctx").services;
+    const parsed = resolveSchema.safeParse(await jsonBody(c));
+    if (!parsed.success) throw badRequest("Expected a group and a choice: mine or website.");
+
+    await handled(() => staging.resolve(parsed.data.group, parsed.data.choice));
+    return c.json(await staging.status());
+  });
+
+  app.post("/changes/discard", async (c) => {
+    const { staging } = c.get("ctx").services;
+    const parsed = discardSchema.safeParse(await jsonBody(c));
+    if (!parsed.success) throw badRequest("Expected a list of change paths.");
+
+    return c.json(await handled(() => staging.discard(parsed.data.paths)));
+  });
+
+  return app;
+}

package/src/routes/admin-system.ts

@@ -0,0 +1,146 @@
+/**
+ * Schema, dashboard and system information. The SPA knows no collection; it
+ * renders what `/schema` returns.
+ */
+
+import { Hono } from "hono";
+
+import { listedFields, resolveSlugField, resolveTitleField } from "@micacms/core";
+
+import type { Env } from "../http.js";
+import { schemaStats } from "../lib/schema-stats.js";
+import { schemaOrigin } from "../schema.js";
+import { VERSION } from "../lib/version.js";
+import { formatBytes } from "../services/media.js";
+
+export function adminSystemRoutes(): Hono<Env> {
+  const app = new Hono<Env>();
+
+  /** The content model, plus the derived values that the UI would otherwise recompute. */
+  app.get("/schema", (c) => {
+    const { site } = c.get("ctx");
+
+    return c.json({
+      collections: Object.values(site.model.collections).map((def) => ({
+        name: def.name,
+        label: def.label,
+        labelSingular: def.labelSingular ?? def.label,
+        description: def.description ?? null,
+        sortable: def.sortable ?? false,
+        defaultSort: def.defaultSort ?? null,
+        titleField: resolveTitleField(def),
+        slugField: resolveSlugField(def),
+        listedFields: listedFields(def),
+        fields: def.fields,
+        readOnly: site.readOnly.get(`collections.${def.name}`) ?? null,
+      })),
+      singletons: Object.values(site.model.singletons).map((def) => ({
+        name: def.name,
+        label: def.label,
+        description: def.description ?? null,
+        fields: def.fields,
+        readOnly: site.readOnly.get(`singletons.${def.name}`) ?? null,
+      })),
+    });
+  });
+
+  app.get("/overview", async (c) => {
+    const ctx = c.get("ctx");
+    const { content, media } = ctx.services;
+
+    const collections = await Promise.all(
+      Object.values(ctx.site.model.collections).map(async (def) => ({
+        name: def.name,
+        label: def.label,
+        total: (await content.list(def.name)).length,
+      })),
+    );
+
+    const files = await media.list();
+
+    return c.json({
+      collections,
+      media: {
+        files: files.length,
+        bytes: files.reduce((sum, file) => sum + file.size, 0),
+        readable: formatBytes(files.reduce((sum, file) => sum + file.size, 0)),
+      },
+      repository: ctx.site.contentRepository.origin,
+    });
+  });
+
+  /**
+   * What this deployment is and serves. Every admitted editor sees it, because
+   * there is no administrator role. It never returns a secret value.
+   */
+  app.get("/system", async (c) => {
+    const ctx = c.get("ctx");
+    const { config } = ctx;
+
+    const stats = schemaStats(ctx.site.model);
+
+    const counts = Object.fromEntries(
+      await Promise.all(
+        Object.values(ctx.site.model.collections).map(
+          async (def) => [def.name, (await ctx.services.content.list(def.name)).length] as const,
+        ),
+      ),
+    );
+
+    const files = await ctx.services.media.list();
+    const mediaBytes = files.reduce((sum, file) => sum + file.size, 0);
+
+    const uptimeSeconds = Math.floor(process.uptime());
+
+    const operational = ctx.operational();
+    const repository = await ctx.services.staging.repository();
+
+    return c.json({
+      cms: {
+        version: VERSION,
+        environment: config.NODE_ENV,
+        node: process.version,
+        platform: `${process.platform}/${process.arch}`,
+        startedAt: new Date(Date.now() - uptimeSeconds * 1000).toISOString(),
+        uptimeSeconds,
+      },
+      schema: {
+        totals: stats.totals,
+        kinds: stats.kinds,
+        relations: stats.relations,
+        collections: stats.collections.map((item) => ({
+          ...item,
+          entries: counts[item.name] ?? 0,
+        })),
+        singletons: stats.singletons,
+      },
+      repository: {
+        origin: ctx.site.contentRepository.origin,
+        entries: Object.values(counts).reduce((sum, count) => sum + count, 0),
+        media: { files: files.length, bytes: mediaBytes, readable: formatBytes(mediaBytes) },
+        ...repository,
+      },
+      deployment: {
+        site: ctx.site.id,
+        baseUrl: config.MICA_PUBLIC_URL,
+        schemaOrigin: schemaOrigin(ctx.site.contentRepository),
+        // A clone that Mica keeps names its remote in `repository.url` instead.
+        contentRoot: repository.owner === "developer" ? config.contentRoot : null,
+        dataDir: operational.dataDir ?? null,
+        logLevel: config.MICA_LOG_LEVEL,
+        maxUploadBytes: config.MICA_MAX_UPLOAD_BYTES,
+        maxUploadReadable: formatBytes(config.MICA_MAX_UPLOAD_BYTES),
+        sessionTtlHours: operational.sessionTtlHours ?? null,
+        sessionIdleHours: operational.sessionIdleHours ?? null,
+        auth: operational.auth,
+        admission: operational.admission ?? null,
+        trustProxy: config.MICA_TRUST_PROXY,
+        adminOrigins: config.adminOrigins,
+        generatedSecrets: operational.generatedSecrets ?? [],
+        memoryBytes: process.memoryUsage().rss,
+      },
+    });
+  });
+
+  return app;
+}