@micacms/runtime 0.5.0-rc.2 → 0.6.0-rc.1

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;
+}

package/src/routes/health.ts

@@ -0,0 +1,67 @@
+/**
+ * `/health` does no I/O, so a repository outage does not restart the container.
+ * `/ready` checks the content repository and is cached because it is public.
+ * Neither names the repository or the uptime.
+ */
+
+import { Hono, type Context } from "hono";
+
+import type { Env } from "../http.js";
+
+type Check = "ok" | "unavailable";
+
+interface Readiness {
+  status: "ok" | "error";
+  repository: Check;
+  /** Short codes from the composition, such as `sync_failing`. */
+  reasons?: string[];
+}
+
+export interface HealthOptions {
+  /** How long a readiness result is reused. */
+  cacheMs?: number;
+  now?: () => number;
+}
+
+export function healthRoutes(options: HealthOptions = {}): Hono<Env> {
+  const cacheMs = options.cacheMs ?? 30_000;
+  const now = options.now ?? Date.now;
+  // The promise, not the result: requests that arrive during a probe share it.
+  let cached: { at: number; result: Promise<Readiness> } | null = null;
+
+  const app = new Hono<Env>();
+
+  app.get("/health", (c) => c.json({ status: "ok" }));
+
+  app.get("/ready", async (c) => {
+    if (!cached || now() - cached.at >= cacheMs) {
+      cached = { at: now(), result: probe(c) };
+    }
+    const result = await cached.result;
+    return c.json(result, result.status === "ok" ? 200 : 503);
+  });
+
+  return app;
+}
+
+async function probe(c: Context<Env>): Promise<Readiness> {
+  const ctx = c.get("ctx");
+  const logger = c.get("logger");
+
+  // A managed clone knows whether it can be edited without asking the remote.
+  if (ctx.health.ready) {
+    const { ok, reasons } = ctx.health.ready();
+    return { status: ok ? "ok" : "error", repository: ok ? "ok" : "unavailable", reasons };
+  }
+
+  // `list` on a missing root returns an empty array, so this proves reachability only.
+  let repository: Check = "ok";
+  try {
+    await ctx.site.contentRepository.list("");
+  } catch (error) {
+    logger.error("Content repository is unreachable", { error: String(error) });
+    repository = "unavailable";
+  }
+
+  return { status: repository === "ok" ? "ok" : "error", repository };
+}

package/src/schema.ts

@@ -0,0 +1,217 @@
+/**
+ * Reads the content model from `.mica/schema.json` in the content repository.
+ * The Astro project writes it. The manifest is untrusted input (another core
+ * version, hand-edited or truncated), so it is validated again here.
+ */
+
+import {
+  checkCompatibility,
+  defineSite,
+  deriveLayout,
+  entryLayout,
+  LayoutError,
+  misplacedFiles,
+  recordLayout,
+  isFieldKind,
+  isProtocolManifest,
+  MANIFEST_PATH,
+  PROTOCOL_VERSION,
+  type Collection,
+  type ContentSource,
+  type FieldMap,
+  type Singleton,
+  type Site,
+} from "@micacms/core";
+
+export class SchemaError extends Error {
+  override name = "SchemaError";
+}
+
+/** Where a model came from, for logs and the system screen. */
+export function schemaOrigin(source: ContentSource): string {
+  return `${source.origin}/${MANIFEST_PATH}`;
+}
+
+/**
+ * Reads the model from the content repository. A missing file gets a long
+ * message because a first deployment hits it.
+ */
+export async function loadSchema(source: ContentSource): Promise<Site> {
+  const origin = schemaOrigin(source);
+
+  let text: string | null;
+  try {
+    text = await source.read(MANIFEST_PATH);
+  } catch (error) {
+    // An unreachable repository is not a bad model; the fixes are different.
+    throw new SchemaError(
+      `Could not read the content model from ${source.origin}.\n` +
+        `  ${(error as Error).message}\n` +
+        `  The repository has to be reachable before Mica can start: the model\n` +
+        `  lives in it, at ${MANIFEST_PATH}.`,
+    );
+  }
+
+  if (text === null) throw new SchemaError(describeMissing(origin));
+
+  let raw: unknown;
+  try {
+    raw = JSON.parse(text);
+  } catch (error) {
+    throw new SchemaError(`${origin} is not valid JSON: ${(error as Error).message}`);
+  }
+
+  return checkSchema(raw, origin);
+}
+
+/**
+ * One message for each collection or singleton with entries in the other
+ * layout. Mica refuses to start on any: editing next to hidden entries would
+ * let a save create a second copy of a page.
+ */
+export async function layoutProblems(source: ContentSource, site: Site): Promise<string[]> {
+  const problems: string[] = [];
+  const parts = [
+    ...Object.entries(site.collections).map(([name, def]) => [name, def.fields, "collection"] as const),
+    ...Object.entries(site.singletons).map(([name, def]) => [name, def.fields, "singleton"] as const),
+  ];
+  for (const [name, fields, kind] of parts) {
+    const paths = await misplacedFiles(source, fields, name, kind);
+    if (paths.length > 0) problems.push(new LayoutError(paths, name, entryLayout(fields)).message);
+  }
+  return problems;
+}
+
+function describeMissing(origin: string): string {
+  return (
+    `No content model at ${origin}.\n` +
+    `  Mica ships without one — the Astro project defines it and writes it here.\n` +
+    `  In the project:  npx astro build   (or start the dev server once)\n` +
+    `  then commit ${MANIFEST_PATH} and push it to the branch Mica is reading.`
+  );
+}
+
+/**
+ * Runs the `defineSite` checks on untrusted input. A newer `protocolVersion` is
+ * refused; an unknown field kind is not, and `readOnlyParts` names what it locks.
+ */
+export function checkSchema(raw: unknown, origin = "the schema"): Site {
+  if (raw === null || typeof raw !== "object") {
+    throw new SchemaError(`${origin} is ${raw === null ? "null" : typeof raw}, expected an object.`);
+  }
+
+  // A bare `{ collections }` without the protocol envelope is also accepted.
+  if (isProtocolManifest(raw)) {
+    const compatibility = checkCompatibility(raw);
+    if (!compatibility.ok && compatibility.reason === "newer") {
+      throw new SchemaError(
+        `${origin} follows protocol version ${compatibility.version}; this build of Mica ` +
+          `understands version ${PROTOCOL_VERSION}.\n` +
+          `  The project was built against a newer @micacms/astro. Upgrade Mica.`,
+      );
+    }
+  }
+
+  const candidate = raw as { collections?: unknown; singletons?: unknown };
+
+  if (candidate.collections === null || typeof candidate.collections !== "object") {
+    throw new SchemaError(`${origin} has no \`collections\`. Expected defineSite({ collections: { ... } }).`);
+  }
+
+  const rawSingletons = candidate.singletons;
+  if (rawSingletons !== undefined && (rawSingletons === null || typeof rawSingletons !== "object")) {
+    throw new SchemaError(`${origin} has a \`singletons\` that is not an object.`);
+  }
+
+  const collections = candidate.collections as Record<string, Collection>;
+  const singletons = (rawSingletons ?? {}) as Record<string, Singleton>;
+
+  for (const [name, def] of Object.entries(collections)) {
+    assertFieldMap(def?.fields, `collections.${name}`, origin);
+  }
+  for (const [name, def] of Object.entries(singletons)) {
+    assertFieldMap(def?.fields, `singletons.${name}`, origin);
+  }
+
+  // Drop, do not refuse, a default sort on an undeclared field: only the list order is affected.
+  for (const def of Object.values(collections)) {
+    const field = def?.defaultSort?.field;
+    if (field && field !== "position" && !def.fields?.[field]) delete def.defaultSort;
+  }
+
+  try {
+    const site = defineSite({ collections, singletons });
+    // Read and classify entries where the manifest says they are, not where fields this build may not know imply.
+    for (const def of [...Object.values(site.collections), ...Object.values(site.singletons)]) {
+      const stored = (def as { layout?: unknown }).layout;
+      if (stored === "file" || stored === "directory") recordLayout(def.fields, stored);
+    }
+    return site;
+  } catch (error) {
+    throw new SchemaError(`${origin} is not a valid content model.\n  ${(error as Error).message}`);
+  }
+}
+
+function assertFieldMap(fields: unknown, at: string, origin: string): void {
+  if (fields === null || typeof fields !== "object") {
+    throw new SchemaError(`${origin}: "${at}" has no \`fields\` object.`);
+  }
+
+  for (const [key, field] of Object.entries(fields as FieldMap)) {
+    const here = `${at}.${key}`;
+
+    if (field === null || typeof field !== "object") {
+      throw new SchemaError(`${origin}: field "${here}" is not an object.`);
+    }
+    if (field.kind === "object" || field.kind === "repeater") {
+      assertFieldMap(field.fields, here, origin);
+    }
+  }
+}
+
+/**
+ * The collections and singletons this build of Mica must not write, keyed
+ * `collections.<name>` or `singletons.<name>`, with the reason for the editor.
+ * A field kind from a newer @micacms/astro makes only its own collection or
+ * singleton read-only; Mica still starts, and the rest stays editable.
+ */
+export function readOnlyParts(site: Site): Map<string, string> {
+  const parts = new Map<string, string>();
+  const add = (key: string, def: Collection | Singleton) => {
+    const unknown = unknownKinds(def.fields, []);
+    const stored = (def as { layout?: unknown }).layout;
+    if (unknown.length > 0) {
+      parts.set(
+        key,
+        `"${def.label}" uses ${unknown.map((field) => `"${field.path}" (${field.kind})`).join(", ")}, ` +
+          "a field type that this version of Mica does not know. Upgrade Mica to edit it.",
+      );
+    } else if (stored !== undefined && stored !== deriveLayout(def.fields)) {
+      parts.set(
+        key,
+        `"${def.label}" is stored as ${String(stored)}, which this version of Mica does not expect. ` +
+          "Upgrade Mica to edit it.",
+      );
+    }
+  };
+  for (const [name, def] of Object.entries(site.collections)) add(`collections.${name}`, def);
+  for (const [name, def] of Object.entries(site.singletons)) add(`singletons.${name}`, def);
+  return parts;
+}
+
+function unknownKinds(fields: FieldMap, at: string[]): Array<{ path: string; kind: string }> {
+  return Object.entries(fields).flatMap(([key, field]) => {
+    const here = [...at, key];
+    if (!isFieldKind(field.kind)) return [{ path: here.join("."), kind: String(field.kind) }];
+    return field.kind === "object" || field.kind === "repeater" ? unknownKinds(field.fields, here) : [];
+  });
+}
+
+/**
+ * A short digest of a model, to show drift. Field order counts, because it is
+ * the order of the admin form.
+ */
+export async function schemaFingerprint(site: Site): Promise<string> {
+  const { createHash } = await import("node:crypto");
+  return createHash("sha256").update(JSON.stringify(site)).digest("hex").slice(0, 12);
+}

package/src/server.ts

@@ -0,0 +1,68 @@
+/**
+ * Binds the app to a socket and shuts down cleanly on SIGTERM and SIGINT. Each
+ * app keeps its own startup message.
+ */
+
+import { serve } from "@hono/node-server";
+import type { Hono } from "hono";
+
+import type { Env } from "./http.js";
+import type { Logger } from "./lib/logger.js";
+
+export interface StartServerOptions {
+  app: Hono<Env>;
+  host: string;
+  port: number;
+  logger: Logger;
+  onListening(info: { port: number }): void;
+  portInUseMessage?(): string;
+  shutdown(): Promise<void>;
+}
+
+export function startServer(options: StartServerOptions): void {
+  const { logger } = options;
+
+  const server = serve(
+    { fetch: options.app.fetch, hostname: options.host, port: options.port },
+    (info) => options.onListening({ port: info.port }),
+  );
+
+  server.on("error", (error: NodeJS.ErrnoException) => {
+    if (error.code !== "EADDRINUSE") throw error;
+
+    process.stderr.write(
+      options.portInUseMessage?.() ??
+        `Port ${options.port} on ${options.host} is already in use. Stop the other ` +
+          `process, or set PORT.\n`,
+    );
+    process.exit(1);
+  });
+
+  let shuttingDown = false;
+
+  const shutdown = (signal: string): void => {
+    if (shuttingDown) return;
+    shuttingDown = true;
+    logger.info("Shutting down", { signal });
+
+    server.close(() => {
+      void options.shutdown().then(() => {
+        logger.info("Shutdown complete");
+        process.exit(0);
+      });
+    });
+
+    // A hung connection must not block a container restart.
+    setTimeout(() => {
+      logger.warn("Forcing exit after shutdown timeout");
+      process.exit(1);
+    }, 15_000).unref();
+  };
+
+  process.on("SIGTERM", () => shutdown("SIGTERM"));
+  process.on("SIGINT", () => shutdown("SIGINT"));
+
+  process.on("unhandledRejection", (reason) => {
+    logger.error("Unhandled promise rejection", { reason: String(reason) });
+  });
+}