@saacms/core 0.1.0

package/dist/codegen/to-d1-migration.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"to-d1-migration.d.ts","sourceRoot":"","sources":["../../src/codegen/to-d1-migration.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4CG;AAIH,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,oBAAoB,CAAA;AAqFvD;;;;;;;;;;GAUG;AACH,wBAAgB,gBAAgB,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAErD;AAsBD,mGAAmG;AACnG,wBAAgB,eAAe,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CASpD;AAED;;;;;GAKG;AACH,wBAAgB,2BAA2B,CACzC,KAAK,EAAE,aAAa,CAAC;IAAE,QAAQ,CAAC,IAAI,EAAE,kBAAkB,CAAA;CAAE,CAAC,GAC1D,IAAI,CAgBN;AAED,KAAK,kBAAkB,GAAG,aAAa,CAAC,MAAM,CAAC,CAAA;AA+E/C;;;;;;GAMG;AACH,wBAAgB,mBAAmB,CAAC,IAAI,EAAE,aAAa,GAAG,MAAM,CAqD/D;AAED;;;;;;GAMG;AACH,wBAAgB,oBAAoB,CAClC,KAAK,EAAE,aAAa,CAAC,aAAa,CAAC,GAClC,MAAM,CAMR"}

package/dist/codegen/to-drizzle.d.ts

@@ -0,0 +1,131 @@
+/**
+ * Schema → Drizzle table projection per ADR 0005 (Effect Schema is the single
+ * source of truth) and ADR 0024 (v1 alpha targets D1/SQLite, so we emit
+ * `drizzle-orm/sqlite-core` tables).
+ *
+ * One function:
+ *   - `schemaToDrizzle(slug, schema)` — projects an Effect Schema struct to a
+ *     Drizzle SQLite table with auto-injected `id`, `createdAt`, `updatedAt`.
+ *
+ * --------------------------------------------------------------------
+ * Annotation namespace (saacms-prefixed; mirrors `to-openapi.ts` convention)
+ * --------------------------------------------------------------------
+ *
+ * The following Effect-Schema annotations are recognised on per-property AST
+ * nodes (read with `.annotations({ ... })`). All keys are saacms-prefixed
+ * strings (per ADR 0005 §Consequences — "Annotation collision avoidance").
+ *
+ *   `saacmsRef: <CollectionSlug>` — marks a `Schema.String` field as a foreign
+ *      key to another Collection's `id` column. v1 emits a Drizzle `references`
+ *      callback that resolves through an internal placeholder registry (the
+ *      foreign Collection's table doesn't have to be in scope at projection
+ *      time — the codegen-CLI assembler swaps the placeholder for the real
+ *      table later). Cascading delete defaults to `cascade` per task spec
+ *      (most natural for saacms); override later via a config knob if needed.
+ *
+ *   `saacmsInt: true` — narrows a `Schema.Number` field from `real` (SQLite
+ *      REAL / IEEE-754 double) to `integer`. Use when the field is logically
+ *      an integer count (e.g. `views`, `priority`).
+ *
+ *   `saacmsLength: number` — max length on a `Schema.String`. SQLite stores
+ *      TEXT regardless, but Drizzle's text builder accepts a `length` config
+ *      for dialect dialects that honour it; harmless on SQLite, useful when
+ *      the same Schema is reprojected for postgres/mysql in v1.x.
+ *
+ *   `saacmsRefOnDelete: "cascade" | "restrict" | "set null" | "no action"` —
+ *      overrides the default `cascade` behaviour for a `saacmsRef` field.
+ *
+ * --------------------------------------------------------------------
+ * AST-walking decisions (callable out for review)
+ * --------------------------------------------------------------------
+ *
+ * 1. The root schema MUST be a `TypeLiteral` (i.e. `Schema.Struct({...})`).
+ *    Suspended / refined / union root schemas throw — we want a single canonical
+ *    table shape per Collection.
+ *
+ * 2. A field is treated as nullable (omit `.notNull()`) when EITHER
+ *      a) the PropertySignature has `isOptional: true` (i.e. `key?:` in the
+ *         encoded type), OR
+ *      b) the property's type is a `Union` containing `UndefinedKeyword` or
+ *         `NullKeyword`.
+ *    Both are produced by `Schema.optional(X)` / `Schema.NullOr(X)`. We strip
+ *    those wrappers to get the inner "data" type before mapping to a column.
+ *
+ * 3. `Refinement` wrappers (e.g. `Schema.String.pipe(Schema.minLength(1))`)
+ *    are walked through — we look at `refinement.from` recursively until we
+ *    hit a non-refinement. SQLite has no `CHECK length(x) >= 1` enforced by
+ *    Drizzle's column builder; the validation lives in the Effect Schema and
+ *    runs at the application boundary (per ADR 0005).
+ *
+ * 4. `Schema.Array(X)` becomes `text(name, { mode: "json" })` for v1. Dedicated
+ *    junction tables (the structurally-correct projection) are deferred — JSON
+ *    column is the pragmatic SQLite default and matches what every CMS that
+ *    targets D1 ships today.
+ *
+ * 5. `Schema.Date` / `Schema.DateFromSelf` are detected by Effect's identifier
+ *    annotation (`getIdentifierAnnotation(ast) === "DateFromSelf"`). Both
+ *    project to `integer(name, { mode: "timestamp" })` — SQLite stores Unix
+ *    seconds, Drizzle hydrates to JS `Date`.
+ *
+ * 6. Annotations are read off the inner data type's annotations (after
+ *    union-stripping). `Schema.optional(Schema.String.annotations({saacmsRef: "x"}))`
+ *    works; the annotation is on the String, not on the optional wrapper.
+ *
+ * 7. The synthetic `id`, `createdAt`, `updatedAt` columns are ALWAYS injected
+ *    and override any user-defined columns of the same name. Logged in dev as
+ *    a TODO when collision is detected (left for the codegen-CLI assembler).
+ *
+ * --------------------------------------------------------------------
+ * Foreign-key resolution (placeholder registry)
+ * --------------------------------------------------------------------
+ *
+ * Drizzle's `references(callback, actions)` takes a thunk returning a real
+ * `SQLiteColumn`. At projection time the foreign Collection's table object
+ * may not exist yet (chicken-and-egg when both Collections reference each
+ * other). We resolve this with a per-projection placeholder map:
+ *
+ *   - First time we see `saacmsRef: "users"`, we synthesize a stub
+ *     `usersPlaceholder = sqliteTable("users", { id: text("id").primaryKey() })`
+ *     and cache it.
+ *   - The reference thunk returns `usersPlaceholder.id`.
+ *   - The codegen-CLI assembler (when it eventually merges all real tables)
+ *     replaces placeholders with actual table refs. For v1 unit-test
+ *     purposes, `getTableConfig(...).foreignKeys[i].reference()` returns a
+ *     well-formed `{ foreignTable, foreignColumns }` shape with the right
+ *     table NAME, which is what tests assert against.
+ */
+import type { Schema } from "effect";
+/**
+ * Project an Effect Schema struct to a Drizzle SQLite table.
+ *
+ * Auto-injects `id` (text PK), `createdAt`, `updatedAt` (integer timestamps
+ * with default `() => new Date()`).
+ *
+ * @param slug   — the Collection slug (also used as the table name)
+ * @param schema — an `effect/Schema` whose root is a `Schema.Struct({...})`
+ */
+export declare function schemaToDrizzle<TSchema extends Schema.Schema<any, any, any>>(slug: string, schema: TSchema): import("drizzle-orm/sqlite-core").SQLiteTableWithColumns<{
+    name: string;
+    schema: undefined;
+    columns: {
+        [x: string]: import("drizzle-orm/sqlite-core").SQLiteColumn<{
+            name: string;
+            tableName: string;
+            dataType: import("drizzle-orm").ColumnDataType;
+            columnType: string;
+            data: unknown;
+            driverParam: unknown;
+            notNull: false;
+            hasDefault: false;
+            isPrimaryKey: false;
+            isAutoincrement: false;
+            hasRuntimeDefault: false;
+            enumValues: string[] | undefined;
+            baseColumn: never;
+            identity: undefined;
+            generated: undefined;
+        }, object>;
+    };
+    dialect: "sqlite";
+}>;
+//# sourceMappingURL=to-drizzle.d.ts.map

package/dist/codegen/to-drizzle.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"to-drizzle.d.ts","sourceRoot":"","sources":["../../src/codegen/to-drizzle.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+FG;AAEH,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,QAAQ,CAAA;AAsLpC;;;;;;;;GAQG;AACH,wBAAgB,eAAe,CAAC,OAAO,SAAS,MAAM,CAAC,MAAM,CAAC,GAAG,EAAE,GAAG,EAAE,GAAG,CAAC,EAC1E,IAAI,EAAE,MAAM,EACZ,MAAM,EAAE,OAAO;;;;;;;;;;;;;;;;;;;;;;;GAuChB"}

package/dist/codegen/to-openapi.d.ts

@@ -0,0 +1,80 @@
+/**
+ * Schema → OpenAPI projections per ADR 0005 (Schema is the source) and
+ * ADR 0018 (the API design contract every endpoint follows).
+ *
+ * Two functions:
+ *   - `schemaToOpenApiSchema(schema)` — projects an Effect Schema to an
+ *     OpenAPI 3.1 Schema Object (also a JSON Schema 2020-12 document, since
+ *     OAS 3.1 aligns with that JSON Schema dialect).
+ *   - `collectionToOpenApiPaths(coll, opts?)` — emits the canonical CRUD path
+ *     set for a Collection, ETag/Idempotency-Key/If-Match conventions,
+ *     Problem Details error responses, and tags.
+ *
+ * Implementation notes (edge-case decisions made here, callable out for review):
+ *
+ * 1. We pass `target: "openApi3.1"` to Effect's `JSONSchema.make`. That dialect
+ *    aligns with JSON Schema 2020-12 (OAS 3.1's chosen dialect — see OAS 3.1
+ *    §4.7.24.5), so the output is already OpenAPI-shaped: it uses
+ *    `type: ["string","null"]` arrays for nullable rather than the OAS 3.0
+ *    `nullable: true` keyword. We do NOT post-translate to 3.0; we target 3.1.
+ *
+ * 2. Effect Schema annotation surfacing: we walk the AST and, for each
+ *    PropertySignature, read three saacms-namespaced annotations (`saacmsLabel`,
+ *    `saacmsHelp`, `saacmsFormat`) plus the standard Effect annotations
+ *    (`title`, `description`, `examples`). We project them onto the matching
+ *    `properties[name]` slot in the emitted Schema Object. `saacmsLabel` wins
+ *    over `title` for `description` (it's the human label intended for forms);
+ *    `saacmsHelp` falls back to existing `description`; `saacmsFormat` overrides
+ *    `format`.
+ *
+ * 3. `cookieAuth` and `bearerAuth` security schemes are *referenced* on every
+ *    operation; their `components.securitySchemes` definitions are NOT emitted
+ *    here. The runtime layer that assembles the full OpenAPI document attaches
+ *    those scheme definitions (Better Auth cookie + JWT bearer per ADR 0008).
+ *    TODO(runtime-assembler): wire securitySchemes when ADR 0008 lands.
+ *
+ * 4. Per ADR 0006, this generator emits the FULL spec for the Collection (every
+ *    field, every verb). The runtime layer that returns `/api/openapi.json` per
+ *    user calls into this output and then prunes routes/fields the user can't
+ *    reach. The pruning is intentionally NOT done here so this projection stays
+ *    a pure function of the Schema and CollectionDef (deterministic, cacheable,
+ *    snapshot-testable).
+ *
+ * 5. Tag policy: one tag per Collection, equal to the Collection slug. Lets
+ *    typed-client generators (`openapi-typescript`, `orval`, etc.) group SDK
+ *    methods by Collection.
+ */
+import { Schema } from "effect";
+import type { CollectionDef, AnySchema } from "../schema/index.ts";
+import type { OpenAPIPathsObject, OpenAPISchemaObject } from "./openapi-types.ts";
+/**
+ * Pure pre-pass: returns a Schema equivalent to `schema` except every
+ * date-class field projects to `{ type: "string", format: "date-time" }`
+ * under `JSONSchema.make`. General over property path (top-level, nested
+ * struct, array items, union members, optional fields). Idempotent.
+ */
+export declare function normalizeDateSchemas(schema: Schema.Schema<any, any, any>): Schema.Schema<any, any, any>;
+/**
+ * Project an Effect Schema to an OpenAPI 3.1 Schema Object.
+ *
+ * Uses Effect's first-class JSON Schema export (`JSONSchema.make` with
+ * `target: "openApi3.1"`) and post-processes per-property to surface saacms
+ * UI annotations (label / help text / format) into OpenAPI fields.
+ *
+ * Date-class fields are normalized to the canonical RFC 3339 date-time string
+ * form first (see `normalizeDateSchemas`) so the projection is total for any
+ * valid schema per ADR 0005.
+ */
+export declare function schemaToOpenApiSchema(schema: Schema.Schema<any, any, any>): OpenAPISchemaObject;
+export interface CollectionToOpenApiPathsOptions {
+    /** Per ADR 0018 §13 — defaults to `/api/saacms/v1`. */
+    readonly basePath?: string;
+}
+export interface CollectionToOpenApiPathsResult {
+    readonly paths: OpenAPIPathsObject;
+    readonly components: {
+        readonly schemas: Record<string, OpenAPISchemaObject>;
+    };
+}
+export declare function collectionToOpenApiPaths(coll: CollectionDef<AnySchema>, opts?: CollectionToOpenApiPathsOptions): CollectionToOpenApiPathsResult;
+//# sourceMappingURL=to-openapi.d.ts.map

package/dist/codegen/to-openapi.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"to-openapi.d.ts","sourceRoot":"","sources":["../../src/codegen/to-openapi.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6CG;AAEH,OAAO,EAAc,MAAM,EAAa,MAAM,QAAQ,CAAA;AAEtD,OAAO,KAAK,EAAE,aAAa,EAAE,SAAS,EAAE,MAAM,oBAAoB,CAAA;AAClE,OAAO,KAAK,EAEV,kBAAkB,EAKlB,mBAAmB,EAEpB,MAAM,oBAAoB,CAAA;AA4Q3B;;;;;GAKG;AACH,wBAAgB,oBAAoB,CAClC,MAAM,EAAE,MAAM,CAAC,MAAM,CAAC,GAAG,EAAE,GAAG,EAAE,GAAG,CAAC,GACnC,MAAM,CAAC,MAAM,CAAC,GAAG,EAAE,GAAG,EAAE,GAAG,CAAC,CAE9B;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,qBAAqB,CACnC,MAAM,EAAE,MAAM,CAAC,MAAM,CAAC,GAAG,EAAE,GAAG,EAAE,GAAG,CAAC,GACnC,mBAAmB,CAUrB;AA8GD,MAAM,WAAW,+BAA+B;IAC9C,uDAAuD;IACvD,QAAQ,CAAC,QAAQ,CAAC,EAAE,MAAM,CAAA;CAC3B;AAED,MAAM,WAAW,8BAA8B;IAC7C,QAAQ,CAAC,KAAK,EAAE,kBAAkB,CAAA;IAClC,QAAQ,CAAC,UAAU,EAAE;QACnB,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,mBAAmB,CAAC,CAAA;KACtD,CAAA;CACF;AAED,wBAAgB,wBAAwB,CACtC,IAAI,EAAE,aAAa,CAAC,SAAS,CAAC,EAC9B,IAAI,GAAE,+BAAoC,GACzC,8BAA8B,CA+ChC"}

package/dist/codegen/to-puck-fields.d.ts

@@ -0,0 +1,109 @@
+/**
+ * Schema → Puck field-config projection per ADR 0011 (the visual editor renders
+ * fields off a Puck `fields` config object generated at build time from the
+ * Effect Schema). One function:
+ *
+ *   - `schemaToPuckFields(coll)` — walks the Collection's root Struct and
+ *     returns a `{ <fieldName>: PuckField }` map.
+ *
+ * --------------------------------------------------------------------
+ * Annotation namespace (saacms-prefixed; mirrors `to-drizzle.ts` convention)
+ * --------------------------------------------------------------------
+ *
+ * Recognised on the per-property data-type AST node (read with
+ * `.annotations({ ... })` on the inner Schema):
+ *
+ *   `saacmsLabel: string`     — UI label override; otherwise the camelCase JS
+ *      name is converted to Title Case (`publishedAt` → `Published At`).
+ *
+ *   `saacmsMultiline: true`   — narrows a `Schema.String` field from `text` to
+ *      `textarea` in the Puck UI.
+ *
+ *   `saacmsRadio: true`       — switches a `Schema.Literal(...)` string-literal
+ *      union from the default `select` to a `radio` field in the Puck UI.
+ *
+ * --------------------------------------------------------------------
+ * AST-walking decisions
+ * --------------------------------------------------------------------
+ *
+ * 1. The root schema MUST be a `TypeLiteral` (i.e. `Schema.Struct({...})`).
+ *    Suspended / refined / union root schemas throw — Puck's `fields` config
+ *    is shaped as a flat keyed map and presupposes a struct.
+ *
+ * 2. `Schema.optional(X)` and `Schema.Union(X, undefined|null)` are peeled
+ *    when the only remaining non-nullable member is a single type. A
+ *    string-literal union (`Literal("a") | Literal("b")`) is preserved as-is
+ *    so the select/radio detection sees the full member set.
+ *
+ *    Optionality is currently INVISIBLE to Puck at this layer per the brief —
+ *    Puck treats every field as optional UI-wise; the Effect Schema enforces
+ *    required-ness server-side on PUT/POST. So no marker is emitted.
+ *
+ * 3. `Refinement` wrappers (e.g. `Schema.minLength(1)`) are walked through —
+ *    we look at `refinement.from` recursively until we hit a non-refinement.
+ *    Puck has no constraint-validation hook at the field-config layer; the
+ *    refinement still runs server-side via the Schema.
+ *
+ * 4. `Schema.Array(Schema.Struct({...}))` becomes `{ type: "array", arrayFields }`.
+ *    `Schema.Array(scalar)` falls back to `{ type: "text" }` — Puck's array
+ *    field requires sub-`fields` (record-shaped), and a primitive-array UI
+ *    is deferred to v1.x.
+ *
+ * 5. Annotations live on the inner data-type node after union- and
+ *    refinement-stripping. `Schema.optional(Schema.String.annotations({...}))`
+ *    works identically to a non-optional annotated string.
+ *
+ * 6. Anything we don't recognise (union of non-literal types, arbitrary
+ *    transformations, …) falls back to `{ type: "text" }`. The codegen-CLI
+ *    surfaces this as a warning at build time.
+ */
+import type { CollectionDef } from "../schema/index.ts";
+export interface PuckFields {
+    readonly [name: string]: PuckField;
+}
+export type PuckField = {
+    readonly type: "text";
+    readonly label?: string;
+} | {
+    readonly type: "textarea";
+    readonly label?: string;
+} | {
+    readonly type: "number";
+    readonly label?: string;
+} | {
+    readonly type: "select";
+    readonly label?: string;
+    readonly options: ReadonlyArray<{
+        readonly label: string;
+        readonly value: string;
+    }>;
+} | {
+    readonly type: "radio";
+    readonly label?: string;
+    readonly options: ReadonlyArray<{
+        readonly label: string;
+        readonly value: string;
+    }>;
+} | {
+    readonly type: "array";
+    readonly label?: string;
+    readonly arrayFields: PuckFields;
+} | {
+    readonly type: "object";
+    readonly label?: string;
+    readonly objectFields: PuckFields;
+};
+/**
+ * camelCase → "Camel Case". Splits on uppercase letters, capitalizes the
+ * first letter of each token. `"title"` → `"Title"`, `"publishedAt"` →
+ * `"Published At"`.
+ */
+export declare function defaultLabel(jsName: string): string;
+/**
+ * Project a Collection's Effect Schema struct to a Puck `fields` config.
+ *
+ * Returns a `{ <fieldName>: PuckField }` map keyed by the JS property name
+ * (camelCase), one entry per top-level property of the root struct.
+ */
+export declare function schemaToPuckFields(coll: CollectionDef): PuckFields;
+//# sourceMappingURL=to-puck-fields.d.ts.map

package/dist/codegen/to-puck-fields.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"to-puck-fields.d.ts","sourceRoot":"","sources":["../../src/codegen/to-puck-fields.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA0DG;AAIH,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,oBAAoB,CAAA;AAMvD,MAAM,WAAW,UAAU;IACzB,QAAQ,EAAE,IAAI,EAAE,MAAM,GAAG,SAAS,CAAA;CACnC;AAED,MAAM,MAAM,SAAS,GACjB;IAAE,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IAAC,QAAQ,CAAC,KAAK,CAAC,EAAE,MAAM,CAAA;CAAE,GAClD;IAAE,QAAQ,CAAC,IAAI,EAAE,UAAU,CAAC;IAAC,QAAQ,CAAC,KAAK,CAAC,EAAE,MAAM,CAAA;CAAE,GACtD;IAAE,QAAQ,CAAC,IAAI,EAAE,QAAQ,CAAC;IAAC,QAAQ,CAAC,KAAK,CAAC,EAAE,MAAM,CAAA;CAAE,GACpD;IACE,QAAQ,CAAC,IAAI,EAAE,QAAQ,CAAA;IACvB,QAAQ,CAAC,KAAK,CAAC,EAAE,MAAM,CAAA;IACvB,QAAQ,CAAC,OAAO,EAAE,aAAa,CAAC;QAAE,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;QAAC,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAA;KAAE,CAAC,CAAA;CACpF,GACD;IACE,QAAQ,CAAC,IAAI,EAAE,OAAO,CAAA;IACtB,QAAQ,CAAC,KAAK,CAAC,EAAE,MAAM,CAAA;IACvB,QAAQ,CAAC,OAAO,EAAE,aAAa,CAAC;QAAE,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;QAAC,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAA;KAAE,CAAC,CAAA;CACpF,GACD;IAAE,QAAQ,CAAC,IAAI,EAAE,OAAO,CAAC;IAAC,QAAQ,CAAC,KAAK,CAAC,EAAE,MAAM,CAAC;IAAC,QAAQ,CAAC,WAAW,EAAE,UAAU,CAAA;CAAE,GACrF;IAAE,QAAQ,CAAC,IAAI,EAAE,QAAQ,CAAC;IAAC,QAAQ,CAAC,KAAK,CAAC,EAAE,MAAM,CAAC;IAAC,QAAQ,CAAC,YAAY,EAAE,UAAU,CAAA;CAAE,CAAA;AAwE3F;;;;GAIG;AACH,wBAAgB,YAAY,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,CAOnD;AAkGD;;;;;GAKG;AACH,wBAAgB,kBAAkB,CAAC,IAAI,EAAE,aAAa,GAAG,UAAU,CAWlE"}

package/dist/codegen/to-ts-types.d.ts

@@ -0,0 +1,59 @@
+/**
+ * Schema → TypeScript client-types projection per ADR 0005 (Effect Schema is
+ * the single source of truth). Two functions:
+ *
+ *   - `schemaToTsType(coll)`   — projects ONE Collection's root Struct to an
+ *     `export interface <PascalCaseSlug> { ... }` source string.
+ *   - `schemaToTsTypes(colls)` — joins many with a blank line, prefixed once
+ *     by a `// generated by saacms — do not edit` header.
+ *
+ * This is the hand-editable client-types artefact `saacms codegen` writes to
+ * `.saacms/types/<slug>.ts`. It agrees with `to-drizzle.ts` /
+ * `to-d1-migration.ts` on field names, auto-injected columns, and the order
+ * convention (id first, user fields in declared order, createdAt/updatedAt
+ * last).
+ *
+ * --------------------------------------------------------------------
+ * Annotation namespace (saacms-prefixed; mirrors `to-d1-migration.ts`)
+ * --------------------------------------------------------------------
+ *
+ *   `saacmsTsName: string` — override the emitted TS property name (rare;
+ *      for when the DB column and the TS field intentionally differ, e.g. an
+ *      `authorId` column surfaced as `authorRef` client-side). Read on the
+ *      inner data-type node after optional/refinement stripping.
+ *
+ * --------------------------------------------------------------------
+ * Type mapping (Effect Schema → TS source)
+ * --------------------------------------------------------------------
+ *
+ *   - `Schema.String`                     → `string`
+ *   - `Schema.Number`                     → `number`
+ *   - `Schema.Boolean`                    → `boolean`
+ *   - `Schema.Literal("a","b")`           → `"a" | "b"`
+ *   - `Schema.Date` / DateFromString      → `string` (ISO-8601)
+ *   - `Schema.Array(X)`                   → `<TS-of-X>[]` (recurse)
+ *   - nested `Schema.Struct({...})`       → inline `{ a: string; b: number }`
+ *   - `Schema.optional(X)` / Union(X,⊥)   → optional KEY (`name?: <TS-of-X>`),
+ *                                            never `| undefined` in the value
+ *   - `Union(X, null)`                    → `<TS-of-X> | null` (key NOT optional)
+ *   - unrecognised shape                  → `unknown` (graceful fallback; the
+ *                                            codegen-CLI surfaces a warning)
+ *
+ * Refinements (`Schema.minLength` etc.) are unwrapped to their base type — TS
+ * has no refinement types; the constraint still runs server-side via Schema.
+ */
+import type { CollectionDef } from "../schema/index.ts";
+/**
+ * Project a Collection's Effect Schema struct to an `export interface` source
+ * string. Auto-injected fields mirror `to-d1-migration.ts`: `id` first, then
+ * the user fields in declared order, then `createdAt` / `updatedAt` last (all
+ * ISO strings).
+ */
+export declare function schemaToTsType(coll: CollectionDef): string;
+/**
+ * Project an ordered list of Collections to a single TS source file: one
+ * `// generated by saacms — do not edit` header, then each interface
+ * separated by a blank line.
+ */
+export declare function schemaToTsTypes(colls: ReadonlyArray<CollectionDef>): string;
+//# sourceMappingURL=to-ts-types.d.ts.map

package/dist/codegen/to-ts-types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"to-ts-types.d.ts","sourceRoot":"","sources":["../../src/codegen/to-ts-types.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2CG;AAIH,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,oBAAoB,CAAA;AAuLvD;;;;;GAKG;AACH,wBAAgB,cAAc,CAAC,IAAI,EAAE,aAAa,GAAG,MAAM,CAyB1D;AAED;;;;GAIG;AACH,wBAAgB,eAAe,CAC7B,KAAK,EAAE,aAAa,CAAC,aAAa,CAAC,GAClC,MAAM,CAER"}

package/dist/hooks/index.d.ts

@@ -0,0 +1,94 @@
+/**
+ * Effect-returning lifecycle hooks per ADR 0013.
+ *
+ * Hooks attach to Collections, Blocks, and Pages. Command-phase hooks (the
+ * `before*` family) can mutate data and cancel the operation via `Effect.fail`.
+ * Event-phase hooks (the `after*` family) run best-effort by default; failures
+ * are observable but non-blocking unless `failOnError` is set.
+ */
+import type { Schema } from "effect";
+import { Effect } from "effect";
+import type { User } from "../types/user.ts";
+export type CollectionHookMoment = "beforeValidate" | "beforeChange" | "afterChange" | "beforeRead" | "afterRead" | "beforeDelete" | "afterDelete" | "beforePublish" | "afterPublish";
+export type BlockHookMoment = "beforeRender" | "afterRender";
+export type PageHookMoment = "beforePublish" | "afterPublish";
+export type HookMoment = CollectionHookMoment | BlockHookMoment | PageHookMoment;
+export type HookOp = "create" | "update" | "delete" | "read" | "publish" | "render";
+/**
+ * Argument passed to every hook. Typed against the target Collection/Block schema
+ * so the inferred `data` / `record` properties carry the right shape.
+ *
+ * For command-phase hooks `data` is the proposed new state; for event-phase
+ * hooks `record` is the state after the operation succeeded.
+ */
+export interface HookContext<TSchema extends Schema.Schema<any, any, any>> {
+    readonly op: HookOp;
+    readonly user: User | null;
+    readonly data?: Schema.Schema.Type<TSchema>;
+    readonly record?: Schema.Schema.Type<TSchema>;
+    /** Free-form services container; populated by the runtime layer (Effect DI). */
+    readonly services?: Readonly<Record<string, unknown>>;
+}
+/**
+ * A hook is an Effect-returning function. The `R` (requirements) channel may
+ * carry user-declared service tags resolved by the runtime layer; we leave it
+ * `unknown` at the type boundary so both DI-using and DI-free hooks fit.
+ */
+export type HookFn<TSchema extends Schema.Schema<any, any, any>> = (ctx: HookContext<TSchema>) => Effect.Effect<unknown, unknown, unknown>;
+/**
+ * Per-hook configuration knobs (ADR 0013 §Shape).
+ * `failOnError` forces an `after*` hook to bubble failures to the caller.
+ * `queue` defers execution onto the platform queue (CF Queues / Vercel Queue).
+ */
+export interface HookOptions {
+    readonly failOnError?: boolean;
+    readonly queue?: boolean;
+}
+/** A resolved hook entry: function plus optional per-hook configuration. */
+export interface HookEntry<TSchema extends Schema.Schema<any, any, any>> {
+    readonly fn: HookFn<TSchema>;
+    readonly options?: HookOptions;
+}
+/**
+ * Run the resolved chain of hooks for a `moment` against `ctx`.
+ *
+ * `hooks` is pre-resolved (already filtered to the right moment, already in
+ * user-then-plugin order per ADR 0014 conflict resolution). Use
+ * {@link resolveHooksFor} to derive it from a `SaacmsConfig` slice.
+ *
+ * Command-phase moments (`before*`) compose sequentially via `Effect.flatMap`:
+ * any failure short-circuits and propagates; each hook sees a `ctx` whose
+ * `data` is the previous hook's success value (when that value is a
+ * non-undefined object), else the data is left untouched.
+ *
+ * Event-phase moments (`after*`) compose in parallel via `Effect.all` with
+ * `concurrency: "unbounded"`. Failures are warned to the console under the
+ * `[saacms/hooks]` prefix unless the entry sets `options.failOnError === true`,
+ * in which case the failure propagates.
+ *
+ * `options.queue: true` is a v1.x platform-queue marker — documented here but
+ * a no-op for this dispatch; `@saacms/plugin-queues` will pick this up and
+ * lift the hook onto the host's queue (CF Queues / Vercel Queue) in v1.x.
+ */
+export declare function runHooks<TSchema extends Schema.Schema<any, any, any>>(moment: HookMoment, ctx: HookContext<TSchema>, hooks: ReadonlyArray<HookEntry<TSchema>>): Effect.Effect<unknown, unknown, unknown>;
+/**
+ * Build the ordered hook chain for `moment` from a `SaacmsConfig` slice.
+ *
+ * Walks `source.collection.hooks[moment]` first, then each
+ * `source.plugins[i].hooks[moment]` in declaration order — matching ADR 0014
+ * §Conflict resolution (user wins, then plugins in listed order).
+ *
+ * Each `hooks[moment]` entry may be either a bare `HookFn` (wrapped as `{ fn }`)
+ * or a structured `{ fn, options? }` object. Anything else — strings, numbers,
+ * `undefined`, etc. — is silently skipped, since `hooks` is user-supplied data
+ * and a typo in a config file should not crash the runtime.
+ */
+export declare function resolveHooksFor<TSchema extends Schema.Schema<any, any, any>>(moment: HookMoment, source: {
+    readonly collection?: {
+        readonly hooks?: Record<string, unknown>;
+    };
+    readonly plugins?: ReadonlyArray<{
+        readonly hooks?: Record<string, unknown>;
+    }>;
+}): ReadonlyArray<HookEntry<TSchema>>;
+//# sourceMappingURL=index.d.ts.map

package/dist/hooks/index.d.ts.map

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

package/dist/hooks/index.js

@@ -0,0 +1,8 @@
+import {
+  resolveHooksFor,
+  runHooks
+} from "../index-zgbq60fy.js";
+export {
+  runHooks,
+  resolveHooksFor
+};

package/dist/host/index.d.ts

@@ -0,0 +1,109 @@
+/**
+ * Host adapter interface per ADRs 0001 (compile step + runtime), 0003 (per-host
+ * adapter responsibilities), and 0004 (per-block preview routes).
+ *
+ * One host adapter exists per host framework (`@saacms/host-nextjs`,
+ * `@saacms/host-sveltekit`, `@saacms/host-nuxt`, `@saacms/host-astro`). Each
+ * knows three things and only three things:
+ *
+ *   1. how to *generate* native route files in the host's idiom (compile step),
+ *   2. how to *mount* the saacms runtime handler at the host's API location,
+ *   3. how to *emit* per-block preview routes the Puck canvas can fetch.
+ *
+ * This interface is the seam at the Hosting bounded context (ADR 0020).
+ * Everything above it is host-agnostic; everything below it is host-specific.
+ */
+import type { Hono } from "hono";
+import type { PageDef, PageTemplateDef, BlockDef, RenderMode } from "../schema/index.ts";
+/** Cookie names for the theme signal; constant so all host adapters are aligned. */
+export declare const SCHEME_COOKIE: "saacms-scheme";
+export declare const DARK_MODE_COOKIE: "saacms-dark";
+/**
+ * No-FOUC theme-render contract (ADR 0033).
+ *
+ * A host adapter that supports themed SSR SHOULD implement this contract.
+ * saacms calls these methods during SSR to emit the active scheme's resolved
+ * token values into the initial document head before the body — zero flash,
+ * cache-correct.
+ *
+ * Contract only — concrete per-host emit is the named follow-up
+ * `theme-host-render`. An in-process conformance test proves correctness
+ * without a browser (same boundary discipline as the rest of the fleet).
+ */
+export interface ThemeRenderContract {
+    /**
+     * Read the active scheme ID and dark-mode preference from the request.
+     * Reads `saacms-scheme` (scheme ID) and `saacms-dark` ("1" = dark) cookies
+     * server-side. Returns `{ schemeId: null, darkMode: false }` when no cookies
+     * are set — zero JavaScript required; the server reads directly from headers.
+     */
+    resolveActiveScheme(req: Request): {
+        schemeId: string | null;
+        darkMode: boolean;
+    };
+    /**
+     * Emit the scheme's resolved token values as an inline `<style>` block
+     * targeting `:root`. The returned HTML string is injected into the document
+     * `<head>` before any external stylesheets so cascade order is preserved.
+     *
+     * @param tokens — map of CSS custom-property name → value (without `--` prefix).
+     */
+    emitThemeStyles(tokens: Record<string, string>): string;
+    /**
+     * Emit attribute markup for the document root element that identifies the
+     * active scheme and dark mode. Returns a string of HTML attributes
+     * (e.g. `data-theme="ocean" class="dark"`) to be placed on the `<html>` tag
+     * pre-body — the browser renders with the correct theme on the first paint.
+     */
+    emitThemeAttribute(schemeId: string, darkMode: boolean): string;
+}
+export interface GeneratedRoute {
+    /** Repo-relative output path the host expects (e.g. `app/blog/[slug]/page.tsx`). */
+    readonly path: string;
+    readonly contents: string;
+    /** Per ADR 0021 — the cache emitter records mode metadata for cache wiring. */
+    readonly mode?: RenderMode;
+}
+export interface GenerateRouteContext {
+    readonly page: PageDef | PageTemplateDef;
+    /** When the page is a template, the bound Collection slug. */
+    readonly boundCollection?: string;
+    /** Repo-absolute path to the host's route root (`app/`, `src/routes/`, …). */
+    readonly routeRoot: string;
+}
+export interface GeneratePreviewRouteContext {
+    readonly block: BlockDef;
+    /** Repo-absolute path to the host's route root. */
+    readonly routeRoot: string;
+}
+/**
+ * Returned from `mountTemplate` so `saacms init` can write the right ~3-line
+ * mount file in the host's conventional location (e.g.
+ * `app/api/saacms/[...slug]/route.ts` for Next.js).
+ */
+export interface MountTemplate {
+    /** Repo-relative path of the mount file the host adapter expects. */
+    readonly path: string;
+    /** File contents — typically a tiny re-export of the runtime handler. */
+    readonly contents: string;
+}
+export interface HostAdapter {
+    readonly name: string;
+    /** Generate native route file(s) for a Page or Page template. */
+    generateRoute(ctx: GenerateRouteContext): ReadonlyArray<GeneratedRoute>;
+    /**
+     * Generate the per-Block preview route the Puck canvas fetches in dev mode
+     * (ADR 0004). Returns `null` if the block doesn't need a preview route
+     * (e.g. WC-mode blocks that render entirely client-side).
+     */
+    generatePreviewRoute(ctx: GeneratePreviewRouteContext): GeneratedRoute | null;
+    /** Repo-relative directory the host serves static assets from (`public/` / `static/`). */
+    readonly assetRoot: string;
+    /**
+     * Returns the mount-file template `saacms init` writes into the host repo.
+     * Receives the runtime app so the adapter can decide whether to import it
+     * lazily, wrap it in framework-specific request adapters, etc.
+     */
+    mountTemplate(runtime: Hono): MountTemplate;
+}
+//# sourceMappingURL=index.d.ts.map

package/dist/host/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/host/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAEH,OAAO,KAAK,EAAE,IAAI,EAAE,MAAM,MAAM,CAAA;AAChC,OAAO,KAAK,EAAE,OAAO,EAAE,eAAe,EAAE,QAAQ,EAAE,UAAU,EAAE,MAAM,oBAAoB,CAAA;AAMxF,oFAAoF;AACpF,eAAO,MAAM,aAAa,EAAG,eAAwB,CAAA;AACrD,eAAO,MAAM,gBAAgB,EAAG,aAAsB,CAAA;AAEtD;;;;;;;;;;;GAWG;AACH,MAAM,WAAW,mBAAmB;IAClC;;;;;OAKG;IACH,mBAAmB,CAAC,GAAG,EAAE,OAAO,GAAG;QAAE,QAAQ,EAAE,MAAM,GAAG,IAAI,CAAC;QAAC,QAAQ,EAAE,OAAO,CAAA;KAAE,CAAA;IAEjF;;;;;;OAMG;IACH,eAAe,CAAC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,GAAG,MAAM,CAAA;IAEvD;;;;;OAKG;IACH,kBAAkB,CAAC,QAAQ,EAAE,MAAM,EAAE,QAAQ,EAAE,OAAO,GAAG,MAAM,CAAA;CAChE;AAMD,MAAM,WAAW,cAAc;IAC7B,oFAAoF;IACpF,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAA;IACrB,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAA;IACzB,+EAA+E;IAC/E,QAAQ,CAAC,IAAI,CAAC,EAAE,UAAU,CAAA;CAC3B;AAED,MAAM,WAAW,oBAAoB;IACnC,QAAQ,CAAC,IAAI,EAAE,OAAO,GAAG,eAAe,CAAA;IACxC,8DAA8D;IAC9D,QAAQ,CAAC,eAAe,CAAC,EAAE,MAAM,CAAA;IACjC,8EAA8E;IAC9E,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAA;CAC3B;AAED,MAAM,WAAW,2BAA2B;IAC1C,QAAQ,CAAC,KAAK,EAAE,QAAQ,CAAA;IACxB,mDAAmD;IACnD,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAA;CAC3B;AAMD;;;;GAIG;AACH,MAAM,WAAW,aAAa;IAC5B,qEAAqE;IACrE,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAA;IACrB,yEAAyE;IACzE,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAA;CAC1B;AAMD,MAAM,WAAW,WAAW;IAC1B,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAA;IAErB,iEAAiE;IACjE,aAAa,CAAC,GAAG,EAAE,oBAAoB,GAAG,aAAa,CAAC,cAAc,CAAC,CAAA;IAEvE;;;;OAIG;IACH,oBAAoB,CAAC,GAAG,EAAE,2BAA2B,GAAG,cAAc,GAAG,IAAI,CAAA;IAE7E,0FAA0F;IAC1F,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAA;IAE1B;;;;OAIG;IACH,aAAa,CAAC,OAAO,EAAE,IAAI,GAAG,aAAa,CAAA;CAC5C"}

package/dist/host/index.js

@@ -0,0 +1,16 @@
+/**
+ * Host adapter interface per ADRs 0001 (compile step + runtime), 0003 (per-host
+ * adapter responsibilities), and 0004 (per-block preview routes).
+ *
+ * One host adapter exists per host framework (`@saacms/host-nextjs`,
+ * `@saacms/host-sveltekit`, `@saacms/host-nuxt`, `@saacms/host-astro`). Each
+ * knows three things and only three things:
+ *
+ *   1. how to *generate* native route files in the host's idiom (compile step),
+ *   2. how to *mount* the saacms runtime handler at the host's API location,
+ *   3. how to *emit* per-block preview routes the Puck canvas can fetch.
+ *
+ * This interface is the seam at the Hosting bounded context (ADR 0020).
+ * Everything above it is host-agnostic; everything below it is host-specific.
+ */
+export {};

package/dist/index-172n82sz.js

@@ -0,0 +1,4 @@
+// src/signals/index.ts
+import { signal, computed, effect } from "@preact/signals-core";
+
+export { signal, computed, effect };