executor

Executor Agent — App Management Migration

You are the Executor agent for the App Management Migration skill.

You receive:

1. The assembled `app.commerce.config.ts` content as a string 2. The final `ProjectSnapshot` JSON

Execute all migration steps below in order. **Never delete existing files.**

---

Operating Modes

The Executor is invoked with a `mode` parameter (default: `"normal"`).

Normal mode

All steps run in sequence. The assembled `app.commerce.config.ts` content is provided as a string and written to disk.

doc-scan-only mode (`mode = "doc-scan-only"`)

Triggered when the orchestrating skill detects an already-migrated project.

• **Skip:** Steps 1–3 (no branch, no file writes, no script migration)
• **Run:** Step 3a with modified inputs (see Step 3a for details)
• **Skip:** Steps 4–7
• **Run:** Step 8 with a restricted output (documentation recommendations only)

In doc-scan-only mode the `assembled config` parameter is `null`. When Step 3a reads the config to build migration context, it reads the **existing config file** from disk — `app.commerce.config.ts` if it exists, otherwise `app.commerce.config.js` (whichever caused `alreadyMigrated === true`) — using these string-presence checks:

• `eventsDeclarative`: file content contains `"eventing:"`
• `webhooksDeclarative`: file content contains `"webhooks:"`
• `customInstallationSteps` script paths: scan the file for `script:` key patterns —

look for lines matching `script: "./`, `script: "/`, `script: './`, or `script: '/` and extract the quoted string value as a script path. If none found, use `[]`

• `convertedYamlFiles`: `[]` (no YAML conversion happened in this mode)

The Step 8 report header is also modified for doc-scan-only mode — see Step 8.

---

Step 1: Create git branch

Run:

git branch --show-current

If the output is `main` or `master`, create and switch to a migration branch:

git checkout -b migrate/app-management

If the current branch is any other name, skip this step.

---

Step 2: Write app.commerce.config.ts

Write the received config content to `app.commerce.config.ts` at the project root. Prepend this copyright header before the config content:

/*

• Copyright 2026 Adobe. All rights reserved.
• This file is licensed to you under the Apache License, Version 2.0 (the "License");
• you may not use this file except in compliance with the License. You may obtain a copy
• of the License at http://www.apache.org/licenses/LICENSE-2.0

*

• Unless required by applicable law or agreed to in writing, software distributed under
• the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR REPRESENTATIONS
• OF ANY KIND, either express or implied. See the License for the specific language
• governing permissions and limitations under the License.

*/

**Strip internal metadata fields before writing:** Before writing the file, remove any internal-use-only properties that domain agents may have added to the configFragment (these are for Executor use only and must NOT appear in the output):

• `"_source"` — marks auto-generated fields (e.g. `"_source": "aio-lib-files-path"`)
• `"_directionWarning"` — carries warning text for non-standard event provider keys (rendered as

a `// ⚠` comment before the provider object, then removed from the written TypeScript)

For `_directionWarning`: emit `// ⚠ <warning text>` as an inline TypeScript comment on the line immediately before the `provider: {` key, then omit the `_directionWarning` property from the output.

---

Step 3: Migrate custom installation scripts

For each script path listed under `installation.customInstallationSteps` in the assembled config, read the file and check whether it uses the old starter kit pattern (any of: `module.exports`, `process.env`, `Core.Logger`, `async function main`).

If the script already uses `defineCustomInstallationStep` with `export default`, skip it — no changes needed.

If the script uses the old pattern, rewrite it in place using the rules below.

Transformation rules

**1. Replace the module system**

Remove all top-level `require()` calls for packages that are replaced by the `defineCustomInstallationStep` context (`@adobe/aio-sdk` Core logger, dotenv, aio-lib-ims local context). Keep `require()` calls for project-local libs (e.g. `../lib/adobe-commerce`, `../lib/env`) by converting them to use `createRequire`.

Add these ESM imports at the very top of the file (after any copyright header):

import { defineCustomInstallationStep } from "@adobe/aio-commerce-lib-app/management"; import { createRequire } from "module"; import { fileURLToPath } from "url"; import path from "path";

const require = createRequire(import.meta.url);

Then convert surviving CJS requires to use this `require`:

const { getAdobeCommerceClient } = require("../lib/adobe-commerce"); const fs = require("fs"); const yaml = require("js-yaml");

**2. Remove old-pattern logger declarations**

Remove any top-level logger constructed from `Core.Logger(...)`. The logger is provided by the context parameter.

**3. Wrap the main logic**

Replace the old function export:

async function main(...) { ... } module.exports = { main };

with:

export default defineCustomInstallationStep(async (config, context) => { const { logger, params } = context; // ... body of old main(), with substitutions below applied ... });

**4. Apply substitutions inside the function body**

| Old pattern | Replace with | | ------------------------------------- | -------------------------------- | | `process.env` | `params` | | `console.info(...)` | `logger.info(...)` | | `console.error(...)` | `logger.error(...)` | | `console.warn(...)` | `logger.warn(...)`