@aligent/nx-appbuilder 0.2.0

package/src/generators/app/files/commerce-backend-ui/src/commerce-backend-ui-1/web-src/src/types/ActionName.ts.template

@@ -0,0 +1,9 @@
+/**
+ * Known App Builder action names registered in config.json.
+ * Update this type when actions are added or removed in app.config.yaml — it
+ * keeps the useAppBuilderAction / useLazyAppBuilderAction hooks type-safe.
+ *
+ * @example
+ * export type ActionName = 'my-package/my-action' | 'my-package/another-action';
+ */
+export type ActionName = never;

package/src/generators/app/files/commerce-backend-ui/src/commerce-backend-ui-1/web-src/tsconfig.json.template

@@ -0,0 +1,14 @@
+{
+    "extends": "@aligent/ts-code-standards/tsconfigs-react",
+    "compilerOptions": {
+        "allowImportingTsExtensions": true,
+        "resolveJsonModule": true,
+        "baseUrl": "../../..",
+        "paths": {
+            "@/web/*": ["src/commerce-backend-ui-1/web-src/src/*"],
+            "@/*": ["src/*"]
+        }
+    },
+    "include": ["**/*.tsx", "**/*.ts"],
+    "exclude": []
+}

package/src/generators/app/files/commerce-config/src/commerce-configuration-1/ext.config.yaml.template

@@ -0,0 +1,37 @@
+# The [pre-app-build] hooks are auto-generated. Do not remove or manually edit.
+hooks:
+  pre-app-build: EXTENSION=configuration/1 npx aio-commerce-lib-app hooks pre-app-build
+
+operations:
+  # These worker processes definitions are auto-generated. Do not remove or manually edit.
+  workerProcess:
+    - type: action
+      impl: app-management/config
+    - type: action
+      impl: app-management/scope-tree
+
+runtimeManifest:
+  packages:
+    # This package definition is auto-generated. Do not remove or manually edit.
+    app-management:
+      license: Apache-2.0
+      actions:
+        config:
+          function: .generated/actions/app-management/config.js
+          web: yes
+          runtime: nodejs:22
+          inputs:
+            LOG_LEVEL: $LOG_LEVEL
+            AIO_COMMERCE_CONFIG_ENCRYPTION_KEY: $AIO_COMMERCE_CONFIG_ENCRYPTION_KEY
+          annotations:
+            require-adobe-auth: true
+            final: true
+        scope-tree:
+          function: .generated/actions/app-management/scope-tree.js
+          web: yes
+          runtime: nodejs:22
+          inputs:
+            LOG_LEVEL: $LOG_LEVEL
+          annotations:
+            require-adobe-auth: true
+            final: true

package/src/generators/app/files/commerce-config/src/commerce-configuration-1/my-webpack-config.cjs.template

@@ -0,0 +1,24 @@
+const path = require('path');
+
+module.exports = {
+    module: {
+        rules: [
+            {
+                test: /\.js$/,
+                // Do not exclude node_modules if you need to process ES modules from dependencies
+                // but for now let's focus on the .generated folder
+                include: [
+                    path.resolve(__dirname, '.generated'),
+                    /node_modules\/@adobe\/aio-commerce-lib-app/,
+                ],
+                use: {
+                    loader: 'babel-loader',
+                    options: {
+                        configFile: path.resolve(__dirname, '../../babel.actions.config.js'),
+                        sourceType: 'unambiguous',
+                    },
+                },
+            },
+        ],
+    },
+};

package/src/generators/app/files/commerce-extensibility/app.commerce.config.ts.template

@@ -0,0 +1,138 @@
+import { defineConfig } from '@adobe/aio-commerce-lib-app/config';
+
+export default defineConfig({
+    metadata: {
+        id: '<%= name %>',
+        displayName: '<%= displayName %>',
+        description: '<%= description %>',
+        version: '0.0.1',
+    },
+<%_ if (hasBusinessConfig) { _%>
+    businessConfig: {
+        schema: [
+            // Add merchant-facing configuration fields here. Each field
+            // renders a control in the Commerce admin under
+            // Stores → Configuration for this app's section.
+            //
+            // Examples:
+            //
+            // {
+            //     type: 'text',
+            //     name: 'api_key',
+            //     label: 'API Key',
+            //     description: 'Authentication key for the upstream service.',
+            // },
+            // {
+            //     type: 'list',
+            //     name: 'environment',
+            //     label: 'Environment',
+            //     selectionMode: 'single',
+            //     options: [
+            //         { label: 'Staging', value: 'staging' },
+            //         { label: 'Production', value: 'production' },
+            //     ],
+            //     default: 'staging',
+            // },
+        ],
+    },
+<%_ } _%>
+<%_ if (hasEvents) { _%>
+    eventing: {
+        // Commerce events fire from Adobe Commerce instances. Subscribe a
+        // runtime action by name; pre-app-build wires it up.
+        commerce: [
+            {
+                provider: {
+                    label: '<%= displayName %> Commerce Events',
+                    description: 'Events emitted by the connected Commerce instance.',
+                },
+                events: [
+                    {
+                        name: 'observer.sales_order_place_after',
+                        label: 'Order placed',
+                        description: 'Fired after an order is successfully placed.',
+                        fields: [
+                            { name: 'order.entity_id' },
+                            { name: 'order.increment_id' },
+                            { name: 'order.customer_email' },
+                        ],
+                        runtimeActions: ['<%= runtimePackageName %>/handle-sample-event'],
+                    },
+                ],
+            },
+        ],
+        // External events come from third-party systems (ERP, CRM, etc.).
+        // Remove this block if you don't subscribe to any.
+        external: [
+            {
+                provider: {
+                    label: '<%= displayName %> External Events',
+                    description: 'Events emitted by an external integration.',
+                },
+                events: [
+                    {
+                        name: 'be-observer.sample_event',
+                        label: 'Sample external event',
+                        description: 'Use case description for the event.',
+                        runtimeActions: ['<%= runtimePackageName %>/handle-sample-event'],
+                    },
+                ],
+            },
+        ],
+    },
+<%_ } _%>
+<%_ if (hasCommerceWebhooks) { _%>
+    webhooks: [
+        // Each webhook binds a Commerce extensibility hook to one of your
+        // runtime actions (declared in app.config.yaml). At install time the
+        // lib provisions the subscription on the Commerce instance.
+        //
+        // Schema reference:
+        //   https://developer.adobe.com/commerce/extensibility/app-management/installation/webhooks/
+        //
+        // Worked example — point at a runtime action you've defined:
+        //
+        // {
+        //     label: 'Validate order before placement',
+        //     description: 'Halt order placement when a custom rule fails.',
+        //     category: 'validation',
+        //     runtimeAction: '<%= runtimePackageName %>/validate-order',
+        //     requireAdobeAuth: true,
+        //     webhook: {
+        //         webhook_method: 'observer.sales_order_place_before',
+        //         webhook_type: 'before',
+        //         batch_name: '<%= runtimePackageName %>_validate_batch',
+        //         hook_name: '<%= runtimePackageName %>_validate_hook',
+        //         method: 'POST',
+        //         priority: 100,
+        //         required: true,
+        //         timeout: 5000,
+        //         fallback_error_message: '<%= displayName %> validation unavailable',
+        //         fields: [
+        //             { name: 'grand_total', source: 'data.order.grand_total' },
+        //         ],
+        //         rules: [],
+        //         headers: [],
+        //     },
+        // },
+        //
+        // Or send to an external URL instead of a runtime action — drop
+        // `runtimeAction`/`requireAdobeAuth` and add `url` under `webhook`.
+    ],
+<%_ } _%>
+<%_ if (hasCustomInstallSteps) { _%>
+    installation: {
+        messages: {
+            // preInstallation: 'Shown to the merchant before installing the app.',
+            // postInstallation: 'Shown to the merchant after the app installs successfully.',
+        },
+        customInstallationSteps: [
+            {
+                name: 'sample-step',
+                description: 'Use case description for the step.',
+                script: './scripts/install/sample-step.js',
+            },
+        ],
+    },
+<%_ } _%>
+});

package/src/generators/app/files/commerce-extensibility/install.yaml.template

@@ -0,0 +1,17 @@
+$schema: http://json-schema.org/draft-07/schema
+$id: https://adobe.io/schemas/app-builder-templates/1
+
+categories:
+    - action
+<%_ if (hasAdminUI) { _%>
+    - ui
+<%_ } _%>
+
+extensions:
+<%_ if (hasAdminUI) { _%>
+    - extensionPointId: commerce/backend-ui/1
+<%_ } _%>
+<%_ if (hasBusinessConfig) { _%>
+    - extensionPointId: commerce/configuration/1
+<%_ } _%>
+    - extensionPointId: commerce/extensibility/1

package/src/generators/app/files/commerce-extensibility/src/commerce-extensibility-1/ext.config.yaml.template

@@ -0,0 +1,25 @@
+# The [pre-app-build] hooks are auto-generated. Do not remove or manually edit.
+hooks:
+  pre-app-build: EXTENSION=extensibility/1 npx aio-commerce-lib-app hooks pre-app-build
+
+operations:
+  # These worker processes definitions are auto-generated. Do not remove or manually edit.
+  workerProcess:
+    - type: action
+      impl: app-management/app-config
+
+runtimeManifest:
+  packages:
+    # This package definition is auto-generated. Do not remove or manually edit.
+    app-management:
+      license: Apache-2.0
+      actions:
+        app-config:
+          function: .generated/actions/app-management/app-config.js
+          web: yes
+          runtime: nodejs:22
+          inputs:
+            LOG_LEVEL: $LOG_LEVEL
+          annotations:
+            require-adobe-auth: true
+            final: true

package/src/generators/app/files/commerce-extensibility/src/commerce-extensibility-1/my-webpack-config.cjs.template

@@ -0,0 +1,24 @@
+const path = require('path');
+
+module.exports = {
+    module: {
+        rules: [
+            {
+                test: /\.js$/,
+                // Do not exclude node_modules if you need to process ES modules from dependencies
+                // but for now let's focus on the .generated folder
+                include: [
+                    path.resolve(__dirname, '.generated'),
+                    /node_modules\/@adobe\/aio-commerce-lib-app/,
+                ],
+                use: {
+                    loader: 'babel-loader',
+                    options: {
+                        configFile: path.resolve(__dirname, '../../babel.actions.config.js'),
+                        sourceType: 'unambiguous',
+                    },
+                },
+            },
+        ],
+    },
+};

package/src/generators/app/files/events/global-types/@adobe/aio-sdk/aio-lib-events.d.ts.template

@@ -0,0 +1,7 @@
+/// <reference types="@adobe/aio-lib-events/types.d.ts" />
+
+declare module '@adobe/aio-sdk' {
+    namespace Events {
+        export { init };
+    }
+}

package/src/generators/app/files/events/src/actions/handle-sample-event.ts.template

@@ -0,0 +1,35 @@
+import { Core } from '@adobe/aio-sdk';
+
+/**
+ * Stub event handler.
+ *
+ * The `eventing` section of `app.commerce.config.ts` references this action by
+ * name. When the user installs the app, `aio-commerce-lib-app` registers the
+ * subscription and routes matching events here as CloudEvent payloads —
+ * `params.type` is the event type, `params.data` is the payload.
+ */
+
+interface EventParams {
+    type?: string;
+    source?: string;
+    id?: string;
+    data?: Record<string, unknown>;
+    LOG_LEVEL?: string;
+}
+
+export async function main(params: EventParams) {
+    const logger = Core.Logger('handle-sample-event', { level: params.LOG_LEVEL || 'info' });
+
+    logger.info('Event received', {
+        type: params.type,
+        source: params.source,
+        id: params.id,
+    });
+
+    // TODO: dispatch on params.type and process params.data.
+
+    return {
+        statusCode: 200,
+        body: { received: true },
+    };
+}

package/src/generators/app/files/install-steps/scripts/install/sample-step.js.template

@@ -0,0 +1,14 @@
+/**
+ * Custom installation step.
+ *
+ * Referenced from `installation.customInstallationSteps` in
+ * `app.commerce.config.ts`. Runs once during merchant install of the app.
+ *
+ * The script receives the runtime context as its argument and should return
+ * `{ success: true }` to proceed, or throw to halt installation.
+ */
+
+module.exports = async function sampleStep(_context) {
+    // TODO: implement the install step.
+    return { success: true };
+};

package/src/generators/app/files/rest-actions/src/actions/rest-sample.ts.template

@@ -0,0 +1,30 @@
+import { Core } from '@adobe/aio-sdk';
+
+/**
+ * Stub REST endpoint. Adjust the response shape and add domain logic as needed.
+ *
+ * Invoked at:
+ *   https://{namespace}.adobeioruntime.net/api/v1/web/<runtime-package-name>/rest-sample
+ */
+
+interface ActionParams {
+    __ow_method?: string;
+    __ow_query?: string;
+    __ow_body?: string;
+    __ow_headers: Record<string, string | undefined>;
+    LOG_LEVEL?: string;
+}
+
+export async function main(params: ActionParams) {
+    const logger = Core.Logger('rest-sample', { level: params.LOG_LEVEL || 'info' });
+
+    logger.info('REST request received', {
+        method: params.__ow_method,
+        query: params.__ow_query,
+    });
+
+    return {
+        statusCode: 200,
+        body: { message: 'Hello from rest-sample' },
+    };
+}

package/src/generators/app/files/scheduled/src/actions/cron-sample.ts.template

@@ -0,0 +1,23 @@
+import { Core } from '@adobe/aio-sdk';
+
+/**
+ * Stub cron-triggered action.
+ *
+ * Bound to a `/whisk.system/alarms/alarm` trigger by the rule declared in
+ * app.config.yaml. The default cron expression is hourly — adjust it under
+ * `triggers.cron-sample-trigger.inputs.cron` to suit.
+ */
+
+interface CronParams {
+    LOG_LEVEL?: string;
+}
+
+export async function main(params: CronParams) {
+    const logger = Core.Logger('cron-sample', { level: params.LOG_LEVEL || 'info' });
+
+    logger.info('Scheduled action fired', { timestamp: new Date().toISOString() });
+
+    // TODO: implement scheduled work.
+
+    return { ok: true };
+}

package/src/generators/app/generator.d.ts

@@ -0,0 +1,3 @@
+import { type Tree } from '@nx/devkit';
+import type { AppGeneratorSchema } from './schema';
+export default function appGenerator(tree: Tree, rawOptions: AppGeneratorSchema): Promise<() => void>;

package/src/generators/app/generator.js

@@ -0,0 +1,38 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.default = appGenerator;
+const devkit_1 = require("@nx/devkit");
+const enquirer_1 = require("enquirer");
+const apply_feature_files_1 = require("./lib/apply-feature-files");
+const compose_package_json_1 = require("./lib/compose-package-json");
+const normalize_options_1 = require("./lib/normalize-options");
+const update_root_package_1 = require("./lib/update-root-package");
+const update_root_tsconfig_1 = require("./lib/update-root-tsconfig");
+async function appGenerator(tree, rawOptions) {
+    await promptForConditionalInputs(rawOptions);
+    const options = (0, normalize_options_1.normalizeOptions)(tree, rawOptions);
+    (0, apply_feature_files_1.applyFeatureFiles)(tree, options);
+    (0, compose_package_json_1.writePackageJson)(tree, options);
+    (0, update_root_package_1.updateRootPackageJson)(tree, options);
+    (0, update_root_tsconfig_1.addTsConfigReference)(tree, options);
+    await (0, devkit_1.formatFiles)(tree);
+    return () => {
+        (0, devkit_1.installPackagesTask)(tree);
+    };
+}
+/**
+ * Prompts that depend on the value of other prompts can't be expressed in
+ * Nx's schema.json, so they're driven from here. Currently only one:
+ * sidebar category is asked iff hasAdminUI=true and the user didn't pass it.
+ */
+async function promptForConditionalInputs(opts) {
+    if (opts.hasAdminUI && opts.sidebarCategory === undefined) {
+        const answer = await (0, enquirer_1.prompt)({
+            type: 'select',
+            name: 'sidebarCategory',
+            message: 'Which sidebar category does the menu item belong under?',
+            choices: ['catalog', 'sales', 'customers', 'content', 'none'],
+        });
+        opts.sidebarCategory = answer.sidebarCategory;
+    }
+}

package/src/generators/app/lib/apply-feature-files.d.ts

@@ -0,0 +1,9 @@
+import { type Tree } from '@nx/devkit';
+import type { NormalizedSchema } from '../schema';
+/**
+ * Renders template files into the new app's directory based on selected flags.
+ *
+ * Each call to generateFiles overwrites earlier ones for the same file paths,
+ * so subtree order matters when subtrees overlap (none currently do).
+ */
+export declare function applyFeatureFiles(tree: Tree, options: NormalizedSchema): void;

package/src/generators/app/lib/apply-feature-files.js

@@ -0,0 +1,76 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.applyFeatureFiles = applyFeatureFiles;
+const devkit_1 = require("@nx/devkit");
+const path = __importStar(require("path"));
+/**
+ * Renders template files into the new app's directory based on selected flags.
+ *
+ * Each call to generateFiles overwrites earlier ones for the same file paths,
+ * so subtree order matters when subtrees overlap (none currently do).
+ */
+function applyFeatureFiles(tree, options) {
+    const filesRoot = path.join(__dirname, '..', 'files');
+    const subs = {
+        ...options,
+        nodeMajor: options.nodeVersion.split('.')[0],
+    };
+    (0, devkit_1.generateFiles)(tree, path.join(filesRoot, 'base'), options.appRoot, subs);
+    const usesCommerceLib = options.hasAdminUI || options.hasBusinessConfig || options.hasCommerceWebhooks;
+    if (usesCommerceLib) {
+        (0, devkit_1.generateFiles)(tree, path.join(filesRoot, 'commerce-extensibility'), options.appRoot, subs);
+    }
+    if (options.hasBusinessConfig) {
+        (0, devkit_1.generateFiles)(tree, path.join(filesRoot, 'commerce-config'), options.appRoot, subs);
+    }
+    if (options.hasAdminUI) {
+        (0, devkit_1.generateFiles)(tree, path.join(filesRoot, 'commerce-backend-ui'), options.appRoot, subs);
+    }
+    // Webhooks no longer have their own subtree — they're a section in
+    // app.commerce.config.ts (rendered above as part of commerce-extensibility).
+    if (options.hasRestActions) {
+        (0, devkit_1.generateFiles)(tree, path.join(filesRoot, 'rest-actions'), options.appRoot, subs);
+    }
+    if (options.hasEvents) {
+        (0, devkit_1.generateFiles)(tree, path.join(filesRoot, 'events'), options.appRoot, subs);
+    }
+    if (options.hasScheduledActions) {
+        (0, devkit_1.generateFiles)(tree, path.join(filesRoot, 'scheduled'), options.appRoot, subs);
+    }
+    if (options.hasCustomInstallSteps) {
+        (0, devkit_1.generateFiles)(tree, path.join(filesRoot, 'install-steps'), options.appRoot, subs);
+    }
+}

package/src/generators/app/lib/compose-package-json.d.ts

@@ -0,0 +1,3 @@
+import { type Tree } from '@nx/devkit';
+import type { NormalizedSchema } from '../schema';
+export declare function writePackageJson(tree: Tree, options: NormalizedSchema): void;