appbuilder-project-init

# App Builder Project Initialization Maps user intent to the right Adobe App Builder template and runs non-interactive `aio app init`. Default: `@adobe/generator-app-excshell` (SPA + actions). For headless/bare projects, use `init-bare`. When a Developer Console project / workspace / API subscription does not yet exist, this skill walks the agent through creating them non-interactively by calling `aio console …` directly — see the **Bootstrap** section and [references/bootstrap.md](references/bootstrap.md). The latest `@adobe/aio-cli` bundle exposes non-interactive `aio console project create` / `workspace create` / `api list` / `workspace api add` (with `--license-config` for services that require a product profile), and non-interactive `aio app init --org/--project/--template-options`. Together they remove every blocking "open the Developer Console UI and click" step from the agentic setup path. Just install the latest CLI (`npm install -g @adobe/aio-cli`) and use them. ## Machine setup (first time) Do this once per machine before initializing a project — plus a login per environment. If the CLI is already installed and you're logged in, skip to **Bootstrap** below. ### 1. Node 20 App Builder needs **Node 20** (npm ships with it). Check what's active: `node -v` → expect `v20.x`. - **Have nvm?** `nvm install 20 && nvm use 20 && nvm alias default 20` so new shells keep it. If several Node versions are installed, the *active* one must be 20. - **No Node / no nvm?** Install nvm, then Node 20: ```bash curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.40.1/install.sh | bash # reopen the shell, then: nvm install 20 && nvm use 20 && nvm alias default 20 ``` (Alternatives: `brew install node@20`, or the official installer at nodejs.org.) > Older Adobe docs say Node 18 — use **20**. A global `aio` belongs to whichever Node was active when you ran `npm i -g`; if you switch Node versions the old `aio` won't be on PATH. Symptom of a mismatch: `aio` dies with `SyntaxError: Unexpected token '??='` (a pre-20 Node parsing the Node-20 `aio`) — fix with `nvm use 20` and reinstall `aio` there. ### 2. Install the aio CLI + log in ```bash npm install -g @adobe/aio-cli # on Node 20 aio login # opens a browser; `aio login -f` forces a fresh prompt aio where # confirm the correct IMS org/context aio console org list # list orgs and their IDs (then `aio console org select <id>` if needed) ``` Tokens are stored by the CLI automatically; a normal `aio login` lasts hours/days — one login per session, not per command. Confirm the **correct IMS org** — wrong-org is the most common setup mistake. ### 3. Stage vs prod The default environment is **prod**. To target **stage**, set the env var and re-authenticate: ```bash export AIO_CLI_ENV=stage aio logout && aio login ``` Unset the variable (or open a new shell) to return to prod. The stage CLI talks to the stage Console (`developer-stage`). ### Logging in without a browser (CI / no human) - **Import creds:** in the Developer Console open the workspace → **Download all** → `console.json`, then `aio app init <app> --import path/to/console.json` (fills `.env`/`.aio` — treat `console.json` as a secret, gitignore it). - **CI / pipeline:** add an **OAuth Server-to-Server** credential to the workspace; `aio` and Runtime authenticate from the client id/secret with no human. Don't script SSO/MFA headlessly. ## Bootstrap the Developer Console (project, workspace, APIs) If the user is starting from zero — no Developer Console project yet, or an existing project that is missing a workspace or API subscription — bootstrap that state **before** `aio app init`. Otherwise `aio app init` / `aio app use` / `aio app deploy` have nothing to wire the local app to. The full bootstrap is just `aio` commands; **call them directly**, not through a wrapper script. They are already non-interactive in the recent plugin releases, and per-step calls let you react to "already exists" or "needs a product profile" responses without baking those decisions into bash. ### Preflight Make sure the CLI is current — that's what brings in the non-interactive Console + app init commands: ```bash npm install -g @adobe/aio-cli aio --version ``` Don't try to assert specific plugin versions; just take the latest. If a `console` or `app` subcommand below is rejected as "command not found" or "unknown flag" after this, the CLI install genuinely failed (PATH issue, permissions, registry mirror) — fix the install rather than working around it. Confirm an org is selected (or pass `--orgId` on every command below): ```bash aio console org list --json # if needed, then: aio console org select <orgId> ``` ### Decision rule | User state | Next action | | --- | --- | | "Create a project + workspace + add APIs from scratch" | Run the bootstrap chain (project → workspace → APIs), then `aio app init`. | | Project exists, workspace missing | Skip project-create. Run `aio console workspace create`, then optionally `aio console workspace api add`. | | Project + workspace exist, only need to add an API | Run `aio console api list` to discover service codes, then `aio console workspace api add`. | | Everything already wired | Skip bootstrap. Go straight to **Initialize via Script**. | Always check what already exists with `aio console project list --json` and `aio console workspace api list --projectName <p> --workspaceName <w> --json` before creating — these commands fail loudly on "already exists" and there is no built-in idempotency. ### The bootstrap chain (raw commands) Step 1 — create the Console project: ```bash aio console project create -n my-project --json # optional: -t "Title" -d "Description" -o <orgId> ``` Step 2 — create a workspace inside it (`Stage` is the conventional first non-Production workspace; pick a more descriptive name in long-lived shared projects): ```bash aio console workspace create \ --projectName my-project \ --name Stage \ --json # optional: --orgId <orgId> --title "Stage workspace" ``` Step 3 — discover and subscribe the APIs the app needs: ```bash aio console api list --json # see all service codes available to the org # entries flagged for whether they need a product profile # Free-tier service: aio console workspace api add \ --projectName my-project \ --workspaceName Stage \ --service-code AdobeIOManagementAPISDK \ --json # Service that requires a product profile: aio console workspace api add \ --projectName my-project \ --workspaceName Stage \ --service-code AdobeAnalyticsSDK \ --license-config AdobeAnalyticsSDK=AnalyticsProductionProfile \ --json ``` `--service-code` accepts a comma-separated list to subscribe several free-tier services in one call. `--license-config` is repeatable when several profile-bound services are added together. ### Recover from per-step failures | Failure | What to do | | --- | --- | | `project create` fails with "already exists" | Read `aio console project list --json`, reuse the existing project's name, and continue at step 2. | | `workspace create` fails with "already exists" | List workspaces with `aio console workspace list --projectName <p> --json` and continue at step 3. | | `workspace api add` returns "product profile required" | The service code requires `--license-config`. Ask the user (or the org admin) for the profile name and retry with `--license-config CODE=PROFILE`. | | Any step returns an org-selection error | Pass `--orgId <id>` explicitly, or `aio console org select <id>` once before retrying. | ### Wire the local app to the bootstrapped state Two equivalent ways to point a fresh `aio app init` at the project/workspace you just created: 1. **Pass them as flags to `init` itself** (cleanest): ```bash skills/appbuilder-project-init/scripts/init.sh init \ "@adobe/generator-app-excshell" ./my-project \ --org <orgId> --project my-project ``` The wrapper passes `--org` / `--project` / `--template-options` straight through to `aio app init`, on top of the existing `-y --no-login --no-install` flags. 2. **Run `aio app use` after init** (works on any plugin version): ```bash cd ./my-project aio app use --no-input # adopts the currently selected project/workspace, no prompts ``` Either route ends with the local `.aio` and `.env` pointing at the workspace you just bootstrapped, so `aio app deploy` publishes to the right namespace. ## Fast Path (for clear requests) When the user's intent maps unambiguously to a single template — for example, they name a template directly or describe an app that clearly matches exactly one entry below — skip straight to **Initialize via Script** below. Use the matched template and any project name the user provided (or a sensible default). Examples of fast-path triggers: - "Create an App Builder app using `@adobe/generator-app-excshell`" → use that template, run init - "Set up an Asset Compute worker" → maps unambiguously to `@adobe/generator-app-asset-compute`, run init - "Create a new App Builder app" (no specifics) → defaults to `@adobe/generator-app-excshell`, run init - "Initialize a bare project" → use `init-bare`, run init If there is any ambiguity — multiple templates could fit, or the user's constraints are unclear — use the full template decision table and workflow below. ## Template Decision Table Pick the template that matches the user's intent. When unclear, default to `@adobe/generator-app-excshell`. | User wants | Template | | --- | --- | | SPA with actions + React UI | @adobe/generator-app-excshell | | Content Hub extension (asset details panel, card action, bulk action) | No generator — scaffold from sample app, see [`references/templates.md`](references/templates.md) | | AEM Content Fragment Console extension | @adobe/aem-cf-admin-ui-ext-tpl | | AEM React SPA (WKND-based) | @adobe/generator-app-aem-react | | Adobe API Mesh (GraphQL) | @adobe/generator-app-api-mesh | | Asset Compute custom worker | @adobe/generator-app-asset-compute | | Remote server on App Builder | @adobe/generator-app-remote-mcp-server-generic | | Bare / from-scratch project (no pre-scaffolded actions or UI) | init.sh init-bare | For a headless/backend-only request, prefer `init-bare` when possible. If the user still needs a template that generates UI files, plan a post-init cleanup so the final project has no `web-src` frontend directory or web manifest wiring. ## Initialize via Script The `aio app *` wrappers go through a single script: `scripts/init.sh`. (Console bootstrap commands are called directly — see the **Bootstrap** section above for the rationale.) > **Note:** The path to this skill's scripts may be `skills/`, `.augment/skills/`, or `.github/skills/` depending on your platform and repository layout. Adjust the prefix in the commands below accordingly. **With a template:** ```bash skills/appbuilder-project-init/scripts/init.sh init "@adobe/generator-app-excshell" ./my-project ``` **With a template, fully wired to a specific Console org/project (no post-init `aio app use` needed):** ```bash skills/appbuilder-project-init/scripts/init.sh init \ "@adobe/generator-app-excshell" ./my-project \ --org <orgId> --project my-project ``` `--org`, `--project`, `--template-options` (base64-encoded JSON), and `--no-config-validation` are passed straight through to `aio app init`. Use the latest `@adobe/aio-cli` so they're all recognised; `--no-config-validation` is the escape hatch for the rare case where a partial scaffold shouldn't yet have to pass schema validation. **Bare project (no template):** ```bash skills/appbuilder-project-init/scripts/init.sh init-bare ./my-project ``` Use `init-bare` only when the user explicitly wants to configure everything from scratch. In that case, "bare" means the generated project should stay minimal: - `app.config.yaml` exists with an empty or minimal `application.runtimeManifest` - `package.json` exists with only the basic project dependencies - No pre-scaffolded `src/`, `web-src/`, or `actions/` directories Why this matters: if the user asked for a bare project, pre-generated actions or web assets contradict that intent and remove the clean starting point they requested. The script outputs JSON with `success`, `path`, and `output` fields. Check `success` before proceeding. ## Full Workflow (for ambiguous or complex requests) ### Step 1 — Gather intent Ask the user (or infer from conversation context): | Question | Examples | | --- | --- | | What type of app? | SPA shell, headless API, AEM extension, Asset Compute worker, API Mesh, remote server | | Needs a UI? | Yes (React Spectrum in ExC Shell), No (actions only) | | Extension point? | dx/excshell/1, aem/cf-console-admin/1, dx/asset-compute/worker/1, or N/A | | Additional actions? | Names and purposes of custom actions beyond the default | | Console state? | Existing project + workspace? Or do we need to create them and subscribe APIs first? | | APIs needed? | e.g. Adobe I/O Management, Analytics, Target — including any that require a product profile | If the user simply says "create an App Builder app" with no specifics, default to `@adobe/generator-app-excshell`. If the Console state is "from scratch" or unknown, run the **Bootstrap the Developer Console** flow before continuing to template selection. See [references/bootstrap.md](references/bootstrap.md) for the full agentic bootstrap playbook. ### Step 2 — Select template Consult the Template Decision Table above and [references/templates.md](references/templates.md) to map the user's intent to a template. ### Step 3 — Initialize, customize, validate Follow the **Initialize via Script**, **Post-init customization**, and **Validate** sections below. ## Post-init Customization Consult [references/templates.md](references/templates.md) for template-specific post-init guidance. Common tasks: 1. **Install dependencies** — Run `npm install` in the project directory. The init script uses `--no-install` to keep initialization fast, but dependencies are required before building or testing. 2. **For API Mesh projects, verify **`mesh.json`** is at the project root** — After `aio app init` with `@adobe/generator-app-api-mesh`, confirm `./mesh.json` exists before treating the scaffold as ready. If the file only exists at `node_modules/@adobe/generator-app-api-mesh/templates/mesh.json`, copy it into place with `cp node_modules/@adobe/generator-app-api-mesh/templates/mesh.json ./mesh.json`. The file under `node_modules/` is the generator's template source, not the project's active API Mesh configuration. Then customize the root `mesh.json` with the user's real source handlers; for multi-backend scenarios, configure at least two handlers. 3. **Clean up bare-project scaffolding if needed** — After `init-bare`, inspect the generated project. If the initializer created `actions/`, `src/`, or `web-src/`, remove those directories before continuing. A bare project should not keep auto-generated action code or web assets. 4. **Headless cleanup after template init** — If the user wants a headless project with **no frontend**, delete any generated UI directory after `aio app init`: `rm -rf web-src/` or the template-specific path such as `rm -rf src/<extension>/web-src/`. Then remove matching `web-src` config from `app.config.yaml` or `ext.config.yaml` if present, especially `web: web-src` and `operations.view` / `impl: index.html` entries. This avoids unnecessary frontend build artifacts and stale manifest wiring in a backend-only project. 5. **Add actions** — If the user later wants custom actions, run `cd ./my-project && skills/appbuilder-project-init/scripts/init.sh add-action "my-action"`. 6. **Add web assets** — Only if the user later decides the bare project needs a UI, run `skills/appbuilder-project-init/scripts/init.sh add-web-assets`. 7. **Edit ext.config.yaml directly** — Customize action definitions: - Set `runtime: nodejs:22` for production. Stage workspaces also accept `runtime: nodejs:24`. - Add `inputs:` for environment variables the action needs - Set `annotations.require-adobe-auth: true` if the action needs IMS tokens - Set `web: 'yes'` or `web: 'raw'` depending on HTTP access needs 8. **Edit app.config.yaml** — For multi-extension projects, add `$include` entries. 9. **Apply action boilerplate** — Use the `appbuilder-action-scaffolder` skill's boilerplate pattern for production-ready action code with logging, input validation, and error handling. ## Validate Verify the project structure by checking these items directly: 1. `app.config.yaml`** exists** and contains valid YAML