@micacms/runtime 0.2.0

package/README.md

@@ -0,0 +1,16 @@
+# @micacms/runtime
+
+> **Experimental.** Pre-1.0: the API can still change without notice.
+
+The single-site Mica runtime: the Hono API, application services and staging
+orchestration, deliberately **authentication-neutral**. It answers "who is
+this request?" with whatever `AuthSurface` the composing app hands in, and
+never imports an auth implementation — that direction is what keeps
+`npx @micacms/editor` free of authentication code.
+
+You normally do not depend on this package directly. The two compositions do:
+
+- [`@micacms/editor`](https://www.npmjs.com/package/@micacms/editor) — the
+  local editor: loopback, no auth, no database.
+- [`@micacms/self-hosted`](https://www.npmjs.com/package/@micacms/self-hosted)
+  — the Docker composition, behind `@micacms/auth-oidc`.

package/dist/app.d.ts

@@ -0,0 +1,62 @@
+/**
+ * Application assembly.
+ *
+ *   cms.example.com
+ *          │
+ *          ▼
+ *         Hono
+ *   ┌──────┴───┬──────────┐
+ *   │          │          │
+ * /api/*    /admin/*   /health
+ *   │          │
+ * connector  Vue SPA
+ *   │
+ * content repository
+ *
+ * There is no public content API and no `/media/*`. A website is built from the
+ * repository, not from this server, so nothing here has to be reachable for a
+ * site to deploy — or to stay up.
+ *
+ * Authentication is not assembled here — it is *received*. The composing app
+ * hands in an `AuthSurface`: routes for `/api/auth`, and the gate applied in
+ * front of every admin route. The self-hosted app passes the OIDC surface
+ * from `@micacms/auth-oidc`; the local editor passes nothing and gets the
+ * unauthenticated surface below, which is a statement of fact — on your own
+ * machine there is nobody to be — not a bypass of anything.
+ */
+import { Hono } from "hono";
+import type { MiddlewareHandler } from "hono";
+import type { RuntimeContext } from "./context.js";
+import type { Env } from "./http.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, in order. Must either set the
+     * `access` variable or refuse the request — nothing behind it runs without
+     * an `AccessContext`.
+     */
+    gate: MiddlewareHandler<Env>[];
+}
+/**
+ * The unauthenticated surface: every request is allowed, and none is anybody.
+ *
+ * An authorization policy, not authentication code. It exists so action
+ * checks stay uniform without inventing a user, and it is safe only because
+ * the local editor is loopback-bound and Host-guarded by construction.
+ */
+export declare function allowAll(): MiddlewareHandler<Env>;
+export interface CreateAppOptions {
+    /** Absent means the unauthenticated local surface. */
+    auth?: AuthSurface;
+    /**
+     * Extra middleware in front of everything — the local editor's Host
+     * allowlist goes here, so even /health answers only to this machine.
+     */
+    guards?: MiddlewareHandler<Env>[];
+    /** Where the built admin SPA is served from. */
+    adminDir?: string;
+}
+export declare function createApp(ctx: RuntimeContext, options?: CreateAppOptions): Hono<Env>;
+//# sourceMappingURL=app.d.ts.map

package/dist/app.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"app.d.ts","sourceRoot":"","sources":["../src/app.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AAEH,OAAO,EAAE,IAAI,EAAE,MAAM,MAAM,CAAC;AAE5B,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,MAAM,CAAC;AAE9C,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,cAAc,CAAC;AACnD,OAAO,KAAK,EAAE,GAAG,EAAE,MAAM,WAAW,CAAC;AAgBrC,wEAAwE;AACxE,MAAM,WAAW,WAAW;IAC1B,8EAA8E;IAC9E,MAAM,EAAE,IAAI,CAAC,GAAG,CAAC,CAAC;IAClB;;;;OAIG;IACH,IAAI,EAAE,iBAAiB,CAAC,GAAG,CAAC,EAAE,CAAC;CAChC;AAED;;;;;;GAMG;AACH,wBAAgB,QAAQ,IAAI,iBAAiB,CAAC,GAAG,CAAC,CAKjD;AASD,MAAM,WAAW,gBAAgB;IAC/B,sDAAsD;IACtD,IAAI,CAAC,EAAE,WAAW,CAAC;IACnB;;;OAGG;IACH,MAAM,CAAC,EAAE,iBAAiB,CAAC,GAAG,CAAC,EAAE,CAAC;IAClC,gDAAgD;IAChD,QAAQ,CAAC,EAAE,MAAM,CAAC;CACnB;AAED,wBAAgB,SAAS,CAAC,GAAG,EAAE,cAAc,EAAE,OAAO,GAAE,gBAAqB,GAAG,IAAI,CAAC,GAAG,CAAC,CA4ExF"}

package/dist/app.js

@@ -0,0 +1,107 @@
+/**
+ * Application assembly.
+ *
+ *   cms.example.com
+ *          │
+ *          ▼
+ *         Hono
+ *   ┌──────┴───┬──────────┐
+ *   │          │          │
+ * /api/*    /admin/*   /health
+ *   │          │
+ * connector  Vue SPA
+ *   │
+ * content repository
+ *
+ * There is no public content API and no `/media/*`. A website is built from the
+ * repository, not from this server, so nothing here has to be reachable for a
+ * site to deploy — or to stay up.
+ *
+ * Authentication is not assembled here — it is *received*. The composing app
+ * hands in an `AuthSurface`: routes for `/api/auth`, and the gate applied in
+ * front of every admin route. The self-hosted app passes the OIDC surface
+ * from `@micacms/auth-oidc`; the local editor passes nothing and gets the
+ * unauthenticated surface below, which is a statement of fact — on your own
+ * machine there is nobody to be — not a bypass of anything.
+ */
+import { Hono } from "hono";
+import { cors } from "hono/cors";
+import { allowedOrigins, errorHandler, originGuard, 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";
+/**
+ * The unauthenticated surface: every request is allowed, and none is anybody.
+ *
+ * An authorization policy, not authentication code. It exists so action
+ * checks stay uniform without inventing a user, and it is safe only because
+ * the local editor is loopback-bound and Host-guarded by construction.
+ */
+export function allowAll() {
+    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() {
+    const routes = new Hono();
+    routes.get("/config", (c) => c.json({ authRequired: false, provider: null }));
+    return { routes, gate: [allowAll()] };
+}
+export function createApp(ctx, options = {}) {
+    const app = new Hono();
+    const auth = options.auth ?? unauthenticatedSurface();
+    /* ---------------------------------------------------------- baseline */
+    app.use("*", requestContext(ctx));
+    for (const guard of options.guards ?? [])
+        app.use("*", guard);
+    app.use("*", securityHeaders());
+    app.onError(errorHandler());
+    /* ------------------------------------------------------------ health */
+    app.route("/health", healthRoutes());
+    /* --------------------------------------------------------------- API */
+    // In development the SPA is served by Vite on another origin, so the API has
+    // to accept credentialed cross-origin calls from it. In production the SPA is
+    // same-origin and ADMIN_ORIGINS is normally empty.
+    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.route("/api/auth", auth.routes);
+    /* ------------------------------------------------------- admin API */
+    // One gate, and no second one behind it: whoever the surface admits is an
+    // editor of this site. There are no roles, because there are no accounts to
+    // hang them on.
+    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", message: "No such endpoint." } }, 404));
+    /* --------------------------------------------------------- admin SPA */
+    const adminDir = options.adminDir ?? ctx.config.ADMIN_DIR;
+    if (adminDir && adminAssetsExist(adminDir)) {
+        app.route("/admin", adminSpaRoutes(adminDir));
+    }
+    else {
+        // Running from source with only the API built: point at the Vite server
+        // rather than returning a blank 404.
+        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;
+}
+//# sourceMappingURL=app.js.map

package/dist/app.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"app.js","sourceRoot":"","sources":["../src/app.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AAEH,OAAO,EAAE,IAAI,EAAE,MAAM,MAAM,CAAC;AAC5B,OAAO,EAAE,IAAI,EAAE,MAAM,WAAW,CAAC;AAKjC,OAAO,EACL,cAAc,EACd,YAAY,EACZ,WAAW,EACX,SAAS,EACT,cAAc,EACd,eAAe,GAChB,MAAM,uBAAuB,CAAC;AAC/B,OAAO,EAAE,kBAAkB,EAAE,MAAM,2BAA2B,CAAC;AAC/D,OAAO,EAAE,gBAAgB,EAAE,MAAM,yBAAyB,CAAC;AAC3D,OAAO,EAAE,cAAc,EAAE,gBAAgB,EAAE,MAAM,uBAAuB,CAAC;AACzE,OAAO,EAAE,kBAAkB,EAAE,MAAM,2BAA2B,CAAC;AAC/D,OAAO,EAAE,iBAAiB,EAAE,MAAM,0BAA0B,CAAC;AAC7D,OAAO,EAAE,YAAY,EAAE,MAAM,oBAAoB,CAAC;AAclD;;;;;;GAMG;AACH,MAAM,UAAU,QAAQ;IACtB,OAAO,KAAK,EAAE,CAAC,EAAE,IAAI,EAAE,EAAE;QACvB,CAAC,CAAC,GAAG,CAAC,QAAQ,EAAE,EAAE,QAAQ,EAAE,IAAI,EAAE,CAAC,CAAC;QACpC,MAAM,IAAI,EAAE,CAAC;IACf,CAAC,CAAC;AACJ,CAAC;AAED,gFAAgF;AAChF,SAAS,sBAAsB;IAC7B,MAAM,MAAM,GAAG,IAAI,IAAI,EAAO,CAAC;IAC/B,MAAM,CAAC,GAAG,CAAC,SAAS,EAAE,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,IAAI,CAAC,EAAE,YAAY,EAAE,KAAK,EAAE,QAAQ,EAAE,IAAI,EAAE,CAAC,CAAC,CAAC;IAC9E,OAAO,EAAE,MAAM,EAAE,IAAI,EAAE,CAAC,QAAQ,EAAE,CAAC,EAAE,CAAC;AACxC,CAAC;AAcD,MAAM,UAAU,SAAS,CAAC,GAAmB,EAAE,UAA4B,EAAE;IAC3E,MAAM,GAAG,GAAG,IAAI,IAAI,EAAO,CAAC;IAC5B,MAAM,IAAI,GAAG,OAAO,CAAC,IAAI,IAAI,sBAAsB,EAAE,CAAC;IAEtD,yEAAyE;IAEzE,GAAG,CAAC,GAAG,CAAC,GAAG,EAAE,cAAc,CAAC,GAAG,CAAC,CAAC,CAAC;IAClC,KAAK,MAAM,KAAK,IAAI,OAAO,CAAC,MAAM,IAAI,EAAE;QAAE,GAAG,CAAC,GAAG,CAAC,GAAG,EAAE,KAAK,CAAC,CAAC;IAC9D,GAAG,CAAC,GAAG,CAAC,GAAG,EAAE,eAAe,EAAE,CAAC,CAAC;IAChC,GAAG,CAAC,OAAO,CAAC,YAAY,EAAE,CAAC,CAAC;IAE5B,yEAAyE;IAEzE,GAAG,CAAC,KAAK,CAAC,SAAS,EAAE,YAAY,EAAE,CAAC,CAAC;IAErC,yEAAyE;IAEzE,6EAA6E;IAC7E,8EAA8E;IAC9E,mDAAmD;IACnD,IAAI,GAAG,CAAC,MAAM,CAAC,YAAY,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;QACvC,GAAG,CAAC,GAAG,CACL,QAAQ,EACR,IAAI,CAAC;YACH,MAAM,EAAE,cAAc,CAAC,GAAG,CAAC,MAAM,CAAC;YAClC,WAAW,EAAE,IAAI;YACjB,YAAY,EAAE,CAAC,cAAc,EAAE,cAAc,CAAC;YAC9C,YAAY,EAAE,CAAC,KAAK,EAAE,MAAM,EAAE,KAAK,EAAE,OAAO,EAAE,QAAQ,EAAE,SAAS,CAAC;SACnE,CAAC,CACH,CAAC;IACJ,CAAC;IAED,GAAG,CAAC,GAAG,CAAC,QAAQ,EAAE,SAAS,EAAE,CAAC,CAAC;IAC/B,GAAG,CAAC,GAAG,CAAC,QAAQ,EAAE,WAAW,EAAE,CAAC,CAAC;IAEjC,GAAG,CAAC,KAAK,CAAC,WAAW,EAAE,IAAI,CAAC,MAAM,CAAC,CAAC;IAEpC,uEAAuE;IAEvE,0EAA0E;IAC1E,4EAA4E;IAC5E,gBAAgB;IAChB,KAAK,MAAM,UAAU,IAAI,IAAI,CAAC,IAAI;QAAE,GAAG,CAAC,GAAG,CAAC,cAAc,EAAE,UAAU,CAAC,CAAC;IAExE,GAAG,CAAC,KAAK,CAAC,YAAY,EAAE,iBAAiB,EAAE,CAAC,CAAC;IAC7C,GAAG,CAAC,KAAK,CAAC,YAAY,EAAE,kBAAkB,EAAE,CAAC,CAAC;IAC9C,GAAG,CAAC,KAAK,CAAC,YAAY,EAAE,kBAAkB,EAAE,CAAC,CAAC;IAC9C,GAAG,CAAC,KAAK,CAAC,kBAAkB,EAAE,gBAAgB,EAAE,CAAC,CAAC;IAElD,GAAG,CAAC,GAAG,CAAC,QAAQ,EAAE,CAAC,CAAC,EAAE,EAAE,CACtB,CAAC,CAAC,IAAI,CAAC,EAAE,KAAK,EAAE,EAAE,IAAI,EAAE,WAAoB,EAAE,OAAO,EAAE,mBAAmB,EAAE,EAAE,EAAE,GAAG,CAAC,CACrF,CAAC;IAEF,yEAAyE;IAEzE,MAAM,QAAQ,GAAG,OAAO,CAAC,QAAQ,IAAI,GAAG,CAAC,MAAM,CAAC,SAAS,CAAC;IAE1D,IAAI,QAAQ,IAAI,gBAAgB,CAAC,QAAQ,CAAC,EAAE,CAAC;QAC3C,GAAG,CAAC,KAAK,CAAC,QAAQ,EAAE,cAAc,CAAC,QAAQ,CAAC,CAAC,CAAC;IAChD,CAAC;SAAM,CAAC;QACN,wEAAwE;QACxE,qCAAqC;QACrC,GAAG,CAAC,GAAG,CAAC,UAAU,EAAE,CAAC,CAAC,EAAE,EAAE,CACxB,CAAC,CAAC,IAAI,CACJ,2CAA2C;YACzC,mEAAmE,EACrE,GAAG,CACJ,CACF,CAAC;IACJ,CAAC;IAED,GAAG,CAAC,GAAG,CAAC,GAAG,EAAE,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,QAAQ,CAAC,SAAS,CAAC,CAAC,CAAC;IAE3C,GAAG,CAAC,QAAQ,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,IAAI,CAAC,WAAW,EAAE,GAAG,CAAC,CAAC,CAAC;IAE9C,OAAO,GAAG,CAAC;AACb,CAAC"}

package/dist/config.d.ts

@@ -0,0 +1,187 @@
+/**
+ * The runtime's slice of the environment, as a fragment.
+ *
+ * There is no `loadConfig` here, deliberately. The runtime is composed by an
+ * app — the local editor, the self-hosted container — and which variables
+ * exist, which are refused and what the defaults are is exactly what makes
+ * one app not the other. Each app builds its own Zod schema from this shape,
+ * adds its own variables, and derives a `RuntimeConfig` with `deriveRuntime`;
+ * this module only states what the runtime itself reads.
+ *
+ * `MICA_MODE` is gone. The mode is which app you run.
+ */
+import { z } from "zod";
+/**
+ * `.default` takes the *output* value in Zod 4, and short-circuits: an absent
+ * variable returns the boolean without going through the transform.
+ */
+export declare const bool: (fallback: boolean) => z.ZodDefault<z.ZodPipe<z.ZodEnum<{
+    0: "0";
+    1: "1";
+    true: "true";
+    false: "false";
+}>, z.ZodTransform<boolean, "0" | "1" | "true" | "false">>>;
+/** `a, b , c` and `a,b,c` are the same list, and an empty entry is not one. */
+export declare const list: (value: string | undefined) => string[];
+export declare class ConfigError extends Error {
+    name: string;
+}
+/** Hostnames that are this machine, and nowhere else. */
+export declare const LOOPBACK: Set<string>;
+/** The variables the runtime itself reads. Apps spread this into their schema. */
+export declare const runtimeEnv: {
+    NODE_ENV: z.ZodDefault<z.ZodEnum<{
+        development: "development";
+        test: "test";
+        production: "production";
+    }>>;
+    LOG_LEVEL: z.ZodDefault<z.ZodEnum<{
+        debug: "debug";
+        info: "info";
+        warn: "warn";
+        error: "error";
+        silent: "silent";
+    }>>;
+    /** The address to listen on. Defaulted by the app: loopback for the local
+     *  editor (which refuses anything else), every interface for a container. */
+    HOST: z.ZodOptional<z.ZodString>;
+    PORT: z.ZodDefault<z.ZodCoercedNumber<unknown>>;
+    /** Public origin of the CMS itself. Used for cookies, CORS and media URLs. */
+    MICA_PUBLIC_URL: z.ZodDefault<z.ZodString>;
+    /**
+     * The content repository this Mica serves, when it reaches it as a working
+     * tree on disk. Ignored for a provider connector, which is given
+     * REPOSITORY_ROOT inside the remote repository instead.
+     */
+    CONTENT_ROOT: z.ZodDefault<z.ZodString>;
+    /**
+     * How Mica reaches that repository. `local` is a working tree beside the
+     * server — and the working tree is then the draft workspace. `github` and
+     * `gitlab` publish through the provider's API, with saves staged in the
+     * draft store until an editor publishes.
+     */
+    REPOSITORY: z.ZodDefault<z.ZodEnum<{
+        local: "local";
+        github: "github";
+        gitlab: "gitlab";
+    }>>;
+    /** Where the content root sits *inside* the remote repository. */
+    REPOSITORY_ROOT: z.ZodDefault<z.ZodString>;
+    REPOSITORY_BRANCH: z.ZodDefault<z.ZodString>;
+    /** Token with write access to the content repository. */
+    REPOSITORY_TOKEN: z.ZodOptional<z.ZodString>;
+    /** `owner/repo` for GitHub, `group/project` or a numeric id for GitLab. */
+    REPOSITORY_PROJECT: z.ZodOptional<z.ZodString>;
+    /** For GitHub Enterprise or self-managed GitLab. */
+    REPOSITORY_API_BASE: z.ZodOptional<z.ZodString>;
+    /**
+     * Whether working-tree staging may commit and push. `false` reduces Publish
+     * to autosave plus a read-only view of the pending changes.
+     */
+    MICA_LOCAL_PUBLISH: z.ZodDefault<z.ZodPipe<z.ZodEnum<{
+        0: "0";
+        1: "1";
+        true: "true";
+        false: "false";
+    }>, z.ZodTransform<boolean, "0" | "1" | "true" | "false">>>;
+    MAX_UPLOAD_BYTES: z.ZodDefault<z.ZodCoercedNumber<unknown>>;
+    /** Read the client IP from X-Forwarded-For. Only enable behind a proxy. */
+    TRUST_PROXY: z.ZodDefault<z.ZodPipe<z.ZodEnum<{
+        0: "0";
+        1: "1";
+        true: "true";
+        false: "false";
+    }>, z.ZodTransform<boolean, "0" | "1" | "true" | "false">>>;
+    /** Extra browser origins allowed to call the admin API (dev Vite server). */
+    ADMIN_ORIGINS: z.ZodOptional<z.ZodString>;
+    /** Overrides where the built admin SPA is served from. */
+    ADMIN_DIR: z.ZodOptional<z.ZodString>;
+};
+declare const runtimeSchema: z.ZodObject<{
+    NODE_ENV: z.ZodDefault<z.ZodEnum<{
+        development: "development";
+        test: "test";
+        production: "production";
+    }>>;
+    LOG_LEVEL: z.ZodDefault<z.ZodEnum<{
+        debug: "debug";
+        info: "info";
+        warn: "warn";
+        error: "error";
+        silent: "silent";
+    }>>;
+    HOST: z.ZodOptional<z.ZodString>;
+    PORT: z.ZodDefault<z.ZodCoercedNumber<unknown>>;
+    MICA_PUBLIC_URL: z.ZodDefault<z.ZodString>;
+    CONTENT_ROOT: z.ZodDefault<z.ZodString>;
+    REPOSITORY: z.ZodDefault<z.ZodEnum<{
+        local: "local";
+        github: "github";
+        gitlab: "gitlab";
+    }>>;
+    REPOSITORY_ROOT: z.ZodDefault<z.ZodString>;
+    REPOSITORY_BRANCH: z.ZodDefault<z.ZodString>;
+    REPOSITORY_TOKEN: z.ZodOptional<z.ZodString>;
+    REPOSITORY_PROJECT: z.ZodOptional<z.ZodString>;
+    REPOSITORY_API_BASE: z.ZodOptional<z.ZodString>;
+    MICA_LOCAL_PUBLISH: z.ZodDefault<z.ZodPipe<z.ZodEnum<{
+        0: "0";
+        1: "1";
+        true: "true";
+        false: "false";
+    }>, z.ZodTransform<boolean, "0" | "1" | "true" | "false">>>;
+    MAX_UPLOAD_BYTES: z.ZodDefault<z.ZodCoercedNumber<unknown>>;
+    TRUST_PROXY: z.ZodDefault<z.ZodPipe<z.ZodEnum<{
+        0: "0";
+        1: "1";
+        true: "true";
+        false: "false";
+    }>, z.ZodTransform<boolean, "0" | "1" | "true" | "false">>>;
+    ADMIN_ORIGINS: z.ZodOptional<z.ZodString>;
+    ADMIN_DIR: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>;
+export type RuntimeEnv = z.infer<typeof runtimeSchema>;
+/**
+ * The derived values the runtime reads, on top of the parsed environment.
+ *
+ * Called from each app's own `transform`, so every composition derives them
+ * the same way and none forgets one.
+ */
+export declare function deriveRuntime<T extends RuntimeEnv>(env: T): T & {
+    isProduction: boolean;
+    contentRoot: string;
+    adminOrigins: string[];
+};
+/** 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;
+};
+/**
+ * A remote repository needs to be told which one, and with what.
+ *
+ * Checked at startup rather than at the first save: a Mica that starts, shows
+ * the editor their content, and only fails when they press Save has already
+ * wasted their work.
+ */
+export declare function requireRepositoryConfig(config: RuntimeConfig): void;
+/**
+ * Folds `./.env` into the ambient environment.
+ *
+ * `process.loadEnvFile` leaves already-set variables alone, so a container's
+ * `environment:` block still beats a file that happened to be copied into the
+ * image.
+ */
+export declare function loadEnvFile(): void;
+/**
+ * An unset variable and one set to the empty string mean the same thing.
+ *
+ * `.env.example` ships blanks for the operator to fill in, and the docs say to
+ * copy it verbatim; without this, doing so reads as "the secret is a
+ * zero-length string" and the server refuses on the documented happy path.
+ */
+export declare function withoutBlanks(env: NodeJS.ProcessEnv): NodeJS.ProcessEnv;
+/** Formats a Zod refusal the way a person at a terminal reads it. */
+export declare function describeConfigIssues(error: z.ZodError): string;
+export {};
+//# sourceMappingURL=config.d.ts.map

package/dist/config.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"config.d.ts","sourceRoot":"","sources":["../src/config.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAGH,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAIxB;;;GAGG;AACH,eAAO,MAAM,IAAI,GAAI,UAAU,OAAO;;;;;2DAIhB,CAAC;AAEvB,+EAA+E;AAC/E,eAAO,MAAM,IAAI,GAAI,OAAO,MAAM,GAAG,SAAS,KAAG,MAAM,EAInC,CAAC;AAErB,qBAAa,WAAY,SAAQ,KAAK;IAC3B,IAAI,SAAiB;CAC/B;AAED,yDAAyD;AACzD,eAAO,MAAM,QAAQ,aAAyE,CAAC;AAE/F,kFAAkF;AAClF,eAAO,MAAM,UAAU;;;;;;;;;;;;;IAIrB;iFAC6E;;;IAI7E,8EAA8E;;IAG9E;;;;OAIG;;IAGH;;;;;OAKG;;;;;;IAEH,kEAAkE;;;IAGlE,yDAAyD;;IAEzD,2EAA2E;;IAE3E,oDAAoD;;IAGpD;;;OAGG;;;;;;;;IASH,2EAA2E;;;;;;;IAE3E,6EAA6E;;IAE7E,0DAA0D;;CAE3D,CAAC;AAEF,QAAA,MAAM,aAAa;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;iBAAuB,CAAC;AAC3C,MAAM,MAAM,UAAU,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,aAAa,CAAC,CAAC;AAEvD;;;;;GAKG;AACH,wBAAgB,aAAa,CAAC,CAAC,SAAS,UAAU,EAAE,GAAG,EAAE,CAAC;;;;EAOzD;AAED,6DAA6D;AAC7D,MAAM,MAAM,aAAa,GAAG,UAAU,CAAC,OAAO,aAAa,CAAC,UAAU,CAAC,CAAC,GAAG;IACzE,iEAAiE;IACjE,IAAI,EAAE,MAAM,CAAC;CACd,CAAC;AAEF;;;;;;GAMG;AACH,wBAAgB,uBAAuB,CAAC,MAAM,EAAE,aAAa,GAAG,IAAI,CAgBnE;AAED;;;;;;GAMG;AACH,wBAAgB,WAAW,IAAI,IAAI,CAWlC;AAED;;;;;;GAMG;AACH,wBAAgB,aAAa,CAAC,GAAG,EAAE,MAAM,CAAC,UAAU,GAAG,MAAM,CAAC,UAAU,CAIvE;AAED,qEAAqE;AACrE,wBAAgB,oBAAoB,CAAC,KAAK,EAAE,CAAC,CAAC,QAAQ,GAAG,MAAM,CAK9D"}

package/dist/config.js

@@ -0,0 +1,154 @@
+/**
+ * The runtime's slice of the environment, as a fragment.
+ *
+ * There is no `loadConfig` here, deliberately. The runtime is composed by an
+ * app — the local editor, the self-hosted container — and which variables
+ * exist, which are refused and what the defaults are is exactly what makes
+ * one app not the other. Each app builds its own Zod schema from this shape,
+ * adds its own variables, and derives a `RuntimeConfig` with `deriveRuntime`;
+ * this module only states what the runtime itself reads.
+ *
+ * `MICA_MODE` is gone. The mode is which app you run.
+ */
+import path from "node:path";
+import { z } from "zod";
+import { DEFAULT_BASE_URL, DEFAULT_PORT } from "./lib/ports.js";
+/**
+ * `.default` takes the *output* value in Zod 4, and short-circuits: an absent
+ * variable returns the boolean without going through the transform.
+ */
+export const bool = (fallback) => z
+    .enum(["true", "false", "1", "0"])
+    .transform((value) => value === "true" || value === "1")
+    .default(fallback);
+/** `a, b , c` and `a,b,c` are the same list, and an empty entry is not one. */
+export const list = (value) => (value ?? "")
+    .split(",")
+    .map((entry) => entry.trim())
+    .filter(Boolean);
+export class ConfigError extends Error {
+    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"),
+    LOG_LEVEL: z.enum(["debug", "info", "warn", "error", "silent"]).default("info"),
+    /** The address to listen on. Defaulted by the app: loopback for the local
+     *  editor (which refuses anything else), every interface for a container. */
+    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 repository this Mica serves, when it reaches it as a working
+     * tree on disk. Ignored for a provider connector, which is given
+     * REPOSITORY_ROOT inside the remote repository instead.
+     */
+    CONTENT_ROOT: z.string().default("../../examples/muster-consulting/content"),
+    /**
+     * How Mica reaches that repository. `local` is a working tree beside the
+     * server — and the working tree is then the draft workspace. `github` and
+     * `gitlab` publish through the provider's API, with saves staged in the
+     * draft store until an editor publishes.
+     */
+    REPOSITORY: z.enum(["local", "github", "gitlab"]).default("local"),
+    /** Where the content root sits *inside* the remote repository. */
+    REPOSITORY_ROOT: z.string().default("content"),
+    REPOSITORY_BRANCH: z.string().default("main"),
+    /** Token with write access to the content repository. */
+    REPOSITORY_TOKEN: z.string().optional(),
+    /** `owner/repo` for GitHub, `group/project` or a numeric id for GitLab. */
+    REPOSITORY_PROJECT: z.string().optional(),
+    /** For GitHub Enterprise or self-managed GitLab. */
+    REPOSITORY_API_BASE: z.string().url().optional(),
+    /**
+     * Whether working-tree staging may commit and push. `false` reduces Publish
+     * to autosave plus a read-only view of the pending changes.
+     */
+    MICA_LOCAL_PUBLISH: bool(true),
+    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. */
+    TRUST_PROXY: bool(false),
+    /** Extra browser origins allowed to call the admin API (dev Vite server). */
+    ADMIN_ORIGINS: z.string().optional(),
+    /** Overrides where the built admin SPA is served from. */
+    ADMIN_DIR: z.string().optional(),
+};
+const runtimeSchema = z.object(runtimeEnv);
+/**
+ * The derived values the runtime reads, on top of the parsed environment.
+ *
+ * Called from each app's own `transform`, so every composition derives them
+ * the same way and none forgets one.
+ */
+export function deriveRuntime(env) {
+    return {
+        ...env,
+        isProduction: env.NODE_ENV === "production",
+        contentRoot: path.resolve(env.CONTENT_ROOT),
+        adminOrigins: list(env.ADMIN_ORIGINS),
+    };
+}
+/**
+ * A remote repository needs to be told which one, and with what.
+ *
+ * Checked at startup rather than at the first save: a Mica that starts, shows
+ * the editor their content, and only fails when they press Save has already
+ * wasted their work.
+ */
+export function requireRepositoryConfig(config) {
+    if (config.REPOSITORY === "local")
+        return;
+    const needed = ["REPOSITORY_PROJECT", "REPOSITORY_TOKEN"].filter((key) => !config[key]);
+    if (needed.length > 0) {
+        throw new ConfigError(`REPOSITORY is "${config.REPOSITORY}", so ${needed.join(" and ")} must be set.\n` +
+            (config.REPOSITORY === "github"
+                ? "  REPOSITORY_PROJECT is owner/repo, and the token needs contents: write."
+                : "  REPOSITORY_PROJECT is group/project or a numeric id, and the token needs\n" +
+                    "  the write_repository scope."));
+    }
+}
+/**
+ * Folds `./.env` into the ambient environment.
+ *
+ * `process.loadEnvFile` leaves already-set variables alone, so a container's
+ * `environment:` block still beats a file that happened to be copied into the
+ * image.
+ */
+export function loadEnvFile() {
+    try {
+        process.loadEnvFile();
+    }
+    catch (error) {
+        // No `.env` is the normal case in production. Anything else — unreadable,
+        // malformed — is a real misconfiguration, and silently starting with
+        // default secrets is exactly the failure config exists to prevent.
+        if (error.code !== "ENOENT") {
+            throw new ConfigError(`Could not read .env: ${error.message}`);
+        }
+    }
+}
+/**
+ * An unset variable and one set to the empty string mean the same thing.
+ *
+ * `.env.example` ships blanks for the operator to fill in, and the docs say to
+ * copy it verbatim; without this, doing so reads as "the secret is a
+ * zero-length string" and the server refuses on the documented happy path.
+ */
+export function withoutBlanks(env) {
+    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) {
+    const details = error.issues
+        .map((issue) => `  ${issue.path.join(".") || "(root)"}: ${issue.message}`)
+        .join("\n");
+    return `Invalid environment configuration:\n${details}`;
+}
+//# sourceMappingURL=config.js.map

package/dist/config.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"config.js","sourceRoot":"","sources":["../src/config.ts"],"names":[],"mappings":"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"}