import type { Pool, PoolClient } from 'pg'; import { type AssetUploader } from './assets.js'; import { Conflict, DiffResult, LiveDbState } from './diff.js'; import type { Manifest } from './manifest.js'; import { 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; } /** * 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 declare 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; /** * 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 declare function installOrUpgrade(opts: InstallOpts): Promise; /** * 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 declare function dryRunDiff(themeId: string, manifest: Manifest, pool: Pool): Promise;