@endora-commerce/mod-megamenu 0.100.0

package/dist/backend/services/target-validator.js

@@ -0,0 +1,105 @@
+// Per-kind target validation for Megamenu items — feature 015 / T012.
+//
+// The Zod boundary in `packages/contracts/src/megamenu.ts` enforces the
+// shape rules (URL schemes, button variants, asset kinds). Cross-module
+// existence + scope checks (Category exists, CMS Page / Block exists in
+// scope, Asset matches an expected kind) live here so the unit test can
+// stub them without booting a server.
+import { ERROR_CODES } from '@endora-commerce/contracts';
+import { HttpError } from '@endora-commerce/platform/http';
+const externalUrlRe = /^(?:https?:\/\/|tel:|mailto:)/i;
+/**
+ * Validates a single MegamenuItem against the cross-module ports. Throws
+ * `HttpError` on the first failure so callers (`MegamenuItemService.setTree`)
+ * can re-raise unchanged.
+ *
+ * The four checks used to arrive as `TargetValidatorDeps`, an interface this
+ * module exported for a composition root to build closures against
+ * (`specs/110-instance-repository/` T118c). They are their owners' published read
+ * ports now, resolved by `backend/index.ts` and declared in this module's
+ * manifest.
+ *
+ * **`_channelIds` is threaded and read by nothing, which is what the roots' SQL
+ * did.** `setTree` computes the union of the menu's bound channels and passes it
+ * here; neither root's closure ever looked at it, so `MEGAMENU_TARGET_OUT_OF_SCOPE`
+ * has only ever meant *the target does not exist*. That is a documented v1
+ * narrowing — `megamenu-item-service.ts` says so at the call site, and the scope
+ * refusal is US3's — and the parameter is kept so US3 lands inside this function
+ * rather than re-plumbing its caller. Naming it `_` is the only change: the
+ * ignoring used to happen two files away in a root nobody reads.
+ */
+export async function validateTarget(item, _channelIds, ports) {
+    // Defence in depth — Zod has already filtered URL schemes at the
+    // boundary, but the validator double-checks any free URL on a kind
+    // where we expect one.
+    if (item.kind === 'external-link') {
+        if (!externalUrlRe.test(item.target.url)) {
+            throw new HttpError(400, ERROR_CODES.VALIDATION_FAILED, `External link URL "${item.target.url}" must use http://, https://, tel:, or mailto:.`);
+        }
+    }
+    // Optional icon on link kinds: must reference an image asset.
+    if (item.kind === 'category-link' ||
+        item.kind === 'cms-page-link' ||
+        item.kind === 'external-link') {
+        const iconAssetId = item.target.iconAssetId;
+        if (iconAssetId) {
+            const icon = await ports.assets.findById(iconAssetId);
+            if (icon?.kind !== 'image') {
+                throw new HttpError(400, ERROR_CODES.MEGAMENU_ASSET_KIND_MISMATCH, `Icon asset ${iconAssetId} is not an image.`);
+            }
+        }
+    }
+    switch (item.kind) {
+        case 'category-link': {
+            // No `liveOnly` and no `isActive` test: the roots' `select 1 from
+            // categories where id = ?` accepted a deactivated or soft-deleted
+            // category, and an admin pointing a menu item at one is not making an
+            // error the storefront cannot answer — `resolveCategoryUrl` drops the
+            // item at render time.
+            const ok = (await ports.categories.findById(item.target.categoryId)) !== null;
+            if (!ok) {
+                throw new HttpError(400, ERROR_CODES.MEGAMENU_TARGET_OUT_OF_SCOPE, `Category ${item.target.categoryId} is not in scope of the megamenu's bindings.`);
+            }
+            return;
+        }
+        case 'cms-page-link': {
+            const ok = (await ports.pages.findById(item.target.pageId)) !== null;
+            if (!ok) {
+                throw new HttpError(400, ERROR_CODES.MEGAMENU_TARGET_OUT_OF_SCOPE, `CMS Page ${item.target.pageId} is not in scope of the megamenu's bindings.`);
+            }
+            return;
+        }
+        case 'cms-block-embed': {
+            // `findById` and not `findLocalizedById`: existence, `active` included,
+            // is the question — an operator may be pointing a menu item at a block
+            // they have deactivated while they edit it, and the roots' SQL accepted
+            // one. The storefront refuses it later, where a shopper is the one asking.
+            const ok = (await ports.blocks.findById(item.target.blockId)) !== null;
+            if (!ok) {
+                throw new HttpError(400, ERROR_CODES.MEGAMENU_TARGET_OUT_OF_SCOPE, `CMS Block ${item.target.blockId} is not in scope of the megamenu's bindings.`);
+            }
+            return;
+        }
+        case 'asset': {
+            if ('assetId' in item.target) {
+                const asset = await ports.assets.findById(item.target.assetId);
+                if (asset?.kind !== item.target.kind) {
+                    throw new HttpError(400, ERROR_CODES.MEGAMENU_ASSET_KIND_MISMATCH, `Asset ${item.target.assetId} is not a ${item.target.kind}.`);
+                }
+            }
+            else {
+                // Free-URL asset items require a server-side import into the
+                // Assets Library (T068). The Library does not yet expose
+                // `importFromUrl`; until it does, refuse free URLs at the
+                // validator with a clear error so admins know to upload first.
+                throw new HttpError(400, ERROR_CODES.VALIDATION_FAILED, 'Free-URL asset items are not yet supported. Upload the asset to the Assets Library first and reference it by id.');
+            }
+            return;
+        }
+        case 'external-link':
+        case 'button':
+            // No cross-module check beyond the icon already covered above.
+            return;
+    }
+}
+//# sourceMappingURL=target-validator.js.map

package/dist/backend/services/target-validator.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"target-validator.js","sourceRoot":"","sources":["../../../src/backend/services/target-validator.ts"],"names":[],"mappings":"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"}

package/dist/manifest.d.ts

@@ -0,0 +1,167 @@
+/**
+ * Megamenu module — feature 015.
+ *
+ * Owns the megamenu (multi-column dropdown navigation) configuration.
+ * Manifest backfilled alongside feature 020.
+ */
+export declare const manifest: {
+    id: string;
+    name: string;
+    version: string;
+    dependencies: string[];
+    description?: string | undefined;
+    acknowledgedDependencies?: {
+        moduleId: string;
+        port: string;
+        reason: string;
+    }[] | undefined;
+    nonBindingDependencies?: {
+        moduleId: string;
+        name: string;
+        kind: "contributes-to" | "degrades-without" | "refuses-without";
+        reason: string;
+        whenAbsent?: string | undefined;
+    }[] | undefined;
+    activation?: {
+        settingCode: string;
+        default: boolean;
+    } | {
+        nonDeactivatable: true;
+        reason: string;
+    } | undefined;
+    settings?: {
+        moduleCode: string;
+        groups: {
+            code: string;
+            name: string;
+            salesChannelCodes?: string[] | undefined;
+            isSystemProtected?: boolean | undefined;
+        }[];
+        settings: {
+            code: string;
+            name: string;
+            valueType: "string" | "number" | "boolean" | "json" | "string_list" | "secret" | "credential_ref";
+            defaultValue: unknown;
+            description?: string | undefined;
+            groupCode?: string | undefined;
+            previousDefaultValues?: unknown[] | undefined;
+            salesChannelCodes?: string[] | undefined;
+            enumOptions?: string[] | undefined;
+            configurationType?: string | undefined;
+            hidden?: boolean | undefined;
+        }[];
+    } | undefined;
+    i18n?: {
+        bundlesDir: string;
+    } | undefined;
+    docs?: false | {
+        dir: string;
+    } | undefined;
+    demo?: false | {
+        summary: string;
+        seed: (context: import("@endora-commerce/contracts").ModuleDemoContext<never>) => Promise<import("@endora-commerce/contracts").DemoSeedResult>;
+        reset: (context: import("@endora-commerce/contracts").ModuleDemoContext<never>) => Promise<import("@endora-commerce/contracts").DemoResetResult>;
+        after?: readonly string[] | undefined;
+        package?: string | undefined;
+    } | undefined;
+    actions?: {
+        id: string;
+        labelKey: string;
+        icon: "Plus" | "Sparkles" | "Settings" | "Search" | "Boxes" | "Layers" | "Menu" | "PlusCircle" | "PlusSquare" | "FilePlus" | "FolderPlus" | "Upload" | "FileUp" | "CloudUpload" | "Download" | "FileDown" | "FileText" | "BookOpen" | "Rss" | "Package" | "Tag" | "ShoppingCart" | "Receipt" | "CreditCard" | "Users" | "UserPlus" | "Inbox" | "ListChecks" | "ClipboardList" | "Image" | "Video" | "LayoutDashboard" | "PanelLeft" | "KeyRound" | "ShieldCheck" | "Edit" | "Archive" | "Box" | "Truck" | "CircleDollarSign" | "Activity" | "LineChart" | "Smartphone" | "Webhook" | "Scale" | "PlugZap" | "PercentDiamond" | "Newspaper" | "Languages" | "Eraser" | "Warehouse" | "TrendingDown" | "Bell" | "PackageOpen" | "Building2" | "Store" | "ClipboardCheck";
+        targetRoute: string;
+        keywords: string[];
+        weight: number;
+        descriptionKey?: string | undefined;
+        requiredPermission?: string | undefined;
+    }[] | undefined;
+    permissions?: {
+        code: string;
+        label: string;
+        module?: string | undefined;
+        description?: string | undefined;
+        requires?: string[] | undefined;
+    }[] | undefined;
+    transactionalEmails?: {
+        code: string;
+        name: string;
+        variables: {
+            key: string;
+            label: string;
+            sampleValue?: string | undefined;
+            description?: string | undefined;
+        }[];
+        description?: string | undefined;
+        group?: string | undefined;
+    }[] | undefined;
+    capabilities?: string[] | undefined;
+    exclusiveCapabilities?: {
+        key: string;
+        errorCode: string;
+    }[] | undefined;
+    errorCodes?: {
+        code: string;
+        tokens?: string[] | undefined;
+    }[] | undefined;
+    blocks?: {
+        name: string;
+        labelKey: string;
+        category: string;
+        contexts: ("cms" | "invoice" | "email" | "newsletter")[];
+        fields: Record<string, {
+            type: "number" | "object" | "array" | "text" | "textarea" | "select" | "radio" | "external" | "uuid" | "richtext";
+            label?: string | undefined;
+            required?: boolean | undefined;
+            options?: {
+                label: string;
+                value: string | number;
+            }[] | undefined;
+            refKind?: string | undefined;
+        }>;
+        descriptionKey?: string | undefined;
+        defaultProps?: Record<string, unknown> | undefined;
+        responsiveFields?: string[] | undefined;
+        previewIcon?: string | undefined;
+        weight?: number | undefined;
+    }[] | undefined;
+    blockCategories?: {
+        key: string;
+        titleKey: string;
+        contexts: ("cms" | "invoice" | "email" | "newsletter")[];
+        weight?: number | undefined;
+        visible?: boolean | undefined;
+    }[] | undefined;
+    env?: {
+        name: string;
+        describes: {
+            en: string;
+            pl: string;
+        };
+        requirement: {
+            kind: "required";
+        } | {
+            kind: "requiredWhen";
+            input: string;
+            equals: string;
+        } | {
+            kind: "optional";
+            without: {
+                en: string;
+                pl: string;
+            };
+        };
+        secret: boolean;
+        generable: boolean;
+        owner: {
+            kind: "platform";
+        } | {
+            kind: "application";
+            application: "admin" | "backend" | "storefront";
+        } | {
+            kind: "module";
+            moduleId: string;
+        };
+        consumers: ("admin" | "backend" | "storefront")[];
+        addressOf: "admin" | "backend" | "storefront" | null;
+    }[] | undefined;
+};
+//# sourceMappingURL=manifest.d.ts.map

package/dist/manifest.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"manifest.d.ts","sourceRoot":"","sources":["../src/manifest.ts"],"names":[],"mappings":"AAEA;;;;;GAKG;AACH,eAAO,MAAM,QAAQ;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CAkKnB,CAAC"}

package/dist/manifest.js

@@ -0,0 +1,170 @@
+import { defineModuleManifest } from '@endora-commerce/contracts';
+/**
+ * Megamenu module — feature 015.
+ *
+ * Owns the megamenu (multi-column dropdown navigation) configuration.
+ * Manifest backfilled alongside feature 020.
+ */
+export const manifest = defineModuleManifest({
+    id: 'megamenu',
+    name: 'Megamenu',
+    description: 'Multi-column dropdown navigation builder.',
+    version: '1.0.0',
+    // `auth` owns the `requireAdmin` port the admin routes are gated by — feature
+    // 072 made it required rather than defaulting to a permissive no-op.
+    // `dictionaries` owns the validator the menu service checks languages with.
+    // `assets_library` owns the reference registry this module contributes its
+    // asset-and-icon scan to (T143a); `cms` owns the one it contributes the
+    // page/block scan to. Both edges existed as composition-root
+    // cross-registrations, which is to say nowhere an operator could see them.
+    // `languages` owns `languageReferenceRegistry`, the registry this module
+    // contributes its "which languages do bindings carry" descriptor to (feature
+    // 077, D-87). `languages` used to ask the question itself, with a
+    // `count(*) from "megamenu_bindings"` naming this module's table.
+    //
+    // `catalog` is new with `specs/110-instance-repository/` T118c, and it is the
+    // one edge this module did not already have. A menu item may target a
+    // category, so validating it and resolving its storefront URL are reads of
+    // `catalog`'s table — issued by a composition root in raw SQL until T118c, in
+    // a file that is nobody's declared dependency, so the edge existed nowhere an
+    // operator or a check could see it. It is `catalogCategoryReadPort` now, and
+    // the `demo` block below records what that changes about its own argument.
+    //
+    // The bind costs no operator a control, and that is derived rather than
+    // waived: `catalog` declares itself non-deactivatable, so this is not an edge
+    // into a switchable module and it owes no `nonBindingDependencies` entry. The
+    // other two owners T118c's ports belong to — `cms` and `assets_library` — were
+    // both already declared here, for the reference registries above, so the drain
+    // adds one line to this array and no judgement beyond it.
+    dependencies: [
+        'assets_library',
+        'catalog',
+        'cms',
+        'languages',
+        'sales_channels',
+        'auth',
+        'dictionaries',
+    ],
+    settings: {
+        moduleCode: 'megamenu',
+        groups: [{ code: 'megamenu', name: 'Megamenu' }],
+        settings: [
+            {
+                // Feature 073 — the operator's activation control. Platform-wide.
+                code: 'megamenu.enabled',
+                name: 'Megamenu enabled',
+                description: 'Switches the megamenu admin screens, their API and the storefront navigation they drive on or off. Nothing is dropped: menus, items and channel bindings stay in the database and reappear exactly as configured when you switch it back on.',
+                groupCode: 'megamenu',
+                valueType: 'boolean',
+                defaultValue: true,
+            },
+        ],
+    },
+    /**
+     * The ten error codes this module owns — feature 090, Phase 3.
+     *
+     * **This list is the incumbent prefix chain's answer, copied from
+     * `backend/test/fixtures/error-code-routing/chain-answers.ts`, not a
+     * judgement.** The migration is answer-preserving over all 289 codes with no
+     * exception list (`specs/090-module-owned-error-codes/contracts/error-code-declaration.md`
+     * §6.2), so nothing here was added or dropped because it looked misplaced;
+     * re-routing is §6.5's and out of scope.
+     *
+     * **Two codes a reader would attribute elsewhere, in both directions.**
+     * `MEGAMENU_LANGUAGE_NOT_IN_CHANNEL_SCOPE` reads as `sales_channels`' — it
+     * is raised while checking a language against a Sales Channel's configured
+     * language set — and is ours: the chain routes it on the `MEGAMENU_` prefix
+     * and `megamenu-service.ts` is what raises it. Going the other way, the three
+     * codes this module raises and does **not** own are `NOT_FOUND`,
+     * `VALIDATION_FAILED` and `VERSION_CONFLICT`, all the platform's; the first
+     * of those is raised for a *Sales Channel* that does not exist, so a reader
+     * tracing that refusal would look in `sales_channels` and find it in `core`.
+     *
+     * **Two of the ten are raised by nothing, and neither is a missing rule.**
+     * Both spellings were searched over `packages` and `backend/src` —
+     * `ERROR_CODES.<CODE>` and the bare quoted literal — because a module need
+     * not spell its codes the first way (runbook step 2, T12).
+     * `MEGAMENU_DEPTH_EXCEEDED` is built, enforced and covered by
+     * `test/contract/megamenu/admin-items-depth.contract.test.ts`, and it reaches
+     * the client — as a `meta.warnings` entry on a **200**, because FR-011 makes
+     * depth a non-blocking soft warning. It is never thrown, so the envelope can
+     * never render the `errors.MEGAMENU_DEPTH_EXCEEDED` sentence written for it
+     * in both languages. `MEGAMENU_REFERENCED` is built too: this module
+     * contributes reference descriptors to `assets_library`'s and `cms`' delete
+     * scans (`asset-references.ts`, `cms-references.ts`), the delete *is* refused
+     * and the holder list *does* name the menu — but the refusal is answered
+     * under the deleting module's code, `ASSET_REFERENCED` or `CMS_REFERENCED`,
+     * so this one never travels either.
+     * `specs/015-megamenu/contracts/megamenu-reference-scan.contract.md`
+     * still specifies `409 MEGAMENU_REFERENCED`; the contract and the
+     * implementation disagree, and that is a product finding rather than this
+     * merge request's to repair.
+     *
+     * **No `tokens`, derived rather than assumed.** The envelope's `refusalToken`
+     * (`packages/platform/src/http/error-envelope.ts`) reads exactly one member
+     * of `details` — `code`, and only when `details` is an object. Every raise of
+     * one of these codes was enumerated over `packages` and `backend/src` rather
+     * than over this package alone (runbook §5): all sixteen pass three
+     * arguments to `HttpError` and no fourth at all, so none can carry a token.
+     * The bundle agrees from the other direction — ten `errors.<CODE>` keys and
+     * not one `errors.<CODE>.<token>`.
+     */
+    errorCodes: [
+        { code: 'MEGAMENU_ASSET_KIND_MISMATCH' },
+        { code: 'MEGAMENU_BINDING_ALREADY_EXISTS' },
+        { code: 'MEGAMENU_BINDING_NOT_FOUND' },
+        { code: 'MEGAMENU_DEPTH_EXCEEDED' },
+        { code: 'MEGAMENU_EMPTY_TREE' },
+        { code: 'MEGAMENU_HAS_ACTIVE_BINDINGS' },
+        { code: 'MEGAMENU_LANGUAGE_NOT_IN_CHANNEL_SCOPE' },
+        { code: 'MEGAMENU_NOT_FOUND' },
+        { code: 'MEGAMENU_REFERENCED' },
+        { code: 'MEGAMENU_TARGET_OUT_OF_SCOPE' },
+    ],
+    i18n: { bundlesDir: 'i18n' },
+    docs: { dir: 'docs' },
+    permissions: [
+        { code: 'megamenu.read', label: 'View megamenu configuration' },
+        { code: 'megamenu.write', label: 'Edit megamenu configuration' },
+    ],
+    actions: [
+        {
+            id: 'edit-megamenu',
+            labelKey: 'actions.editMegamenu.label',
+            descriptionKey: 'actions.editMegamenu.description',
+            icon: 'Menu',
+            targetRoute: '/megamenu',
+            requiredPermission: 'megamenu.write',
+            keywords: ['menu', 'edit', 'navigation', 'edytuj', 'nawigacja'],
+            weight: 240,
+        },
+    ],
+    // Feature 073 — the operator's activation control. Platform-wide. A platform
+    // without a megamenu is a smaller platform, not a broken one: the menus,
+    // their items and their channel bindings stay in the database and reappear
+    // exactly as configured when it is switched back on.
+    /**
+      * Nothing to demonstrate of its own (feature 113, T225 — contract §1.2).
+      *
+      * The demo shop does have a megamenu, and it is not this module's demo data:
+      * it mirrors `catalog`'s demo category tree and binds to the demo sales
+      * channels, so it is three modules' rows in one step and belongs to whoever
+      * owns the instance (§5.1). It is step 1 of `backend/src/seeds/
+      * demo-composition.ts`.
+      *
+      * **This block used to add *"and this module does not declare `catalog`"* as
+      * §2.3's measured case.** It declares it since
+      * `specs/110-instance-repository/` T118c, for a reason that has nothing to do
+      * with demo data: a menu item may target a category, so validating one is a
+      * read of `catalogCategoryReadPort`. The clause is retired rather than
+      * updated because it was the weaker half of the argument all along — the rule
+      * is that `demo` may not become a way of *acquiring* a dependency, and it
+      * holds identically now that the dependency is here on its own merits.
+      *
+      * `false` rather than absent, because the two are different states: this is
+      * a decision that the module owes nothing, not a module nobody has looked at.
+      */
+    demo: false,
+    activation: { settingCode: 'megamenu.enabled', default: true },
+});
+//# sourceMappingURL=manifest.js.map

package/dist/manifest.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"manifest.js","sourceRoot":"","sources":["../src/manifest.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,oBAAoB,EAAE,MAAM,4BAA4B,CAAC;AAElE;;;;;GAKG;AACH,MAAM,CAAC,MAAM,QAAQ,GAAG,oBAAoB,CAAC;IAC3C,EAAE,EAAE,UAAU;IACd,IAAI,EAAE,UAAU;IAChB,WAAW,EAAE,2CAA2C;IACxD,OAAO,EAAE,OAAO;IAChB,8EAA8E;IAC9E,qEAAqE;IACrE,4EAA4E;IAC5E,2EAA2E;IAC3E,wEAAwE;IACxE,6DAA6D;IAC7D,2EAA2E;IAC3E,yEAAyE;IACzE,6EAA6E;IAC7E,kEAAkE;IAClE,kEAAkE;IAClE,EAAE;IACF,8EAA8E;IAC9E,sEAAsE;IACtE,2EAA2E;IAC3E,8EAA8E;IAC9E,8EAA8E;IAC9E,6EAA6E;IAC7E,2EAA2E;IAC3E,EAAE;IACF,wEAAwE;IACxE,8EAA8E;IAC9E,8EAA8E;IAC9E,+EAA+E;IAC/E,+EAA+E;IAC/E,0DAA0D;IAC1D,YAAY,EAAE;QACZ,gBAAgB;QAChB,SAAS;QACT,KAAK;QACL,WAAW;QACX,gBAAgB;QAChB,MAAM;QACN,cAAc;KACf;IACD,QAAQ,EAAE;QACR,UAAU,EAAE,UAAU;QACtB,MAAM,EAAE,CAAC,EAAE,IAAI,EAAE,UAAU,EAAE,IAAI,EAAE,UAAU,EAAE,CAAC;QAChD,QAAQ,EAAE;YACR;gBACE,kEAAkE;gBAClE,IAAI,EAAE,kBAAkB;gBACxB,IAAI,EAAE,kBAAkB;gBACxB,WAAW,EACT,8OAA8O;gBAChP,SAAS,EAAE,UAAU;gBACrB,SAAS,EAAE,SAAS;gBACpB,YAAY,EAAE,IAAI;aACnB;SACF;KACF;IACD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OAgDG;IACH,UAAU,EAAE;QACV,EAAE,IAAI,EAAE,8BAA8B,EAAE;QACxC,EAAE,IAAI,EAAE,iCAAiC,EAAE;QAC3C,EAAE,IAAI,EAAE,4BAA4B,EAAE;QACtC,EAAE,IAAI,EAAE,yBAAyB,EAAE;QACnC,EAAE,IAAI,EAAE,qBAAqB,EAAE;QAC/B,EAAE,IAAI,EAAE,8BAA8B,EAAE;QACxC,EAAE,IAAI,EAAE,wCAAwC,EAAE;QAClD,EAAE,IAAI,EAAE,oBAAoB,EAAE;QAC9B,EAAE,IAAI,EAAE,qBAAqB,EAAE;QAC/B,EAAE,IAAI,EAAE,8BAA8B,EAAE;KACzC;IACD,IAAI,EAAE,EAAE,UAAU,EAAE,MAAM,EAAE;IAC5B,IAAI,EAAE,EAAE,GAAG,EAAE,MAAM,EAAE;IACrB,WAAW,EAAE;QACX,EAAE,IAAI,EAAE,eAAe,EAAE,KAAK,EAAE,6BAA6B,EAAE;QAC/D,EAAE,IAAI,EAAE,gBAAgB,EAAE,KAAK,EAAE,6BAA6B,EAAE;KACjE;IACD,OAAO,EAAE;QACP;YACE,EAAE,EAAE,eAAe;YACnB,QAAQ,EAAE,4BAA4B;YACtC,cAAc,EAAE,kCAAkC;YAClD,IAAI,EAAE,MAAM;YACZ,WAAW,EAAE,WAAW;YACxB,kBAAkB,EAAE,gBAAgB;YACpC,QAAQ,EAAE,CAAC,MAAM,EAAE,MAAM,EAAE,YAAY,EAAE,QAAQ,EAAE,WAAW,CAAC;YAC/D,MAAM,EAAE,GAAG;SACZ;KACF;IACD,6EAA6E;IAC7E,yEAAyE;IACzE,2EAA2E;IAC3E,qDAAqD;IACrD;;;;;;;;;;;;;;;;;;;;QAoBI;IACJ,IAAI,EAAE,KAAK;IACX,UAAU,EAAE,EAAE,WAAW,EAAE,kBAAkB,EAAE,OAAO,EAAE,IAAI,EAAE;CAC/D,CAAC,CAAC"}

package/dist/migrations/20260505T193836_megamenu_init.d.ts

@@ -0,0 +1,23 @@
+import { Migration } from '@mikro-orm/migrations';
+/**
+ * Megamenu module — feature 015 / data-model.md.
+ *
+ * Schema changes (one atomic migration):
+ *   - new tables: `megamenus`, `megamenu_items`, `megamenu_bindings`.
+ *   - GIN index on `megamenu_items.target` (jsonb_path_ops) so the
+ *     cross-module reference scan stays fast.
+ *   - btree index on `megamenu_items(megamenu_id, parent_id, position)`
+ *     drives the per-tree fetch.
+ *   - **partial unique index** on
+ *     `megamenu_bindings(sales_channel_id, language) WHERE active = true`
+ *     enforces "exactly one active megamenu per (channel, language)"
+ *     (FR-008 + research § R3) at the DB level.
+ *
+ * No seed rows; no data backfill — first-time admins create the first
+ * configuration through the admin UI.
+ */
+export declare class Migration20260505T193836MegamenuInit extends Migration {
+    up(): Promise<void>;
+    down(): Promise<void>;
+}
+//# sourceMappingURL=20260505T193836_megamenu_init.d.ts.map

package/dist/migrations/20260505T193836_megamenu_init.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"20260505T193836_megamenu_init.d.ts","sourceRoot":"","sources":["../../src/migrations/20260505T193836_megamenu_init.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,SAAS,EAAE,MAAM,uBAAuB,CAAC;AAElD;;;;;;;;;;;;;;;;GAgBG;AACH,qBAAa,oCAAqC,SAAQ,SAAS;IAClD,EAAE,IAAI,OAAO,CAAC,IAAI,CAAC;IA4EnB,IAAI,IAAI,OAAO,CAAC,IAAI,CAAC;CAKrC"}

package/dist/migrations/20260505T193836_megamenu_init.js

@@ -0,0 +1,91 @@
+import { Migration } from '@mikro-orm/migrations';
+/**
+ * Megamenu module — feature 015 / data-model.md.
+ *
+ * Schema changes (one atomic migration):
+ *   - new tables: `megamenus`, `megamenu_items`, `megamenu_bindings`.
+ *   - GIN index on `megamenu_items.target` (jsonb_path_ops) so the
+ *     cross-module reference scan stays fast.
+ *   - btree index on `megamenu_items(megamenu_id, parent_id, position)`
+ *     drives the per-tree fetch.
+ *   - **partial unique index** on
+ *     `megamenu_bindings(sales_channel_id, language) WHERE active = true`
+ *     enforces "exactly one active megamenu per (channel, language)"
+ *     (FR-008 + research § R3) at the DB level.
+ *
+ * No seed rows; no data backfill — first-time admins create the first
+ * configuration through the admin UI.
+ */
+export class Migration20260505T193836MegamenuInit extends Migration {
+    async up() {
+        // ────────────────────────────────────────────────────────────────────
+        // 1) megamenus
+        // ────────────────────────────────────────────────────────────────────
+        this.addSql(`
+      create table "megamenus" (
+        "id" uuid not null,
+        "name" varchar(200) not null,
+        "description" text null,
+        "version" int not null default 1,
+        "created_at" timestamptz not null,
+        "updated_at" timestamptz not null,
+        constraint "megamenus_pkey" primary key ("id")
+      );
+    `);
+        // ────────────────────────────────────────────────────────────────────
+        // 2) megamenu_items — adjacency-list tree
+        // ────────────────────────────────────────────────────────────────────
+        this.addSql(`
+      create table "megamenu_items" (
+        "id" uuid not null,
+        "megamenu_id" uuid not null,
+        "parent_id" uuid null,
+        "position" int not null default 0,
+        "kind" varchar(32) not null,
+        "labels" jsonb not null default '{}'::jsonb,
+        "descriptions" jsonb null,
+        "target" jsonb not null default '{}'::jsonb,
+        "created_at" timestamptz not null,
+        "updated_at" timestamptz not null,
+        constraint "megamenu_items_pkey" primary key ("id"),
+        constraint "megamenu_items_megamenu_fk" foreign key ("megamenu_id")
+          references "megamenus" ("id") on delete cascade,
+        constraint "megamenu_items_parent_fk" foreign key ("parent_id")
+          references "megamenu_items" ("id") on delete cascade
+      );
+    `);
+        this.addSql('create index "idx_megamenu_items_tree" on "megamenu_items" ("megamenu_id", "parent_id", "position");');
+        this.addSql('create index "idx_megamenu_items_target_refs" on "megamenu_items" using gin ("target" jsonb_path_ops);');
+        // ────────────────────────────────────────────────────────────────────
+        // 3) megamenu_bindings
+        // ────────────────────────────────────────────────────────────────────
+        this.addSql(`
+      create table "megamenu_bindings" (
+        "megamenu_id" uuid not null,
+        "sales_channel_id" uuid not null,
+        "language" varchar(8) not null,
+        "active" boolean not null default false,
+        "version" int not null default 1,
+        "created_at" timestamptz not null,
+        "updated_at" timestamptz not null,
+        constraint "megamenu_bindings_pkey"
+          primary key ("megamenu_id", "sales_channel_id", "language"),
+        constraint "megamenu_bindings_megamenu_fk" foreign key ("megamenu_id")
+          references "megamenus" ("id") on delete cascade,
+        constraint "megamenu_bindings_channel_fk" foreign key ("sales_channel_id")
+          references "sales_channels" ("id") on delete cascade
+      );
+    `);
+        // Partial unique index (FR-008 / R3) — exactly one active megamenu
+        // per (sales_channel_id, language).
+        this.addSql('create unique index "idx_megamenu_bindings_active_uniq" on "megamenu_bindings" ("sales_channel_id", "language") where "active" = true;');
+        // Lookup index for the storefront resolver.
+        this.addSql('create index "idx_megamenu_bindings_channel_lang" on "megamenu_bindings" ("sales_channel_id", "language");');
+    }
+    async down() {
+        this.addSql('drop table if exists "megamenu_bindings" cascade;');
+        this.addSql('drop table if exists "megamenu_items" cascade;');
+        this.addSql('drop table if exists "megamenus" cascade;');
+    }
+}
+//# sourceMappingURL=20260505T193836_megamenu_init.js.map

package/dist/migrations/20260505T193836_megamenu_init.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"20260505T193836_megamenu_init.js","sourceRoot":"","sources":["../../src/migrations/20260505T193836_megamenu_init.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,SAAS,EAAE,MAAM,uBAAuB,CAAC;AAElD;;;;;;;;;;;;;;;;GAgBG;AACH,MAAM,OAAO,oCAAqC,SAAQ,SAAS;IACxD,KAAK,CAAC,EAAE;QACf,uEAAuE;QACvE,eAAe;QACf,uEAAuE;QACvE,IAAI,CAAC,MAAM,CAAC;;;;;;;;;;KAUX,CAAC,CAAC;QAEH,uEAAuE;QACvE,0CAA0C;QAC1C,uEAAuE;QACvE,IAAI,CAAC,MAAM,CAAC;;;;;;;;;;;;;;;;;;KAkBX,CAAC,CAAC;QACH,IAAI,CAAC,MAAM,CACT,sGAAsG,CACvG,CAAC;QACF,IAAI,CAAC,MAAM,CACT,wGAAwG,CACzG,CAAC;QAEF,uEAAuE;QACvE,uBAAuB;QACvB,uEAAuE;QACvE,IAAI,CAAC,MAAM,CAAC;;;;;;;;;;;;;;;;KAgBX,CAAC,CAAC;QACH,mEAAmE;QACnE,oCAAoC;QACpC,IAAI,CAAC,MAAM,CACT,wIAAwI,CACzI,CAAC;QACF,4CAA4C;QAC5C,IAAI,CAAC,MAAM,CACT,4GAA4G,CAC7G,CAAC;IACJ,CAAC;IAEQ,KAAK,CAAC,IAAI;QACjB,IAAI,CAAC,MAAM,CAAC,mDAAmD,CAAC,CAAC;QACjE,IAAI,CAAC,MAAM,CAAC,gDAAgD,CAAC,CAAC;QAC9D,IAAI,CAAC,MAAM,CAAC,2CAA2C,CAAC,CAAC;IAC3D,CAAC;CACF"}

package/dist/migrations/index.d.ts

@@ -0,0 +1,27 @@
+/**
+ * The `./migrations` subpath — every migration class this module owns, as one
+ * ordered `migrations` array.
+ *
+ * The array is what the platform reads when this module is **installed**:
+ * `src/packages/package-runtime.ts` takes `exported['migrations']` and refuses
+ * the package outright when it is absent (D-168).
+ *
+ * Listed in ascending timestamp, which orders **this module's own** migrations
+ * and nothing else (feature 081). Where the block sits relative to every other
+ * module's is decided by the manifest `dependencies` graph.
+ *
+ * The **named** exports stay, and the asymmetry with `./backend` — which
+ * publishes an array and no entity class by name (D-168) — is deliberate.
+ * `db/migrations-registry.generated.ts` imports each class by name from this
+ * specifier, and a migration class name is contract in a way an entity class
+ * name is not: `mikro_orm_migrations` persists it, so it is a string every
+ * already-migrated database holds.
+ *
+ * A class that is in neither the array nor the barrel is a migration that does
+ * not run: `migration:pending` reports nothing pending and the first symptom
+ * is a query against a table nobody created.
+ */
+import { Migration20260505T193836MegamenuInit } from './20260505T193836_megamenu_init.js';
+export declare const migrations: (typeof Migration20260505T193836MegamenuInit)[];
+export { Migration20260505T193836MegamenuInit, };
+//# sourceMappingURL=index.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/migrations/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;GAsBG;AAEH,OAAO,EAAE,oCAAoC,EAAE,MAAM,oCAAoC,CAAC;AAE1F,eAAO,MAAM,UAAU,iDAEtB,CAAC;AAEF,OAAO,EACL,oCAAoC,GACrC,CAAC"}

package/dist/migrations/index.js

@@ -0,0 +1,29 @@
+/**
+ * The `./migrations` subpath — every migration class this module owns, as one
+ * ordered `migrations` array.
+ *
+ * The array is what the platform reads when this module is **installed**:
+ * `src/packages/package-runtime.ts` takes `exported['migrations']` and refuses
+ * the package outright when it is absent (D-168).
+ *
+ * Listed in ascending timestamp, which orders **this module's own** migrations
+ * and nothing else (feature 081). Where the block sits relative to every other
+ * module's is decided by the manifest `dependencies` graph.
+ *
+ * The **named** exports stay, and the asymmetry with `./backend` — which
+ * publishes an array and no entity class by name (D-168) — is deliberate.
+ * `db/migrations-registry.generated.ts` imports each class by name from this
+ * specifier, and a migration class name is contract in a way an entity class
+ * name is not: `mikro_orm_migrations` persists it, so it is a string every
+ * already-migrated database holds.
+ *
+ * A class that is in neither the array nor the barrel is a migration that does
+ * not run: `migration:pending` reports nothing pending and the first symptom
+ * is a query against a table nobody created.
+ */
+import { Migration20260505T193836MegamenuInit } from './20260505T193836_megamenu_init.js';
+export const migrations = [
+    Migration20260505T193836MegamenuInit,
+];
+export { Migration20260505T193836MegamenuInit, };
+//# sourceMappingURL=index.js.map

package/dist/migrations/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/migrations/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;GAsBG;AAEH,OAAO,EAAE,oCAAoC,EAAE,MAAM,oCAAoC,CAAC;AAE1F,MAAM,CAAC,MAAM,UAAU,GAAG;IACxB,oCAAoC;CACrC,CAAC;AAEF,OAAO,EACL,oCAAoC,GACrC,CAAC"}