@abraca/schema 2.3.0

package/src/generated/slides.ts

@@ -0,0 +1,35 @@
+/**
+ * AUTO-GENERATED by @abraca/schema (slides).
+ *
+ * Source: ../types/slides.ts
+ * Run `pnpm schema:gen` to regenerate. Do not edit by hand —
+ * CI verifies that this file matches the generator output.
+ */
+
+import type * as Y from "yjs";
+import type { z } from "zod";
+import type { SlidesMeta } from "../types/slides.ts";
+
+export type DocTypeName = "slides";
+
+export type DocMetaMap = {
+	"slides": z.infer<typeof SlidesMeta>;
+};
+
+export type DocBodyMap = {
+	"slides": never;
+};
+
+export type DocChildrenMap = {
+	"slides": never;
+};
+
+export interface DocOf<N extends DocTypeName> {
+	readonly id: string;
+	readonly type: N;
+	readonly meta: DocMetaMap[N];
+	readonly body: DocBodyMap[N];
+	readonly children: ReadonlyArray<DocOf<DocChildrenMap[N]>>;
+}
+
+export type Doc = { [N in DocTypeName]: DocOf<N> }[DocTypeName];

package/src/generated/table.ts

@@ -0,0 +1,35 @@
+/**
+ * AUTO-GENERATED by @abraca/schema (table).
+ *
+ * Source: ../types/table.ts
+ * Run `pnpm schema:gen` to regenerate. Do not edit by hand —
+ * CI verifies that this file matches the generator output.
+ */
+
+import type * as Y from "yjs";
+import type { z } from "zod";
+import type { TableMeta } from "../types/table.ts";
+
+export type DocTypeName = "table";
+
+export type DocMetaMap = {
+	"table": z.infer<typeof TableMeta>;
+};
+
+export type DocBodyMap = {
+	"table": never;
+};
+
+export type DocChildrenMap = {
+	"table": never;
+};
+
+export interface DocOf<N extends DocTypeName> {
+	readonly id: string;
+	readonly type: N;
+	readonly meta: DocMetaMap[N];
+	readonly body: DocBodyMap[N];
+	readonly children: ReadonlyArray<DocOf<DocChildrenMap[N]>>;
+}
+
+export type Doc = { [N in DocTypeName]: DocOf<N> }[DocTypeName];

package/src/generated/timeline.ts

@@ -0,0 +1,35 @@
+/**
+ * AUTO-GENERATED by @abraca/schema (timeline).
+ *
+ * Source: ../types/timeline.ts
+ * Run `pnpm schema:gen` to regenerate. Do not edit by hand —
+ * CI verifies that this file matches the generator output.
+ */
+
+import type * as Y from "yjs";
+import type { z } from "zod";
+import type { TimelineMeta } from "../types/timeline.ts";
+
+export type DocTypeName = "timeline";
+
+export type DocMetaMap = {
+	"timeline": z.infer<typeof TimelineMeta>;
+};
+
+export type DocBodyMap = {
+	"timeline": never;
+};
+
+export type DocChildrenMap = {
+	"timeline": never;
+};
+
+export interface DocOf<N extends DocTypeName> {
+	readonly id: string;
+	readonly type: N;
+	readonly meta: DocMetaMap[N];
+	readonly body: DocBodyMap[N];
+	readonly children: ReadonlyArray<DocOf<DocChildrenMap[N]>>;
+}
+
+export type Doc = { [N in DocTypeName]: DocOf<N> }[DocTypeName];

package/src/index.ts

@@ -0,0 +1,389 @@
+/**
+ * @abraca/schema — public surface.
+ *
+ * The package exposes:
+ *   1. A small DSL (`defineDocType`, `defineSchema`, `ref`) for declaring
+ *      doc-types backed by Zod meta schemas.
+ *   2. CRDT primitive markers (`ytext`, `yarray`, `ymap`) — see `./crdt.ts`.
+ *   3. A library of independently-importable per-page-type schemas (see
+ *      `./types/`). Each file exports:
+ *        - the doc-type value (e.g. `Kanban`)
+ *        - the meta Zod schema (e.g. `KanbanMeta`)
+ *        - a single-type `SchemaRegistry` (e.g. `kanbanSchema`)
+ *      Consumers compose registries by hand:
+ *        `defineSchema({ types: [Kanban, Calendar, Doc] })`.
+ *   4. A shared `UniversalMeta` zod object for cross-cutting meta keys.
+ *
+ * No aggregate "all page types" schema is shipped — each app picks the
+ * subset it needs.
+ */
+
+import type { z, ZodType } from "zod";
+
+export { ytext, yarray, ymap, crdtMetaOf } from "./crdt.ts";
+export type { CrdtKind, CrdtMeta } from "./crdt.ts";
+
+export { UniversalMeta } from "./types/universal.ts";
+
+export {
+	META_COLUMNS,
+	WhereClauseSchema,
+	parseWhereClause,
+} from "./query.ts";
+export type { MetaColumn, WhereClause } from "./query.ts";
+
+export { Doc, DocMeta, docSchema } from "./types/doc.ts";
+export { Prose, ProseMeta, proseSchema } from "./types/prose.ts";
+export { Kanban, KanbanMeta, kanbanSchema } from "./types/kanban.ts";
+export { Gallery, GalleryMeta, gallerySchema } from "./types/gallery.ts";
+export { Table, TableMeta, tableSchema } from "./types/table.ts";
+export { Outline, OutlineMeta, outlineSchema } from "./types/outline.ts";
+export { Checklist, ChecklistMeta, checklistSchema } from "./types/checklist.ts";
+export { Graph, GraphMeta, graphSchema } from "./types/graph.ts";
+export { Timeline, TimelineMeta, timelineSchema } from "./types/timeline.ts";
+export { Calendar, CalendarMeta, calendarSchema } from "./types/calendar.ts";
+export { MapDocType, MapMeta, mapSchema } from "./types/map.ts";
+export { Dashboard, DashboardMeta, dashboardSchema } from "./types/dashboard.ts";
+export { Chart, ChartMeta, chartSchema } from "./types/chart.ts";
+export { Sheets, SheetsMeta, sheetsSchema } from "./types/sheets.ts";
+export { Slides, SlidesMeta, slidesSchema } from "./types/slides.ts";
+export { Overview, OverviewMeta, overviewSchema } from "./types/overview.ts";
+
+// ---------------------------------------------------------------------------
+// Plugin manifest validation — opt-in runtime validator for @abraca/plugin's
+// `PluginManifest` type. Used by the registry server, the plugin CLI, and
+// hosts that want defence-in-depth before instantiating external plugins.
+// ---------------------------------------------------------------------------
+
+export {
+	PluginManifestSchema,
+	PluginManifestAuthorSchema,
+	PluginManifestContributesSchema,
+	PluginCapabilitySchema,
+	PluginIdSchema,
+	SemverSchema,
+	SemverRangeSchema,
+	IntegritySchema,
+	RelativePathSchema,
+	PluginPricingSchema,
+	PluginVersionStatusSchema,
+	validatePluginManifest,
+} from "./manifest/plugin-manifest.ts";
+export type {
+	ManifestValidationIssue,
+	ManifestValidationResult,
+} from "./manifest/plugin-manifest.ts";
+
+// ---------------------------------------------------------------------------
+// Public types
+// ---------------------------------------------------------------------------
+
+/** A reference to another doc-type by name. Resolved at registry build time. */
+export interface DocTypeRef {
+	readonly __ref: string;
+}
+
+/** Declaration handed to {@link defineDocType}. */
+export interface DocTypeSpec<
+	Name extends string = string,
+	MetaSchema extends ZodType = ZodType,
+	BodySchema extends ZodType | undefined = ZodType | undefined,
+> {
+	readonly name: Name;
+	readonly version: number;
+	readonly meta: MetaSchema;
+	/**
+	 * Body slot — the document's primary content. Typically a CRDT marker
+	 * (`ytext()`, `yarray(...)`, `ymap(...)`) but can be any Zod schema for
+	 * documents whose body is read as a POJO snapshot.
+	 */
+	readonly body?: BodySchema;
+	/** Allowed child doc-types, by ref. */
+	readonly children?: ReadonlyArray<DocTypeRef>;
+	/** Reserved for Phase 2 — declarative permissions per field. */
+	readonly permissions?: Record<string, unknown>;
+	/**
+	 * Forward migrations between versions. Each entry's key is the
+	 * **source** version: `migrations[1]` migrates a v1 meta to v2.
+	 * `runMigrations` chains them up to `version`. Reserved versions
+	 * with no migration entry stop the chain; the meta is returned at
+	 * the highest version reached.
+	 */
+	readonly migrations?: {
+		readonly [fromVersion: number]: (oldMeta: any) => any;
+	};
+}
+
+/** Resolved doc-type after registry build. */
+export interface DocType<
+	Name extends string = string,
+	MetaSchema extends ZodType = ZodType,
+	BodySchema extends ZodType | undefined = ZodType | undefined,
+> extends DocTypeSpec<Name, MetaSchema, BodySchema> {
+	readonly __resolved: true;
+}
+
+export interface SchemaSpec {
+	readonly types: ReadonlyArray<DocType>;
+}
+
+/**
+ * Phantom meta-type witness on the registry. Carrying the meta map at the
+ * type level lets consumers (e.g. `provider.docs(schema).get(type, id)`)
+ * extract per-doc-type meta types via {@link DocMetaOf}/{@link DocTypeNameOf}
+ * without re-importing the source declarations.
+ *
+ * Default `Record<string, unknown>` keeps existing untyped consumers working
+ * unchanged (Rule 4).
+ */
+export interface SchemaRegistry<
+	TMap extends Record<string, unknown> = Record<string, unknown>,
+> {
+	readonly types: ReadonlyMap<string, DocType>;
+	get(name: string): DocType | undefined;
+	validateMeta(name: string, value: unknown): ValidationResult;
+	/**
+	 * Returns ok if `child` is allowed under `parent`, err otherwise.
+	 * `parent === null` means the document tree root — only doc-types
+	 * declared as root-eligible (none today; reserved) are accepted there.
+	 */
+	validateChildType(
+		parent: string | null,
+		child: string,
+	): ValidationResult;
+	/**
+	 * Phantom-only field. Exists for type-inference (`infer` patterns in
+	 * {@link DocTypeNameOf}/{@link DocMetaOf}). Always `undefined` at runtime.
+	 */
+	readonly __metaMap?: TMap;
+}
+
+/**
+ * Extract the doc-type names from a typed registry. Works against any
+ * `SchemaRegistry<TMap>` value.
+ */
+export type DocTypeNameOf<S> = S extends SchemaRegistry<infer M>
+	? keyof M & string
+	: never;
+
+/** Extract the meta type for a given doc-type name from a typed registry. */
+export type DocMetaOf<S, N extends string> = S extends SchemaRegistry<infer M>
+	? N extends keyof M
+		? M[N]
+		: never
+	: never;
+
+/**
+ * Internal: derive the meta-map type from a `SchemaSpec` so `defineSchema`
+ * can return `SchemaRegistry<MetaMapFor<typeof spec>>` and consumers get
+ * fully-inferred per-doc-type meta types at the call site.
+ */
+type MetaMapFor<S extends SchemaSpec> = {
+	[T in S["types"][number] as T["name"]]: T extends DocType<
+		string,
+		infer M extends ZodType
+	>
+		? z.infer<M>
+		: never;
+};
+
+export type ValidationResult =
+	| { ok: true; value: unknown }
+	| { ok: false; errors: ReadonlyArray<ValidationIssue> };
+
+export interface ValidationIssue {
+	readonly path: ReadonlyArray<PropertyKey>;
+	readonly message: string;
+	readonly code?: string;
+}
+
+// ---------------------------------------------------------------------------
+// Public API
+// ---------------------------------------------------------------------------
+
+/**
+ * Declare a doc-type. The returned value carries enough type information for
+ * downstream codegen and is a `DocType` once registered.
+ */
+export function defineDocType<
+	Name extends string,
+	MetaSchema extends ZodType,
+	BodySchema extends ZodType | undefined = undefined,
+>(
+	spec: DocTypeSpec<Name, MetaSchema, BodySchema>,
+): DocType<Name, MetaSchema, BodySchema> {
+	return { ...spec, __resolved: true };
+}
+
+/** Reference another doc-type by name. Resolution happens in {@link defineSchema}. */
+export function ref(name: string): DocTypeRef {
+	return { __ref: name };
+}
+
+/**
+ * Build a registry from a list of doc-types. Validates that all `ref(...)`
+ * targets exist; throws on dangling references.
+ *
+ * The returned registry carries a phantom `__metaMap` witness inferred from
+ * `spec`, so call sites like `provider.docs(schema).get("kanban", id)`
+ * see fully-typed meta even though the registry's runtime shape is generic.
+ */
+export function defineSchema<S extends SchemaSpec>(
+	spec: S,
+): SchemaRegistry<MetaMapFor<S>> {
+	const types = new Map<string, DocType>();
+	for (const t of spec.types) {
+		if (types.has(t.name)) {
+			throw new Error(`Duplicate doc-type name: ${t.name}`);
+		}
+		types.set(t.name, t);
+	}
+	for (const t of spec.types) {
+		for (const child of t.children ?? []) {
+			if (!types.has(child.__ref)) {
+				throw new Error(
+					`Doc-type "${t.name}" references unknown child doc-type "${child.__ref}"`,
+				);
+			}
+		}
+	}
+	return {
+		types,
+		get(name) {
+			return types.get(name);
+		},
+		validateChildType(parent, child) {
+			if (!types.has(child)) {
+				return {
+					ok: false,
+					errors: [{ path: [], message: `Unknown doc-type: ${child}` }],
+				};
+			}
+			if (parent === null) {
+				return {
+					ok: false,
+					errors: [
+						{
+							path: [],
+							message: `Doc-type "${child}" cannot be a root document — root-eligibility is reserved for Phase 2`,
+						},
+					],
+				};
+			}
+			const parentType = types.get(parent);
+			if (!parentType) {
+				return {
+					ok: false,
+					errors: [{ path: [], message: `Unknown parent doc-type: ${parent}` }],
+				};
+			}
+			const allowed = (parentType.children ?? []).some((c) => c.__ref === child);
+			if (allowed) {
+				return { ok: true, value: undefined };
+			}
+			return {
+				ok: false,
+				errors: [
+					{
+						path: [],
+						message: `Doc-type "${child}" is not an allowed child of "${parent}"`,
+					},
+				],
+			};
+		},
+		validateMeta(name, value) {
+			const t = types.get(name);
+			// Rule 4 (feedback_schema_free_core): doc-types not in this
+			// registry are unconstrained. Existing-app traffic for types the
+			// registry doesn't know about is never rejected — callers can
+			// check membership explicitly via `registry.get(name)` if they
+			// need strict semantics.
+			if (!t) {
+				return { ok: true, value };
+			}
+			const parsed = t.meta.safeParse(value);
+			if (parsed.success) {
+				return { ok: true, value: parsed.data };
+			}
+			return {
+				ok: false,
+				errors: parsed.error.issues.map((i) => ({
+					path: i.path,
+					message: i.message,
+					code: i.code,
+				})),
+			};
+		},
+	};
+}
+
+/**
+ * Apply forward migrations to a meta object.
+ *
+ * Reads `meta.__schemaVersion` (defaults to `1` if absent) and applies
+ * each `migrations[v]` from there up to the schema's declared `version`.
+ * Each migration function receives the previous version's meta and
+ * returns the next version's meta. The final value carries
+ * `__schemaVersion = <highest version reached>`.
+ *
+ * Behaviour:
+ * - **Unknown doc-type**: returns `meta` unchanged. Rule 4 — registries
+ *   only constrain the types they declare.
+ * - **No migrations declared**: returns `meta` unchanged. Useful for
+ *   freshly-introduced doc-types still at v1.
+ * - **Missing migration entry mid-chain**: stops at the highest
+ *   reachable version. Caller can detect by inspecting
+ *   `result.__schemaVersion` against `schema.get(typeName)?.version`.
+ * - **Non-object meta** (null, undefined, primitives): returns
+ *   unchanged. Migrations only operate on object meta.
+ *
+ * Migrations are pure: they receive a meta value and return a new
+ * one. They MUST NOT mutate the input (callers may pass shared
+ * references).
+ *
+ * @example
+ *   // v2 of kanban introduces a new required-shape `boardLayout` key.
+ *   const Kanban = defineDocType({
+ *     name: "kanban",
+ *     version: 2,
+ *     meta: KanbanMetaV2,
+ *     migrations: {
+ *       1: (oldMeta) => ({ ...oldMeta, boardLayout: "default" }),
+ *     },
+ *   });
+ *   const fresh = runMigrations(kanbanSchema, "kanban", { kanbanShowIcon: true });
+ *   // fresh.boardLayout === "default"
+ *   // fresh.__schemaVersion === 2
+ */
+export function runMigrations(
+	registry: SchemaRegistry,
+	typeName: string,
+	meta: unknown,
+): unknown {
+	if (meta === null || typeof meta !== "object") return meta;
+	const t = registry.get(typeName);
+	if (!t) return meta; // Rule 4
+	const target = t.version;
+	const migrations = t.migrations;
+
+	const m = meta as Record<string, unknown>;
+	let currentVersion: number =
+		typeof m.__schemaVersion === "number" && m.__schemaVersion >= 1
+			? m.__schemaVersion
+			: 1;
+	if (currentVersion >= target) return meta;
+	if (!migrations) return meta;
+
+	let working: unknown = meta;
+	let migrated = false;
+	while (currentVersion < target) {
+		const fn = migrations[currentVersion];
+		if (typeof fn !== "function") break;
+		working = fn(working);
+		currentVersion += 1;
+		migrated = true;
+	}
+	if (!migrated) return meta; // no migration ran → return original unchanged
+	if (working === null || typeof working !== "object") return working;
+	return { ...(working as Record<string, unknown>), __schemaVersion: currentVersion };
+}