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

package/package.json

@@ -1,9 +1,16 @@
 {
   "name": "@micacms/runtime",
-  "version": "0.5.0-rc.2",
+  "version": "0.6.0-rc.1",
   "type": "module",
   "description": "The Mica single-site runtime: the Hono API, application services and staging orchestration, authentication-neutral. Composed by @micacms/editor locally and @micacms/self-hosted behind OIDC.",
   "license": "MIT",
+  "homepage": "https://micacms.com",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/micacms/mica.git",
+    "directory": "packages/runtime"
+  },
+  "bugs": "https://github.com/micacms/mica/issues",
   "author": "Alexander Müdespacher",
   "keywords": [
     "mica",
@@ -22,14 +29,15 @@
     }
   },
   "files": [
-    "dist"
+    "dist",
+    "src"
   ],
   "dependencies": {
     "@hono/node-server": "^1.13.8",
     "hono": "^4.13.7",
     "image-size": "^2.0.3",
     "zod": "^4.3.6",
-    "@micacms/core": "0.5.0-rc.2"
+    "@micacms/core": "0.6.0-rc.1"
   },
   "devDependencies": {
     "@types/node": "^22.20.1",
@@ -37,7 +45,7 @@
     "typescript": "^5.7.3"
   },
   "engines": {
-    "node": ">=22.12.0"
+    "node": ">=24"
   },
   "scripts": {
     "build": "tsc -p tsconfig.json",

package/src/app.ts

@@ -0,0 +1,127 @@
+/**
+ * Assembles the app: health, the admin API and the admin SPA. There is no
+ * public content API and no `/media/*`; a website builds from the repository,
+ * not from this server. Authentication comes from the composing app.
+ */
+
+import { Hono } from "hono";
+import { cors } from "hono/cors";
+import type { MiddlewareHandler } from "hono";
+
+import type { RuntimeContext } from "./context.js";
+import type { Env } from "./http.js";
+import {
+  allowedOrigins,
+  errorHandler,
+  originGuard,
+  requestSizeLimit,
+  rateLimit,
+  requestContext,
+  securityHeaders,
+} from "./middleware/index.js";
+import { adminContentRoutes } from "./routes/admin-content.js";
+import { adminMediaRoutes } from "./routes/admin-media.js";
+import { adminSpaRoutes, adminAssetsExist } from "./routes/admin-spa.js";
+import { adminStagingRoutes } from "./routes/admin-staging.js";
+import { adminSystemRoutes } from "./routes/admin-system.js";
+import { healthRoutes } from "./routes/health.js";
+
+/** What a composing app contributes around the auth-neutral runtime. */
+export interface AuthSurface {
+  /** Mounted at `/api/auth`: sign-in, callback, logout, whatever auth needs. */
+  routes: Hono<Env>;
+  /** Applied before every `/api/admin` route. Must set `access` or refuse the request. */
+  gate: MiddlewareHandler<Env>[];
+}
+
+/**
+ * Allows every request with no identity. Safe only because the local editor is
+ * loopback-bound and Host-guarded.
+ */
+export function allowAll(): MiddlewareHandler<Env> {
+  return async (c, next) => {
+    c.set("access", { identity: null });
+    await next();
+  };
+}
+
+/** `/api/auth/config` with nothing behind it: the SPA's cue to skip sign-in. */
+function unauthenticatedSurface(): AuthSurface {
+  const routes = new Hono<Env>();
+  routes.get("/config", (c) => c.json({ authRequired: false, provider: null }));
+  return { routes, gate: [allowAll()] };
+}
+
+export interface CreateAppOptions {
+  /** Absent means the unauthenticated local surface. */
+  auth?: AuthSurface;
+  /**
+   * Middleware in front of everything, so the local editor's Host allowlist
+   * also guards the health endpoints.
+   */
+  guards?: MiddlewareHandler<Env>[];
+  adminDir?: string;
+}
+
+export function createApp(ctx: RuntimeContext, options: CreateAppOptions = {}): Hono<Env> {
+  const app = new Hono<Env>();
+  const auth = options.auth ?? unauthenticatedSurface();
+
+  app.use("*", requestContext(ctx));
+  for (const guard of options.guards ?? []) app.use("*", guard);
+  app.use("*", securityHeaders());
+  app.onError(errorHandler());
+
+  app.route("/", healthRoutes());
+
+  // Only for the Vite dev server on another origin; in production the SPA is same-origin.
+  if (ctx.config.adminOrigins.length > 0) {
+    app.use(
+      "/api/*",
+      cors({
+        origin: allowedOrigins(ctx.config),
+        credentials: true,
+        allowHeaders: ["content-type", "x-csrf-token"],
+        allowMethods: ["GET", "POST", "PUT", "PATCH", "DELETE", "OPTIONS"],
+      }),
+    );
+  }
+
+  app.use("/api/*", rateLimit());
+  app.use("/api/*", originGuard());
+  app.use("/api/*", requestSizeLimit());
+
+  app.route("/api/auth", auth.routes);
+
+  // One gate and no roles: whoever the surface admits is an editor of this site.
+  for (const middleware of auth.gate) app.use("/api/admin/*", middleware);
+
+  app.route("/api/admin", adminSystemRoutes());
+  app.route("/api/admin", adminContentRoutes());
+  app.route("/api/admin", adminStagingRoutes());
+  app.route("/api/admin/media", adminMediaRoutes());
+
+  app.all("/api/*", (c) =>
+    c.json({ error: { code: "not_found" as const, message: "No such endpoint." } }, 404),
+  );
+
+  const adminDir = options.adminDir ?? ctx.config.MICA_ADMIN_DIR;
+
+  if (adminDir && adminAssetsExist(adminDir)) {
+    app.route("/admin", adminSpaRoutes(adminDir));
+  } else {
+    app.get("/admin/*", (c) =>
+      c.text(
+        "The admin interface has not been built.\n" +
+          "Run `rush build`, or use `rush dev` and open the Vite dev server.",
+        503,
+      ),
+    );
+  }
+
+  app.get("/", (c) => c.redirect("/admin/"));
+
+  app.notFound((c) => c.text("Not found", 404));
+
+  return app;
+}

package/src/config.ts

@@ -0,0 +1,113 @@
+/**
+ * The environment variables the runtime reads. There is no `loadConfig`: each
+ * app builds its own schema from `runtimeEnv`, because the variables and
+ * defaults are what make one app different from another.
+ */
+
+import path from "node:path";
+import { z } from "zod";
+
+import { DEFAULT_BASE_URL, DEFAULT_PORT } from "./lib/ports.js";
+
+/** In Zod 4, `.default` takes the output value and skips the transform. */
+export const bool = (fallback: boolean) =>
+  z
+    .enum(["true", "false", "1", "0"])
+    .transform((value) => value === "true" || value === "1")
+    .default(fallback);
+
+/** Splits a comma-separated list, trims entries and drops empty ones. */
+export const list = (value: string | undefined): string[] =>
+  (value ?? "")
+    .split(",")
+    .map((entry) => entry.trim())
+    .filter(Boolean);
+
+export class ConfigError extends Error {
+  override name = "ConfigError";
+}
+
+/** Hostnames that are this machine, and nowhere else. */
+export const LOOPBACK = new Set(["localhost", "127.0.0.1", "[::1]", "::1", "0:0:0:0:0:0:0:1"]);
+
+/** The variables the runtime itself reads. Apps spread this into their schema. */
+export const runtimeEnv = {
+  NODE_ENV: z.enum(["development", "test", "production"]).default("development"),
+  MICA_LOG_LEVEL: z.enum(["debug", "info", "warn", "error", "silent"]).default("info"),
+
+  /** The listen address. The app sets the default. */
+  HOST: z.string().optional(),
+  PORT: z.coerce.number().int().min(1).max(65535).default(DEFAULT_PORT),
+
+  /** Public origin of the CMS itself. Used for cookies, CORS and media URLs. */
+  MICA_PUBLIC_URL: z.string().url().default(DEFAULT_BASE_URL),
+
+  /** The content root this Mica serves: a directory in a Git working tree. Each app sets it. */
+  MICA_CONTENT_ROOT: z.string(),
+
+  /** `false` disables commit and push: Publish shows the pending changes read-only. */
+  MICA_LOCAL_PUBLISH: bool(true),
+
+  MICA_MAX_UPLOAD_BYTES: z.coerce
+    .number()
+    .int()
+    .positive()
+    .default(25 * 1024 * 1024),
+
+  /** Read the client IP from X-Forwarded-For. Only enable behind a proxy. */
+  MICA_TRUST_PROXY: bool(false),
+  /** Extra browser origins allowed to call the admin API (dev Vite server). */
+  MICA_ADMIN_ORIGINS: z.string().optional(),
+  /** Overrides where the built admin SPA is served from. */
+  MICA_ADMIN_DIR: z.string().optional(),
+};
+
+const runtimeSchema = z.object(runtimeEnv);
+export type RuntimeEnv = z.infer<typeof runtimeSchema>;
+
+/**
+ * Adds the derived values to the parsed environment. Each app calls it from its
+ * own `transform`.
+ */
+export function deriveRuntime<T extends RuntimeEnv>(env: T) {
+  return {
+    ...env,
+    isProduction: env.NODE_ENV === "production",
+    contentRoot: path.resolve(env.MICA_CONTENT_ROOT),
+    adminOrigins: list(env.MICA_ADMIN_ORIGINS),
+  };
+}
+
+/** What the runtime requires of a finished configuration. */
+export type RuntimeConfig = ReturnType<typeof deriveRuntime<RuntimeEnv>> & {
+  /** Resolved by the app: the runtime never guesses an address. */
+  HOST: string;
+};
+
+/** Loads `./.env` into `process.env`. Variables that are already set win. */
+export function loadEnvFile(): void {
+  try {
+    process.loadEnvFile();
+  } catch (error) {
+    // A missing `.env` is normal; an unreadable or malformed one must not start
+    // the server with defaults.
+    if ((error as NodeJS.ErrnoException).code !== "ENOENT") {
+      throw new ConfigError(`Could not read .env: ${(error as Error).message}`);
+    }
+  }
+}
+
+/** Treats a blank variable as unset, so a verbatim copy of `.env.example` with blanks is valid. */
+export function withoutBlanks(env: NodeJS.ProcessEnv): NodeJS.ProcessEnv {
+  return Object.fromEntries(
+    Object.entries(env).filter(([, value]) => value !== undefined && value.trim() !== ""),
+  );
+}
+
+/** Formats a Zod refusal the way a person at a terminal reads it. */
+export function describeConfigIssues(error: z.ZodError): string {
+  const details = error.issues
+    .map((issue) => `  ${issue.path.join(".") || "(root)"}: ${issue.message}`)
+    .join("\n");
+  return `Invalid environment configuration:\n${details}`;
+}

package/src/context.ts

@@ -0,0 +1,167 @@
+/**
+ * Builds the runtime's services for one site, with no module-level singletons.
+ * The app supplies the working tree's files and the owner policy, so the
+ * runtime stays authentication-neutral.
+ */
+
+import type { Site } from "@micacms/core";
+
+import type { RuntimeConfig } from "./config.js";
+import { createLogger, type Logger } from "./lib/logger.js";
+import { createRateLimiter, type RateLimiter } from "./lib/rate-limit.js";
+import { readOnlyParts } from "./schema.js";
+import { createMediaService, type MediaService } from "./services/media.js";
+import type { ContentStagingService } from "./services/changes.js";
+import { createContentStore, type ContentStore } from "./services/content-store.js";
+import { createWorkingTreeStagingService } from "./services/staging.js";
+import { createWorkspaceLocks, lockedFiles, type WorkspaceLocks } from "./workspace/locks.js";
+import type { OwnerPolicy } from "./workspace/policy.js";
+import type { ContentFiles } from "./workspace/files.js";
+import type { GitTree } from "./workspace/tree.js";
+
+/** The one site this process serves. Several sites means several processes. */
+export interface SiteContext {
+  /** Identifies this site in logs. */
+  id: string;
+  /** The content model, read from the repository at startup. */
+  model: Site;
+  /** The working tree's files behind the workspace locks. Only Publish makes a commit. */
+  contentRepository: ContentFiles;
+  /**
+   * Revision of `.mica/schema.json` when the model was loaded. The publish
+   * drift gate compares against it.
+   */
+  schemaRevision: string | null;
+  /** Collections and singletons this build cannot write, from `readOnlyParts`, with the reason. */
+  readOnly: ReadonlyMap<string, string>;
+}
+
+export const DEFAULT_SITE_ID = "default";
+
+/** Facts about the composition that the System page shows and the runtime cannot know. */
+export interface OperationalInfo {
+  /** How this deployment authenticates, in words. */
+  auth: string;
+  /** What decides who may edit, in the operator's own words. */
+  admission?: string;
+  dataDir?: string;
+  sessionTtlHours?: number;
+  sessionIdleHours?: number;
+  /** Names of the secrets this process generated for itself. */
+  generatedSecrets?: string[];
+}
+
+/** What /ready asks the composition. */
+export interface RuntimeHealth {
+  /**
+   * Whether the site can be edited, with short reason codes. Never names the
+   * repository: the endpoint is public.
+   */
+  ready?: () => { ok: boolean; reasons: string[] };
+}
+
+export interface RuntimeContext {
+  config: RuntimeConfig;
+  site: SiteContext;
+  logger: Logger;
+  services: {
+    content: ContentStore;
+    media: MediaService;
+    staging: ContentStagingService;
+  };
+  limiters: {
+    api: RateLimiter;
+  };
+  operational(): OperationalInfo;
+  health: RuntimeHealth;
+  shutdown(): Promise<void>;
+}
+
+export interface CreateRuntimeContextOptions {
+  config: RuntimeConfig;
+  model: Site;
+  /** The working tree's files, without locks. The app builds it. */
+  files: ContentFiles;
+  /** Revision of the manifest the model was read from. Null when unknown. */
+  schemaRevision?: string | null;
+  siteId?: string;
+  logger?: Logger;
+  operational?: () => OperationalInfo;
+  health?: RuntimeHealth;
+  /** Who owns the working tree. Defaults to the developer. */
+  policy?: OwnerPolicy;
+  /** Shared with the owner's own work on the tree, such as a sync. */
+  locks?: WorkspaceLocks;
+  /** See `WorkingTreeStagingDeps.tree`. */
+  tree?: GitTree;
+  onShutdown?: () => void | Promise<void>;
+}
+
+export function createRuntimeContext(options: CreateRuntimeContextOptions): RuntimeContext {
+  const { config, model } = options;
+
+  const logger =
+    options.logger ??
+    createLogger({
+      level: config.MICA_LOG_LEVEL,
+      pretty: !config.isProduction,
+    });
+
+  const schemaRevision = options.schemaRevision ?? null;
+
+  // Services write through the lock wrapper; staging takes the locks itself.
+  const locks = options.locks ?? createWorkspaceLocks();
+
+  const readOnly = readOnlyParts(model);
+  for (const reason of readOnly.values()) logger.warn("Read-only in this version of Mica", { reason });
+
+  const site: SiteContext = {
+    id: options.siteId ?? DEFAULT_SITE_ID,
+    model,
+    contentRepository: lockedFiles(options.files, locks.tree),
+    schemaRevision,
+    readOnly,
+  };
+
+  const services = {
+    content: createContentStore(model, site.contentRepository, readOnly),
+    media: createMediaService({
+      files: site.contentRepository,
+      maxBytes: config.MICA_MAX_UPLOAD_BYTES,
+    }),
+    staging: createWorkingTreeStagingService({
+      model,
+      files: options.files,
+      contentRoot: config.contentRoot,
+      schemaRevision,
+      readOnly,
+      publishEnabled: config.MICA_LOCAL_PUBLISH,
+      logger,
+      locks,
+      ...(options.policy ? { policy: options.policy } : {}),
+      ...(options.tree ? { tree: options.tree } : {}),
+    }),
+  };
+
+  const limiters = {
+    // Generous: it stops runaway scripts, it does not shape traffic.
+    api: createRateLimiter({ limit: 600, windowMs: 60_000 }),
+  };
+
+  return {
+    config,
+    site,
+    logger,
+    services,
+    limiters,
+    operational:
+      options.operational ??
+      (() => ({ auth: "unspecified" })),
+    health: options.health ?? {},
+
+    async shutdown() {
+      limiters.api.stop();
+      await options.onShutdown?.();
+    },
+  };
+}

package/src/http.ts

@@ -0,0 +1,46 @@
+import type { Context } from "hono";
+
+import type { AccessContext } from "@micacms/core";
+
+import type { RuntimeContext } from "./context.js";
+import type { Logger } from "./lib/logger.js";
+
+export interface Env {
+  Variables: {
+    ctx: RuntimeContext;
+    logger: Logger;
+    requestId: string;
+    /**
+     * Who this request acts as. The auth surface's gate sets it on every admin
+     * route; the runtime never sets it.
+     */
+    access: AccessContext;
+  };
+}
+
+/**
+ * Client IP. Reads `X-Forwarded-For` only with MICA_TRUST_PROXY, or a client could
+ * spoof its address past the rate limit. The right-most entry is the address
+ * the proxy saw; the entries to its left come from the client.
+ */
+export function clientIp(c: Context<Env>): string {
+  const { config } = c.get("ctx");
+
+  if (config.MICA_TRUST_PROXY) {
+    const forwarded = c.req.header("x-forwarded-for");
+    const last = forwarded?.split(",").at(-1)?.trim();
+    if (last) return last;
+  }
+
+  const info = c.env as { incoming?: { socket?: { remoteAddress?: string } } } | undefined;
+  return info?.incoming?.socket?.remoteAddress ?? "unknown";
+}
+
+/**
+ * The commit author. Null in the local editor, where the commit keeps the
+ * developer's own Git identity.
+ */
+export function actorOf(c: Context<Env>): { id: string; email: string; name: string } | null {
+  const identity = c.get("access")?.identity;
+  return identity ? { id: identity.subject, email: identity.email, name: identity.name } : null;
+}

package/src/index.ts

@@ -0,0 +1,141 @@
+/**
+ * @micacms/runtime: the single-site, authentication-neutral Mica runtime.
+ * It must never import an auth implementation; the composing app supplies the `AuthSurface`.
+ */
+
+export { createApp, allowAll, type AuthSurface, type CreateAppOptions } from "./app.js";
+export {
+  createRuntimeContext,
+  DEFAULT_SITE_ID,
+  type CreateRuntimeContextOptions,
+  type OperationalInfo,
+  type RuntimeContext,
+  type RuntimeHealth,
+  type SiteContext,
+} from "./context.js";
+export {
+  bool,
+  ConfigError,
+  deriveRuntime,
+  describeConfigIssues,
+  list,
+  loadEnvFile,
+  LOOPBACK,
+  runtimeEnv,
+  withoutBlanks,
+  type RuntimeConfig,
+  type RuntimeEnv,
+} from "./config.js";
+export { startServer, type StartServerOptions } from "./server.js";
+export { actorOf, clientIp, type Env } from "./http.js";
+export {
+  checkSchema,
+  layoutProblems,
+  loadSchema,
+  readOnlyParts,
+  SchemaError,
+  schemaFingerprint,
+  schemaOrigin,
+} from "./schema.js";
+export {
+  allowedOrigins,
+  errorHandler,
+  originGuard,
+  rateLimit,
+  requestContext,
+  securityHeaders,
+} from "./middleware/index.js";
+export { adminAssetsExist } from "./routes/admin-spa.js";
+export {
+  ApiError,
+  badRequest,
+  conflict,
+  forbidden,
+  notFound,
+  unauthenticated,
+  type ApiErrorBody,
+  type ErrorCode,
+} from "./lib/errors.js";
+export { createLogger, type Logger } from "./lib/logger.js";
+export { createRateLimiter, type RateLimiter } from "./lib/rate-limit.js";
+export { randomToken } from "./lib/id.js";
+export { DEFAULT_BASE_URL, DEFAULT_PORT } from "./lib/ports.js";
+export { VERSION } from "./lib/version.js";
+export {
+  analyseChanges,
+  classifyPath,
+  describeProblems,
+  flattenProblems,
+  type AnnotatedChange,
+  type ChangeOwner,
+  type ContentStagingService,
+  type RepositoryInfo,
+  type PublishInput,
+  type StagingProblem,
+  type StagingStatus,
+  type StagingValidation,
+} from "./services/changes.js";
+export {
+  createWorkingTreeStagingService,
+  type WorkingTreeStagingDeps,
+} from "./services/staging.js";
+export { createMediaService, formatBytes, type MediaFile, type MediaService } from "./services/media.js";
+export {
+  createContentStore,
+  ContentError,
+  ValidationError,
+  type ContentStore,
+  type SavedEntry,
+  type SaveEntryInput,
+} from "./services/content-store.js";
+export {
+  checkChangePaths,
+  ConflictError,
+  contentFiles,
+  FilesError,
+  type Author,
+  type ContentFiles,
+  type ContentFilesOptions,
+  type FileChange,
+  type FileChanges,
+} from "./workspace/files.js";
+export {
+  developerEnvironment,
+  firstLine,
+  GitError,
+  gitRunner,
+  type GitCallOptions,
+  type GitRunner,
+  type GitRunnerOptions,
+} from "./workspace/git.js";
+export {
+  createMutex,
+  createReadWriteLock,
+  createWorkspaceLocks,
+  lockedFiles,
+  type Mutex,
+  type ReadWriteLock,
+  type WorkspaceLocks,
+} from "./workspace/locks.js";
+export type {
+  OwnerPolicy,
+  PublishAvailability,
+  RepositoryDescription,
+  SyncConflict,
+  SyncStatus,
+} from "./workspace/policy.js";
+export { developerPolicy, type DeveloperPolicyOptions } from "./workspace/developer.js";
+export {
+  commitPaths,
+  headRevision,
+  headSource,
+  inRepo,
+  listTreeChanges,
+  LITERAL,
+  locateTree,
+  parseStatus,
+  recommitPaths,
+  type GitTree,
+  type TreeChange,
+} from "./workspace/tree.js";
+export { schemaStats } from "./lib/schema-stats.js";