@tideworthy/tidysites-platform 0.1.7 → 0.2.0

package/CHANGELOG.md

@@ -1,5 +1,9 @@
 # Changelog
 
+## 0.2.0
+
+- New route `POST /_tidy/fill`: real content over the template's sample content. Settings, entries upserted by slug with field-level merge over the existing entry, `$ref` and `$media` resolved as in a seed, and a `remove` list for sample entries the fill did not replace. Client gains `fill()`.
+
 ## 0.1.7
 
 - Bootstrap applies the seed with the site's configured storage, so `$media` references in a template seed are downloaded into the site's media library. Before this every seed photo was skipped with "no storage configured". The storage comes from EmDash's `virtual:emdash/config` and `virtual:emdash/storage` modules, the same way the setup wizard builds it.

package/README.md

@@ -86,6 +86,23 @@ The browser lands here. Signs the user in (an Astro session, exactly as EmDash's
 
 Replaces the platform API token. `{ "email": "...", "tokenName": "platform" }`. Both optional: with no email, the token's current owner is used. Returns `{ ok, userId, token }`.
 
+### `POST /_tidy/fill`
+
+Writes real content over the template's sample content on a bootstrapped site. Same document shape as a seed's `content` section, so `$ref:<id>` and `$media: { url, alt, filename }` resolve the same way (media is downloaded into the site's storage).
+
+```json
+{
+  "settings": { "title": "Romney Pest Control", "tagline": "Pest control on demand" },
+  "content": {
+    "services": [{ "id": "ant-control", "data": { "title": "Ant control", "summary": "…" } }],
+    "reviews": [{ "id": "google-1", "data": { "title": "Dana R.", "quote": "…", "rating": 5, "service": "$ref:ant-control" } }]
+  },
+  "remove": { "services": ["mosquito-treatment"], "posts": ["fire-ants-after-rain"] }
+}
+```
+
+Entries are upserted by slug (`slug` defaults to `id`). An existing entry keeps every field the document does not name, so a fill can send only what it knows and the template's images and blocks stay underneath. `remove` deletes the named sample entries; slugs written by the same call are never removed, and unknown slugs are reported back in `missing`. Refuses with 409 before bootstrap. Returns `{ ok, settings, content: { created, updated, media }, removed, missing }`. Re-running the same document is safe.
+
 ### `POST /_tidy/maintenance?cron=…`
 
 Runs EmDash's scheduled work now (scheduled publishing, cleanup) and returns what it published. Workers in a dispatch namespace never receive cron triggers, so the platform's cron calls this on every site each minute.

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@tideworthy/tidysites-platform",
-	"version": "0.1.7",
+	"version": "0.2.0",
 	"description": "The Tidysites platform integration for EmDash sites: bootstrap, sessions, maintenance, health, and publish hooks under /_tidy/*.",
 	"license": "MIT",
 	"type": "module",
@@ -24,6 +24,7 @@
 		"./routes/session-claim": "./src/routes/session-claim.ts",
 		"./routes/health": "./src/routes/health.ts",
 		"./routes/rotate-token": "./src/routes/rotate-token.ts",
+		"./routes/fill": "./src/routes/fill.ts",
 		"./routes/maintenance": "./src/routes/maintenance.ts"
 	},
 	"scripts": {

package/src/client.ts

@@ -3,9 +3,9 @@
  * platform app. Pass `fetch` to route calls through a dispatch-namespace
  * binding instead of the public internet.
  */
-import type { BootstrapInput, BootstrapResult, HealthResult, MintSessionInput, MintSessionResult, RotateTokenInput } from "./lib/handlers";
+import type { BootstrapInput, BootstrapResult, FillEntry, FillInput, FillResult, HealthResult, MintSessionInput, MintSessionResult, RotateTokenInput } from "./lib/handlers";
 
-export type { BootstrapInput, BootstrapResult, HealthResult, MintSessionInput, MintSessionResult, RotateTokenInput };
+export type { BootstrapInput, BootstrapResult, FillEntry, FillInput, FillResult, HealthResult, MintSessionInput, MintSessionResult, RotateTokenInput };
 
 export interface MaintenanceResult {
 	ok: true;
@@ -56,6 +56,7 @@ export function createTidySiteClient(options: TidySiteClientOptions) {
 		mintSession: (input: MintSessionInput) => call<MintSessionResult>("POST", "/_tidy/session", input),
 		health: () => call<HealthResult>("GET", "/_tidy/health"),
 		rotateToken: (input: RotateTokenInput = {}) => call<{ ok: true; userId: string; token: string }>("POST", "/_tidy/rotate-token", input),
+		fill: (input: FillInput) => call<FillResult>("POST", "/_tidy/fill", input),
 		maintenance: (cron?: string) => call<MaintenanceResult>("POST", `/_tidy/maintenance${cron ? `?cron=${encodeURIComponent(cron)}` : ""}`)
 	};
 }

package/src/index.ts

@@ -27,6 +27,7 @@ export const PLATFORM_ROUTES = [
 	{ pattern: "/_tidy/session/claim", entrypoint: `${PACKAGE}/routes/session-claim` },
 	{ pattern: "/_tidy/health", entrypoint: `${PACKAGE}/routes/health` },
 	{ pattern: "/_tidy/rotate-token", entrypoint: `${PACKAGE}/routes/rotate-token` },
+	{ pattern: "/_tidy/fill", entrypoint: `${PACKAGE}/routes/fill` },
 	{ pattern: "/_tidy/maintenance", entrypoint: `${PACKAGE}/routes/maintenance` }
 ] as const;
 

package/src/lib/handlers.ts

@@ -12,6 +12,13 @@ export interface SeedOps {
 	load(): Promise<Record<string, unknown> & { settings?: Record<string, unknown> }>;
 	validate(seed: unknown): { valid: boolean; errors?: unknown };
 	apply(seed: Record<string, unknown>): Promise<{ collections?: unknown; content?: unknown }>;
+	/** Upsert content entries by slug (existing entries are updated), downloading `$media` URLs into the site's storage. */
+	upsertContent(content: Record<string, FillEntry[]>): Promise<{ created: number; updated: number; media: number }>;
+}
+
+export interface ContentOps {
+	findIdBySlug(collection: string, slug: string): Promise<string | null>;
+	delete(collection: string, id: string): Promise<boolean>;
 }
 
 export interface TokenOps {
@@ -24,6 +31,7 @@ export interface Deps {
 	store: PlatformStore;
 	seed: SeedOps;
 	tokens: TokenOps;
+	content: ContentOps;
 	now?: () => number;
 }
 
@@ -113,6 +121,117 @@ export async function bootstrap(input: BootstrapInput, deps: Deps, requestOrigin
 	return { ok: true, userId: user.id, token: t.raw, steps };
 }
 
+// ---------------------------------------------------------------------------
+// Fill: write real content over the template's sample content
+// ---------------------------------------------------------------------------
+
+/** One entry in the seed's content shape: `data` holds field values, `$ref:<id>` and `$media` resolve as in a template seed. */
+export interface FillEntry {
+	id: string;
+	slug?: string | null;
+	status?: "published" | "draft";
+	data: Record<string, unknown>;
+}
+
+export interface FillInput {
+	/** Site title and tagline; either may be omitted. */
+	settings?: unknown;
+	/** Entries per collection slug, upserted by slug. */
+	content?: unknown;
+	/** Entry slugs per collection slug to delete (sample entries the fill did not replace). Unknown slugs are ignored. */
+	remove?: unknown;
+}
+
+export interface FillResult {
+	ok: true;
+	settings: string[];
+	content: { created: number; updated: number; media: number };
+	removed: number;
+	missing: Array<{ collection: string; slug: string }>;
+}
+
+const COLLECTION_SLUG = /^[a-z0-9][a-z0-9_-]{0,63}$/;
+const ENTRY_SLUG = /^[a-z0-9][a-z0-9_-]{0,127}$/i;
+const MAX_ENTRIES = 2000;
+
+function fillContent(value: unknown): Record<string, FillEntry[]> {
+	if (value === undefined) return {};
+	if (value === null || typeof value !== "object" || Array.isArray(value)) throw new HttpError(400, "content must be an object of collection slug to entry list");
+	const out: Record<string, FillEntry[]> = {};
+	let count = 0;
+	for (const [collection, entries] of Object.entries(value as Record<string, unknown>)) {
+		if (!COLLECTION_SLUG.test(collection)) throw new HttpError(400, `content: "${collection}" is not a collection slug`);
+		if (!Array.isArray(entries)) throw new HttpError(400, `content.${collection} must be a list of entries`);
+		out[collection] = entries.map((e, i) => {
+			if (e === null || typeof e !== "object" || Array.isArray(e)) throw new HttpError(400, `content.${collection}[${i}] must be an entry object`);
+			const entry = e as Record<string, unknown>;
+			if (typeof entry.id !== "string" || !ENTRY_SLUG.test(entry.id)) throw new HttpError(400, `content.${collection}[${i}].id must be a slug-like id`);
+			if (entry.slug !== undefined && entry.slug !== null && (typeof entry.slug !== "string" || !ENTRY_SLUG.test(entry.slug))) throw new HttpError(400, `content.${collection}[${i}].slug must be a slug`);
+			if (entry.status !== undefined && entry.status !== "published" && entry.status !== "draft") throw new HttpError(400, `content.${collection}[${i}].status must be published or draft`);
+			if (entry.data === null || typeof entry.data !== "object" || Array.isArray(entry.data)) throw new HttpError(400, `content.${collection}[${i}].data must be an object`);
+			count++;
+			return { id: entry.id, slug: entry.slug === undefined ? entry.id : (entry.slug as string | null), status: entry.status as FillEntry["status"], data: entry.data as Record<string, unknown> };
+		});
+	}
+	if (count > MAX_ENTRIES) throw new HttpError(400, `content: at most ${MAX_ENTRIES} entries per call`);
+	return out;
+}
+
+function fillRemove(value: unknown): Array<{ collection: string; slug: string }> {
+	if (value === undefined) return [];
+	if (value === null || typeof value !== "object" || Array.isArray(value)) throw new HttpError(400, "remove must be an object of collection slug to slug list");
+	const out: Array<{ collection: string; slug: string }> = [];
+	for (const [collection, slugs] of Object.entries(value as Record<string, unknown>)) {
+		if (!COLLECTION_SLUG.test(collection)) throw new HttpError(400, `remove: "${collection}" is not a collection slug`);
+		if (!Array.isArray(slugs) || slugs.some((x) => typeof x !== "string" || !ENTRY_SLUG.test(x))) throw new HttpError(400, `remove.${collection} must be a list of slugs`);
+		for (const slug of slugs as string[]) out.push({ collection, slug });
+	}
+	return out;
+}
+
+/**
+ * Write real content over a bootstrapped site: settings, entries upserted by
+ * slug (so re-running with the same document is safe), then sample entries
+ * the platform names for removal. Writes happen in that order so a removed
+ * sample is never a dangling reference target for an entry written here.
+ */
+export async function fill(input: FillInput, deps: Deps): Promise<FillResult> {
+	if (input.settings !== undefined && (input.settings === null || typeof input.settings !== "object" || Array.isArray(input.settings))) throw new HttpError(400, "settings must be an object");
+	const settings = (input.settings ?? {}) as Record<string, unknown>;
+	if (settings.title !== undefined && (typeof settings.title !== "string" || settings.title.length > 200)) throw new HttpError(400, "settings.title must be a string of at most 200 characters");
+	if (settings.tagline !== undefined && (typeof settings.tagline !== "string" || settings.tagline.length > 500)) throw new HttpError(400, "settings.tagline must be a string of at most 500 characters");
+	const content = fillContent(input.content);
+	const remove = fillRemove(input.remove);
+	if ((await deps.store.getOption("emdash:setup_complete")) !== true) throw new HttpError(409, "site is not bootstrapped yet");
+
+	const applied: string[] = [];
+	if (typeof settings.title === "string") {
+		await deps.store.setOption("emdash:site_title", settings.title);
+		applied.push("title");
+	}
+	if (typeof settings.tagline === "string") {
+		await deps.store.setOption("emdash:site_tagline", settings.tagline);
+		applied.push("tagline");
+	}
+
+	const written = Object.keys(content).length > 0 ? await deps.seed.upsertContent(content) : { created: 0, updated: 0, media: 0 };
+
+	// Never delete something this same call just wrote.
+	const kept = new Set(Object.entries(content).flatMap(([c, entries]) => entries.map((e) => `${c}/${e.slug ?? e.id}`)));
+	let removed = 0;
+	const missing: Array<{ collection: string; slug: string }> = [];
+	for (const r of remove) {
+		if (kept.has(`${r.collection}/${r.slug}`)) continue;
+		const id = await deps.content.findIdBySlug(r.collection, r.slug);
+		if (!id) {
+			missing.push(r);
+			continue;
+		}
+		if (await deps.content.delete(r.collection, id)) removed++;
+	}
+	return { ok: true, settings: applied, content: written, removed, missing };
+}
+
 // ---------------------------------------------------------------------------
 // Sessions: mint a one-time handoff, then a browser claims it
 // ---------------------------------------------------------------------------

package/src/lib/runtime.ts

@@ -6,7 +6,7 @@
  * This is the only file (besides src/plugin.ts) that imports EmDash. Keep it
  * that way: it is the list of things to re-verify on an EmDash upgrade.
  */
-import { OptionsRepository, UserRepository, applySeed, getMigrationStatus, ulid, validateSeed } from "emdash";
+import { ContentRepository, OptionsRepository, UserRepository, applySeed, getMigrationStatus, ulid, validateSeed } from "emdash";
 import { getDb } from "emdash/runtime";
 import { loadSeed } from "emdash/seed";
 import { VALID_SCOPES, generatePrefixedToken } from "@emdash-cms/auth";
@@ -38,12 +38,38 @@ async function storageProvider(): Promise<unknown> {
 export async function buildDeps(): Promise<Deps> {
 	const [db, storage] = await Promise.all([getDb(), storageProvider()]);
 	const store = createEmdashStore(db, { OptionsRepository, UserRepository, ulid, getMigrationStatus });
+	const content = new ContentRepository(db);
+	const storageOpt = storage ? { storage: storage as never } : {};
 	return {
 		store,
 		seed: {
 			load: async () => (await loadSeed()) as unknown as Record<string, unknown> & { settings?: Record<string, unknown> },
 			validate: (seed) => validateSeed(seed),
-			apply: (seed) => applySeed(db, seed as unknown as Parameters<typeof applySeed>[1], { includeContent: true, onConflict: "skip", ...(storage ? { storage: storage as never } : {}) })
+			apply: (seed) => applySeed(db, seed as unknown as Parameters<typeof applySeed>[1], { includeContent: true, onConflict: "skip", ...storageOpt }),
+			// A content-only seed document: no collections, menus, or settings, so
+			// applySeed touches nothing but entries. "update" makes it an upsert by
+			// slug. applySeed replaces an existing entry's data wholesale, so fields
+			// the caller did not send are carried over from the current entry first:
+			// a fill names only what it knows and the template's images and blocks
+			// survive underneath.
+			upsertContent: async (entries) => {
+				const merged: typeof entries = {};
+				for (const [collection, list] of Object.entries(entries)) {
+					merged[collection] = [];
+					for (const e of list) {
+						const slug = e.slug ?? e.id;
+						const existing = slug ? await content.findBySlug(collection, slug) : null;
+						const current = (existing?.data ?? {}) as Record<string, unknown>;
+						merged[collection].push({ ...e, data: existing ? { ...current, ...e.data } : e.data });
+					}
+				}
+				const r = await applySeed(db, { version: 1, content: merged } as unknown as Parameters<typeof applySeed>[1], { includeContent: true, onConflict: "update", ...storageOpt });
+				return { created: r.content?.created ?? 0, updated: r.content?.updated ?? 0, media: r.media?.created ?? 0 };
+			}
+		},
+		content: {
+			findIdBySlug: async (collection, slug) => (await content.findBySlug(collection, slug))?.id ?? null,
+			delete: (collection, id) => content.delete(collection, id)
 		},
 		tokens: {
 			generate: () => generatePrefixedToken("ec_pat_"),

package/src/routes/fill.ts

@@ -0,0 +1,13 @@
+/** POST /_tidy/fill: real content over the template's sample content. */
+import { fill, type FillInput } from "../lib/handlers";
+import { json, readJson } from "../lib/http";
+import { methodNotAllowed, platformRoute } from "./_shared";
+
+export const prerender = false;
+
+export const POST = platformRoute(async (context, deps) => {
+	const body = await readJson<FillInput>(context.request);
+	return json(await fill(body, deps));
+});
+
+export const ALL = methodNotAllowed("POST");

package/src/version.ts

@@ -1,3 +1,3 @@
 /** Kept in step with package.json by the release checklist in MAINTAINING.md. */
-export const VERSION = "0.1.7";
+export const VERSION = "0.2.0";
 export const PLUGIN_ID = "tidy-platform";