import { commit, del, insert, rollback, startTransaction, update } from '@evershop/postgres-query-builder'; import type { Pool, PoolClient } from 'pg'; import semver from 'semver'; import { resolveAssetTokens, uploadThemeAssets, type AssetUploader } from './assets.js'; import { writeAuditLog } from './auditLog.js'; import { Conflict, DiffResult, diffManifest, LiveDbState, PlanOp } from './diff.js'; import type { LandingPageLiveRow, ScopedPlacement } from './diff.js'; import { contentFingerprint } from './fingerprint.js'; import { findLandingPagesByUuid, insertLandingPage, landingPageUrn, loadUrlKeyGuard, syncUrlRewrite, updateLandingPageFields, type UrlKeyGuard } from './landingPages.js'; import type { LandingPageRecord, Manifest, PlacementRecord, WidgetRecord } from './manifest.js'; import { applyStoreRefs, collectStoreRefs, resolveStoreRefs, type ResolvedStoreRef } from './storeRefs.js'; export interface InstallOpts { themeId: string; manifest: Manifest; pool: Pool; /** * The theme's directory, needed to read the files `manifest.assets` declares. * Omit to skip asset upload entirely (tests, and callers that only diff). */ themeDir?: string; /** * Uploads a theme's assets through the store's configured storage provider. * Injected so `lib/theme` stays free of a hard `modules/cms` import and so * install can be tested without touching a filesystem or a bucket. */ uploadAsset?: AssetUploader; } export interface StoreRefReport { resolved: ResolvedStoreRef[]; } export interface AssetUploadReport { uploaded: { path: string; url: string }[]; /** Declared but absent from the theme folder; their tokens stay unresolved. */ missing: string[]; } export interface InstallResult { command: 'install' | 'upgrade' | 'no-op' | 'rejected'; /** Present when the manifest declared `assets[]`. */ assets?: AssetUploadReport; /** Present when the manifest referenced store data (`store-ref:` tokens). */ storeRefs?: StoreRefReport; counts: DiffResult['counts']; conflicts: Conflict[]; /** * On a fresh install, content that already existed in the DB for this theme * and was left untouched (not re-inserted). Non-zero when a theme author * builds content in the page-builder, exports it, then runs `theme:active` * on the same DB. */ adopted?: { widgets: number; placements: number; landingPages: number }; /** Pages dropped from the manifest whose row was left in place (D5). */ releasedLandingPages?: Array<{ uuid: string; name: string }>; /** Set when `command === 'rejected'` (a refused downgrade). */ rejectedReason?: string; /** * Set on a `no-op` when the manifest's content differs from what's installed * but the `version` is unchanged — the CLI warns the author to bump it. */ contentDriftAtSameVersion?: boolean; } const ZERO_COUNTS: DiffResult['counts'] = { widgets_added: 0, widgets_updated: 0, widgets_removed: 0, placements_added: 0, placements_updated: 0, placements_removed: 0, landing_pages_added: 0, landing_pages_updated: 0, landing_pages_released: 0 }; /** Every landing-page uuid this theme knows about: snapshot ∪ manifest. */ function knownPageUuids(...manifests: Array): string[] { const out = new Set(); for (const m of manifests) { for (const lp of m?.landingPages ?? []) { if (typeof lp?.uuid === 'string') out.add(lp.uuid); } } return [...out]; } /** * Load the live `widget_instance` / `widget_placement` state for a theme as * the diff engine's `D` input (spec 04 § 7.2.1). Exported so `theme:status` * can run a dry-run diff without an install. Entity-scoped placements (and * instances that live only inside landing page bodies) are excluded, mirroring * `exportToManifest`, so the diff can never update or delete page content. */ export async function loadLiveDbForTheme( client: Pool | PoolClient, themeId: string, /** * Landing pages this theme knows about (snapshot ∪ manifest). Their * entity-scoped placements ARE part of the theme's content and must be * diffed; every other entity-scoped row (a merchant's own page, a homepage * backup) stays invisible. */ pageUuids: string[] = [] ): Promise { const widgetRows = await client.query< WidgetRecord & { status?: boolean } >( `SELECT wi.uuid::text AS uuid, wi.type, wi.name, wi.settings, wi.status FROM widget_instance wi WHERE wi.theme = $1 AND NOT ( EXISTS (SELECT 1 FROM widget_placement p WHERE p.widget_instance_id = wi.widget_instance_id AND p.entity_urn IS NOT NULL) AND NOT EXISTS (SELECT 1 FROM widget_placement p WHERE p.widget_instance_id = wi.widget_instance_id AND p.entity_urn IS NULL) )`, [themeId] ); const knownUrns = pageUuids.map((u) => landingPageUrn(u)); const placementRows = await client.query( `SELECT p.uuid::text AS uuid, wi.uuid::text AS widget_instance_uuid, p.route, p.area, p.sort_order, p.entity_urn FROM widget_placement p INNER JOIN widget_instance wi ON wi.widget_instance_id = p.widget_instance_id WHERE p.theme = $1 AND (p.entity_urn IS NULL OR p.entity_urn = ANY($2::text[]))`, [themeId, knownUrns] ); const landingPageRows = pageUuids.length === 0 ? { rows: [] as LandingPageLiveRow[] } : await client.query( `SELECT uuid::text AS uuid, name, description, meta_title, meta_description, status FROM landing_page WHERE uuid::text = ANY($1::text[])`, [pageUuids] ); return { widgets: new Map( widgetRows.rows.map((w) => [ w.uuid, { ...w, settings: w.settings ?? {} } ]) ), placements: new Map( placementRows.rows.map((p) => [ p.uuid, { ...p, sort_order: Number(p.sort_order) } ]) ), landingPages: new Map(landingPageRows.rows.map((lp) => [lp.uuid, lp])) }; } async function resolveWidgetInstanceId( conn: PoolClient, uuid: string ): Promise { const { rows } = await conn.query<{ widget_instance_id: number }>( `SELECT widget_instance_id FROM widget_instance WHERE uuid::text = $1`, [uuid] ); if (rows.length === 0) { throw new Error( `cannot place widget: widget_instance '${uuid}' not found (op order bug?)` ); } return Number(rows[0].widget_instance_id); } async function applyWidgetOp( conn: PoolClient, themeId: string, op: PlanOp ): Promise { if (op.op === 'INSERT') { // `status: true` per spec § 7.2.2 — installed widgets are enabled. The // column has no DB default, and the manifest never carries status, so we // stamp it here (the merchant can disable it later in the page-builder). await insert('widget_instance') .given({ status: true, ...(op.payload as object), theme: themeId }) .execute(conn); return; } if (op.op === 'UPDATE') { await update('widget_instance') .given(op.payload as object) .where('uuid', '=', op.uuid) .execute(conn); return; } await del('widget_instance').where('uuid', '=', op.uuid).execute(conn); } async function applyPlacementOp( conn: PoolClient, themeId: string, op: PlanOp ): Promise { if (op.op === 'INSERT') { const payload = { ...(op.payload as Record) }; const widgetUuid = payload.widget_instance_uuid as string; delete payload.widget_instance_uuid; payload.widget_instance_id = await resolveWidgetInstanceId(conn, widgetUuid); payload.theme = themeId; payload.entity_urn = payload.entity_urn ?? null; await insert('widget_placement').given(payload).execute(conn); return; } if (op.op === 'UPDATE') { await update('widget_placement') .given(op.payload as object) .where('uuid', '=', op.uuid) .execute(conn); return; } await del('widget_placement').where('uuid', '=', op.uuid).execute(conn); } /** * Landing pages carry no theme tag (they are not theme property). INSERT * generates the url_key from the name; UPDATE only ever touches the * manifest-carried fields the diff resolved. DELETE never happens — a page * dropped from the manifest keeps its row. */ async function applyLandingPageOp( conn: PoolClient, op: PlanOp, guard: UrlKeyGuard ): Promise { if (op.op === 'INSERT') { await insertLandingPage(conn, op.payload as unknown as LandingPageRecord, guard); return; } if (op.op === 'UPDATE') { await updateLandingPageFields(conn, op.uuid, op.payload as Record); } } /** * Apply the diff ops in array order (which is already the § 7.4 sequence). The * theme tag is stamped on every widget/placement INSERT here — the diff stays * theme-agnostic. */ async function applyOps( conn: PoolClient, themeId: string, ops: PlanOp[], guard: UrlKeyGuard ): Promise { for (const op of ops) { if (op.table === 'widget_instance') { await applyWidgetOp(conn, themeId, op); } else if (op.table === 'landing_page') { await applyLandingPageOp(conn, op, guard); } else { await applyPlacementOp(conn, themeId, op); } } } function freshInstallOps(manifest: Manifest): PlanOp[] { const landingPages = manifest.landingPages ?? []; return [ ...manifest.widgets.map( (w): PlanOp => ({ table: 'widget_instance', op: 'INSERT', uuid: w.uuid, payload: { uuid: w.uuid, type: w.type, name: w.name, settings: w.settings } }) ), // Pages before their bodies. ...landingPages.map( (lp): PlanOp => ({ table: 'landing_page', op: 'INSERT', uuid: lp.uuid, payload: { uuid: lp.uuid, name: lp.name, description: lp.description ?? null, meta_title: lp.meta_title ?? null, meta_description: lp.meta_description ?? null, status: lp.status === true } }) ), ...manifest.placements.map( (p): PlanOp => ({ table: 'widget_placement', op: 'INSERT', uuid: p.uuid, payload: { uuid: p.uuid, widget_instance_uuid: p.widget_instance_uuid, route: p.route, area: p.area, sort_order: p.sort_order, entity_urn: null } }) ), ...landingPages.flatMap((lp) => (lp.placements ?? []).map( (p): PlanOp => ({ table: 'widget_placement', op: 'INSERT', uuid: p.uuid, payload: { uuid: p.uuid, widget_instance_uuid: p.widget_instance_uuid, route: 'landingPageView', area: p.area, sort_order: p.sort_order, entity_urn: landingPageUrn(lp.uuid) } }) ) ) ]; } /** * Install or upgrade a theme's content in one transaction (spec 04 § 7). * * - No `theme_install_state` row → fresh install (every manifest row inserted). * - Row exists, content fingerprint matches → no-op (a metadata-only release). * - Row exists, fingerprint differs → three-way diff + apply. * * The transaction opens with `SELECT ... FOR UPDATE` on the state row to * serialize concurrent upgrades of the same theme (§ 7.3). */ export async function installOrUpgrade( opts: InstallOpts ): Promise { // Reserved slugs + enabled locales, read once: url_key generation consults // them for every new landing page. const guard = await loadUrlKeyGuard(); // Ship the theme's files into the store's storage BEFORE the transaction: // it is network I/O (S3/Azure/GCS), and an upload is idempotent by key, so a // later rollback leaves a harmless overwritten object rather than a torn // transaction. `assetUrls` then resolves `theme-asset:` tokens on BOTH sides // of the diff — the snapshot keeps the authored tokens (see the write below), // so an upgrade compares like with like instead of reading every image as a // change. const declaredAssets = opts.manifest.assets ?? []; let assets: AssetUploadReport | undefined; let assetUrls = new Map(); if (declaredAssets.length > 0 && opts.themeDir && opts.uploadAsset) { const result = await uploadThemeAssets( opts.themeDir, opts.themeId, declaredAssets, opts.uploadAsset ); assetUrls = result.urls; assets = { uploaded: result.uploaded, missing: result.missing }; } // Point the theme's widgets at THIS store's data. Read-only: activation // installs a theme's content, never a store's catalogue, so a reference that // matches nothing becomes an empty setting (the widget renders its own empty // state) and is reported rather than invented. const refs = collectStoreRefs(opts.manifest); const resolvedRefs = refs.length > 0 ? await resolveStoreRefs(opts.pool, refs) : []; const storeRefs: StoreRefReport | undefined = resolvedRefs.length > 0 ? { resolved: resolvedRefs } : undefined; const manifest = applyStoreRefs( resolveAssetTokens(opts.manifest, assetUrls), resolvedRefs ); const conn = await opts.pool.connect(); await startTransaction(conn); try { const stateRow = await conn.query<{ snapshot: Manifest }>( `SELECT snapshot FROM theme_install_state WHERE theme = $1 FOR UPDATE`, [opts.themeId] ); if (stateRow.rows.length === 0) { // Fresh install. Some (or all) of the manifest's content may already // exist in the DB for this theme — e.g. an author built it in the // page-builder, exported it, then ran `theme:active` on the same DB. // Validation already guaranteed any pre-existing uuids belong to THIS // theme (a foreign-theme uuid is a hard error), so adopt those rows: // skip their INSERT (they're already the source of truth) and insert // only what's genuinely missing. This avoids colliding on the uuid // unique constraint while still recording the install baseline. const pageUuids = knownPageUuids(manifest); const liveDb = await loadLiveDbForTheme(conn, opts.themeId, pageUuids); // A landing page uuid that already exists is ADOPTED, whatever theme (if // any) built it: pages are not theme property, so there is no foreign // owner to refuse. Its live fields and url_key are left untouched. const existingPages = await findLandingPagesByUuid(conn, pageUuids); const toInsert = freshInstallOps(manifest).filter((op) => { if (op.table === 'widget_instance') return !liveDb.widgets.has(op.uuid); if (op.table === 'landing_page') return !existingPages.has(op.uuid); return !liveDb.placements.has(op.uuid); }); await applyOps(conn, opts.themeId, toInsert, guard); await conn.query( `INSERT INTO theme_install_state (theme, snapshot) VALUES ($1, $2::jsonb)`, // Authored form on purpose: tokens, not the URLs this store happens // to have produced. Resolution is re-applied on every upgrade. [opts.themeId, JSON.stringify(opts.manifest)] ); const widgetsAdded = toInsert.filter( (o) => o.table === 'widget_instance' ).length; const placementsAdded = toInsert.filter( (o) => o.table === 'widget_placement' ).length; const pagesAdded = toInsert.filter( (o) => o.table === 'landing_page' ).length; const counts: DiffResult['counts'] = { ...ZERO_COUNTS, widgets_added: widgetsAdded, placements_added: placementsAdded, landing_pages_added: pagesAdded }; await writeAuditLog(conn, opts.themeId, 'install', counts, []); await commit(conn); return { command: 'install', counts, conflicts: [], ...(assets ? { assets } : {}), ...(storeRefs ? { storeRefs } : {}), adopted: { widgets: manifest.widgets.length - widgetsAdded, placements: manifest.placements.length + (manifest.landingPages ?? []).reduce( (n, lp) => n + (lp.placements?.length ?? 0), 0 ) - placementsAdded, landingPages: (manifest.landingPages ?? []).length - pagesAdded } }; } // --- Version gate (spec 04 § 7.1) --- // Upgrades are ordered by the manifest's SemVer `version`: // - lower than installed → refuse (no downgrades / reverts) // - equal to installed → no-op (warn if content drifted) // - higher than installed → apply the content diff + record new version const snapshot = stateRow.rows[0].snapshot as Manifest; const resolvedSnapshot = applyStoreRefs( resolveAssetTokens(snapshot, assetUrls), resolvedRefs ); const installedVersion = snapshot.version; const newVersion = manifest.version; // A legacy / invalid recorded version (e.g. a pre-rename snapshot) can't be // compared — treat it as upgradeable rather than crashing the comparator. const cmp = semver.valid(installedVersion) ? semver.compare(newVersion, installedVersion) : 1; if (cmp < 0) { await commit(conn); // nothing applied return { command: 'rejected', counts: { ...ZERO_COUNTS }, conflicts: [], rejectedReason: `cannot downgrade '${opts.themeId}' from version ${installedVersion} ` + `to ${newVersion} — reverting a theme is not allowed` }; } if (cmp === 0) { // Same version: no upgrade. Flag content drift so the CLI can nudge the // author to bump the version. const contentSame = contentFingerprint(manifest) === contentFingerprint(resolvedSnapshot); await commit(conn); return { command: 'no-op', counts: { ...ZERO_COUNTS }, conflicts: [], contentDriftAtSameVersion: !contentSame }; } // Higher version → upgrade. The content diff may be empty (a version-only // bump); either way the recorded version advances. const liveDb = await loadLiveDbForTheme( conn, opts.themeId, knownPageUuids(resolvedSnapshot, manifest) ); const diff = diffManifest(resolvedSnapshot, manifest, liveDb); await applyOps(conn, opts.themeId, diff.ops, guard); await conn.query( `UPDATE theme_install_state SET snapshot = $2::jsonb, updated_at = NOW() WHERE theme = $1`, [opts.themeId, JSON.stringify(opts.manifest)] ); await writeAuditLog( conn, opts.themeId, 'upgrade', diff.counts, diff.conflicts ); await commit(conn); return { command: 'upgrade', ...(assets ? { assets } : {}), ...(storeRefs ? { storeRefs } : {}), counts: diff.counts, conflicts: diff.conflicts, releasedLandingPages: diff.releasedLandingPages, adopted: diff.adopted }; } catch (e) { await rollback(conn); throw e; } } /** * Compute the upgrade plan WITHOUT applying it (spec 04 § 6.1 `--dry-run` / * § 6.2 `theme:status `). Returns null when the theme isn't installed. */ export async function dryRunDiff( themeId: string, manifest: Manifest, pool: Pool ): Promise { const stateRow = await pool.query<{ snapshot: Manifest }>( `SELECT snapshot FROM theme_install_state WHERE theme = $1`, [themeId] ); if (stateRow.rows.length === 0) return null; const snapshot = stateRow.rows[0].snapshot; const liveDb = await loadLiveDbForTheme( pool, themeId, knownPageUuids(snapshot, manifest) ); return diffManifest(snapshot, manifest, liveDb); }