@cardinali-studio/adminkit 2.2.23 → 2.2.25

package/LICENSE

@@ -0,0 +1,12 @@
+Copyright (C) 2026 Emanuele Cardinali
+
+Permission to use, copy, modify, and/or distribute this software for any
+purpose with or without fee is hereby granted.
+
+THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES WITH
+REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY
+AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY SPECIAL, DIRECT,
+INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM
+LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE OR
+OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR
+PERFORMANCE OF THIS SOFTWARE.

package/README.md

@@ -0,0 +1,213 @@
+# AdminKit
+
+AdminKit is the administration engine we use for small, content-driven websites built with Hugo and deployed on Cloudflare Pages.
+
+It turns a Zod schema into three things that must agree:
+
+- the model edited in the browser;
+- the YAML front matter stored in the repository;
+- the validation performed by the server.
+
+There is no second list of fields hidden in the UI, and no second serializer hidden in a Worker. A field is declared once. The rest of the system reads that declaration.
+
+The package also contains the React administration shell, a media library for R2, Cloudflare Pages Functions, and the persistence primitives used by the D1 publication path.
+
+## The important property
+
+An admin panel should not damage a file merely because it does not understand all of it.
+
+AdminKit preserves the Markdown body, unknown front-matter keys, and their comments. An omitted managed field means “leave it alone”, not “delete it”. Before overwriting an existing file, `checkFidelity()` can prove that reading and writing it again is byte-for-byte stable.
+
+If the codec cannot reproduce a file, it says so. Refusing a save is better than producing plausible-looking YAML with missing data.
+
+## Install
+
+```sh
+npm install @cardinali-studio/adminkit zod
+```
+
+The core codec needs Zod 4. The React application and form exports also use the optional peer dependencies listed in `package.json`; install the ones required by the entry points you use.
+
+The package is ESM-only.
+
+## A complete codec example
+
+Each field has two pieces of metadata:
+
+- `ui` describes how a human edits it;
+- `fm` describes how it lives in the file.
+
+```ts
+import * as z from "zod";
+import {
+  checkFidelity,
+  deserializeItem,
+  fm,
+  serializeItem,
+  ui,
+  yamlStr,
+} from "@cardinali-studio/adminkit";
+
+const Article = {
+  title: z.string().min(1).max(120)
+    .register(ui, {
+      label: "Title",
+      widget: "text",
+      group: "content",
+    })
+    .register(fm, {
+      keys: ["title"],
+      encode: (value) => [`title: ${yamlStr(value)}`],
+      decode: (raw) => String(raw.title ?? ""),
+    }),
+
+  published: z.boolean()
+    .register(ui, {
+      label: "Published",
+      widget: "boolean",
+      group: "visibility",
+    })
+    .register(fm, {
+      keys: ["visible"],
+      encode: (value) => [`visible: ${value === true}`],
+      decode: (raw) => raw.visible === true,
+    }),
+};
+
+const markdown = `---
+# Kept with the field.
+title: "A small page"
+visible: false
+
+# AdminKit does not own this key, so it stays untouched.
+build-note: "keep me"
+---
+The Markdown body stays untouched too.
+`;
+
+if (!checkFidelity(markdown, Article).ok) {
+  throw new Error("This file cannot be edited without loss");
+}
+
+const article = deserializeItem(markdown, Article);
+
+const updated = serializeItem(
+  { ...article, published: true },
+  { shape: Article, oldMd: markdown },
+);
+```
+
+Notice that the model calls the boolean `published` while the file calls it `visible`. That conversion belongs to the schema. Hugo templates, React components, and API handlers should not each invent their own version of it.
+
+### Deleting and retiring fields
+
+Absence is not deletion. To clear a value, pass the empty value understood by its encoder and return no YAML lines.
+
+When a key is obsolete, `retired(schema, keys)` keeps ownership of the old key while emitting nothing. Existing files then lose that key on their next intentional save, without maintaining a separate migration list.
+
+## Mounting the admin application
+
+The application is deliberately mounted as one unit:
+
+```ts
+import { mountAdmin, type SiteAdminConfig } from "@cardinali-studio/adminkit/app";
+import "@cardinali-studio/adminkit/theme.css";
+import "./site-theme.css";
+
+const site: SiteAdminConfig = {
+  // Site identity, page types, schemas, enabled modules and persistence mode.
+  // TypeScript checks the complete contract here.
+};
+
+mountAdmin({
+  site,
+  root: document.querySelector("#root"),
+  storagePrefix: "example-admin",
+});
+```
+
+Import the site's theme after AdminKit's theme. This lets a site replace the CSS custom properties without increasing selector specificity.
+
+`storagePrefix` is part of the site's browser data. Changing it on a live installation silently resets saved media preferences, so migrations should keep the old value.
+
+The shell currently speaks Italian. Content can be monolingual or multilingual; the language of the administration interface is a separate concern.
+
+## Cloudflare Pages Functions
+
+Cloudflare routes Functions by file, while an npm package cannot create files in a consuming project's `functions/` directory. A site therefore keeps two small adapters.
+
+The API catch-all:
+
+```js
+// functions/admin/api/[[path]].js
+import { handleAdminApi } from "@cardinali-studio/adminkit/functions";
+import { serverConfig } from "../../../src/admin/site-config.js";
+
+export function onRequest(context) {
+  return handleAdminApi(context, serverConfig);
+}
+```
+
+And the access middleware:
+
+```js
+// functions/admin/_middleware.js
+export { adminAccess as onRequest } from "@cardinali-studio/adminkit/functions";
+```
+
+Site-specific endpoints may live beside these files. More specific Cloudflare routes take precedence over the catch-all.
+
+The server configuration is site-owned. It supplies schemas, repository details, enabled modules, storage bindings and, in D1 mode, the complete document validator. Missing optional modules fail closed.
+
+## Persistence and publication
+
+The original persistence path writes Markdown through GitHub and lets Hugo build it. The newer path stores immutable revisions in D1 and publishes an exact release snapshot.
+
+The D1 modules are intentionally lower-level than the admin shell. They provide:
+
+- deterministic request checksums and idempotent saves;
+- compare-and-swap protection for concurrent drafts;
+- immutable, checksum-covered release exports;
+- a single deployment lane for code and content;
+- copy-first media moves and delete journals for R2;
+- versioned site-access secrets;
+- pure release materialization, with filesystem effects left to CI.
+
+They do not decide what a site's document means. Validation and materialization remain site-owned.
+
+## Entry points
+
+| Import | Purpose |
+| --- | --- |
+| `@cardinali-studio/adminkit` | Schema registries, front-matter codec, API client, i18n, persistence and release primitives |
+| `@cardinali-studio/adminkit/app` | Complete React administration shell |
+| `@cardinali-studio/adminkit/form` | Schema form and media components |
+| `@cardinali-studio/adminkit/functions` | Cloudflare Pages API router and access middleware |
+| `@cardinali-studio/adminkit/materializer` | Pure release-to-files materialization |
+| `@cardinali-studio/adminkit/preview` | Local preview component |
+| `@cardinali-studio/adminkit/testing` | Content-stability checks for consuming sites |
+| `@cardinali-studio/adminkit/theme.css` | Default design tokens |
+
+## What this is not
+
+AdminKit is not a generic headless CMS, a form builder, or a promise to support every YAML construct.
+
+It is opinionated about the useful narrow case: Hugo content, React 19, Zod 4, Cloudflare Pages, R2 and optionally D1. The front-matter emitter supports the structures used by that system and throws on values it cannot represent safely.
+
+This narrowness is intentional. A smaller system with explicit failure modes is easier to trust around content that people have edited by hand.
+
+## Development
+
+```sh
+npm test
+npm run build
+npm run check
+```
+
+`npm run check` rebuilds the package and runs the Node test suite. The tests include byte-identical codec round trips, malformed-input rejection, import resolution, concurrency conflicts, release invariants, media-operation transitions, and a guard against site-specific code entering the shared package.
+
+Generated files live in `dist/` and are the only application files included in the npm tarball, in addition to npm's standard package metadata and this README.
+
+## License
+
+[0BSD](./LICENSE). Use it, copy it, change it, ship it. Attribution is appreciated but not required.

package/dist/functions/_shared/d1-media.js

@@ -2,10 +2,10 @@
  * validator remains the authority for every draft revision generated by an
  * explicit Media operation. Git is never consulted from this module. */
 import {
-  canonicalChecksum, canonicalJson, contentSaveRequestChecksum, D1ContentRepository,
+  canonicalChecksum, contentSaveRequestChecksum, D1ContentRepository,
 } from "../../persistence.js";
 import {
-  D1MediaOperationRepository, mediaPublicUrl, prepareMediaCopy, rewriteMediaValue,
+  canonicalR2Metadata, D1MediaOperationRepository, mediaPublicUrl, prepareMediaCopy, rewriteMediaValue,
 } from "../../media.js";
 import { validateContentDocument } from "../site.js";
 import { isKey, moveToTrash, sanitizeName } from "./assets.js";
@@ -137,7 +137,7 @@ async function inspectSource(bucket, entry) {
     ...entry,
     objectChecksum,
     etag: object.etag ?? null,
-    metadataJson: canonicalJson({ httpMetadata: object.httpMetadata ?? {}, customMetadata: object.customMetadata ?? {} }),
+    metadataJson: canonicalR2Metadata(object.httpMetadata ?? {}, object.customMetadata ?? {}),
   };
 }
 

package/dist/media.d.ts

@@ -177,6 +177,9 @@ export type MediaR2Bucket = {
 };
 export type MediaPreparationJournal = Pick<D1MediaOperationRepository, "recordPreparedEntry">;
 export type MediaFinalizationJournal = Pick<D1MediaOperationRepository, "beginFinalization" | "recordFinalizedEntry">;
+/** Cloudflare may expose unset R2 metadata fields as enumerable `undefined`
+ * values. Persist the JSON-visible representation, not the runtime wrapper. */
+export declare function canonicalR2Metadata(httpMetadata?: MediaR2Object["httpMetadata"], customMetadata?: MediaR2Object["customMetadata"]): string;
 /** Copy-first R2 effect. No existing destination is overwritten: an identical
  * prior copy is an idempotent retry, while any opaque collision stops safely. */
 export declare function prepareMediaCopy(input: {

package/dist/media.js

@@ -449,6 +449,11 @@ export class D1MediaOperationRepository {
     }
 }
 const MEDIA_CHECKSUM_METADATA = "adminkit-sha256";
+/** Cloudflare may expose unset R2 metadata fields as enumerable `undefined`
+ * values. Persist the JSON-visible representation, not the runtime wrapper. */
+export function canonicalR2Metadata(httpMetadata = {}, customMetadata = {}) {
+    return canonicalJson(JSON.parse(JSON.stringify({ httpMetadata, customMetadata })));
+}
 async function bytesChecksum(bytes) {
     const digest = await crypto.subtle.digest("SHA-256", bytes);
     return Array.from(new Uint8Array(digest), (byte) => byte.toString(16).padStart(2, "0")).join("");
@@ -477,7 +482,7 @@ export async function prepareMediaCopy(input) {
     return input.journal.recordPreparedEntry({
         operationId: input.operationId, entryId: input.entryId, now: input.now, objectChecksum: checksum,
         etag: verified.etag ?? null,
-        metadataJson: canonicalJson({ httpMetadata: source.httpMetadata ?? {}, customMetadata: source.customMetadata ?? {} }),
+        metadataJson: canonicalR2Metadata(source.httpMetadata ?? {}, source.customMetadata ?? {}),
     });
 }
 /** Cleanup starts only after the release is published. Failures are recorded as

package/package.json

@@ -1,9 +1,9 @@
 {
   "name": "@cardinali-studio/adminkit",
-  "version": "2.2.23",
+  "version": "2.2.25",
   "type": "module",
   "description": "Motore riusabile di un pannello di amministrazione per siti Hugo su Cloudflare Pages: codec del front matter guidato dallo schema, form React, libreria media su R2. NIENTE di specifico di un sito qui dentro.",
-  "license": "UNLICENSED",
+  "license": "0BSD",
   "main": "./dist/index.js",
   "types": "./dist/index.d.ts",
   "exports": {