@squiz/dxp-cli-next 5.30.0 → 5.31.0-develop.1

package/lib/page/layouts/deploy/deploy.js

@@ -90,8 +90,34 @@ const createDeployCommand = () => {
     return deployCommand;
 };
 exports.default = createDeployCommand;
+/**
+ * Formats backend error responses into user-friendly error messages.
+ * Handles both validation errors (400s) and unknown server errors (500s).
+ *
+ * @param data - The error response data from the backend
+ * @param statusCode - The HTTP status code (optional)
+ * @returns Formatted error message string
+ */
+function formatErrorResponse(data, statusCode) {
+    // For 500 errors or unknown errors, show a generic message
+    if (statusCode && statusCode >= 500) {
+        return data.message || data.data || 'An unknown error occurred';
+    }
+    // For validation errors (400s), format with details
+    let errorMessage = data.message || 'Validation failed';
+    // Options validation errors come as an object with field keys
+    if (data.details &&
+        typeof data.details === 'object' &&
+        !Array.isArray(data.details)) {
+        const details = Object.entries(data.details)
+            .map(([field, error]) => `  - ${field}: ${error.message}`)
+            .join('\n');
+        errorMessage += `\n${details}`;
+    }
+    return errorMessage;
+}
 function uploadLayout(client, layout, contentServiceUrl, dryRun) {
-    var _a, _b;
+    var _a;
     return __awaiter(this, void 0, void 0, function* () {
         try {
             const queryParam = dryRun ? '?_dryRun=true' : '';
@@ -101,13 +127,13 @@ function uploadLayout(client, layout, contentServiceUrl, dryRun) {
             if (response.status === 200) {
                 return response;
             }
-            const error = new Error(response.data.message);
-            if ((_b = (_a = response.data.details) === null || _a === void 0 ? void 0 : _a.input) === null || _b === void 0 ? void 0 : _b.message) {
-                error.message += `: ${response.data.details.input.message}`;
-            }
-            throw error;
+            throw new Error(formatErrorResponse(response.data, response.status));
         }
         catch (error) {
+            // Extract error details from axios error response
+            if ((_a = error.response) === null || _a === void 0 ? void 0 : _a.data) {
+                throw new Error(formatErrorResponse(error.response.data, error.response.status));
+            }
             throw error;
         }
     });

package/lib/page/layouts/deploy/deploy.spec.js

@@ -170,7 +170,7 @@ describe('deployCommand', () => {
         const program = (0, deploy_1.default)();
         errorSpy = jest.spyOn(program, 'error').mockImplementation();
         yield program.parseAsync(createMockArgs({ contentServiceUrl }));
-        expect(errorSpy).toHaveBeenCalledWith(expect.stringContaining('An unknown error occurred'));
+        expect(errorSpy).toHaveBeenCalledWith(expect.stringContaining('Internal server error'));
     }));
     it('should log additional details when layout validation fails', () => __awaiter(void 0, void 0, void 0, function* () {
         const dxpBaseUrl = 'http://dxp-base-url.com';
@@ -187,8 +187,61 @@ describe('deployCommand', () => {
         const program = (0, deploy_1.default)();
         errorSpy = jest.spyOn(program, 'error').mockImplementation();
         yield program.parseAsync(createMockArgs({ dxpBaseUrl }));
-        expect(errorSpy).toHaveBeenCalledWith(expect.stringContaining('Layout validation failed: ERROR: Validation failed: "version" is an excess property and therefore is not allowed'));
+        const errorCall = errorSpy.mock.calls[0][0];
+        expect(errorCall).toContain('- input: ERROR: Validation failed: "version" is an excess property and therefore is not allowed');
     }));
+    describe('backend option validation error reporting', () => {
+        it('should display clean error when single option validation fails', () => __awaiter(void 0, void 0, void 0, function* () {
+            const contentServiceUrl = 'http://localhost:9999';
+            (0, nock_1.default)(contentServiceUrl)
+                .post('/page-layout')
+                .reply(400, {
+                message: 'Validation failed',
+                details: {
+                    'input.options.myBoolean': {
+                        message: "Option 'myBoolean' with valueType 'boolean' can not have values specified",
+                    },
+                },
+            });
+            const program = (0, deploy_1.default)();
+            errorSpy = jest.spyOn(program, 'error').mockImplementation();
+            yield program.parseAsync(createMockArgs({ contentServiceUrl }));
+            const errorCall = errorSpy.mock.calls[0][0];
+            expect(errorCall).toContain('Validation failed');
+            expect(errorCall).toContain("- input.options.myBoolean: Option 'myBoolean' with valueType 'boolean' can not have values specified");
+        }));
+        it('should display multiple option validation errors cleanly', () => __awaiter(void 0, void 0, void 0, function* () {
+            const contentServiceUrl = 'http://localhost:9999';
+            (0, nock_1.default)(contentServiceUrl)
+                .post('/page-layout')
+                .reply(400, {
+                message: 'Validation failed',
+                details: {
+                    'input.options.badBoolean': {
+                        message: "Option 'badBoolean' with valueType 'boolean' can not have values specified",
+                    },
+                    'input.options.badText': {
+                        message: "Option 'badText' with valueType 'text' can not have values specified",
+                    },
+                    'input.options.emptyEnum': {
+                        message: "Option 'emptyEnum' with valueType 'string-enum' must have at least one value defined",
+                    },
+                    'input.options.badOption.valueType': {
+                        message: "Option 'badOption' has invalid valueType 'INVALID'. Must be one of: string-enum, boolean, text",
+                    },
+                },
+            });
+            const program = (0, deploy_1.default)();
+            errorSpy = jest.spyOn(program, 'error').mockImplementation();
+            yield program.parseAsync(createMockArgs({ contentServiceUrl }));
+            const errorCall = errorSpy.mock.calls[0][0];
+            expect(errorCall).toContain('Validation failed');
+            expect(errorCall).toContain("- input.options.badBoolean: Option 'badBoolean' with valueType 'boolean' can not have values specified");
+            expect(errorCall).toContain("- input.options.badText: Option 'badText' with valueType 'text' can not have values specified");
+            expect(errorCall).toContain("- input.options.emptyEnum: Option 'emptyEnum' with valueType 'string-enum' must have at least one value defined");
+            expect(errorCall).toContain("- input.options.badOption.valueType: Option 'badOption' has invalid valueType 'INVALID'. Must be one of: string-enum, boolean, text");
+        }));
+    });
     describe('zone consistency validation', () => {
         it('should handle zone consistency validation errors where zones are used but not defined in the layout', () => __awaiter(void 0, void 0, void 0, function* () {
             const file = './src/__tests__/layout.yaml';

package/lib/page/layouts/dev/dev.js

@@ -45,12 +45,14 @@ const createDevCommand = () => {
             }
             // Confirm for entry property
             const layoutDefinition = Object.assign({}, rawLayoutDefinition);
+            // Normalize options to convert string booleans to actual booleans
+            const normalizedOptions = (0, parse_args_1.normalizeLayoutOptions)(options.options, layoutDefinition);
             exports.logger.info('Starting development server...');
             yield (0, server_1.startDevServer)({
                 configPath: path_1.default.resolve(options.config),
                 layoutDefinition,
                 zoneContent: options.zones,
-                layoutOptions: options.options,
+                layoutOptions: normalizedOptions,
                 stylesheet: options.stylesheet
                     ? path_1.default.resolve(options.stylesheet)
                     : undefined,

package/lib/page/layouts/dev/dev.spec.js

@@ -136,6 +136,33 @@ describe('devCommand', () => {
             layoutOptions,
         }));
     }));
+    it('normalizes boolean options from strings to actual booleans', () => __awaiter(void 0, void 0, void 0, function* () {
+        const mockLayout = {
+            name: 'Test Layout',
+            options: {
+                showFooter: { valueType: 'boolean' },
+                showHeader: { valueType: 'boolean' },
+                theme: { valueType: 'string-enum' },
+            },
+        };
+        definitions_1.loadLayoutDefinition.mockResolvedValue(mockLayout);
+        const layoutOptions = {
+            showFooter: 'true',
+            showHeader: 'false',
+            theme: 'dark',
+        };
+        const program = (0, dev_1.default)();
+        const args = createMockArgs({ layoutOptions });
+        process.argv = args;
+        yield program.parseAsync(args);
+        expect(server_1.startDevServer).toHaveBeenCalledWith(expect.objectContaining({
+            layoutOptions: {
+                showFooter: true,
+                showHeader: false,
+                theme: 'dark', // Remains string
+            },
+        }));
+    }));
     it('handles failure to load layout definition', () => __awaiter(void 0, void 0, void 0, function* () {
         const config = './src/__tests__/layout.yaml';
         definitions_1.loadLayoutDefinition.mockResolvedValue(undefined);

package/lib/page/utils/definitions.d.ts

@@ -49,15 +49,18 @@ export declare const BaseLayoutDefinition: z.ZodObject<{
     options: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodObject<{
         displayName: z.ZodString;
         description: z.ZodString;
-        values: z.ZodArray<z.ZodString, "many">;
+        valueType: z.ZodOptional<z.ZodEnum<["string-enum", "boolean", "text"]>>;
+        values: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
     }, "strip", z.ZodTypeAny, {
-        values: string[];
         description: string;
         displayName: string;
+        values?: string[] | undefined;
+        valueType?: "boolean" | "text" | "string-enum" | undefined;
     }, {
-        values: string[];
         description: string;
         displayName: string;
+        values?: string[] | undefined;
+        valueType?: "boolean" | "text" | "string-enum" | undefined;
     }>>>;
 }, "strip", z.ZodTypeAny, {
     name: string;
@@ -70,9 +73,10 @@ export declare const BaseLayoutDefinition: z.ZodObject<{
         maxNodes?: number | undefined;
     }>;
     options?: Record<string, {
-        values: string[];
         description: string;
         displayName: string;
+        values?: string[] | undefined;
+        valueType?: "boolean" | "text" | "string-enum" | undefined;
     }> | undefined;
 }, {
     name: string;
@@ -85,9 +89,10 @@ export declare const BaseLayoutDefinition: z.ZodObject<{
         maxNodes?: number | undefined;
     }>;
     options?: Record<string, {
-        values: string[];
         description: string;
         displayName: string;
+        values?: string[] | undefined;
+        valueType?: "boolean" | "text" | "string-enum" | undefined;
     }> | undefined;
 }>;
 export declare const InputLayoutDefinition: z.ZodObject<z.objectUtil.extendShape<{
@@ -133,15 +138,18 @@ export declare const InputLayoutDefinition: z.ZodObject<z.objectUtil.extendShape
     options: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodObject<{
         displayName: z.ZodString;
         description: z.ZodString;
-        values: z.ZodArray<z.ZodString, "many">;
+        valueType: z.ZodOptional<z.ZodEnum<["string-enum", "boolean", "text"]>>;
+        values: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
     }, "strip", z.ZodTypeAny, {
-        values: string[];
         description: string;
         displayName: string;
+        values?: string[] | undefined;
+        valueType?: "boolean" | "text" | "string-enum" | undefined;
     }, {
-        values: string[];
         description: string;
         displayName: string;
+        values?: string[] | undefined;
+        valueType?: "boolean" | "text" | "string-enum" | undefined;
     }>>>;
 }, {
     entry: z.ZodString;
@@ -157,9 +165,10 @@ export declare const InputLayoutDefinition: z.ZodObject<z.objectUtil.extendShape
         maxNodes?: number | undefined;
     }>;
     options?: Record<string, {
-        values: string[];
         description: string;
         displayName: string;
+        values?: string[] | undefined;
+        valueType?: "boolean" | "text" | "string-enum" | undefined;
     }> | undefined;
 }, {
     name: string;
@@ -173,9 +182,10 @@ export declare const InputLayoutDefinition: z.ZodObject<z.objectUtil.extendShape
         maxNodes?: number | undefined;
     }>;
     options?: Record<string, {
-        values: string[];
         description: string;
         displayName: string;
+        values?: string[] | undefined;
+        valueType?: "boolean" | "text" | "string-enum" | undefined;
     }> | undefined;
 }>;
 export declare const LayoutDefinition: z.ZodObject<z.objectUtil.extendShape<{
@@ -221,15 +231,18 @@ export declare const LayoutDefinition: z.ZodObject<z.objectUtil.extendShape<{
     options: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodObject<{
         displayName: z.ZodString;
         description: z.ZodString;
-        values: z.ZodArray<z.ZodString, "many">;
+        valueType: z.ZodOptional<z.ZodEnum<["string-enum", "boolean", "text"]>>;
+        values: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
     }, "strip", z.ZodTypeAny, {
-        values: string[];
         description: string;
         displayName: string;
+        values?: string[] | undefined;
+        valueType?: "boolean" | "text" | "string-enum" | undefined;
     }, {
-        values: string[];
         description: string;
         displayName: string;
+        values?: string[] | undefined;
+        valueType?: "boolean" | "text" | "string-enum" | undefined;
     }>>>;
 }, {
     template: z.ZodString;
@@ -245,9 +258,10 @@ export declare const LayoutDefinition: z.ZodObject<z.objectUtil.extendShape<{
     }>;
     template: string;
     options?: Record<string, {
-        values: string[];
         description: string;
         displayName: string;
+        values?: string[] | undefined;
+        valueType?: "boolean" | "text" | "string-enum" | undefined;
     }> | undefined;
 }, {
     name: string;
@@ -261,9 +275,10 @@ export declare const LayoutDefinition: z.ZodObject<z.objectUtil.extendShape<{
     }>;
     template: string;
     options?: Record<string, {
-        values: string[];
         description: string;
         displayName: string;
+        values?: string[] | undefined;
+        valueType?: "boolean" | "text" | "string-enum" | undefined;
     }> | undefined;
 }>;
 export declare type InputLayoutDefinition = z.infer<typeof InputLayoutDefinition>;

package/lib/page/utils/definitions.js

@@ -56,6 +56,7 @@ const zod_1 = require("zod");
 const yaml_1 = require("yaml");
 // Local
 const validation_1 = require("../templates/validation");
+const render_1 = require("./render");
 function loadLayoutDefinition(layoutFile) {
     return __awaiter(this, void 0, void 0, function* () {
         try {
@@ -149,7 +150,8 @@ exports.BaseLayoutDefinition = zod_1.z.object({
         .record(zod_1.z.string(), zod_1.z.object({
         displayName: zod_1.z.string(),
         description: zod_1.z.string(),
-        values: zod_1.z.array(zod_1.z.string()),
+        valueType: zod_1.z.enum(render_1.LayoutOptionValueTypes).optional(),
+        values: zod_1.z.array(zod_1.z.string()).optional(),
     }))
         .optional(),
 });

package/lib/page/utils/definitions.spec.js

@@ -88,6 +88,16 @@ entry: template.hbs
                 description: 'Color options',
                 values: ['red', 'blue'],
             },
+            showHeader: {
+                displayName: 'Show Header',
+                description: 'Toggle header visibility',
+                valueType: 'boolean',
+            },
+            customTitle: {
+                displayName: 'Custom Title',
+                description: 'Enter a custom title',
+                valueType: 'text',
+            },
         },
         entry: 'template.hbs',
     });
@@ -178,6 +188,16 @@ entry: template.hbs
                     description: 'Color options',
                     values: ['red', 'blue'],
                 },
+                showHeader: {
+                    displayName: 'Show Header',
+                    description: 'Toggle header visibility',
+                    valueType: 'boolean',
+                },
+                customTitle: {
+                    displayName: 'Custom Title',
+                    description: 'Enter a custom title',
+                    valueType: 'text',
+                },
             },
             template: templateContent,
         });
@@ -436,6 +456,114 @@ describe('LayoutDefinitionParse', () => {
         });
         expect(layoutDefinition.zones.main.minNodes).toBe(0);
     });
+    describe('option schema validation', () => {
+        it('should accept specified valueTypes', () => {
+            var _a, _b, _c;
+            const layoutDefinition = definitions_1.BaseLayoutDefinition.parse({
+                name: 'test-layout',
+                displayName: 'Test Layout',
+                description: 'A test layout',
+                zones: {
+                    main: {
+                        displayName: 'Main Zone',
+                        description: 'Main content area',
+                    },
+                },
+                options: {
+                    theme: {
+                        displayName: 'Theme',
+                        description: 'Color theme',
+                        valueType: 'string-enum',
+                        values: ['light', 'dark'],
+                    },
+                    showSidebar: {
+                        displayName: 'Show Sidebar',
+                        description: 'Toggle sidebar',
+                        valueType: 'boolean',
+                    },
+                    customCss: {
+                        displayName: 'Custom CSS',
+                        description: 'Enter custom CSS',
+                        valueType: 'text',
+                    },
+                },
+            });
+            expect((_a = layoutDefinition.options) === null || _a === void 0 ? void 0 : _a.theme.valueType).toBe('string-enum');
+            expect((_b = layoutDefinition.options) === null || _b === void 0 ? void 0 : _b.showSidebar.valueType).toBe('boolean');
+            expect((_c = layoutDefinition.options) === null || _c === void 0 ? void 0 : _c.customCss.valueType).toBe('text');
+        });
+        it('should reject invalid valueType', () => {
+            expect(() => definitions_1.BaseLayoutDefinition.parse({
+                name: 'test-layout',
+                displayName: 'Test Layout',
+                description: 'A test layout',
+                zones: {
+                    main: {
+                        displayName: 'Main Zone',
+                        description: 'Main content area',
+                    },
+                },
+                options: {
+                    badOption: {
+                        displayName: 'Bad Option',
+                        description: 'Invalid valueType',
+                        valueType: 'INVALID_TYPE',
+                    },
+                },
+            })).toThrow();
+        });
+        it('should allow valueType and values to be optional', () => {
+            var _a, _b, _c, _d, _e, _f, _g, _h;
+            const layoutDefinition = definitions_1.BaseLayoutDefinition.parse({
+                name: 'test-layout',
+                displayName: 'Test Layout',
+                description: 'A test layout',
+                zones: {
+                    main: {
+                        displayName: 'Main Zone',
+                        description: 'Main content area',
+                    },
+                },
+                options: {
+                    withBoth: {
+                        displayName: 'With Both',
+                        description: 'Has valueType and values',
+                        valueType: 'string-enum',
+                        values: ['option1', 'option2'],
+                    },
+                    withValueTypeOnly: {
+                        displayName: 'With ValueType Only',
+                        description: 'Has valueType but no values',
+                        valueType: 'boolean',
+                    },
+                    withValuesOnly: {
+                        displayName: 'With Values Only',
+                        description: 'Has values but no valueType (legacy)',
+                        values: ['legacy1', 'legacy2'],
+                    },
+                    withNeither: {
+                        displayName: 'With Neither',
+                        description: 'Has neither valueType nor values',
+                    },
+                },
+            });
+            // Schema accepts all combinations - Business logic validation (e.g., boolean/text can't have values) happens on backend and reported in CLI on deploy.
+            expect((_a = layoutDefinition.options) === null || _a === void 0 ? void 0 : _a.withBoth.valueType).toBe('string-enum');
+            expect((_b = layoutDefinition.options) === null || _b === void 0 ? void 0 : _b.withBoth.values).toEqual([
+                'option1',
+                'option2',
+            ]);
+            expect((_c = layoutDefinition.options) === null || _c === void 0 ? void 0 : _c.withValueTypeOnly.valueType).toBe('boolean');
+            expect((_d = layoutDefinition.options) === null || _d === void 0 ? void 0 : _d.withValueTypeOnly.values).toBeUndefined();
+            expect((_e = layoutDefinition.options) === null || _e === void 0 ? void 0 : _e.withValuesOnly.valueType).toBeUndefined();
+            expect((_f = layoutDefinition.options) === null || _f === void 0 ? void 0 : _f.withValuesOnly.values).toEqual([
+                'legacy1',
+                'legacy2',
+            ]);
+            expect((_g = layoutDefinition.options) === null || _g === void 0 ? void 0 : _g.withNeither.valueType).toBeUndefined();
+            expect((_h = layoutDefinition.options) === null || _h === void 0 ? void 0 : _h.withNeither.values).toBeUndefined();
+        });
+    });
 });
 describe('validateTemplateFile', () => {
     describe('valid templates', () => {

package/lib/page/utils/parse-args.d.ts

@@ -19,10 +19,26 @@ export declare function parseZonesList(value: string, previous: Record<string, s
  * - Comma-separated list: 'key1=value1,key2=value2' or 'key1:value1,key2:value2'
  * - Multiple --options flags: later values override earlier ones
  *
+ * Note: All values are returned as strings. Use normalizeLayoutOptions() to convert
+ * boolean options to actual boolean types based on the layout definition.
+ *
  * @param value Current value being processed
  * @param previous Previously processed value (used for multiple flags)
- * @returns Record of option names to values
+ * @returns Record of option names to string values
  */
 export declare function parseOptionsList(value: string, previous: Record<string, string>): {
     [x: string]: string;
 };
+/**
+ * Normalizes layout options by converting string boolean values to actual booleans
+ * based on the layout definition's option types.
+ *
+ * @param options The parsed options from CLI (all strings)
+ * @param layoutDefinition The layout definition with option type information
+ * @returns Options with boolean values converted to actual booleans
+ */
+export declare function normalizeLayoutOptions(options: Record<string, string>, layoutDefinition: {
+    options?: Record<string, {
+        valueType?: string;
+    }>;
+}): Record<string, string | boolean>;

package/lib/page/utils/parse-args.js

@@ -1,6 +1,7 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.parseOptionsList = exports.parseZonesList = void 0;
+exports.normalizeLayoutOptions = exports.parseOptionsList = exports.parseZonesList = void 0;
+const render_1 = require("./render");
 /**
  * Parse zones list from command line
  * Supports multiple formats:
@@ -50,9 +51,12 @@ exports.parseZonesList = parseZonesList;
  * - Comma-separated list: 'key1=value1,key2=value2' or 'key1:value1,key2:value2'
  * - Multiple --options flags: later values override earlier ones
  *
+ * Note: All values are returned as strings. Use normalizeLayoutOptions() to convert
+ * boolean options to actual boolean types based on the layout definition.
+ *
  * @param value Current value being processed
  * @param previous Previously processed value (used for multiple flags)
- * @returns Record of option names to values
+ * @returns Record of option names to string values
  */
 function parseOptionsList(value, previous) {
     const result = Object.assign({}, previous);
@@ -82,3 +86,35 @@ function parseOptionsList(value, previous) {
     return result;
 }
 exports.parseOptionsList = parseOptionsList;
+/**
+ * Normalizes layout options by converting string boolean values to actual booleans
+ * based on the layout definition's option types.
+ *
+ * @param options The parsed options from CLI (all strings)
+ * @param layoutDefinition The layout definition with option type information
+ * @returns Options with boolean values converted to actual booleans
+ */
+function normalizeLayoutOptions(options, layoutDefinition) {
+    const normalized = Object.assign({}, options);
+    if (!layoutDefinition.options) {
+        return normalized;
+    }
+    // Convert string "true"/"false" to actual booleans for boolean-type options
+    for (const [key, optionDef] of Object.entries(layoutDefinition.options)) {
+        if (optionDef.valueType === render_1.LayoutOptionValueType.boolean &&
+            key in normalized) {
+            const value = normalized[key];
+            if (value === 'true') {
+                normalized[key] = true;
+            }
+            else if (value === 'false') {
+                normalized[key] = false;
+            }
+            else {
+                throw new Error(`Invalid boolean value "${value}" for option "${key}". Must be "true" or "false".`);
+            }
+        }
+    }
+    return normalized;
+}
+exports.normalizeLayoutOptions = normalizeLayoutOptions;

package/lib/page/utils/parse-args.spec.js

@@ -144,3 +144,141 @@ describe('parseOptionsList', () => {
         });
     });
 });
+describe('normalizeLayoutOptions', () => {
+    it('returns empty object when given no options', () => {
+        const result = (0, parse_args_1.normalizeLayoutOptions)({}, {});
+        expect(result).toEqual({});
+    });
+    it('returns options unchanged when layoutDefinition has no options', () => {
+        const options = {
+            theme: 'dark',
+            size: 'large',
+        };
+        const result = (0, parse_args_1.normalizeLayoutOptions)(options, {});
+        expect(result).toEqual(options);
+    });
+    it('converts string "true" to boolean true for boolean-type options', () => {
+        const options = {
+            showFooter: 'true',
+        };
+        const layoutDefinition = {
+            options: {
+                showFooter: {
+                    valueType: 'boolean',
+                },
+            },
+        };
+        const result = (0, parse_args_1.normalizeLayoutOptions)(options, layoutDefinition);
+        expect(result).toEqual({
+            showFooter: true,
+        });
+        expect(typeof result.showFooter).toBe('boolean');
+    });
+    it('converts string "false" to boolean false for boolean-type options', () => {
+        const options = {
+            showFooter: 'false',
+        };
+        const layoutDefinition = {
+            options: {
+                showFooter: {
+                    valueType: 'boolean',
+                },
+            },
+        };
+        const result = (0, parse_args_1.normalizeLayoutOptions)(options, layoutDefinition);
+        expect(result).toEqual({
+            showFooter: false,
+        });
+        expect(typeof result.showFooter).toBe('boolean');
+    });
+    it('leaves string options unchanged for non-boolean types', () => {
+        const options = {
+            theme: 'dark',
+            customTitle: 'My Title',
+        };
+        const layoutDefinition = {
+            options: {
+                theme: {
+                    valueType: 'string-enum',
+                },
+                customTitle: {
+                    valueType: 'text',
+                },
+            },
+        };
+        const result = (0, parse_args_1.normalizeLayoutOptions)(options, layoutDefinition);
+        expect(result).toEqual(options);
+    });
+    it('handles mixed boolean and string options', () => {
+        const options = {
+            showFooter: 'true',
+            showHeader: 'false',
+            theme: 'dark',
+            customTitle: 'Test',
+        };
+        const layoutDefinition = {
+            options: {
+                showFooter: { valueType: 'boolean' },
+                showHeader: { valueType: 'boolean' },
+                theme: { valueType: 'string-enum' },
+                customTitle: { valueType: 'text' },
+            },
+        };
+        const result = (0, parse_args_1.normalizeLayoutOptions)(options, layoutDefinition);
+        expect(result).toEqual({
+            showFooter: true,
+            showHeader: false,
+            theme: 'dark',
+            customTitle: 'Test',
+        });
+    });
+    it('throws error for invalid boolean value', () => {
+        const options = {
+            showFooter: 'yes',
+        };
+        const layoutDefinition = {
+            options: {
+                showFooter: {
+                    valueType: 'boolean',
+                },
+            },
+        };
+        expect(() => (0, parse_args_1.normalizeLayoutOptions)(options, layoutDefinition)).toThrow('Invalid boolean value "yes" for option "showFooter". Must be "true" or "false".');
+    });
+    it('only normalizes options that exist in layoutDefinition', () => {
+        const options = {
+            showFooter: 'true',
+            unknownOption: 'true',
+        };
+        const layoutDefinition = {
+            options: {
+                showFooter: {
+                    valueType: 'boolean',
+                },
+            },
+        };
+        const result = (0, parse_args_1.normalizeLayoutOptions)(options, layoutDefinition);
+        expect(result).toEqual({
+            showFooter: true,
+            unknownOption: 'true', // Left as string because not in layoutDefinition
+        });
+    });
+    it('preserves options not present in layoutDefinition options', () => {
+        const options = {
+            showFooter: 'true',
+            theme: 'dark',
+        };
+        const layoutDefinition = {
+            options: {
+                showFooter: {
+                    valueType: 'boolean',
+                },
+            },
+        };
+        const result = (0, parse_args_1.normalizeLayoutOptions)(options, layoutDefinition);
+        expect(result).toEqual({
+            showFooter: true,
+            theme: 'dark', // Preserved even though not in layoutDefinition
+        });
+    });
+});

package/lib/page/utils/render.d.ts

@@ -16,18 +16,29 @@ export interface ZoneDefinition {
     minNodes?: number;
     maxNodes?: number;
 }
+/**
+ * Layout option value types.
+ */
+export declare const LayoutOptionValueType: {
+    readonly stringEnum: "string-enum";
+    readonly boolean: "boolean";
+    readonly text: "text";
+};
+export declare type LayoutOptionValueType = typeof LayoutOptionValueType[keyof typeof LayoutOptionValueType];
+export declare const LayoutOptionValueTypes: readonly ["string-enum", "boolean", "text"];
 export interface OptionDefinition {
     displayName: string;
     description: string;
-    values: string[];
+    valueType?: LayoutOptionValueType;
+    values?: string[];
 }
 /**
  * Renders a layout using Handlebars templating
  *
  * @param templateContent The Handlebars template string
  * @param zoneContents Content for each zone as single concatenated strings
- * @param layoutOptions Options for the layout
+ * @param layoutOptions Options for the layout (can include boolean values for boolean-type options)
  * @param layoutDefinition Optional layout definition object to pass to the template
  * @returns The rendered HTML
  */
-export declare function renderLayout(templateContent: string, zoneContents: Record<string, string>, layoutOptions: Record<string, any>, layoutDefinition?: ExtendedLayoutDefinition): Promise<string>;
+export declare function renderLayout(templateContent: string, zoneContents: Record<string, string>, layoutOptions: Record<string, string | boolean>, layoutDefinition?: ExtendedLayoutDefinition): Promise<string>;

package/lib/page/utils/render.js

@@ -12,14 +12,27 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
     return (mod && mod.__esModule) ? mod : { "default": mod };
 };
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.renderLayout = void 0;
+exports.renderLayout = exports.LayoutOptionValueTypes = exports.LayoutOptionValueType = void 0;
 const handlebars_1 = __importDefault(require("handlebars"));
+/**
+ * Layout option value types.
+ */
+exports.LayoutOptionValueType = {
+    stringEnum: 'string-enum',
+    boolean: 'boolean',
+    text: 'text',
+};
+exports.LayoutOptionValueTypes = [
+    exports.LayoutOptionValueType.stringEnum,
+    exports.LayoutOptionValueType.boolean,
+    exports.LayoutOptionValueType.text,
+];
 /**
  * Renders a layout using Handlebars templating
  *
  * @param templateContent The Handlebars template string
  * @param zoneContents Content for each zone as single concatenated strings
- * @param layoutOptions Options for the layout
+ * @param layoutOptions Options for the layout (can include boolean values for boolean-type options)
  * @param layoutDefinition Optional layout definition object to pass to the template
  * @returns The rendered HTML
  */

package/lib/page/utils/render.spec.js

@@ -68,7 +68,7 @@ describe('renderLayout', () => {
             main: '<p>Content</p>',
         };
         const layoutOptions = {
-            theme: { selectedValue: 'dark' },
+            theme: 'dark',
         };
         const result = yield (0, render_1.renderLayout)(templateContent, zoneContents, layoutOptions);
         expect(result).toContain('<div class="theme-dark">');

package/lib/page/utils/server.d.ts

@@ -3,7 +3,7 @@ interface DevServerOptions {
     configPath: string;
     layoutDefinition: ExtendedLayoutDefinition;
     zoneContent: Record<string, string[]>;
-    layoutOptions: Record<string, string>;
+    layoutOptions: Record<string, string | boolean>;
     stylesheet?: string;
     port: number;
     openBrowser: boolean;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@squiz/dxp-cli-next",
-  "version": "5.30.0",
+  "version": "5.31.0-develop.1",
   "repository": {
     "url": "https://gitlab.squiz.net/dxp/dxp-cli-next"
   },