import type { Pool } from 'pg'; import type { ManifestMetafieldDefinition } from '../metafield/provision.js'; import { type AssetRecord } from './assets.js'; /** * Theme manifest (`theme.json`) reader + validator — spec 04 § 5. * * Per the 2026-06-06 decision (spec § 5.5), widget-type-registry and * settings-schema validation are deferred to render time: the CLI never * bootstraps the widget registry, so it validates structure + DB-collision * only and emits a non-blocking soft warning for never-before-seen types. */ export interface WidgetRecord { uuid: string; type: string; name: string; settings: Record; } export interface PlacementRecord { uuid: string; widget_instance_uuid: string; route: string; area: string; sort_order: number; } /** * A landing page shipped by a theme (`landingPages[]`). * * Deliberately carries NO `url_key` (generated at install from `name`, then * merchant data forever) and no publish schedule (campaign dates belong to a * store, not a theme). Its `placements` are nested, so the manifest never * spells an `entity_urn`: the installer derives the scope from the nesting. * See specifications/theme-json-landing-pages.md. */ export interface LandingPageRecord { uuid: string; name: string; description?: string | null; meta_title?: string | null; meta_description?: string | null; /** Defaults to false — a shipped page arrives as a draft. */ status?: boolean; placements: LandingPagePlacementRecord[]; } /** A placement inside a landing page body: like `PlacementRecord` without `route`. */ export interface LandingPagePlacementRecord { uuid: string; widget_instance_uuid: string; area: string; sort_order: number; } export interface Manifest { theme_name: string; /** * The theme content's version — a valid SemVer string (spec 04 § 5.2). * Load-bearing: installs/upgrades are gated on it (only a strictly higher * version upgrades; downgrades are refused). See `install.ts`. */ version: string; widgets: WidgetRecord[]; placements: PlacementRecord[]; /** * Metafield definitions this theme declares (theme-metafields design). * Deliberately OUTSIDE the widget SemVer/snapshot protocol: entries are * ensured idempotently at `theme:active` and every server boot * (`lib/metafield/provision.ts`) — no version bump needed for changes. */ metafieldDefinitions?: ManifestMetafieldDefinition[]; /** * Landing pages this theme ships, each with its own nested body. Part of the * content SemVer/snapshot protocol (unlike `metafieldDefinitions`). */ landingPages?: LandingPageRecord[]; /** * Files this theme ships with its content (images for its widgets). * `theme:active` uploads them through the store's configured storage * provider; settings refer to them as `theme-asset:`. See * `lib/theme/assets.ts`. */ assets?: AssetRecord[]; } export interface ValidationError { scope: 'top-level' | 'widget' | 'placement' | 'landing-page' | 'asset' | 'cross-record' | 'db' | 'metafield'; index?: number; uuid?: string; message: string; /** `warning` entries are reported but never block an install. */ severity?: 'error' | 'warning'; } export interface ValidationContext { themeId: string; pool: Pool; } /** * Read a theme's `theme.json` from its directory. Returns `null` when the file * doesn't exist (theme-without-content, spec § 5.1). Throws on unreadable or * malformed JSON — the CLI surfaces that as an activation failure. */ export declare function readManifest(themeDir: string): Promise; /** * Validate a manifest against spec § 5.5. Returns every error found (empty * array = pass) so the CLI can print them all at once. */ export declare function validateManifest(manifest: Manifest, ctx: ValidationContext): Promise; /** * Non-blocking soft warning (spec § 5.5): warn for any manifest widget type * that has never been instantiated on this install. A fresh module install * legitimately introduces new types, so this is a hint, not an error. */ export declare function warnUnknownTypes(manifest: Manifest, knownTypes: Set, warn: (message: string) => void): void;