@mosetta/content 0.0.0-stage → 0.0.10

package/src/roots.ts

@@ -0,0 +1,105 @@
+// The project's ROOTS (ADR-0052): what every published page and prefab needs of the code, kept
+// beside the generation marker as `roots.json`. A page's entry names its root module (the ssr
+// engine follows it) and the modules its nodes reference where the server renders them; a
+// prefab's entry names the modules of its blocks. The site isolate is composed with the closure
+// of their union — the code of the published site, and nothing else — so a block the site uses
+// is in place before the first visit. Written by every publish and deletion; a store that keeps
+// no such file (dev) derives it from the live revisions when asked.
+//
+// A HINT, not a contract: a module missing from it (a library's prefab, a stale file) is learned
+// by recomposition at the first visit — a render never depends on the file being right.
+import type { ContentKind } from './model';
+
+export const ROOTS_PATH = 'roots.json';
+
+export interface IRootsEntry {
+  /** a page's root module (a prefab has none of its own on a page) */
+  readonly root?: string;
+  /** the component modules (and fallbacks) its server-rendered nodes reference */
+  readonly refs: readonly string[];
+}
+
+export interface IBlueprintManifest {
+  readonly v: 1;
+  readonly pages: Readonly<Record<string, IRootsEntry>>;
+  readonly prefabs: Readonly<Record<string, IRootsEntry>>;
+}
+
+export const EMPTY_ROOTS: IBlueprintManifest = { v: 1, pages: {}, prefabs: {} };
+
+interface INodeLike {
+  readonly reference?: unknown;
+  readonly fallback?: unknown;
+  readonly ssr?: unknown;
+  readonly lazy?: unknown;
+  readonly children?: readonly INodeLike[];
+}
+
+/** a module a render links: a component (prefab references are expanded, never linked) */
+const isLinkable = (ref: unknown): ref is string => typeof ref === 'string' && /_t_component_/.test(ref);
+
+/**
+ * The modules a subtree needs where the server renders it — the rule the server's closure
+ * follows: a branch marked `ssr: false` or a lazy one is the browser's.
+ */
+function serverRefsOf(node: INodeLike, refs: Set<string>): void {
+  if (node.ssr === false || node.lazy === true) return;
+  if (isLinkable(node.reference)) refs.add(node.reference);
+  if (isLinkable(node.fallback)) refs.add(node.fallback);
+  for (const child of node.children ?? []) serverRefsOf(child, refs);
+}
+
+/**
+ * The entry of one published document: a page's root and, when the page renders on the server
+ * (`ssr: true` on its root), the modules of its tree; a prefab's blocks (it renders within a page,
+ * so whatever page it lands in decides whether the server renders — its blocks are named either way).
+ */
+export function rootsEntryOf(kind: ContentKind, doc: unknown): IRootsEntry {
+  const refs = new Set<string>();
+  if (kind === 'prefabs') {
+    const root = (doc as { root?: INodeLike } | null)?.root;
+    for (const child of root?.children ?? []) serverRefsOf(child, refs);
+    if (root && isLinkable(root.fallback)) refs.add(root.fallback);
+    return { refs: [...refs].sort() };
+  }
+  const page = (doc ?? {}) as INodeLike;
+  const root = isLinkable(page.reference) ? page.reference : undefined;
+  if (page.ssr === true) serverRefsOf(page, refs);
+  else if (isLinkable(page.fallback)) refs.add(page.fallback);
+  return { ...(root ? { root } : {}), refs: [...refs].sort() };
+}
+
+/** the file with one entity's entry set (or removed, `entry` null) */
+export function withRootsEntry(file: IBlueprintManifest, kind: ContentKind, name: string, entry: IRootsEntry | null): IBlueprintManifest {
+  const own = { ...file[kind] };
+  if (entry) own[name] = entry;
+  else delete own[name];
+  return { ...file, [kind]: own };
+}
+
+/** a file as read — tolerant: anything malformed is no entry, never a failure */
+export function parseRoots(raw: unknown): IBlueprintManifest {
+  if (!raw || typeof raw !== 'object') return EMPTY_ROOTS;
+  const section = (value: unknown): Record<string, IRootsEntry> => {
+    const out: Record<string, IRootsEntry> = {};
+    if (!value || typeof value !== 'object') return out;
+    for (const [name, entry] of Object.entries(value as Record<string, unknown>)) {
+      const e = entry as { root?: unknown; refs?: unknown } | null;
+      if (!e || !Array.isArray(e.refs)) continue;
+      out[name] = { ...(isLinkable(e.root) ? { root: e.root } : {}), refs: e.refs.filter(isLinkable) };
+    }
+    return out;
+  };
+  const file = raw as { pages?: unknown; prefabs?: unknown };
+  return { v: 1, pages: section(file.pages), prefabs: section(file.prefabs) };
+}
+
+/** every module the published site names: the roots and the references, once each */
+export function referencesOfRoots(file: IBlueprintManifest): string[] {
+  const all = new Set<string>();
+  for (const entry of [...Object.values(file.pages), ...Object.values(file.prefabs)]) {
+    if (entry.root) all.add(entry.root);
+    for (const ref of entry.refs) all.add(ref);
+  }
+  return [...all].sort();
+}

package/src/schemas.ts

@@ -0,0 +1,122 @@
+// Zod schema FACTORIES. Zod is injected (the isolate glue carries
+// zod, monoliths stay lean) — this package has zero runtime deps. An action embeds these into its input
+// schema via `createSchema({ builder })`, so deep structural validation happens at the RPC boundary.
+import type { z as Z } from 'zod';
+import {
+  CANONICAL_REFERENCE_RE,
+  DRAFT_ID_RE,
+  ENTITY_NAME_RE,
+  IBlueprintNodeDoc,
+  PAGE_HISTORY_LIMIT,
+} from './model';
+
+export function createContentSchemas(z: typeof Z) {
+  const canonicalReference = z.string().regex(
+    CANONICAL_REFERENCE_RE,
+    'expected a canonical module reference (_ns_<ns>_t_<type>_n_<name>_v_<version>)',
+  );
+  const entityName = z.string().regex(ENTITY_NAME_RE, 'expected a lowerCamel alphanumeric entity name');
+  const revision = z.number().int().positive();
+  const draftId = z.string().regex(DRAFT_ID_RE, 'expected a draft id (lowercase alphanumeric/hyphen)');
+  const prefabType = z.enum(['page', 'unit']);
+  // what an editing action is about: a page, or a prefab (edited in a page's shape)
+  const contentKind = z.enum(['pages', 'prefabs']);
+  const revisionStatus = z.enum(['published', 'archived']);
+  const settings = z.record(z.string(), z.unknown());
+
+  // the working fields a DRAFT carries on top of its content (publish strips them); declared on
+  // the doc schemas for the same reason history is — zod strips unknown keys on save otherwise
+  const draftFields = {
+    seq: z.number().int().positive().optional(),
+    createdAt: z.string().optional(),
+    baseRev: z.number().int().positive().optional(),
+    title: z.string().max(200).optional(),
+  };
+
+  const treeNode: Z.ZodType<IBlueprintNodeDoc> = z.lazy(() => z.object({
+    id: z.string().min(1),
+    reference: canonicalReference,
+    children: z.array(treeNode),
+    slot: z.string().min(1).optional(),
+    settings: settings.optional(),
+    // effective-ssr flag (SSR epic stage 4) — zod strips unknown keys, so the field MUST be
+    // declared or every save silently loses it
+    ssr: z.boolean().optional(),
+    // a provider that links new blocks' fields of its type at once (the editor's, see the model)
+    autoBind: z.boolean().optional(),
+  }));
+
+  // what a page says about itself (head tags, list entries): declared so a save keeps it
+  const metaWords = {
+    title: z.string().max(300).optional(),
+    description: z.string().max(1000).optional(),
+  };
+  const pageMeta = z.object({
+    ...metaWords,
+    image: z.string().max(2000).optional(),
+    date: z.string().regex(/^\d{4}-\d{2}-\d{2}$/, 'date must be YYYY-MM-DD').optional(),
+    noindex: z.boolean().optional(),
+    category: z.string().regex(/^[a-z0-9][a-z0-9_-]{0,47}$/, 'category: lowercase letters, digits, - and _').optional(),
+    i18n: z.record(z.string().regex(/^[a-z]{2}(-[a-z]{2})?$/, 'a language code'), z.object(metaWords)).optional(),
+  });
+
+  // a prefab's open field: which block's which setting an instance sets, and what its form says
+  const prefabField = z.object({
+    node: z.string().min(1).max(200),
+    setting: z.string().regex(/^[A-Za-z][A-Za-z0-9]*$/, 'a setting name'),
+    label: z.string().min(1).max(100),
+  });
+  const prefabFields = z.array(prefabField).max(50);
+
+  const pageBody = z.object({
+    id: z.string().min(1),
+    reference: canonicalReference,
+    pattern: z.string().regex(/^\//, 'route pattern must start with /'),
+    meta: pageMeta.optional(),
+    fallback: canonicalReference.optional(),
+    devOnly: z.boolean().optional(),
+    settings: settings.optional(),
+    children: z.array(treeNode),
+    ssr: z.boolean().optional(),
+    // a prefab opened in the editor travels in a page's shape, its open fields along
+    fields: prefabFields.optional(),
+  });
+
+  const pageAction = z.object({
+    type: z.enum(['insert', 'remove', 'settings', 'ssr', 'paste', 'cut', 'move']),
+    nodeId: z.string().min(1),
+    reference: canonicalReference.optional(),
+  });
+
+  // history, redo and the draft fields are DECLARED here for the same reason ssr is: zod strips
+  // unknown keys, and every save would silently lose them otherwise. A snapshot is a page WITHOUT
+  // either stack — entries never nest. The page snapshot inside an entry may carry draft fields
+  // (they ride along in the working doc), hence `pageBody.extend(draftFields)` there.
+  const pageSnapshot = pageBody.extend(draftFields);
+  const pageDoc = pageSnapshot.extend({
+    history: z.array(z.object({ action: pageAction, before: pageSnapshot })).max(PAGE_HISTORY_LIMIT).optional(),
+    redo: z.array(z.object({ action: pageAction, after: pageSnapshot })).max(PAGE_HISTORY_LIMIT).optional(),
+  });
+
+  const prefabDoc = z.object({
+    root: treeNode,
+    fields: prefabFields.optional(),
+    attributes: z.record(z.string(), z.unknown()).optional(),
+    devOnly: z.boolean().optional(),
+    ...draftFields,
+    history: pageDoc.shape.history,
+    redo: pageDoc.shape.redo,
+  });
+
+  const meta = z.object({
+    live: z.number().int().positive().nullable(),
+    versions: z.record(z.string().regex(/^[1-9][0-9]*$/), revisionStatus),
+    names: z.record(z.string().regex(/^[1-9][0-9]*$/), z.string().max(80)).optional(),
+    type: prefabType.optional(),
+    locked: z.boolean().optional(),
+  });
+
+  return { canonicalReference, entityName, revision, draftId, prefabType, contentKind, revisionStatus, treeNode, pageDoc, prefabDoc, meta };
+}
+
+export type ContentSchemas = ReturnType<typeof createContentSchemas>;

package/src/transport.ts

@@ -0,0 +1,142 @@
+// Content transport (generalizes the earlier write-only content store).
+// NOT an ambient framework capability — the framework/glue registers nothing writable. A TRUSTED module
+// (the editor) opts IN by adding a transport implementation to its `services`; an ordinary module has no
+// transport (injecting the token throws → no write access blessed by default). Prod: an S3 transport
+// gated by a store-access secret from a secret store (deferred — just the seam).
+import { DiInject, DiService, SingleDiToken } from '@mosetta/di';
+import { PROVIDER_ORIGIN_TOKEN, PROVIDERS_TOKEN } from '@mosetta/server-action/server';
+import { StoreConnectors, parseStoreConnectors } from '@mosetta/stores';
+import type { IStoreConnector, ConnectorHandle, StoreOp } from '@mosetta/stores';
+import { metaPath } from './paths';
+import type { ContentKind } from './model';
+
+export interface IContentTransport {
+  /** read a JSON document; null when it does not exist */
+  read(path: string): Promise<unknown>;
+  write(path: string, json: unknown): Promise<void>;
+  /**
+   * list names under a trailing-slash prefix: entity names for a kind prefix (`pages/`),
+   * draft ids for a drafts prefix (`pages/<name>/drafts/`)
+   */
+  list(prefix: string): Promise<string[]>;
+  /** delete a draft file or a whole entity folder */
+  delete(path: string): Promise<void>;
+  /** RAW object keys under a prefix (no domain reconstruction) — for the publish-marker folder */
+  keys(prefix: string): Promise<string[]>;
+}
+
+export const CONTENT_TRANSPORT_TOKEN = new SingleDiToken<IContentTransport>('CONTENT_TRANSPORT_TOKEN');
+
+// Thrown on non-ok transport responses; `status` lets the repository map the provider's state-machine
+// enforcement (409 = immutable revision) to a domain error.
+export class ContentTransportError extends Error {
+  constructor(
+    readonly status: number,
+    message: string,
+  ) {
+    super(message);
+  }
+}
+
+// DEV transport over the PROVIDER MODEL: providers arrive from the isolate ENV AS IS (including
+// the write entry — until a system of selective secret provisioning per module exists); without
+// them (old compositions) — fall back to the self-description descriptor. Selection is by the
+// REQUIRED operation; in prod only the connector changes.
+@DiService(CONTENT_TRANSPORT_TOKEN)
+export class DevContentTransport implements IContentTransport {
+  private readonly origin: string;
+
+  private readonly envProviders: readonly IStoreConnector[];
+
+  private readonly fetchImpl: typeof fetch;
+
+  private manager: Promise<StoreConnectors> | null = null;
+
+  constructor(
+    @DiInject(PROVIDER_ORIGIN_TOKEN)
+    providerOrigin: string,
+    @DiInject(PROVIDERS_TOKEN)
+    providers: readonly IStoreConnector[],
+  ) {
+    this.origin = providerOrigin.replace(/\/$/, '');
+    this.envProviders = providers;
+    // bind to globalThis — the global fetch must NOT be called as a method of `this` (workerd is strict).
+    this.fetchImpl = fetch.bind(globalThis);
+  }
+
+  async read(path: string): Promise<unknown> {
+    const res = await (await this.handle('get')).get(path);
+    if (res.status === 404) return null;
+    if (!res.ok) throw new ContentTransportError(res.status, `content read ${path} failed: ${res.status} ${await res.text()}`);
+    return res.json();
+  }
+
+  async write(path: string, json: unknown): Promise<void> {
+    const res = await (await this.handle('put')).put(path, JSON.stringify(json));
+    if (!res.ok) throw new ContentTransportError(res.status, `content write ${path} failed: ${res.status} ${await res.text()}`);
+    await res.arrayBuffer(); // body is unused, but the stream must be closed
+  }
+
+  // Names from an S3-style KEY listing (an honest `list`); the domain shape is reconstructed
+  // here: an ENTITY is a folder containing the meta file, a DRAFT is a json file under `drafts/`.
+  async list(prefix: string): Promise<string[]> {
+    const objects = await (await this.handle('list')).list(prefix);
+    if (prefix.endsWith('/drafts/')) {
+      return objects
+        .map((o) => o.key.slice(prefix.length))
+        .filter((rest) => /^[^/]+\.json$/.test(rest))
+        .map((rest) => rest.slice(0, -'.json'.length))
+        .sort();
+    }
+    const kind = prefix.replace(/\/$/, '') as ContentKind;
+    const keys = new Set(objects.map((o) => o.key));
+    const names = new Set<string>();
+    for (const o of objects) {
+      const seg = o.key.slice(prefix.length).split('/')[0];
+      if (seg && keys.has(metaPath(kind, seg))) names.add(seg);
+    }
+    return [...names].sort();
+  }
+
+  async keys(prefix: string): Promise<string[]> {
+    return (await (await this.handle('list')).list(prefix)).map((o) => o.key).sort();
+  }
+
+  /**
+   * A draft file by its path, or a whole ENTITY FOLDER. Two kinds of store answer the folder:
+   * dev's disk removes the directory with everything in it (and refuses its files one by one —
+   * metas and versions are immutable there), while an S3 store has no folders — only keys under
+   * a prefix — and answers a missing key with 204, deleting nothing (the page stayed in the
+   * production store with every file it had). So: the folder path first, then whatever is still
+   * listed under it, object by object — nothing on a disk, every file on S3.
+   */
+  async delete(path: string): Promise<void> {
+    await this.deleteKey(path);
+    if (path.endsWith('.json')) return;
+    const left = await (await this.handle('list')).list(`${path}/`);
+    for (const object of left) await this.deleteKey(object.key);
+  }
+
+  private async deleteKey(key: string): Promise<void> {
+    const res = await (await this.handle('delete')).delete(key);
+    if (res.status === 404) return; // already gone — deletion is idempotent
+    if (!res.ok) throw new ContentTransportError(res.status, `content delete ${key} failed: ${res.status} ${await res.text()}`);
+    await res.arrayBuffer();
+  }
+
+  private async handle(op: StoreOp): Promise<ConnectorHandle> {
+    this.manager ??= this.envProviders.length
+      ? Promise.resolve(new StoreConnectors(this.envProviders, this.fetchImpl))
+      : (async () => {
+        // fallback for compositions without an env projection: the self-description descriptor
+        // (it carries no credentials — against a locked-down dev such a transport can only do
+        // what is open)
+        const res = await this.fetchImpl(`${this.origin}/__mosetta__/providers`);
+        if (!res.ok) throw new ContentTransportError(res.status, `provider descriptor failed: ${res.status} ${await res.text()}`);
+        return new StoreConnectors(parseStoreConnectors(await res.json()), this.fetchImpl);
+      })();
+    const handle = (await this.manager).pick('content', op);
+    if (!handle) throw new ContentTransportError(501, `no content provider capable of "${op}"`);
+    return handle;
+  }
+}